diff --git a/src/doc/manual/example.xml b/src/doc/manual/example.xml index 04ad38c..62de48c 100644 --- a/src/doc/manual/example.xml +++ b/src/doc/manual/example.xml @@ -7,8 +7,16 @@

Examples

-

The figure below contains a complete and working grammar file - example for a simple arithmetic language.

+

These examples come from the test/src/grammar and + test/src/java directories. The source code has been + simplified in these examples in order to be easier to read. Please + refer to the original source code in the above directories for the + complete compilable versions. Also note that the corresponding C# + examples are found in the test/src/csharp + directory.

+ +

The figure below contains a complete and working example of a + grammar file for a simple arithmetic language.

A grammar for a simple arithmetic language. @@ -63,5 +71,121 @@ Atom = NUMBER
+

To create a parser for the grammar above, the parser source + code must first be created. If the grammar above has been stored + in the file arithmetic.grammar, this can be + accomplished with the following command:

+ +
# java -jar lib/grammatica-.jar arithmetic.grammar --javaoutput test
+ +

This will create the files ArithmeticAnalyzer.java, + ArithmeticConstants.java, + ArithmeticParser.java, and + ArithmeticTokenizer.java in the test + subdirectory. These files contain the source code for the parser. + In order to call the parser, the method in the figure below can + be inserted into another Java class.

+ +
+ The source code for a method parsing an arithmetic + string. + + +
private Node parseArithmetic(String input) {
+    Parser  parser = null;
+
+    parser = new ArithmeticParser(new StringReader(input));
+    return parser.parse();
+}
+
+
+ +

In the case of the arithmetic language, is it also interesting + to analyze and evaluate the contents of the string. This can be + done by subclassing the ArithmeticAnalyzer class and + overloading the callback methods for the relevant productions. A + small example of this can be seen in the figure below.

+ +
+ The partial (and incomplete) source code for an + analyzer calculating the result of an arithmetic + expression. + + +
class ArithmeticCalculator extends ArithmeticAnalyzer {
+
+    protected Node exitNumber(Token node) {
+        node.addValue(new Integer(node.getImage()));
+        return node;
+    }
+
+    protected Node exitExpression(Production node) {
+        ArrayList  values = getChildValues(node);
+        Integer    value1;
+        Integer    value2;
+        String     op;
+        int        result;
+        
+        if (values.size() == 1) {
+            result = ((Integer) values.get(0)).intValue();
+        } else {
+            value1 = (Integer) values.get(0);
+            value2 = (Integer) values.get(2);
+            op = (String) values.get(1);
+            result = operate(op, value1, value2);
+        }
+        node.addValue(new Integer(result));
+        return node;
+    }
+
+    protected Node exitExpressionTail(Production node) {
+        node.addValues(getChildValues(node));
+        return node;
+    }
+
+    protected Node exitTerm(Production node) {
+        ArrayList  values = getChildValues(node);
+        Integer    value1;
+        Integer    value2;
+        String     op;
+        int        result;
+        
+        if (values.size() == 1) {
+            result = ((Integer) values.get(0)).intValue();
+        } else {
+            value1 = (Integer) values.get(0);
+            value2 = (Integer) values.get(2);
+            op = (String) values.get(1);
+            result = operate(op, value1, value2);
+        }
+        node.addValue(new Integer(result));
+        return node;
+    }
+
+    protected Node exitTermTail(Production node) {
+        node.addValues(getChildValues(node));
+        return node;
+    }
+
+    protected Node exitFactor(Production node) throws ParseException {
+        int  result;
+        
+        if (node.getChildCount() == 1) {
+            result = getIntValue(getChildAt(node, 0), 0);
+        } else {
+            result = getIntValue(getChildAt(node, 1), 0);
+        }
+        node.addValue(new Integer(result));
+        return node;
+    }
+
+    protected Node exitAtom(Production node) {
+        node.addValues(getChildValues(node));
+        return node;
+    }
+
+
+
+ diff --git a/src/doc/manual/index.xml b/src/doc/manual/index.xml index 44cd54e..4136b78 100644 --- a/src/doc/manual/index.xml +++ b/src/doc/manual/index.xml @@ -58,7 +58,8 @@ <ref file="example.xml">Examples</ref> - Contains a complete example of a grammar file. + Examples of a complete grammar file and Java source + code for creating a parser. diff --git a/src/doc/release/version.xml b/src/doc/release/version.xml index 4caf4a0..45546fa 100644 --- a/src/doc/release/version.xml +++ b/src/doc/release/version.xml @@ -14,6 +14,13 @@ release documentation. The build file uses CppDoc to generate the HTML documents. (Bug #3612) + + + Added source code examples to documentation + Some examples of Java source code for creating a + parser has been added to the reference manual. + (Bug #4093) + Improved and clarified the Analyzer API