api.geometry design

Design Goals

• Descriptive (declarative) syntax
• Contrast: procedural syntax, e.g. Postscript, SVG. We say line a b rather than a moveto b lineto
• Natural syntax
• Syntax: for now we stick with Clojure's prefix-n-parens syntax. Infix syntax is more natural, and macros can make it work for Clojure (see Incanter's use of $= for this) but for now we follow the path of least resistance.
• Terminology: "natural" means something like "standard mathematical terminology".

Design Decision Points

• Coordinates: to parenthesize or not to parenthesize. Many geometry APIs do not parenthesize, e.g.

  • line a b c d But parenthesis is more natural: line (a,b) (c,d). The parens carry information. So we use parenthesized points.

• Fixity: prefix, infix, or postfix are the three "natural" ways to do it:

  • line (a,b) (c,d)
  • (a,b) line (c,d)
  • (a,b) (c,d) line

To support infix or postfix we would have to use a macro, e.g. ($= (a,b) line (c,d)). So we stick with prefix notation.

• To macroize or not to macroize. For example:
  1. (line '(0,0) '(1,1))
  2. (line (0,0) (1,1))

Here i is close to natural, but it has those pesky ' marks; ii is more natural. We can support this if we make "line" a macro.