Parser generator - Getting started

From Laja
Jump to: navigation, search

Lets start with the simplest possible example by parsing a digit. We will generate the code that receives the parsing result and print out the result.

  • Make sure Laja is installed.
  • Create a Java project in your favourite IDE, for example Eclipse, with the name Example.
  • Select JDK 1.5 or higher.
  • Create this directory structure in the project directory Example:
 +--- src/main/java/example      // java source code, package 'example'
 +--- src/main/laja              // Laja source code
  • Use src/main/java as Java source directory.
  • Add these two jar files to the project class path (where LAJA_HOME is the path to Laja home directory):
    • LAJA_HOME/system-lib/laja.jar
    • LAJA_HOME/system-lib/commons-lang-2.4.jar
  • Create the files example.laja, example.grammar and example.txt in directory src/main/laja:
 +--- src/main/java/example          // java source code, package 'example'
 +--- src/main/laja/example.laja     // the Laja template
 +--- src/main/laja/example.grammar  // defines the grammar rules and the mapping information
 +--- src/main/laja/example.txt      // the text information we want to parse


example.laja:

#generateParser(
  package: "example"
  grammarFile: "{.}/example.grammar"
  outputDir: "{..}/java/example"
)

#generateParserDom(
  replaceExistingFile: true
  package: "example"
  grammarFile: "{.}/example.grammar"
  inputFile: "{.}/example.txt"
  outputDir: "{..}/java/example"
)

example.grammar:

grammar example {
   example = "5";
}

example.txt:

5


To generate the source code, go to directory Example/src/main/laja and write laja example ($> is the prompt):

$> laja example

This will generate the files:

+--- src/main/java/example/ExampleParser.java    // the parser
+--- src/main/java/example/ExampleDomApp.java    // the application that calls the parser and prints out the result
+--- src/main/java/example/ExampleFactory.java   // responsible for creating the 'Example' instance
+--- src/main/java/example/Example.java          // the result from the parsing

If using Eclipse, refresh the project by pressing <F5> on the project Example. Expand the package example and execute the file ExampleDomApp.java, this will print out:

Result: Example{}

(If it didn't work, check that the text file example.txt only contains the character 5)

The result was empty. That is because we haven't specified any receivers of the parsed information. Lets do that, but first take a look at the parsing settings.

Parser generation settings

Laja generates the class ExampleParser.java based on the grammar file example.grammar and the settings in the system function call #generateParser in example.laja:

#generateParser(
  forwardRef: true
  package: "example"
  grammarFile: "{.}/example.grammar"
  outputDir: "{..}/java/example"
)
Attribute Description
forwardRef This parameter is optional and the default value is true so we can leave this out if we want. If the definitions in the grammar only references already defined definitions, then we can set this to false which will generate a little more readable parser source.
package name of the package. All generated java classes will belong to this package.
grammarFile path to the grammar file, {.} means "same directory as the template example.laja".
outputDir path to output directory of generated files, e.g. ExampleParser.java, {..} means "parent directory relative to directory of example.laja".

Output classes generation settings

In this example we also generate the implementation/output classes Example.java, ExampleDomApp.java and ExampleFactory.java based on example.grammar and the settings in the system function call #generateParserDom in example.laja:

#generateParserDom(
  replaceExistingFile: true
  package: "example"
  grammarFile: "{.}/example.grammar"
  inputFile: "{.}/example.txt"
  outputDir: "{..}/java/example"
)
Attribute Description
replaceExistingFile if true, all existing files will be replaced with the generated files.
package name of the package. All generated java classes will belong to this package.
grammarFile path to the grammar file.
inputFile path to the file that we want to read/parse, example.txt in this example
outputDir path to output directory for the generated classes

Edit the file example.grammar:

grammar example {
   digit = "5";
   example = digit;

   Example example;
   example.setDigit(String digit);
}

Generate the source again (go to directory Example/src/main/laja and write laja example) and execute ExampleDomApp.java, this will print out:

Result: Example{digit=5}


This example is explained more in detail in Parser Generator - Documentation.