add heredocs to Hy

[gilch]

It would be nice if Hy had something like doctests, see #1019. It would also be nice to auto-generate reference docs from our docstrings, see #1040.

Doctests are only feasible in Python because of triple quotes. Hy doesn't have Python's triple quotes. It can do multi-line strings, but quotation marks must be escaped. (I had already complained about this a bit in #831.) Python can even have triple quotes inside triple quotes because ''' and """ both work. Raw strings with quotes inside can (and do) potentially happen with regexes, so escaping the occasional quotation mark isn't really good enough. Python has raw triple quotes r''' and r""" for this. Triple quotes are a good solution.

But they might not be such a good fit for Hy. We're already using ' for something else and you need both ''' and """ to make triple quotes work well. Hy's string literal capabilities are weaker than Python's, but I think we can do even better than triple quotes.

I propose we add heredocs to Hy's reader. This lets you specify an arbitrary terminator for your string. Racket Scheme and many other languages have this feature. Common Lisp has reader macros powerful enough to do it, but Hy doesn't. We'd have to build it in.

Heredocs could give us doctests, auto-generated reference docs, better regex support, and 80% of what Common Lisp reader macros can do, for e.g. DSL's (with the limitation that you have to wrap it in custom delimiters).

[gilch]

Heredocs usually require a newline at the end of the opening delimiter. This includes Racket's here strings. For a docstring this is what you want. For a short regex, maybe not. Other possibilities to consider are Lua's long brackets, which can do both. (Long brackets can be as long as you want.)

[[
spam]] -- same as "spam" (ignores first char if it's a "\n")
[=[
[[spam]] ]=] -- same as "[[spam]] "
[==[ [=[[["spam"]]]=] ]==] -- same as " [=[[[\"spam\"]]]=] " etc. 

And C++11's raw strings, which let you pick arbitrary delimiters in between the quote and parens.

R"foo(spam)foo" // same as "spam"
R"bar(R"foo(spam)foo")bar" // same as "R\"foo(spam)foo\""