Update docs: apply is gone; #* and #** are in

docs/language/api.rst

@@ -154,41 +154,6 @@ it appends it as the last argument. The following code demonstrates this:
     5 10
 
 
-apply
------
-
-``apply`` is used to apply an optional list of arguments and an
-optional dictionary of kwargs to a function. The symbol mangling
-transformations will be applied to all keys in the dictionary of
-kwargs, provided the dictionary and its keys are defined in-place.
-
-Usage: ``(apply fn-name [args] [kwargs])``
-
-Examples:
-
-.. code-block:: clj
-
-    (defn thunk []
-      "hy there")
-
-    (apply thunk)
-    ;=> "hy there"
-
-    (defn total-purchase [price amount &optional [fees 1.05] [vat 1.1]]
-      (* price amount fees vat))
-
-    (apply total-purchase [10 15])
-    ;=> 173.25
-
-    (apply total-purchase [10 15] {"vat" 1.05})
-    ;=> 165.375
-
-    (apply total-purchase [] {"price" 10 "amount" 15 "vat" 1.05})
-    ;=> 165.375
-
-    (apply total-purchase [] {:price 10 :amount 15 :vat 1.05})
-    ;=> 165.375
-
 and
 ---
 
@@ -596,8 +561,8 @@ Parameters may have the following keywords in front of them:
         parameter_1 1
         parameter_2 2
 
-        ; to avoid the mangling of '-' to '_', use apply:
-        => (apply print-parameters [] {"parameter-1" 1 "parameter-2" 2})
+        ; to avoid the mangling of '-' to '_', use unpacking:
+        => (print-parameters #** {"parameter-1" 1 "parameter-2" 2})
         parameter-1 1
         parameter-2 2
 
@@ -634,19 +599,19 @@ Parameters may have the following keywords in front of them:
 
     .. code-block:: clj
 
-        => (defn compare [a b &kwonly keyfn [reverse false]]
+        => (defn compare [a b &kwonly keyfn [reverse False]]
         ...  (setv result (keyfn a b))
         ...  (if (not reverse)
         ...    result
         ...    (- result)))
-        => (apply compare ["lisp" "python"]
-        ...        {"keyfn" (fn [x y]
-        ...                   (reduce - (map (fn [s] (ord (first s))) [x y])))})
+        => (compare "lisp" "python"
+        ...         :keyfn (fn [x y]
+        ...                  (reduce - (map (fn [s] (ord (first s))) [x y]))))
         -4
-        => (apply compare ["lisp" "python"]
-        ...        {"keyfn" (fn [x y]
+        => (compare "lisp" "python"
+        ...         :keyfn (fn [x y]
         ...                   (reduce - (map (fn [s] (ord (first s))) [x y])))
-        ...         "reverse" True})
+        ...         :reverse True)
         4
 
     .. code-block:: python
@@ -1576,6 +1541,49 @@ the given conditional is ``False``. The following shows the expansion of this ma
       (do statement))
 
 
+unpack-iterable, unpack-mapping
+-------------------------------
+
+``unpack-iterable`` and ``unpack-mapping`` allow an iterable or mapping
+object (respectively) to provide positional or keywords arguments
+(respectively) to a function.
+
+.. code-block:: clj
+
+    => (defn f [a b c d] [a b c d])
+    => (f (unpack-iterable [1 2]) (unpack-mapping {"c" 3 "d" 4}))
+    [1, 2, 3, 4]
+
+``unpack-iterable`` is usually written with the shorthand ``#*``, and
+``unpack-mapping`` with ``#**``.
+
+.. code-block:: clj
+
+    => (f #* [1 2] #** {"c" 3 "d" 4})
+    [1, 2, 3, 4]
+
+With Python 3, you can unpack in an assignment list (:pep:`3132`).
+
+.. code-block:: clj
+
+    => (setv [a #* b c] [1 2 3 4 5])
+    => [a b c]
+    [1, [2, 3, 4], 5]
+
+With Python 3.5 or greater, unpacking is allowed in more contexts than just
+function calls, and you can unpack more than once in the same expression
+(:pep:`448`).
+
+.. code-block:: clj
+
+    => [#* [1 2] #* [3 4]]
+    [1, 2, 3, 4]
+    => {#** {1 2} #** {3 4}}
+    {1: 2, 3: 4}
+    => (f #* [1] #* [2] #** {"c" 3} #** {"d" 4})
+    [1, 2, 3, 4]
+
+
 unquote
 -------
 

docs/language/core.rst

@@ -1216,9 +1216,9 @@ if *from-file* ends before a complete expression can be parsed.
 
    => (import io)
    => (def buffer (io.StringIO "(+ 2 2)\n(- 2 1)"))
-   => (eval (apply read [] {"from_file" buffer}))
+   => (eval (read :from_file buffer))
    4
-   => (eval (apply read [] {"from_file" buffer}))
+   => (eval (read :from_file buffer))
    1
 
    => ; assuming "example.hy" contains:

docs/tutorial.rst

@@ -423,8 +423,7 @@ The same thing in Hy::
   => (optional-arg 1 2 3 4)
   [1 2 3 4]
 
-If you're running a version of Hy past 0.10.1 (eg, git master),
-there's also a nice new keyword argument syntax::
+You can call keyword arguments like this::
 
   => (optional-arg :keyword1 1
   ...              :pos2 2
@@ -432,21 +431,13 @@ there's also a nice new keyword argument syntax::
   ...              :keyword2 4)
   [3, 2, 1, 4]
 
-Otherwise, you can always use `apply`.  But what's `apply`?
-
-Are you familiar with passing in `*args` and `**kwargs` in Python?::
-
-  >>> args = [1 2]
-  >>> kwargs = {"keyword2": 3
-  ...           "keyword1": 4}
-  >>> optional_arg(*args, **kwargs)
-
-We can reproduce this with `apply`::
+You can unpack arguments with the syntax ``#* args`` and ``#** kwargs``,
+similar to `*args` and `**kwargs` in Python::
 
   => (setv args [1 2])
   => (setv kwargs {"keyword2" 3
   ...              "keyword1" 4})
-  => (apply optional-arg args kwargs)
+  => (optional-arg #* args #** kwargs)
   [1, 2, 4, 3]
 
 There's also a dictionary-style keyword arguments construction that
@@ -460,7 +451,7 @@ looks like:
 The difference here is that since it's a dictionary, you can't rely on
 any specific ordering to the arguments.
 
-Hy also supports ``*args`` and ``**kwargs``.  In Python::
+Hy also supports ``*args`` and ``**kwargs`` in parameter lists.  In Python::
 
   def some_func(foo, bar, *args, **kwargs):
     import pprint