Alternate string quote syntaxes

Alternate string quote syntaxes

Motivation

• docstrings with examples could be more human readable

• XML, JSON or SQL generation tests become filled with escaped quotes

• pasting JSON into a string, which could then easily have `read-json` called on it
• Writing doc strings which contain usage examples is often tedious if the example contains strings.

Possible Solutions

Python-like triple quoted strings

Pros:

• Relatively simple syntax, for humans and parsers
• Has already been implemented
• Would work nicely for docstrings.
  • (defn foo """my docstring""" [x] ...)

Cons:

• Minor breaking change - """""" which is  3 empty strings would now be interpreted as only one empty string
• Have to add reader macro
• Breaking change to every other tool that reads Clojure syntax
  • Including regexp-based syntax colorers, etc.

Heredocs

Pros:

• Slightly more flexible than triple-quotes
• Addresses some of the issues mentioned in the motivation section

Cons:

• More complex syntax
• Would likely not be a great fit for docstring readability.
  • (defn foo <<HEREDOC hello this is a docstring HEREDOC [x] ...) for example, is pretty bad.

String Interpolation / Templating

Pros:

Cons: 

• Without additional information about specifically what is being proposed, this is likely to be a breaking change.
• There are already many libraries available to do this.
• Does not directly address docstring readability.

Puzzles:

• Is the built-in format function enough?
  • Not for docstrings.
  • In the case of XML, JSON, and SQL generation tests (as mentioned in the Motivation section) it can still be rather difficult to read.

Resource files

Pros:

• Already exists
• Is a well established pattern in the community for reading configuration files

Cons:

• Separate file for each string
• Can't use for macro-interpreted things like doc strings
• In tests, having the test data separate from the test itself is hard to read
• Does not address readability of docstrings in source.
• Does not address SQL, JSON, XML, etc. generation tests.
• In general, does not address the problems outline in the motivation section of this document.