Error formatting macro: pagetree: java.lang.NullPointerException

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Added more pros, cons, puzzles

Alternate string quote syntaxes

Motivation

  • doc strings 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 Relatively simple syntax, for humans and parsers
  • Has already been implemented
  • Would work nicely for docstrings.
    • (defn foo """my docstring"""" [x] ...)

Cons:

  • minor Minor breaking change - """""" which is  3 empty strings would now be interpreted as only one empty string
  • have Have to add reader macro
  • breaking Breaking change to every other tool that reads Clojure syntax
    • including Including regexp-based syntax colorers, etc.
Puzzles:
  • What about the EDN spec?
Heredocs

Pros: slightly

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

Cons: more

  • 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 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.