Style Guide

The following guide is a side product on my work on the new indentation-based grammar. If you stick to it, you can be sure that the new parser will be able to read existing code. The new parser will also have some new constructions that I’m leaving out for now, and some keywords will be optional.

Definitions and cells

• The starting keyword (def, cell etc.) starts on column 1
• The content (after =) follows either completely on the same line, or indented in the following lines, but not partly on the first line and on the following lines

Good:

def x = 1                   # all on a single line
def y =                     # content on followling line, indented
  2
def incr =                  # multiline content, indented
  (x ->
     x+1
  )
in cell x = null            # same with cells
cell y =
  if (x'?) 1 else x'+1

Bad:

def f = (x ->               # BAD: content both on first line and following lines
  x+1)
def g =                     # BAD: content not indented
1+2
  cell x = 42               # BAD: definition doesn't start on column 1

General indentation rules

• everything is ok if a subexpressions starts and ends on the same line (=> you can evade indentation by putting everything on the same line)
• indentation must be used for expressions covering multiple lines
• indentation must “fit” into the bracket structure

Good:

cell y = if (x) "hello" else "world"       # all on one line, perfect!
cell x =                  # subexpressions respect indentation
  if (x)
    "hello " + world      # subexpression 1
  else
    "bye " + world        # subexpression 2

Bad:

cell x =                 # BAD: subexpression 1 starts with an LINDENT but doesn't end with RINDENT
  if (x)
    "hello " + world else
    "bye " + world

How to close brackets

• ideally the right bracket is on the same column as the left bracket
• but we are generous: it is ok to have a “bracket trail” on a single line, closing lots of expressions