Skip to end of metadata
Go to start of metadata

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.
Puzzles:
  • What about the EDN spec?
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.
Labels:
  1. Dec 21, 2011

    Regarding resource files, you can have more than one string per file – consider ordinary java properties files, which are easy enough to work with (and powerful, when the string values contained therein are filled with $... placeholders for format calls).  http://en.wikipedia.org/wiki/.properties

  2. Dec 21, 2011

    Re: interpolation, there's this, which is in clojure.core.strint in core.incubator.

  3. Mar 22, 2013

    As of Clojure 1.5, we should consider EDN compatibility when proposing an extension to the Clojure reader. See http://edn-format.org.  Also, note that Clojure 1.5 added clojure.edn/read and read-string.  As a practical matter, any new string reader syntax should probably be part of EDN as well as Clojure.