Yaltik/hy
2
0
Fork 0
Code Pull Requests Releases Activity

update docs for new hy model reprs

Browse Source
This commit is contained in:
gilch 2017-08-25 22:50:13 -06:00 committed by Kodi Arfer
parent b23f6e5b59
commit af8d209496
4 changed files with 296 additions and 126 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

190
docs/contrib/walk.rst
View File

@ -22,12 +22,18 @@ Example:
.. code-block:: hy .. code-block:: hy
=> (import [hy.contrib.walk [walk]]) => (import [hy.contrib.walk [walk]])
=> (setv a '(a b c d e f)) => (setv a '(a b c d e f))
=> (walk ord identity a) => (walk ord identity a)
(97 98 99 100 101 102) HyExpression([
=> (walk ord first a) 97,
97 98,
99,
100,
101,
102])
=> (walk ord first a)
97
postwalk postwalk
--------- ---------
@ -41,25 +47,73 @@ each sub-form, uses ``f`` 's return value in place of the original.
.. code-block:: hy .. code-block:: hy
=> (import [hy.contrib.walk [postwalk]]) => (import [hy.contrib.walk [postwalk]])
=> (def trail '([1 2 3] [4 [5 6 [7]]])) => (def trail '([1 2 3] [4 [5 6 [7]]]))
=> (defn walking [x] => (defn walking [x]
(print "Walking:" x) ... (print "Walking:" x :sep "\n")
x ) ... x)
=> (postwalk walking trail) => (postwalk walking trail)
Walking: 1 Walking:
Walking: 2 1
Walking: 3 Walking:
Walking: (1 2 3) 2
Walking: 4 Walking:
Walking: 5 3
Walking: 6 Walking:
Walking: 7 HyExpression([
Walking: (7) HyInteger(1),
Walking: (5 6 [7]) HyInteger(2),
Walking: (4 [5 6 [7]]) HyInteger(3)])
Walking: ([1 2 3] [4 [5 6 [7]]]) Walking:
([1 2 3] [4 [5 6 [7]]]) 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 prewalk
-------- --------
@ -73,22 +127,70 @@ each sub-form, uses ``f`` 's return value in place of the original.
.. code-block:: hy .. code-block:: hy
=> (import [hy.contrib.walk [prewalk]]) => (import [hy.contrib.walk [prewalk]])
=> (def trail '([1 2 3] [4 [5 6 [7]]])) => (def trail '([1 2 3] [4 [5 6 [7]]]))
=> (defn walking [x] => (defn walking [x]
(print "Walking:" x) ... (print "Walking:" x :sep "\n")
x ) ... x)
=> (prewalk walking trail) => (prewalk walking trail)
Walking: ([1 2 3] [4 [5 6 [7]]]) Walking:
Walking: [1 2 3] HyExpression([
Walking: 1 HyList([
Walking: 2 HyInteger(1),
Walking: 3 HyInteger(2),
Walking: [4 [5 6 [7]]] HyInteger(3)]),
Walking: 4 HyList([
Walking: [5 6 [7]] HyInteger(4),
Walking: 5 HyList([
Walking: 6 HyInteger(5),
Walking: [7] HyInteger(6),
Walking: 7 HyList([
([1 2 3] [4 [5 6 [7]]]) 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)])])])])

56
docs/language/api.rst
View File

@ -869,7 +869,7 @@ doto
.. code-block:: clj .. code-block:: clj
=> (doto [] (.append 1) (.append 2) .reverse) => (doto [] (.append 1) (.append 2) .reverse)
[2 1] [2, 1]
.. code-block:: clj .. code-block:: clj
@ -878,7 +878,7 @@ doto
=> (.append collection 2) => (.append collection 2)
=> (.reverse collection) => (.reverse collection)
=> collection => collection
[2 1] [2, 1]
eval-and-compile eval-and-compile
@ -1362,9 +1362,10 @@ alternatively be written using the apostrophe (``'``) symbol.
.. code-block:: clj .. code-block:: clj
=> (setv x '(print "Hello World")) => (setv x '(print "Hello World"))
; variable x is set to expression & not evaluated => x ; varible x is set to unevaluated expression
=> x HyExpression([
(u'print' u'Hello World') HySymbol('print'),
HyString('Hello World')])
=> (eval x) => (eval x)
Hello World Hello World
@ -1673,12 +1674,17 @@ is aliased to the tilde (``~``) symbol.
.. code-block:: clj .. code-block:: clj
(def name "Cuddles") => (setv nickname "Cuddles")
(quasiquote (= name (unquote name))) => (quasiquote (= nickname (unquote nickname)))
;=> (u'=' u'name' u'Cuddles') HyExpression([
HySymbol('='),
`(= name ~name) HySymbol('nickname'),
;=> (u'=' u'name' u'Cuddles') 'Cuddles'])
=> `(= nickname ~nickname)
HyExpression([
HySymbol('='),
HySymbol('nickname'),
'Cuddles'])
unquote-splice unquote-splice
@ -1694,15 +1700,25 @@ into the form. ``unquote-splice`` is aliased to the ``~@`` syntax.
.. code-block:: clj .. code-block:: clj
(def nums [1 2 3 4]) => (setv nums [1 2 3 4])
(quasiquote (+ (unquote-splice nums))) => (quasiquote (+ (unquote-splice nums)))
;=> ('+' 1 2 3 4) HyExpression([
HySymbol('+'),
`(+ ~@nums) 1,
;=> ('+' 1 2 3 4) 2,
3,
`[1 2 ~@(if (< (nth nums 0) 0) nums)] 4])
;=> ('+' 1 2) => `(+ ~@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 Here, the last example evaluates to ``('+' 1 2)``, since the condition
``(< (nth nums 0) 0)`` is ``False``, which makes this ``if`` expression ``(< (nth nums 0) 0)`` is ``False``, which makes this ``if`` expression

167
docs/language/core.rst
View File

@ -618,17 +618,29 @@ arguments. If the argument list only has one element, return it.
.. code-block:: hy .. code-block:: hy
=> (list* 1 2 3 4) => (list* 1 2 3 4)
(1 2 3 . 4) <HyCons (
HyInteger(1)
=> (list* 1 2 3 [4]) HyInteger(2)
[1, 2, 3, 4] HyInteger(3)
. HyInteger(4))>
=> (list* 1) => (list* 1 2 3 [4])
1 [HyInteger(1), HyInteger(2), HyInteger(3), 4]
=> (list* 1)
=> (cons? (list* 1 2 3 4)) 1
True => (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 {})
<HyCons (
HyInteger(1)
HyInteger(10)
HyInteger(2)
HyInteger(20)
. HyDict())>
.. _macroexpand-fn: .. _macroexpand-fn:
@ -643,11 +655,23 @@ Returns the full macro expansion of *form*.
.. code-block:: hy .. code-block:: hy
=> (macroexpand '(-> (a b) (x y))) => (macroexpand '(-> (a b) (x y)))
(u'x' (u'a' u'b') u'y') HyExpression([
HySymbol('x'),
=> (macroexpand '(-> (a b) (-> (c d) (e f)))) HyExpression([
(u'e' (u'c' (u'a' u'b') u'd') u'f') 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: .. _macroexpand-1-fn:
@ -662,8 +686,18 @@ Returns the single step macro expansion of *form*.
.. code-block:: hy .. code-block:: hy
=> (macroexpand-1 '(-> (a b) (-> (c d) (e f)))) => (macroexpand-1 '(-> (a b) (-> (c d) (e f))))
(u'_>' (u'a' u'b') (u'c' u'd') (u'e' u'f')) HyExpression([
HySymbol('_>'),
HyExpression([
HySymbol('a'),
HySymbol('b')]),
HyExpression([
HySymbol('c'),
HySymbol('d')]),
HyExpression([
HySymbol('e'),
HySymbol('f')])])
.. _merge-with-fn: .. _merge-with-fn:
@ -839,26 +873,26 @@ Chunks *coll* into *n*-tuples (pairs by default).
.. code-block:: hy .. code-block:: hy
=> (list (partition (range 10))) ; n=2 => (list (partition (range 10))) ; n=2
[(, 0 1) (, 2 3) (, 4 5) (, 6 7) (, 8 9)] [(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. The *step* defaults to *n*, but can be more to skip elements, or less for a sliding window with overlap.
.. code-block:: hy .. code-block:: hy
=> (list (partition (range 10) 2 3)) => (list (partition (range 10) 2 3))
[(, 0 1) (, 3 4) (, 6 7)] [(0, 1), (3, 4), (6, 7)]
=> (list (partition (range 5) 2 1)) => (list (partition (range 5) 2 1))
[(, 0 1) (, 1 2) (, 2 3) (, 3 4)]) [(0, 1), (1, 2), (2, 3), (3, 4)]
The remainder, if any, is not included unless a *fillvalue* is specified. The remainder, if any, is not included unless a *fillvalue* is specified.
.. code-block:: hy .. code-block:: hy
=> (list (partition (range 10) 3)) => (list (partition (range 10) 3))
[(, 0 1 2) (, 3 4 5) (, 6 7 8)] [(0, 1, 2), (3, 4, 5), (6, 7, 8)]
=> (list (partition (range 10) 3 :fillvalue "x")) => (list (partition (range 10) 3 :fillvalue "x"))
[(, 0 1 2) (, 3 4 5) (, 6 7 8) (, 9 "x" "x")] [(0, 1, 2), (3, 4, 5), (6, 7, 8), (9, 'x', 'x')]
.. _pos?-fn: .. _pos?-fn:
@ -1220,36 +1254,43 @@ if *from-file* ends before a complete expression can be parsed.
.. code-block:: hy .. code-block:: hy
=> (read) => (read)
(+ 2 2) (+ 2 2)
('+' 2 2) HyExpression([
=> (eval (read)) HySymbol('+'),
(+ 2 2) HyInteger(2),
4 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
=> (import io) => (with [f (open "example.hy" "w")]
=> (def buffer (io.StringIO "(+ 2 2)\n(- 2 1)")) ... (.write f "(print 'hello)\n(print \"hyfriends!\")"))
=> (eval (read :from_file buffer)) 35
4 => (with [f (open "example.hy")]
=> (eval (read :from_file buffer)) ... (try (while True
1 ... (setv exp (read f))
... (print "OHY" exp)
=> ; assuming "example.hy" contains: ... (eval exp))
=> ; (print "hello") ... (except [e EOFError]
=> ; (print "hyfriends!") ... (print "EOF!"))))
=> (with [f (open "example.hy")] OHY HyExpression([
... (try HySymbol('print'),
... (while True HyExpression([
... (setv exp (read f)) HySymbol('quote'),
... (print "OHY" exp) HySymbol('hello')])])
... (eval exp)) hello
... (except [e EOFError] OHY HyExpression([
... (print "EOF!")))) HySymbol('print'),
OHY ('print' 'hello') HyString('hyfriends!')])
hello hyfriends!
OHY ('print' 'hyfriends!') EOF!
hyfriends!
EOF!
read-str read-str
-------- --------
@ -1261,11 +1302,12 @@ string:
.. code-block:: hy .. code-block:: hy
=> (read-str "(print 1)") => (read-str "(print 1)")
(u'print' 1L) HyExpression([
=> (eval (read-str "(print 1)")) HySymbol('print'),
1 HyInteger(1)])
=> => (eval (read-str "(print 1)"))
1
.. _remove-fn: .. _remove-fn:
@ -1409,3 +1451,4 @@ are available. Some of their names have been changed:
- ``dropwhile`` has been changed to ``drop-while`` - ``dropwhile`` has been changed to ``drop-while``
- ``filterfalse`` has been changed to ``remove`` - ``filterfalse`` has been changed to ``remove``

9
docs/language/internals.rst
View File

@ -39,6 +39,15 @@ Compound Models
Parenthesized and bracketed lists are parsed as compound models by the Parenthesized and bracketed lists are parsed as compound models by the
Hy parser. Hy parser.
Hy uses pretty-printing reprs for its compound models by default.
If this is causing issues,
it can be turned off globally by setting ``hy.models.PRETTY`` to ``False``,
or temporarily by using the ``hy.models.pretty`` context manager.
Hy also attempts to color pretty reprs using ``clint.textui.colored``.
This module has a flag to disable coloring,
and a method ``clean`` to strip colored strings of their color tags.
.. _hylist: .. _hylist:
HyList HyList