From 0c229ebda5ae6a32f99e7f858a05f43d51c73867 Mon Sep 17 00:00:00 2001
From: Kodi Arfer <git@arfer.net>
Date: Fri, 8 Sep 2017 11:26:59 -0700
Subject: [PATCH] NEWS and docs for hashstrings

---
 NEWS                        |  2 ++
 docs/language/api.rst       | 41 ++++++++++++++++++++++++++++---------
 docs/language/internals.rst |  8 +++++++-
 3 files changed, 40 insertions(+), 11 deletions(-)

diff --git a/NEWS b/NEWS
index 3e23f66..a4c307a 100644
--- a/NEWS
+++ b/NEWS
@@ -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)))``
diff --git a/docs/language/api.rst b/docs/language/api.rst
index b051565..ed789eb 100644
--- a/docs/language/api.rst
+++ b/docs/language/api.rst
@@ -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:
 
diff --git a/docs/language/internals.rst b/docs/language/internals.rst
index bf2f4f0..ffd3844 100644
--- a/docs/language/internals.rst
+++ b/docs/language/internals.rst
@@ -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
 ~~~~~~~