From 3c828570766bb3d143854818cc867fa194afbdb9 Mon Sep 17 00:00:00 2001 From: gilch Date: Fri, 25 Aug 2017 22:50:13 -0600 Subject: [PATCH] update docs for new hy model reprs --- docs/contrib/walk.rst | 181 +++++++++++++++++++++++++++++++---------- docs/language/api.rst | 51 +++++++----- docs/language/core.rst | 155 +++++++++++++++++++++-------------- 3 files changed, 260 insertions(+), 127 deletions(-) diff --git a/docs/contrib/walk.rst b/docs/contrib/walk.rst index 01e2bc022..f775f5a8a 100644 --- a/docs/contrib/walk.rst +++ b/docs/contrib/walk.rst @@ -22,12 +22,17 @@ Example: .. code-block:: hy - => (import [hy.contrib.walk [walk]]) - => (setv a '(a b c d e f)) - => (walk ord identity a) - (97 98 99 100 101 102) - => (walk ord first a) - 97 + => (import [hy.contrib.walk [walk]]) + => (setv a '(a b c d e f)) + => (walk ord identity a) + HyExpression([ 97, + 98, + 99, + 100, + 101, + 102]) + => (walk ord first a) + 97 postwalk --------- @@ -41,25 +46,67 @@ each sub-form, uses ``f`` 's return value in place of the original. .. code-block:: hy - => (import [hy.contrib.walk [postwalk]]) - => (def trail '([1 2 3] [4 [5 6 [7]]])) - => (defn walking [x] - (print "Walking:" x) - x ) - => (postwalk walking trail) - Walking: 1 - Walking: 2 - Walking: 3 - Walking: (1 2 3) - Walking: 4 - Walking: 5 - Walking: 6 - Walking: 7 - Walking: (7) - Walking: (5 6 [7]) - Walking: (4 [5 6 [7]]) - Walking: ([1 2 3] [4 [5 6 [7]]]) - ([1 2 3] [4 [5 6 [7]]]) + => (import [hy.contrib.walk [postwalk]]) + => (def trail '([1 2 3] [4 [5 6 [7]]])) + => (defn walking [x] + ... (print "Walking:" x :sep "\n") + ... x) + => (postwalk walking trail) + Walking: + 1 + Walking: + 2 + Walking: + 3 + Walking: + HyExpression([ HyInteger(1), + HyInteger(2), + HyInteger(3)]) + Walking: + 4 + Walking: + 5 + Walking: + 6 + Walking: + 7 + Walking: + HyExpression([ HyInteger(7)]) + Walking: + HyExpression([ HyInteger(5), + HyInteger(6), + HyList([ + HyInteger(7)])]) + Walking: + HyExpression([ HyInteger(4), + HyList([ + HyInteger(5), + HyInteger(6), + HyList([ + HyInteger(7)])])]) + Walking: + HyExpression([ HyList([ + HyInteger(1), + HyInteger(2), + HyInteger(3)]), + HyList([ + HyInteger(4), + HyList([ + HyInteger(5), + HyInteger(6), + HyList([ + HyInteger(7)])])])]) + HyExpression([ HyList([ + HyInteger(1), + HyInteger(2), + HyInteger(3)]), + HyList([ + HyInteger(4), + HyList([ + HyInteger(5), + HyInteger(6), + HyList([ + HyInteger(7)])])])]) prewalk -------- @@ -73,22 +120,68 @@ each sub-form, uses ``f`` 's return value in place of the original. .. code-block:: hy - => (import [hy.contrib.walk [prewalk]]) - => (def trail '([1 2 3] [4 [5 6 [7]]])) - => (defn walking [x] - (print "Walking:" x) - x ) - => (prewalk walking trail) - Walking: ([1 2 3] [4 [5 6 [7]]]) - Walking: [1 2 3] - Walking: 1 - Walking: 2 - Walking: 3 - Walking: [4 [5 6 [7]]] - Walking: 4 - Walking: [5 6 [7]] - Walking: 5 - Walking: 6 - Walking: [7] - Walking: 7 - ([1 2 3] [4 [5 6 [7]]]) + => (import [hy.contrib.walk [prewalk]]) + => (def trail '([1 2 3] [4 [5 6 [7]]])) + => (defn walking [x] + ... (print "Walking:" x :sep "\n") + ... x) + => (prewalk walking trail) + Walking: + HyExpression([ HyList([ + HyInteger(1), + HyInteger(2), + HyInteger(3)]), + HyList([ + HyInteger(4), + HyList([ + HyInteger(5), + HyInteger(6), + HyList([ + HyInteger(7)])])])]) + Walking: + HyList([ + HyInteger(1), + HyInteger(2), + HyInteger(3)]) + Walking: + 1 + Walking: + 2 + Walking: + 3 + Walking: + HyList([ + HyInteger(4), + HyList([ + HyInteger(5), + HyInteger(6), + HyList([ + HyInteger(7)])])]) + Walking: + 4 + Walking: + HyList([ + HyInteger(5), + HyInteger(6), + HyList([ + HyInteger(7)])]) + Walking: + 5 + Walking: + 6 + Walking: + HyList([ + HyInteger(7)]) + Walking: + 7 + HyExpression([ HyList([ + HyInteger(1), + HyInteger(2), + HyInteger(3)]), + HyList([ + HyInteger(4), + HyList([ + HyInteger(5), + HyInteger(6), + HyList([ + HyInteger(7)])])])]) diff --git a/docs/language/api.rst b/docs/language/api.rst index b1a3e1d0a..544dac890 100644 --- a/docs/language/api.rst +++ b/docs/language/api.rst @@ -869,7 +869,7 @@ doto .. code-block:: clj => (doto [] (.append 1) (.append 2) .reverse) - [2 1] + [2, 1] .. code-block:: clj @@ -878,7 +878,7 @@ doto => (.append collection 2) => (.reverse collection) => collection - [2 1] + [2, 1] eval-and-compile @@ -1362,9 +1362,9 @@ alternatively be written using the apostrophe (``'``) symbol. .. code-block:: clj => (setv x '(print "Hello World")) - ; variable x is set to expression & not evaluated - => x - (u'print' u'Hello World') + => x ; varible x is set to unevaluated expression + HyExpression([ HySymbol('print'), + HyString('Hello World')]) => (eval x) Hello World @@ -1673,12 +1673,15 @@ is aliased to the tilde (``~``) symbol. .. code-block:: clj - (def name "Cuddles") - (quasiquote (= name (unquote name))) - ;=> (u'=' u'name' u'Cuddles') - - `(= name ~name) - ;=> (u'=' u'name' u'Cuddles') + => (setv nickname "Cuddles") + => (quasiquote (= nickname (unquote nickname))) + HyExpression([ HySymbol('='), + HySymbol('nickname'), + 'Cuddles']) + => `(= nickname ~nickname) + HyExpression([ HySymbol('='), + HySymbol('nickname'), + 'Cuddles']) unquote-splice @@ -1694,15 +1697,23 @@ into the form. ``unquote-splice`` is aliased to the ``~@`` syntax. .. code-block:: clj - (def nums [1 2 3 4]) - (quasiquote (+ (unquote-splice nums))) - ;=> ('+' 1 2 3 4) - - `(+ ~@nums) - ;=> ('+' 1 2 3 4) - - `[1 2 ~@(if (< (nth nums 0) 0) nums)] - ;=> ('+' 1 2) + => (setv nums [1 2 3 4]) + => (quasiquote (+ (unquote-splice nums))) + HyExpression([ HySymbol('+'), + 1, + 2, + 3, + 4]) + => `(+ ~@nums) + HyExpression([ HySymbol('+'), + 1, + 2, + 3, + 4]) + => `[1 2 ~@(if (neg? (first nums)) nums)] + HyList([ + HyInteger(1), + HyInteger(2)]) Here, the last example evaluates to ``('+' 1 2)``, since the condition ``(< (nth nums 0) 0)`` is ``False``, which makes this ``if`` expression diff --git a/docs/language/core.rst b/docs/language/core.rst index d5b1cef6b..b61f6fb82 100644 --- a/docs/language/core.rst +++ b/docs/language/core.rst @@ -618,17 +618,29 @@ arguments. If the argument list only has one element, return it. .. code-block:: hy - => (list* 1 2 3 4) - (1 2 3 . 4) - - => (list* 1 2 3 [4]) - [1, 2, 3, 4] - - => (list* 1) - 1 - - => (cons? (list* 1 2 3 4)) - True + => (list* 1 2 3 4) + + => (list* 1 2 3 [4]) + [HyInteger(1), HyInteger(2), HyInteger(3), 4] + => (list* 1) + 1 + => (cons? (list* 1 2 3 4)) + True + => (list* 1 10 2 20 '{}) + HyDict([ + HyInteger(1), HyInteger(10), + HyInteger(2), HyInteger(20),]) + => (list* 1 10 2 20 {}) + .. _macroexpand-fn: @@ -643,11 +655,18 @@ Returns the full macro expansion of *form*. .. code-block:: hy - => (macroexpand '(-> (a b) (x y))) - (u'x' (u'a' u'b') u'y') - - => (macroexpand '(-> (a b) (-> (c d) (e f)))) - (u'e' (u'c' (u'a' u'b') u'd') u'f') + => (macroexpand '(-> (a b) (x y))) + HyExpression([ HySymbol('x'), + HyExpression([ HySymbol('a'), + HySymbol('b')]), + HySymbol('y')]) + => (macroexpand '(-> (a b) (-> (c d) (e f)))) + HyExpression([ HySymbol('e'), + HyExpression([ HySymbol('c'), + HyExpression([ HySymbol('a'), + HySymbol('b')]), + HySymbol('d')]), + HySymbol('f')]) .. _macroexpand-1-fn: @@ -662,8 +681,14 @@ Returns the single step macro expansion of *form*. .. code-block:: hy - => (macroexpand-1 '(-> (a b) (-> (c d) (e f)))) - (u'_>' (u'a' u'b') (u'c' u'd') (u'e' u'f')) + => (macroexpand-1 '(-> (a b) (-> (c d) (e f)))) + HyExpression([ HySymbol('_>'), + HyExpression([ HySymbol('a'), + HySymbol('b')]), + HyExpression([ HySymbol('c'), + HySymbol('d')]), + HyExpression([ HySymbol('e'), + HySymbol('f')])]) .. _merge-with-fn: @@ -839,26 +864,26 @@ Chunks *coll* into *n*-tuples (pairs by default). .. code-block:: hy - => (list (partition (range 10))) ; n=2 - [(, 0 1) (, 2 3) (, 4 5) (, 6 7) (, 8 9)] + => (list (partition (range 10))) ; n=2 + [(0, 1), (2, 3), (4, 5), (6, 7), (8, 9)] The *step* defaults to *n*, but can be more to skip elements, or less for a sliding window with overlap. .. code-block:: hy - => (list (partition (range 10) 2 3)) - [(, 0 1) (, 3 4) (, 6 7)] - => (list (partition (range 5) 2 1)) - [(, 0 1) (, 1 2) (, 2 3) (, 3 4)]) + => (list (partition (range 10) 2 3)) + [(0, 1), (3, 4), (6, 7)] + => (list (partition (range 5) 2 1)) + [(0, 1), (1, 2), (2, 3), (3, 4)] The remainder, if any, is not included unless a *fillvalue* is specified. .. code-block:: hy - => (list (partition (range 10) 3)) - [(, 0 1 2) (, 3 4 5) (, 6 7 8)] - => (list (partition (range 10) 3 :fillvalue "x")) - [(, 0 1 2) (, 3 4 5) (, 6 7 8) (, 9 "x" "x")] + => (list (partition (range 10) 3)) + [(0, 1, 2), (3, 4, 5), (6, 7, 8)] + => (list (partition (range 10) 3 :fillvalue "x")) + [(0, 1, 2), (3, 4, 5), (6, 7, 8), (9, 'x', 'x')] .. _pos?-fn: @@ -1220,36 +1245,39 @@ if *from-file* ends before a complete expression can be parsed. .. code-block:: hy - => (read) - (+ 2 2) - ('+' 2 2) - => (eval (read)) - (+ 2 2) - 4 - - => (import io) - => (def buffer (io.StringIO "(+ 2 2)\n(- 2 1)")) - => (eval (read :from_file buffer)) - 4 - => (eval (read :from_file buffer)) - 1 - - => ; assuming "example.hy" contains: - => ; (print "hello") - => ; (print "hyfriends!") - => (with [f (open "example.hy")] - ... (try - ... (while True - ... (setv exp (read f)) - ... (print "OHY" exp) - ... (eval exp)) - ... (except [e EOFError] - ... (print "EOF!")))) - OHY ('print' 'hello') - hello - OHY ('print' 'hyfriends!') - hyfriends! - EOF! + => (read) + (+ 2 2) + HyExpression([ HySymbol('+'), + HyInteger(2), + HyInteger(2)]) + => (eval (read)) + (+ 2 2) + 4 + => (import io) + => (setv buffer (io.StringIO "(+ 2 2)\n(- 2 1)")) + => (eval (read :from_file buffer)) + 4 + => (eval (read :from_file buffer)) + 1 + + => (with [f (open "example.hy" "w")] + ... (.write f "(print 'hello)\n(print \"hyfriends!\")")) + 35 + => (with [f (open "example.hy")] + ... (try (while True + ... (setv exp (read f)) + ... (print "OHY" exp) + ... (eval exp)) + ... (except [e EOFError] + ... (print "EOF!")))) + OHY HyExpression([ HySymbol('print'), + HyExpression([ HySymbol('quote'), + HySymbol('hello')])]) + hello + OHY HyExpression([ HySymbol('print'), + HyString('hyfriends!')]) + hyfriends! + EOF! read-str -------- @@ -1261,11 +1289,11 @@ string: .. code-block:: hy - => (read-str "(print 1)") - (u'print' 1L) - => (eval (read-str "(print 1)")) - 1 - => + => (read-str "(print 1)") + HyExpression([ HySymbol('print'), + HyInteger(1)]) + => (eval (read-str "(print 1)")) + 1 .. _remove-fn: @@ -1409,3 +1437,4 @@ are available. Some of their names have been changed: - ``dropwhile`` has been changed to ``drop-while`` - ``filterfalse`` has been changed to ``remove`` +