// FILE. . . . . /home/hak/hlt/src/hlt/language/syntax/xml/Comment
// EDIT BY . . . Hassan Ait-Kaci
// ON MACHINE. . Hp-Dv7
// STARTED ON. . Sat Apr 07 15:31:10 2007

// Last modified on Fri Oct 12 02:04:20 2012 by hak

/**
 * This grammar specifies the form of XML annotations one can use in a
 * Jacc grammar. These annotations are used for generating an XML
 * serialization of the AST. The grammar of XmlAnnotations is herein
 * expressed as a Jacc grammar itself. Hence, this Jacc grammar
 * generates the parser used by Jacc itself (!) to enable itself to
 * (meta-)parse complicated XML annotations that necessitate parsing
 * power beyond simple Regular Expression matching.
 *
 * <p>
 *
 * This comment explains informally how to annotate a Jacc grammar for
 * XML serialization of the AST.
 *
 * <p>
 *
 * Essentially, the rule format of Jacc is that of Yacc. As in Yacc,
 * Jacc rules may be annotated with semantic actions, in the form of
 * code involving the rule's RHS constituents (denoted by
 * <tt>&#36;1</tt>, <tt>&#36;2</tt>, ..., <tt>&#36;n</tt> - the
 * so-called pseudo-variables - where the index <tt>n</tt> in
 * <tt>&#36;n</tt> refers to the position of a constituent of the rule's
 * RHS). Such actions appear between curly braces
 * ('<tt>{</tt>' and '<tt>}</tt>') wherever a symbol may appear in a
 * rule's RHS.
 *
 * <p>
 * 
 * Jacc also allows an additional form of annotation in the RHS of a
 * rule to indicate the XML serialization pattern of the abstract
 * syntactic tree (AST) node corresponding to a derivation with this
 * rule. This XML serialization meta-annotation comes between square
 * brackets ('<tt>[</tt>' and '<tt>]</tt>').
 *
 * <p>
 *
 * The most basic form of XML annotation is of the form:
 *
 * <pre>
 * [ XmlTag n_1 ... n_k ]
 * </pre>
 *
 * where <code>XmlTag</code> is an identifier to use as XML tag for this
 * node in the XML serialization of the AST, and the <code>n_k</code>'s
 * are a sequence of numbers denoting positions of symbols in the RHS of
 * the rule (as for pseudo-variables but without <tt>'&#36;'</tt>). The
 * number sequence indicates the order in which subnodes are to be
 * serialized.
 *
 * <p>
 *
 * For example, the annotated rule:
 *
 * <pre>
 * QUANTIF
 *    : 'Exists' Var_plus '(' CONDIT ')'
 *      [ Exists 2 4 ]
 *    ;
 * </pre>
 *
 * means that an AST node for this rule will be serialized thus:
 *
 * <pre>
 *  &lt;Exists&gt;
 *    (Xml serialization of Var_plus)
 *    (Xml serialization of CONDIT)
 *  &lt;/Exists&gt;
 * </pre>
 *
 * Rules without XML serialization annotation follow a default behavior:
 * the serialization is the concatenation of those of its RHS's
 * constituents, eliminating punctuation tokens (<i>i.e.</i>, empty nodes
 * and literal tokens - namely, tokens that do not carry a value).
 *
 * <p>
 *
 * Using the above basic form and trusting the default bevavior for
 * generating well-bracketted tag pairs is sufficient for simple
 * serialization. However, whenever attributes are needed, or when the
 * serialized AST form is not strictly homomorphic to the concrete
 * syntax tree's, one needs more complex forms of annotation.
 *
 * <p>
 *
 * In Jacc, XML annotation patterns of more elaborate form than the
 * basic form are possible and given by the following grammar:
 *
 * <pre>
 * XmlAnnotation
 *      : Head ChildrenPositions_opt
 *      ;
 * Head
 *      : URI Attributes_opt
 *      ;
 * ChildPosition
 *      : Value
 *      | XmlAnnotation
 *      ;
 * Attributes
 *      : '(' Attribute_plus ')'
 *      ;
 * Attribute
 *      : URI '=' Value
 *      ;
 * Value
 *      : Path
 *      | Path '.' IDE
 *      ;
 * Path
 *      : INT
 *      | Path '.' INT
 *      ;
 * </pre>
 *
 * Here is an example of use to illustrate:
 *
 * <p>
 *
 * Given the annotated grammar:
 * <pre>
 * Exp
 *      : INT                   [ Int(value = 1."nvalue()") ]
 *      | NAME                  [ Var(name = 1."svalue()") ]
 *      | BinExp
 *      ;
 * BinExp
 *      : Exp BinOp Exp         [ BinExp(operation = 2."function") 1 3 ]
 *      | Exp PartialExp        [ BinExp(operation = 2."relation") 1 2.2 ]
 *                              // or [ BinExp 2.1 1 2.2 ]
 *      ;
 * PartialExp
 *      : RelOp Exp             [ PartialExp(op = 1."relation") 2 ]
 *      ;
 * BinOp
 *      : '+'                   [ BinOp(function = "Plus") ]
 *      | '\*'                  [ BinOp(function = "Multiply") ]
 *      ;
 * RelOp
 *      : '<'                   [ RelOp(relation = "LessThan") ]
 *      | '>'                   [ RelOp(relation = "GreaterThan") ]
 *      ;
 * </pre>
 *
 * The serialization of the expression "<tt>x+1 < y\*3</tt>" is:
 *
 * <pre>
 *     &lt;BinExp operation="LessThan"&gt;
 *       &lt;BinExp operation="Plus"&gt;
 *         &lt;Var name="x"/&gt;
 *         &lt;Int value="1"/&gt;
 *       &lt;/BinExp&gt;
 *       &lt;BinExp operation="Multiply"&gt;
 *         &lt;Var name="y"/&gt;
 *         &lt;Int value="3"/&gt;
 *       &lt;/BinExp&gt;
 *     &lt;/BinExp&gt;
 * </pre>
 *
 * The semantics of an annotation is as follows.
 *
 * <p>Annotation of the form:
 * <pre>
 * XmlAnnotation
 *      : '[' Head ChildrenPositions_opt ']'
 *      ;
 * </pre>
 * means that <tt>Head</tt> specifies the XML tag and its
 * attributes, and that its elements will be specified by
 * <tt>ChildrenPositions_opt</tt>.
 *
 * <p>Annotation of the form:
 * <pre>
 * Head
 *      : URI Attributes_opt
 *      ;
 * </pre>
 * means that <tt>URI</tt> is the XML tag, possibly with
 * attributes, specified by <tt>Attributes_opt</tt>.
 *
 * <p>Annotation of the form:
 * <pre>
 * ChildPosition
 *      : Value
 *      | XmlAnnotation
 *      ;
 * </pre>
 * means that a <tt>ChildPosition</tt> is specified either as a
 * <tt>Value</tt> denoting the position in the annotated rule's RHS
 * of whose XML element is used in the specified XML pattern; or a
 * <tt>XmlAnnotation</tt> specifying an XML serialization to splice in
 * lieu of this <tt>ChildPosition</tt>.
 *
 * <p>Annotation of the form:
 * <pre>
 * Attributes
 *      : '(' Attribute_plus ')'
 *      ;
 * </pre>
 * specifies a sequence of attributes of an XML tag.
 *
 * <p>Annotation of the form:
 * <pre>
 * Attribute
 *      : URI '=' Value
 *      ;
 * </pre>
 * specifies an attribute/value pair.
 *
 * <p>Annotation of the form:
 * <pre>
 * Value
 *      : Path
 *      | Path '.' IDE
 *      ;
 * Path
 *      : INT
 *      | Path '.' INT
 *      ;
 * </pre>
 * means that a <tt>Value</tt> is either a path of period separated
 * natural numbers, possibly terminated by a string.  Each natural
 * number (<i>i.e.</i>, an <tt>INT</tt> in a <tt>Path</tt>, stands for
 * the index of a constituent in the RHS. 
 *----------------- FINISH LATER ...
 *  <i>n</i> denotes the serialization of the
 *           <i>n</i>-th RHS element when in context of a rule, and that of the
 *           <i>n</i>-th element in the XML serialization, when applied to one.
 *      <li> a <tt>IDE</tt>  denotes itself, and
 *      <li> an <tt>IDE</tt> denotes an attribute (of the XML
 *           tag) or a method call (only for a terminal node).
 * </ul>
 */

// The annotated grammar rules:

/**
 * Annotation of the form:
 * <pre>
 * $XmlAnnotation$
 *      : $Head$ $ChildrenPositions_opt$
 *      ;
 * </pre>
 * means that <tt>$Head$</tt> specifies the XML tag and its
 * attributes, and that its elements will be specified by
 * <tt>$ChildrenPositions_opt$</tt>.
 */

/**
 * Annotation of the form:
 * <pre>
 * $Head$
 *      : $URI$ $Attributes_opt$
 *      ;
 * </pre>
 * means that <tt>$URI$</tt> is the XML tag, possibly with
 * attributes, specified by <tt>$Attributes_opt$</tt>.
 *
 */

/**
 * Annotation of the form:
 * <pre>
 * $ChildPosition$
 *      : $Value$
 *      | $XmlAnnotation$
 *      ;
 * </pre>
 * means that a <tt>$ChildPosition$</tt> is specified either as a
 * <tt>$Value$</tt> denoting the position in the annotated rule's RHS
 * of whose XML element is used in the specified XML pattern; or a
 * <tt>$XmlAnnotation$</tt> specifying an XML serialization to splice in
 * lieu of this <tt>$ChildPosition$</tt>.
 *
 */

/**
 * Annotation of the form:
 * <pre>
 * $Attributes$
 *      : '(' $Attribute_plus$ ')'
 *      ;
 * </pre>
 * specifies a sequence of attributes of an XML tag.
 *
 */

/**
 * Annotation of the form:
 * <pre>
 * $Attribute$
 *      : $URI$ '=' $Value$
 *      ;
 * </pre>
 * specifies an attribute/value pair.
 *
 */

/**
 * Annotation of the form:
 * <pre>
 * $Value$
 *      : $BasicValue$
 *      | $Value$ '.' $BasicValue$
 *      ;
 * </pre>
 * means that a <tt>$Value$</tt> is either a basic value such as a natural
 * number, a string, or an identifier with, or without, arguments; or, the
 * projection of a value on an attribute denoted by a basic value.
 *
 */

/**
 * Annotation of the form:
 * <pre>
 * $BasicValue$
 *      : $INT$
 *      | $IDE$
 *      | $IDE$ $Arguments_opt$
 *      ;
 * </pre>
 * is interpreted such that:
 * <ul> <li> an <tt>$INT$</tt> <i>n</i> denotes the serialization of the
 *           <i>n</i>-th RHS element when in context of a rule, and that of the
 *           <i>n</i>-th element in the XML serialization, when applied to one.
 *      <li> a <tt>$IDE$</tt>  denotes itself, and
 *      <li> an <tt>$IDE$</tt> denotes an attribute (of the XML
 *           tag) or a method call (only for a terminal node).
 * </ul>
 */

