diff --git a/NEWS b/NEWS index 2c52152..e4d92ed 100644 --- a/NEWS +++ b/NEWS @@ -13,6 +13,8 @@ Changes from 0.13.0 ``(eval `(+ 1 ~(HyInteger n)))`` * Literal `Inf`s and `NaN`s must now be capitalized like that * `get` is available as a function + * new `comment` macro + * support EDN `#_` syntax to discard the next term [ Bug Fixes ] * Numeric literals are no longer parsed as symbols when followed by a dot diff --git a/docs/language/api.rst b/docs/language/api.rst index 3904e86..1f223f0 100644 --- a/docs/language/api.rst +++ b/docs/language/api.rst @@ -89,6 +89,31 @@ the error ``Keyword argument :foo needs a value``. To avoid this, you can quote the keyword, as in ``(f ':foo)``, or use it as the value of another keyword argument, as in ``(f :arg :foo)``. +discard prefix +-------------- + +Hy supports the Extensible Data Notation discard prefix, like Clojure. +Any form prefixed with ``#_`` is discarded instead of compiled. +This completely removes the form so it doesn't evaluate to anything, +not even None. +It's often more useful than linewise comments for commenting out a +form, because it respects code structure even when part of another +form is on the same line. For example: + +.. code-block:: clj + + => (print "Hy" "cruel" "World!") + Hy cruel World! + => (print "Hy" #_"cruel" "World!") + Hy World! + => (+ 1 1 (print "Math is hard!")) + Math is hard! + Traceback (most recent call last): + ... + TypeError: unsupported operand type(s) for +: 'int' and 'NoneType' + => (+ 1 1 #_(print "Math is hard!")) + 2 + Built-Ins ========= @@ -328,6 +353,30 @@ as the user enters *k*. (print "Try again"))) +comment +---- + +The ``comment`` macro ignores its body and always expands to ``None``. +Unlike linewise comments, the body of the ``comment`` macro must +be grammatically valid Hy, so the compiler can tell where the comment ends. +Besides the semicolon linewise comments, +Hy also has the ``#_`` discard prefix syntax to discard the next form. +This is completely discarded and doesn't expand to anything, not even ``None``. + +.. code-block:: clj + + => (print (comment
You'd be surprised what's grammatically valid in Hy.
+ ...(Keep delimiters in balance, and you're mostly good to go.)
) + ... "Hy") + None Hy + => (print #_(commentYou'd be surprised what's grammatically valid in Hy.
+ ...(Keep delimiters in balance, and you're mostly good to go.)
)) + ... "Hy") + Hy + + cond ----