Extend internals/AST.rst

1 files changed, 70 insertions, 10 deletions

diff --git a/doc/internals/AST.rst b/doc/internals/AST.rst
index 4e77f8f3c..77dba1861 100644
--- a/doc/internals/AST.rst
+++ b/doc/internals/AST.rst
@@ -45,8 +45,18 @@ The AST in GHDL
 The GHDL AST is described in file :file:`vhdl-nodes.ads`.
 
 An interesting particularity about the AST is the presence of a
-meta-model.  The meta-model is not formally described (so, there is no
-meta-meta-model), but it is very simple: there are 3 kinds of vertices:
+meta-model.
+
+The meta-model is not formally described.  What would be the
+meta-meta-model is very simple: there are elements and attributes.  An
+element is composed of attributes, and an attribute is either a value
+(a flag, an integer, an enumeration) or a link to an element.
+
+(When someone wants to be clever, he often speaks about meta-model in
+order to confuse you.  Don't let him impress you.  The trick is to
+answer him with any sentence containing 'meta-meta-model').
+
+In the GHDL meta-mode, there are only 3 elements:
 
 * variable list of nodes (`List`).  These are like vectors as the
   length can be changed.
@@ -56,16 +66,35 @@ meta-meta-model), but it is very simple: there are 3 kinds of vertices:
 * Nodes.  A node has a kind (`Iir_Kind` which is also defined in the file), and fields.
   The kind is set at creation and cannot be changed, while fields can be.
 
-The meta-model describes the type of the fields: most of them are
+Or without using the word meta-model, the AST is composed of nodes and
+lists.
+
+The meta-model describes the type of the attributes: most of them are
 either a node reference, a boolean flag or a enumerated type (like
-`Iir_Staticness`).  But there are various node references.  A node can either owns
-another node, which means this is the main reference to the node; or a node can
-reference another node without owning it.
+`Iir_Staticness`).  But there are also links: a reference to another
+node or to a list.
+
+The accessors for the node are generated automatically by the python
+script :file:`src/xtools/pnodes.py`.
 
 Why a meta-model ?
 ******************
 
-Having a meta-model allows to build algorithm that deals with any
+All ASTs could have a meta-model, because the definition of elements
+and attributes is very generic.  But there is a detail: the definition
+of an element is static.  So for each node, the list of attribute and
+their type is static and each list is a list of the same element type.
+So there is no bag, nor dynamic typing.  This is per the definition of
+the meta-meta-model.
+
+But in GHDL there is an API at the meta-model level in file
+:file:`vhdl-nodes_meta.ads`.  There is the list of all attribute types
+in enumeration `Types_Enum`.  There is the list of all possible
+attributes in enumeration `Fields_Enum`.  For a particular kind of
+node, you can get the list of fields with `Get_Field` and for every
+type, there is API to get or set any field of any node.
+
+Having a meta-model API allows to build algorithm that deals with any
 node.  The dumper (in file :file:`vhdl-disp_tree.ad[sb]`) is used to
 dump a node and possibly its sub-nodes.  This is very useful while
 debugging GHDL.  It is written using the meta-model, so it knows how to display
@@ -81,13 +110,44 @@ are possibly new types).  And creating an instance using the meta-model is much
 simpler (and much more generic) that creating the instance using directly the nodes.
 The code to create instances is in files :file:`vhdl-sem_inst.ad[sb]`.
 
-The meta-model also structures the tree.  We know that each node is owned only by one node, and that each node is owned (except the top-level one).  So it is possible to
-free a sub-tree.  It is also possible to check that the tree is well-formed.
+The meta-model API is moslty automatically generated by the python
+script.
 
 Dealing with ownership
 **********************
 
-TBC: two fields, Is_Ref, Second_XXX; Rust & Scripts.
+The meta-model also structures the tree, because there is a notion of
+ownership: every element (but the root) has only one parent that owns
+it, and there are no cycle in the ownership.  So the tree is really a
+tree.
+
+That simplifies algorithms because it is easier to walk a tree than a
+graph.  It is also easier to free a sub-tree than a sub-graph.
+
+Getting a real tree from the parser might look obvious, but it is
+not.  Consider the following VHDL declaration:
+
+.. code-block:: vhdl
+
+   variable v1, v2 : std_logic_vector (1 downto 0) := "00";
+
+Both variables ``v1`` and ``v2`` share the same type and the same
+initial value.  The GHDL AST uses two different strategies:
+
+* For the type, there is two fields in the node:
+  ``subtype_indication`` and ``type``.  The ``subtype_indication`` is
+  owned and set only on the first variable to the output of the
+  parser.  The ``type`` field is a reference and set on all variables
+  to the result of analysis of ``subtype_indication``.
+
+* For the initial value, there is only one field ``default_value``
+  that is set on all variables.  But the ownership is controlled by a
+  flag in the node (an attribute) named ``is_ref``.  It is set to
+  false on the first variable and true for the others.
+
+The notion of ownership is highlighten by the Rust language, and
+indeed this is an important notion.  The implementation of the Rust
+AST has to be investigated.
 
 Node Type
 *********