Chapter 13: Referenceslinear-chapter13

Co-authored-by: Thalia Archibald <thalia@archibald.dev>
Co-authored-by: Dibyendu Majumdar <mobile@majumdar.org.uk>
Co-authored-by: XmiliaH <45106915+XmiliaH@users.noreply.github.com>
Co-authored-by: Robert Obkircher <robert.obkircher@gmail.com>

3 files changed, 192 insertions, 0 deletions

diff --git a/docs/chapter13/13-grammar.md b/docs/chapter13/13-grammar.md
new file mode 100644
index 00000000..00796552
--- /dev/null
+++ b/docs/chapter13/13-grammar.md
@@ -0,0 +1,135 @@
+# Grammar for Chapter 13
+
+```antlrv4
+grammar SimpleLanguage;
+
+program
+    : statement+ EOF
+    ;
+
+statement
+    : returnStatement
+    | structDeclaration
+    | declStatement
+    | blockStatment
+    | expressionStatement
+    | ifStatement
+    | whileStatement
+    | breakStatement
+    | continueStatment
+    | metaStatement
+    ;
+
+PRIMTYPE
+    : 'int'
+    | 'flt'
+    ;
+
+field
+    : PRIMTYPE IDENTIFIER ';'
+    | structName IDENTIFIER ('?')? ';'
+    ;
+
+fields
+    : field+
+    ;
+
+structDeclaration
+    : 'struct' IDENTIFIER '{' fields '}'
+    ;
+
+whileStatement
+    : 'while' '(' expression ')' statement
+    ;
+
+breakStatement
+    : 'break' ';'
+    ;
+
+continueStatement
+    : 'continue' ';'
+    ;
+
+ifStatement
+    : 'if' '(' expression ')' statement ('else' statement)?
+    ;
+
+metaStatement
+    : '#showGraph' ';'
+    ;
+
+expressionStatement
+    : IDENTIFIER '=' expression ';'
+    | fieldExpression '=' expression ';'
+    ;
+
+blockStatement
+    : '{' statement+ '}'
+    ;
+
+structName
+    : IDENTIFIER
+    ;
+
+declStatement
+    : PRIMTYPE IDENTIFIER '=' expression ';'
+    | structName ('?')? IDENTIFIER '=' expression ';'
+    ;
+
+returnStatement
+    : 'return' expression ';'
+    ;
+
+expression
+    : comparisonExpression
+    ;
+
+comparisonExpression
+    : additiveExpression (('==' | '!='| '>'| '<'| '>='| '<=') additiveExpression)*
+    ;
+
+additiveExpression
+    : multiplicativeExpression (('+' | '-') multiplicativeExpression)*
+    ;
+
+multiplicativeExpression
+    : unaryExpression (('*' | '/') unaryExpression)*
+    ;
+
+unaryExpression
+    : ('-') unaryExpression
+    | '!' unaryExpression
+    | primaryExpression
+    ;
+
+newExpression
+    : 'new' IDENTIFIER
+    ;
+
+fieldExpression
+    : primaryExpresson '.' IDENTIFIER
+    ;
+
+primaryExpression
+    : IDENTIFIER
+    | INTEGER_LITERAL
+    | 'true'
+    | 'false'
+    | 'null'
+    | newExpression
+    | '(' expression ')'
+    | fieldExpression
+    ;
+
+INTEGER_LITERAL
+    : [1-9][0-9]*
+    | [0]
+    ;
+
+IDENTIFIER
+    : NON_DIGIT (NON_DIGIT | DIGIT)*
+    ;
+
+NON_DIGIT: [a-zA-Z_];
+DEC_DIGIT: [0-9];
+```
diff --git a/docs/chapter13/Makefile b/docs/chapter13/Makefile
new file mode 100644
index 00000000..12659b8f
--- /dev/null
+++ b/docs/chapter13/Makefile
@@ -0,0 +1,12 @@
+GV := $(wildcard *.gv)
+SVG := $(patsubst %.gv,%.svg,$(GV))
+
+.PHONY: all
+all: $(SVG)
+
+%.svg: %.gv
+	dot -Tsvg $< > $@
+
+.PHONY: clean
+clean:
+	@rm -f $(SVG)
diff --git a/docs/chapter13/README.md b/docs/chapter13/README.md
new file mode 100644
index 00000000..5d3979ad
--- /dev/null
+++ b/docs/chapter13/README.md
@@ -0,0 +1,45 @@
+# Chapter 13: References
+
+In this chapter, we add references and structs.
+
+You can also read [this chapter](https://github.com/SeaOfNodes/Simple/tree/linear-chapter13) in a linear Git revision history on the [linear](https://github.com/SeaOfNodes/Simple/tree/linear) branch and [compare](https://github.com/SeaOfNodes/Simple/compare/linear-chapter12...linear-chapter13) it to the previous chapter.
+
+## References
+
+Structs can reference other structs; references can be mutually recursive.
+Any reference field can allow null or not, same as a normal variable.
+
+```java
+struct Person {
+  String name;       // No string type, yet
+  int age;
+  FamilyTree tree?;  // A family tree, or not
+}
+struct FamilyTree {
+  Person father?;    // FamilyTree can reference Person
+  Person mother?;
+  Person []kids?;
+}
+```
+
+Normal field syntax works:  
+e.g. `person.tree.father = new Person;` or 
+     `person.tree.father.name = "Dad";`.
+
+Reference fields all start out null, and can be tested as such.  However, a
+non-null reference field can only be stored with a non-null ref.
+
+```java
+struct N { N next; int i; }
+N n = new N;
+return n.next;  // Value reports as null, despite field typed as not-null
+```
+
+And:
+
+```java
+struct N { N next; int i; }
+N n = new N;
+n.next = null; // <<-- Compile error, cannot store null into not-null field
+return n.next;
+```