MPIDE-25: document parser output structure

Added parser.md to detail the data structure resulting from the PEG
parser.

Minor fix in parser: atoms are now built as Behaviors.

docs/parser.md

@@ -0,0 +1,101 @@
+# parser api
+The provided PEGjs parser accepts a text blob of `modellang` as input and returns an object of the following structure:
+
+```
+systems: Map <String, System>
+behaviors: Map <String, Behavior>
+interactions: Array <Interaction>
+triggers: Array <Trigger>
+errors: Array <SyntaxError>
+```
+
+### types you might want to know about
+```
+System:
+  type: "System"
+  id: String
+  body: Array <Sequence & Alternation>
+  refs: Array <String>
+  scope: Scope
+```
+
+```
+Behavior:
+  type: "Behavior"
+  id: String
+  body: Array <Sequence & Alternation>
+  refs: Array <String>
+  scope: Scope
+```
+
+```
+Interaction:
+  type: "Order" | "Join"
+  body: Array <Expression & Selector>
+```
+
+```
+Trigger:
+  type: "Trigger"
+  on: Selector
+  do: ?blob?
+```
+
+```
+Sequence:
+  type: "Sequence"
+  body: Array <Group & Identifier>
+  scope: Scope
+```
+
+```
+Alternation:
+  type: "Alternation"
+  body: Array <Group & Identifier>
+  scope: Scope
+```
+
+```
+Group:
+  type: "Group"
+  async: Boolean
+  body: Array <Group & Identifier>
+  scope: Scope
+```
+
+```
+Expression:
+  type: "Expression"
+  operator: String
+  lhs: Integer & String
+  rhs: Integer & String
+```
+
+```
+Selector:
+  type: "Selector"
+  system: String
+  pattern: Alternation & Sequence
+```
+
+```
+Identifier:
+  id: String
+  scope: Scope
+```
+
+```
+Scope:
+  min: Integer
+  max: Integer
+```
+
+```
+SyntaxError:
+  offset: String
+  line: String
+  column: String
+  expected: String
+  found: String
+  message: String
+```

src/lib/parser/modellang.pegjs

@@ -65,7 +65,7 @@
             var ref = ast.references[r];
 
             if (!model.behaviors[ref])
-                model.behaviors[ref] = { type:"Behavior", id:ref, body:[], refs:[] };
+                model.behaviors[ref] = new Behavior(ref, [], [])
         }
 
         return warnify(model);
@@ -220,7 +220,7 @@ interaction_statement "Interaction"
 interaction_type
     = _ t:( ORDER / JOIN ) _
     { return t; }
-
+/* FIXME: selector patterns should be different from definition patterns */
 system_item_selector "Selector"
     = !([a-z0-9 ]i+ operator) _ sys:system_id ":" _ p:behavior_pattern _
     { return new ast.Selector(sys, p); }