Support trailing maps in keyword argument destructuring (#833)

Fixes #663 
Fixes #834

Author: chrisrink10

CHANGELOG.md

@@ -15,6 +15,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
  * Added the `memoize` core fn (#812)
  * Added support for `thrown-with-msg?` assertions to `basilisp.test/is` (#831)
  * Added support for reading scientific notation literals, octal and hex integer literals, and arbitrary base (2-36) integer literals (#769)
+ * Added support for passing trailing maps to functions which accept Basilisp keyword arguments (#663)
 
 ### Changed
  * Optimize calls to Python's `operator` module into their corresponding native operators (#754)
@@ -41,6 +42,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
  * Fix a bug the variadic arg symbol was not correctly bound to `nil` when no variadic arguments were provided (#801)
  * Fix a bug where the quotient of very large numbers was incorrect (#822)
  * Fix a bug where `basilisp.test/is` may fail to generate expected/actual info on failures when declared inside a macro (#829)
+ * Fix a bug where sequential destructuring bindings do not bind names correctly when nested within associative destructuring bindings (#834)
 
 ### Removed
  * Removed support for PyPy 3.8 (#785)

docs/concepts.rst

@@ -57,7 +57,155 @@ TBD
 Destructuring
 -------------
 
-TBD
+The most common type of name binding encountered in Basilisp code is that of a single symbol to a value.
+For example, below the name ``a`` is bound to the result of the expression ``(+ 1 2)``::
+
+   (let [a (+ 1 2)]
+     a)
+
+In many cases this form of name binding is sufficient.
+However, when dealing with data nested in vectors or maps of known shapes, it would be much more convenient to bind those values directly without needing to write collection accessor functions by hand.
+Basilisp supports a form of name binding known as destructuring, which allows convenient name binding of values from within sequential and associative data structures.
+Destructuring is supported everywhere names are bound: :lpy:form:`fn` argument vectors, :lpy:form:`let` bindings, and :lpy:form:`loop` bindings.
+
+.. note::
+
+   Names without a corresponding element in the data structure (typically due to absence) will bind to ``nil``.
+
+.. _sequential_destructuring:
+
+Sequential Destructuring
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Sequential destructuring is used to bind values from sequential types.
+The binding form for sequential destructuring is a vector.
+Names in the vector will be bound to their corresponding indexed element in the sequential expression value, fetched from that type as by :lpy:fn:`nth`.
+As a result, any data type supported by ``nth`` natively supports sequential destructuring, including vectors, lists, strings, Python lists, and Python tuples.
+It is possible to collect the remaining unbound elements as a ``seq`` by providing a trailing name separated from the individual bindings by an ``&``.
+The rest element will be bound as by :lpy:fn:`nthnext`.
+It is also possible to bind the full collection to a name by adding a trailing ``:as`` name after all binding forms and optional rest binding.
+
+.. code-block::
+
+   (let [[a b c & others :as coll] [:a :b :c :d :e :f]]
+     [a b c others coll])
+   ;;=> [:a :b :c (:d :e :f) [:a :b :c :d :e :f]]
+
+Sequential destructuring may also be nested:
+
+.. code-block::
+
+   (let [[[a b c] & others :as coll] [[:a :b :c] :d :e :f]]
+     [a b c others coll])
+   ;;=> [:a :b :c (:d :e :f) [[:a :b :c] :d :e :f]]
+
+.. _associative_destructuring:
+
+Associative Destructuring
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Associative destructuring is used to bind values from associative types.
+The binding form for associative destructuring is a map.
+Names in the map will be bound to their corresponding key in the associative expression value, fetched from that type as by :lpy:fn:`get`.
+Asd a result, any associative types supported by ``get`` natively supports sequential destructuring, including maps, vectors, strings, sets, and Python dicts.
+It is possible to bind the full collection to a name by adding an ``:as`` key.
+Default values can be provided for keys by providing a map of binding names to default values using the ``:or`` key.
+
+.. code-block::
+
+   (defn f [{x :a y :b :as m :or {y 18}}]
+     [x y m])
+
+   (f {:a 1 :b 2})  ;;=> [1 2 {:a 1 :b 2}]
+   (f {:a 1})       ;;=> [1 18 {:a 1}]
+   (f {})           ;;=> [nil 18 {}]
+
+For the common case where the names you intend to bind directly match the corresponding keyword name, you can use the ``:keys`` notation.
+
+.. code-block::
+
+   (defn f [{:keys [a b] :as m}]
+     [a b m])
+
+   (f {:a 1 :b 2})  ;;=> [1 2 {:a 1 :b 2}]
+   (f {:a 1})       ;;=> [1 nil {:a 1}]
+   (f {})           ;;=> [nil nil {}]
+
+There exists a corresponding construct for the symbol and string key cases as well: ``:syms`` and ``:strs``, respectively.
+
+.. code-block::
+
+   (defn f [{:strs [a] :syms [b] :as m}]
+     [a b m])
+
+   (f {"a" 1 'b 2})  ;;=> [1 2 {"a" 1 'b 2}]
+
+.. note::
+
+   The keys for the ``:strs`` construct must be convertible to valid Basilisp symbols.
+
+It is possible to bind namespaced keys directly using either namespaced individual keys or a namespaced version of ``:keys`` as ``:ns/keys``.
+Values will be bound to the symbol by their *name* only (as by :lpy:fn:`name`) -- the namespace is only used for lookup in the associative data structure.
+
+.. code-block::
+
+   (let [{a :a b :a/b :c/keys [c d]} {:a   "a"
+                                      :b   "b"
+                                      :a/a "aa"
+                                      :a/b "bb"
+                                      :c/c "cc"
+                                      :c/d "dd"}]
+     [a b c d])
+   ;;=> ["a" "bb" "cc" "dd"]
+
+.. _keyword_arguments:
+
+Keyword Arguments
+^^^^^^^^^^^^^^^^^
+
+Basilisp functions can be defined with support for keyword arguments by defining the "rest" argument in an :lpy:fn:`defn` or :lpy:fn:`fn` form with associative destructuring.
+Callers can pass interleaved key/value pairs as positional arguments to the function and they will be collected into a single map argument which can be destructured.
+If a single trailing map argument is passed by callers (instead of or in addition to other key/value pairs), that value will be joined into the final map.
+
+.. code-block::
+
+   (defn f [& {:keys [a b] :as kwargs}]
+     [a b kwargs])
+
+   (f :a 1 :b 2)    ;;=> [1 2 {:a 1 :b 2}]
+   (f :a 1 {:b 2})  ;;=> [1 2 {:a 1 :b 2}]
+   (f {:a 1 :b 2})  ;;=> [1 2 {:a 1 :b 2}]
+
+.. note::
+
+   Basilisp keyword arguments are distinct from Python keyword arguments.
+   Basilisp functions can be :ref:`defined with Python compatible keyword arguments <basilisp_functions_with_kwargs>` but the style described here is intended primarily for Basilisp functions called only by other Basilisp functions.
+
+.. warning::
+
+   The trailing map passed to functions accepting keyword arguments will silently overwrite values passed positionally.
+   Callers should take care when using the trailing map calling convention.
+
+   .. code-block::
+
+      (defn f [& {:keys [a b] :as kwargs}]
+        [a b kwargs])
+
+      (f :a 1 {:b 2 :a 3})
+      ;;=> [3 2 {:a 3 :b 2}]
+
+.. _nested_destructuring:
+
+Nested Destructuring
+^^^^^^^^^^^^^^^^^^^^
+
+Both associative and sequential destructuring binding forms may be nested within one another.
+
+.. code-block::
+
+   (let [[{:keys [a] [e f] :d} [b c]] [{:a 1 :d [4 5]} [:b :c]]]
+     [a b c e f])
+   ;;=> [1 :b :c 4 5]
 
 .. _references_and_refs:
 
@@ -71,6 +219,8 @@ TBD
 Transducers
 -----------
 
+TBD
+
 .. _hierarchies:
 
 Hierarchies

docs/pyinterop.rst

@@ -147,7 +147,7 @@ For properties which are explicitly *not* read only, you can mutate their value
    In most cases, Basilisp's method and property access features should be sufficient.
    However, in case it is not, Python's :ref:`builtins <python_builtins>` such as `getattr` and `setattr` are still available and can supplement Basilisp's interoperability features.
 
-.. _keyword_arguments:
+.. _py_interop_keyword_arguments:
 
 Keyword Arguments
 -----------------
@@ -185,7 +185,7 @@ For functions which do support keyword arguments, two strategies are supported f
 
 .. note::
 
-   Basilisp functions support a variant of keyword arguments via destructuring support provided by ``fn`` and ``defn``.
+   Basilisp functions support a variant of :ref:`keyword_arguments` via destructuring support provided by ``fn`` and ``defn``.
    The ``:apply`` strategy relies on that style of keyword argument support to idiomatically integrate with Basilisp functions.
 
 .. code-block:: clojure
@@ -196,7 +196,7 @@ For functions which do support keyword arguments, two strategies are supported f
 
 The ``:apply`` strategy is appropriate in situations where there are few or no positional arguments defined on your function.
 With this strategy, the compiler converts the Python dict of string keys and values into a sequential stream of de-munged keyword and value pairs which are applied to the function.
-As you can see in the example above, this strategy fits neatly with the existing support for destructuring key and value pairs from rest arguments in a function definition.
+As you can see in the example above, this strategy fits neatly with the existing support for :ref:`destructuring` key and value pairs from rest arguments in a function definition.
 
 .. warning::
 
@@ -210,7 +210,7 @@ As you can see in the example above, this strategy fits neatly with the existing
 
 The ``:collect`` strategy is a better accompaniment to functions with positional arguments.
 With this strategy, Python keyword arguments are converted into a Basilisp map with de-munged keyword arguments and passed as the final positional argument of the function.
-You can use map destructuring on this final positional argument, just as you would with the map in the ``:apply`` case above.
+You can use :ref:`associative_destructuring` on this final positional argument, just as you would with the map in the ``:apply`` case above.
 
 Type Hinting
 ------------

docs/reader.rst

@@ -150,7 +150,7 @@ String literals are always read with the UTF-8 encoding.
 String literals may contain the following escape sequences: ``\\``, ``\a``, ``\b``, ``\f``, ``\n``, ``\r``, ``\t``, ``\v``.
 Their meanings match the equivalent escape sequences supported in `Python string literals <https://docs.python.org/3/reference/lexical_analysis.html#string-and-bytes-literals>`_\.
 
-.. _byte_strings
+.. _byte_strings:
 
 Byte Strings
 ------------