From 3f3cce8785c8d11c711d6429a472bbe646512a35 Mon Sep 17 00:00:00 2001 From: Kodi Arfer Date: Wed, 19 Jul 2017 11:00:43 -0700 Subject: [PATCH] Update docs: `apply` is gone; #* and #** are in --- docs/language/api.rst | 96 +++++++++++++++++++++++------------------- docs/language/core.rst | 4 +- docs/tutorial.rst | 19 +++------ 3 files changed, 59 insertions(+), 60 deletions(-) diff --git a/docs/language/api.rst b/docs/language/api.rst index 5241b3a..3904e86 100644 --- a/docs/language/api.rst +++ b/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 ------- diff --git a/docs/language/core.rst b/docs/language/core.rst index 21c111b..4983af9 100644 --- a/docs/language/core.rst +++ b/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: diff --git a/docs/tutorial.rst b/docs/tutorial.rst index ceeab77..3883abe 100644 --- a/docs/tutorial.rst +++ b/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