NEWS and docs for hashstrings

This commit is contained in:
Kodi Arfer 2017-09-08 11:26:59 -07:00
parent deb801edab
commit 0c229ebda5
3 changed files with 40 additions and 11 deletions

2
NEWS
View File

@ -10,6 +10,8 @@ Changes from 0.13.0
longer names
* Periods are no longer allowed in keywords
* `eval` is now a function instead of a special form
* Added a form of string literal called "bracket strings" delimited by
`#[FOO[` and `]FOO]`, where `FOO` is customizable
* The compiler now automatically promotes values to Hy model objects
as necessary, so you can write ``(eval `(+ 1 ~n))`` instead of
``(eval `(+ 1 ~(HyInteger n)))``

View File

@ -58,20 +58,41 @@ Unlike Python, Hy provides literal forms for NaN and infinity: ``NaN``,
string literals
---------------
Unlike Python, Hy allows only double-quoted strings (e.g., ``"hello"``). The
single-quote character ``'`` is reserved for preventing the evaluation of a
form (e.g., ``'(+ 1 1)``), as in most Lisps.
Hy allows double-quoted strings (e.g., ``"hello"``), but not single-quoted
strings like Python. The single-quote character ``'`` is reserved for
preventing the evaluation of a form (e.g., ``'(+ 1 1)``), as in most Lisps.
Python's so-called triple-quoted strings (e.g., ``'''hello'''`` and
``"""hello"""``) aren't supported. However, in Hy, unlike Python, any string
literal can contain newlines.
literal can contain newlines. Furthermore, Hy supports an alternative form of
string literal called a "bracket string" similar to Lua's long brackets.
Bracket strings have customizable delimiters, like the here-documents of other
languages. A bracket string begins with ``#[FOO[`` and ends with ``]FOO]``,
where ``FOO`` is any string not containing ``[`` or ``]``, including the empty
string. For example::
Whether running under Python 2 or Python 3, Hy treats string literals as
sequences of Unicode characters by default, and allows you to prefix a literal
with ``b`` to treat it as a sequence of bytes. So when running under Python 3,
Hy translates ``"foo"`` and ``b"foo"`` to the identical Python code, but when
running under Python 2, ``"foo"`` is translated to ``u"foo"`` and ``b"foo"`` is
translated to ``"foo"``.
=> (print #[["That's very kind of yuo [sic]" Tom wrote back.]])
"That's very kind of yuo [sic]" Tom wrote back.
=> (print #[==[1 + 1 = 2]==])
1 + 1 = 2
A bracket string can contain newlines, but if it begins with one, the newline
is removed, so you can begin the content of a bracket string on the line
following the opening delimiter with no effect on the content. Any leading
newlines past the first are preserved.
Plain string literals support :ref:`a variety of backslash escapes
<py:strings>`. To create a "raw string" that interprets all backslashes
literally, prefix the string with ``r``, as in ``r"slash\not"``. Bracket
strings are always raw strings and don't allow the ``r`` prefix.
Whether running under Python 2 or Python 3, Hy treats all string literals as
sequences of Unicode characters by default, and allows you to prefix a plain
string literal (but not a bracket string) with ``b`` to treat it as a sequence
of bytes. So when running under Python 3, Hy translates ``"foo"`` and
``b"foo"`` to the identical Python code, but when running under Python 2,
``"foo"`` is translated to ``u"foo"`` and ``b"foo"`` is translated to
``"foo"``.
.. _syntax-keywords:

View File

@ -102,7 +102,7 @@ HyString
~~~~~~~~
``hy.models.HyString`` is the base class of string-equivalent Hy
models. It also represents double-quoted string literals, ``""``, which
models. It also represents string literals (including bracket strings), which
compile down to unicode string literals in Python. ``HyStrings`` inherit
unicode objects in Python 2, and string objects in Python 3 (and are
therefore not encoding-dependent).
@ -113,6 +113,12 @@ Hy literal strings can span multiple lines, and are considered by the
parser as a single unit, respecting the Python escapes for unicode
strings.
``HyString``\s have an attribute ``brackets`` that stores the custom
delimiter used for a bracket string (e.g., ``"=="`` for ``#[==[hello
world]==]`` and the empty string for ``#[[hello world]]``).
``HyString``\s that are not produced by bracket strings have their
``brackets`` set to ``None``.
HyBytes
~~~~~~~