Add a semicolon composition operator & update docs (#111)

* Tidy up a test

* Semicolon operator for pipeline-ordered composition

* Doc on operators and identifiers

* Update syntax docs

Author: gmorpheme

docs/operators-and-identifiers.md

@@ -0,0 +1,120 @@
+# Operators and Identifiers
+
+Eucalypt distinguishes two different types of identifier, *normal*
+identifiers, like `x`, `y`, `α`, `א`, `ziggety-zaggety`, `zoom?`, and
+*operator identifiers* like `*`, `@`, `&&`, `∧`, `∘`, `⊙⊙⊙`, `<>` and
+so on.
+
+It is entirely a matter of the component characters which category and
+identifier falls into. Normal identifiers contain letters (including
+non-ascii characters), numbers, "-", "?", "$". Operator identifiers
+contain the usual suspects and anything identified as an operator or
+symbol in unicode. Neither can contain ":" or "," or brackets which
+are special in eucalypt.
+
+Any sequence of characters at all can be treated as a normal
+identifier by surrounding them in single quotes. This is the only use
+of single quotes in eucalypt. This can be useful when you want to use
+file paths or other external identifiers as block keys for instance:
+
+```eu
+
+home: {
+  '.bashrc': false
+  '.emacs.d': false
+  'notes.txt': true
+}
+
+z: home.'notes.txt'
+
+```
+
+## Normal identifiers
+
+Normal operators are brought into scope by declarations and can be
+referred to without qualification in their own block or in more
+nested blocks:
+
+```eu
+
+x: {
+  z: 99
+  foo: z //=> 99
+  bar: {
+	y: z //=> 99
+  }
+}
+
+```
+
+They can be accessed from within other blocks using the lookup
+operator:
+
+```eu
+
+x: {
+  z: 99
+}
+
+y: x.z //=> 99
+```
+
+They can be overridden using generalised lookup:
+
+```eu
+
+z: 99
+y: { z: 100 }."z is {z}" //=> "z is 100"
+```
+
+They can be shadowed:
+
+```eu
+
+z: 99
+y: { z: 100 r: z //=> 100 }
+```
+
+But beware trying to access the outer value:
+
+```eu
+name: "foo"
+x: { name: name } //=> infinite recursion
+```
+
+Accessing shadowed values is not yet easily possible unless you can
+refer to an enclosing block and use a lookup.
+
+## Operator identifiers
+
+Operator identifiers are more limited than normal identifiers.
+
+They are brought into scope by operator declarations and available
+without qualification in their own block and more nested blocks:
+
+```eu
+( l -->> r): "{l} shoots arrow at {r}"
+
+x: {
+  y: 2 -->> 3 //=> "2 shoots arrow at 3"
+}
+```
+
+...and can be shadowed:
+
+```eu
+
+(l !!! r): l + r
+
+y: {
+  (l !!! r): l - r
+  z: 100 !!! 1 //=> 99
+}
+
+```
+
+But:
+
+- they cannot be accessed by lookup, so there is no way of forming a
+  qualified name to access an operator
+- they cannot be overridden by generalised lookup

docs/syntax.md

@@ -45,6 +45,8 @@ Eucalypt has two types of names:
 - operator names, which are largely symbolic (e.g. `&&&`, `∧`, `-+-|`,
   `⊚`) and are used to name operators
 
+See [Operators and Identifiers](operators-and-identifiers.md) for more.
+
 ## The block DSL
 
 A **block** is surrounded by curly braces:
@@ -86,31 +88,14 @@ c: 3
 So far all these declarations have been **property declarations** which
 contains a name and an expression, separated by a colon.
 
-There is no comma separating declarations. Nor are line endings
-significant. The following is a block of three **property
-declarations**.
+Commas are entirely optional for delimiting declarations. Line endings
+are not significant. The following is a top-level block of three
+**property declarations**.
 
 ```eu
 a: 1 b: 2 c: 3
 ```
 
-(The colon is very important.)
-
-!!! note
-
-	This is a controversial choice and might change in future. Eucalypt
-	aims to be minimal and commas would be redundant. Lacking
-	explicit delimitation makes the parsing slower and closes off
-	evolutions of the languages in which the comma would no longer be
-	redundant (as per some recent enhancements in javascript). Another
-	option would be a "commas are whitespace" approach as per Clojure
-	but that leads to confusion when commas are sometimes used,
-	sometimes not, sometimes places in the wrong place with no
-	objection from the compiler. Leaving them out keeps the
-	possibility of using them as a tupling operator in future - but
-	note that they are required for list literals in the expression
-	DSL.
-
 There are other types of declarations. By specifying a parameter list,
 you get a **function declaration**:
 
@@ -335,4 +320,4 @@ returns that value if they are.
 	There are no explicit lambda expressions in Eucalypt right now.
 	For simple cases, expression or string anaphora should do the job.
 	For more involved cases, you should use a named function declaration.
-	More features are coming...
+	See [Anaphora and Lambdas](anaphora-and-lambdas.md) for more.

harness/test/014_numeric_combinators.eu

@@ -1,5 +1,3 @@
-# doesn't require prelude; uses builtins only
-
 ` :suppress
 (l||r): __OR(l,r)
 ` :suppress
@@ -17,12 +15,9 @@ take(n, l): __IF((n zero?) || (l empty?), [], cons(l head, take(n dec, l tail)))
 ` :suppress
 drop(n, l): __IF((n zero?) || (l empty?), l, drop(n dec, l tail))
 ` :suppress
-repeat-n(n, i): __IF((n zero?), [], cons(i, repeat-n(dec(n), i)))
-
-# TODO: Can't use this until lists are exposed to eu as cons is not
-# currently lazy enough
-` :suppress
 repeat(i): __CONS(i, repeat(i))
+` :suppress
+repeat-n(n, i): repeat(i) take(n)
 
 ten-fives: repeat-n(10, 5)
 ten-hellos: repeat-n(10, "hello")

lib/prelude.eu

@@ -398,11 +398,17 @@ const(k, _): k
 ` "`compose(f,g,x)` - apply function `f` to `g(x)`."
 compose(f, g, x): x g f
 
-` { doc: "`(f ∘ g)` - return composition of `f` and `g`"
+` { doc: "`(f ∘ g)` - return composition of `f` and `g` (`g` then `f`)"
     export: :suppress
     associates: :right
     precedence: 88 }
-(f ∘ g): compose(f,g)
+(f ∘ g): compose(f, g)
+
+` { doc: "`(f ; g)` - return composition of `f` then `g`"
+    export: :suppress
+    associates: :left
+    precedence: 88 }
+(f ; g): compose(g, f)
 
 ` { doc: "(l @ r) - function application operator, for reversing catentation args and eliding parentheses"
     export: :suppress

mkdocs.yml

@@ -1,4 +1,4 @@
-site_name: "Eucalypt: liquiYAML"
+site_name: "eucalypt"
 repo_url: https://github.com/curvelogic/eucalypt
 copyright: "Copyright (C) 2018 Greg Hawkins"
 docs_dir: docs
@@ -7,6 +7,7 @@ nav:
 - Getting Started: getting-started.md
 - Syntax: syntax.md
 - Command Line: command-line.md
+- Operators and Identifiers: operators-and-identifiers.md
 - Anaphora and Lambdas: anaphora-and-lambdas.md
 - Philosophy: philosophy-lang.md
 markdown_extensions:

src/Eucalypt/Syntax/ParseExpr.hs

@@ -45,12 +45,12 @@ operatorIdentifier =
   "operator identifier"
   where
     opIdentStartChar =
-      oneOf (".!@£%^&*|></+=-~" :: String) <|>
+      oneOf (".!@£%^&*|></+=-~;" :: String) <|>
       satisfy
         (\c ->
            (not . isAscii) c && (c /= '•') && (isSymbol c || isPunctuation c))
     opIdentContinuationChar =
-      oneOf (".!@£$%^&*|></?+=-~" :: String) <|>
+      oneOf (".!@£$%^&*|></?+=-~;" :: String) <|>
       satisfy (\c -> (not . isAscii) c && (isSymbol c || isPunctuation c))