From 49465c470c348ef1e8fc8fd546666b1de66c1e7c Mon Sep 17 00:00:00 2001
From: apense <apense@users.noreply.github.com>
Date: Wed, 17 Jun 2015 16:54:02 -0400
Subject: More documentation of AST

Also gave some examples
---
 doc/astspec.txt | 96 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 95 insertions(+), 1 deletion(-)

(limited to 'doc')

diff --git a/doc/astspec.txt b/doc/astspec.txt
index 596d07bab..ebc39322f 100644
--- a/doc/astspec.txt
+++ b/doc/astspec.txt
@@ -824,10 +824,23 @@ AST:
 .. code-block:: nim
   nnkExportStmt(nnkIdent(!"unsigned"))
 
+Similar to the ``import`` statement, the AST is different for 
+``export ... except``.
+
+Concrete syntax:
+
+.. code-block:: nim
+  export math except pow # we're going to implement our own exponentiation
+
+AST:
+
+.. code-block:: nim
+  nnkExportExceptStmt(nnkIdent(!"math"),nnkIdent(!"pow"))
+
 Include statement
 -----------------
 
-Like a plain ``import`` statement.
+Like a plain ``import`` statement but with ``nnkIncludeStmt``.
 
 Concrete syntax:
 
@@ -872,6 +885,20 @@ Let section
 This is equivalent to ``var``, but with ``nnkLetSection`` rather than
 ``nnkVarSection``.
 
+Concrete syntax:
+
+.. code-block:: nim
+  let v = 3
+
+AST:
+
+.. code-block:: nim
+  nnkLetSection(
+    nnkIdentDefs(!"v"),
+    nnkEmpty(), # for the type
+    nnkIntLit(3)
+  )
+
 Const section
 -------------
 
@@ -983,6 +1010,73 @@ AST:
     )
   )
 
+Nim's object syntax is rich. Let's take a look at an involved example in
+its entirety to see some of the complexities.
+
+Concrete syntax:
+
+.. code-block:: nim
+  type Obj[T] = object {.inheritable.}
+    name: string
+    case isFat: bool
+    of true:
+      m: array[100_000, T]
+    of false:
+      m: array[10, T]
+
+AST:
+
+.. code-block:: nim
+  # ...
+  nnkObjectTy(
+    nnkPragma(
+      nnkIdent(!"inheritable")
+    ),
+    nnkEmpty(),
+    nnkRecList( # list of object parameters
+      nnkIdentDefs(
+            nnkIdent(!"name"),
+            nnkIdent(!"string"),
+            nnkEmpty()
+      ),
+      nnkRecCase( # case statement within object (not nnkCaseStmt)
+        nnkIdentDefs(
+              nnkIdent(!"isFat"),
+              nnkIdent(!"bool"),
+              nnkEmpty()
+        ),
+        nnkOfBranch(
+              nnkIdent(!"true"),
+              nnkRecList( # again, a list of object parameters
+                nnkIdentDefs(
+                  nnkIdent(!"m"),
+                  nnkBracketExpr(
+                    nnkIdent(!"array"),
+                    nnkIntLit(100000),
+                    nnkIdent(!"T")
+                  ),
+                  nnkEmpty()
+              )
+        ),
+        nnkOfBranch(
+              nnkIdent(!"false"),
+              nnkRecList(
+                nnkIdentDefs(
+                  nnkIdent(!"m"),
+                  nnkBracketExpr(
+                    nnkIdent(!"array"),
+                    nnkIntLit(10),
+                    nnkIdent(!"T")
+                  ),
+                  nnkEmpty()
+                )
+              )
+        )
+      )
+    )
+  )
+
+
 Using an ``enum`` is similar to using an ``object``.
 
 Concrete syntax:
-- 
cgit 1.4.1-2-gfad0

</a>
<a id='n12' href='#n12'>12</a>
<a id='n13' href='#n13'>13</a>
<a id='n14' href='#n14'>14</a>
<a id='n15' href='#n15'>15</a>
<a id='n16' href='#n16'>16</a>
<a id='n17' href='#n17'>17</a>
<a id='n18' href='#n18'>18</a>
<a id='n19' href='#n19'>19</a>
<a id='n20' href='#n20'>20</a>
<a id='n21' href='#n21'>21</a>
<a id='n22' href='#n22'>22</a>
<a id='n23' href='#n23'>23</a>
<a id='n24' href='#n24'>24</a>
<a id='n25' href='#n25'>25</a>
<a id='n26' href='#n26'>26</a>
<a id='n27' href='#n27'>27</a>
<a id='n28' href='#n28'>28</a>
<a id='n29' href='#n29'>29</a>
<a id='n30' href='#n30'>30</a>
<a id='n31' href='#n31'>31</a>
<a id='n32' href='#n32'>32</a>
<a id='n33' href='#n33'>33</a>
<a id='n34' href='#n34'>34</a>
<a id='n35' href='#n35'>35</a>
<a id='n36' href='#n36'>36</a>
</pre></td>
<td class='lines'><pre><code>