simplereadme.html

This a JavaCC documentation.

	javacc Simple1.jj
	javac *.java

Now you should be able to run the generated parser.  Make sure that
the current directory is in your CLASSPATH and type:

	java Simple1

Now type a sequence of matching braces followed by a return and an end
of file (CTRL-D on UNIX machines).  If this is a problem on your
machine, you can create a file and pipe it as input to the generated
parser in this manner (piping also does not work on all machines - if
this is a problem, just replace "System.in" in the grammar file with
'new FileInputStream("testfile")' and place your input inside this
file):

	java Simple1 < myfile

Also try entering illegal sequences such as mismatched braces, spaces,
and carriage returns between braces as well as other characters and
take a look at the error messages produced by the parser.

---------------------------------------------------------------------

DETAILED DESCRIPTION OF Simple2.jj:

Simple2.jj is a minor modification to Simple1.jj to allow white space
characters to be interspersed among the braces.  So then input such
as:

	"{{  }\n}\n\n"

will now be legal.

Take a look at Simple2.jj.  The first thing you will note is that we
have omitted the options section.  This does not change anything since
the options in Simple1.jj were all assigned their default values.

The other difference between this file and Simple1.jj is that this
file contains a lexical specification - the region that starts with
"SKIP".  Within this region are 4 regular expressions - space, tab,
newline, and return.  This says that matches of these regular
expressions are to be ignored (and not considered for parsing).  Hence
whenever any of these 4 characters are encountered, they are just
thrown away.

In addition to SKIP, JavaCC has three other lexical specification
regions.  These are:

. TOKEN:         This is used to specify lexical tokens (see next example)
. SPECIAL_TOKEN: This is used to specify lexical tokens that are to be
                 ignored during parsing.  In this sense, SPECIAL_TOKEN is
                 the same as SKIP.  However, these tokens can be recovered
                 within parser actions to be handled appropriately.
. MORE:          This specifies a partial token.  A complete token is
                 made up of a sequence of MORE's followed by a TOKEN
                 or SPECIAL_TOKEN.

Please take a look at some of the more complex grammars such as the
Java grammars for examples of usage of these lexical specification
regions.

You may build Simple2 and invoke the generated parser with input from
the keyboard as standard input.

You can also try generating the parser with the various debug options
turned on and see what the output looks like.  To do this type:

	javacc -debug_parser Simple2.jj
	javac Simple2*.java
	java Simple2

Then type:

	javacc -debug_token_manager Simple2.jj
	javac Simple2*.java
	java Simple2

Note that token manager debugging produces a lot of diagnostic
information and it is typically used to look at debug traces a single
token at a time.

---------------------------------------------------------------------

DETAILED DESCRIPTION OF Simple3.jj:

Simple3.jj is the third and final version of our matching brace
detector.  This example illustrates the use of the TOKEN region for
specifying lexical tokens.  In this case, "{" and "}" are defined as
tokens and given names LBRACE and RBRACE respectively.  These labels
can then be used within angular brackets (as in the example) to refer
to this token.  Typically such token specifications are used for
complex tokens such as identifiers and literals.  Tokens that are
simple strings are left as is (in the previous examples).

This example also illustrates the use of actions in the grammar
productions.  The actions inserted in this example count the number of
matching braces.  Note the use of the declaration region to declare
variables "count" and "nested_count".  Also note how the non-terminal
"MatchedBraces" returns its value as a function return value.

---------------------------------------------------------------------

DETAILED DESCRIPTION OF NL_Xlator.jj:

This example goes into the details of writing regular expressions in
JavaCC grammar files.  It also illustrates a slightly more complex set
of actions that translate the expressions described by the grammar
into English.

The new concept in the above example is the use of more complex
regular expressions.  The regular expression:

  < ID: ["a"-"z","A"-"Z","_"] ( ["a"-"z","A"-"Z","_","0"-"9"] )* >

creates a new regular expression whose name is ID.  This can be
referred anywhere else in the grammar simply as <ID>.  What follows in
square brackets are a set of allowable characters - in this case it is
any of the lower or upper case letters or the underscore.  This is
followed by 0 or more occurrences of any of the lower or upper case
letters, digits, or the underscore.

Other constructs that may appear in regular expressions are:

  ( ... )+	: One or more occurrences of ...
  ( ... )?	: An optional occurrence of ... (Note that in the case
                  of lexical tokens, (...)? and [...] are not equivalent)
  ( r1 | r2 | ... ) : Any one of r1, r2, ...

A construct of the form [...] is a pattern that is matched by the
characters specified in ... .  These characters can be individual
characters or character ranges.  A "~" before this construct is a
pattern that matches any character not specified in ... .  Therefore:

  ["a"-"z"] matches all lower case letters
  ~[] matches any character
  ~["\n","\r"] matches any character except the new line characters

When a regular expression is used in an expansion, it takes a value of
type "Token".  This is generated into the generated parser directory
as "Token.java".  In the above example, we have defined a variable of
type "Token" and assigned the value of the regular expression to it.

---------------------------------------------------------------------

DETAILED DESCRIPTION OF IdList.jj:

This example illustrates an important attribute of the SKIP
specification.  The main point to note is that the regular expressions
in the SKIP specification are only ignored *between tokens* and not
*within tokens*.  This grammar accepts any sequence of identifiers
with white space in between.

A legal input for this grammar is:

"abc xyz123 A B C \t\n aaa"

This is because any number of the SKIP regular expressions are allowed
in between consecutive <Id>'s.  However, the following is not a legal
input:

"xyz 123"

This is because the space character after "xyz" is in the SKIP
category and therefore causes one token to end and another to begin.
This requires "123" to be a separate token and hence does not match
the grammar.

If spaces were OK within <Id>'s, then all one has to do is to replace
the definition of Id to:

TOKEN :
{
  < Id: ["a"-"z","A"-"Z"] ( (" ")* ["a"-"z","A"-"Z","0"-"9"] )* >
}

Note that having a space character within a TOKEN specification does
not mean that the space character cannot be used in the SKIP
specification.  All this means is that any space character that
appears in the context where it can be placed within an identifier
will participate in the match for <Id>, whereas all other space
characters will be ignored.  The details of the matching algorithm are
described in the JavaCC documentation in the web pages.

As a corollary, one must define as tokens anything within which
characters such as white space characters must not be present.  In the
above example, if <Id> was defined as a grammar production rather than
a lexical token as shown below this paragraph, then "xyz 123" would
have been recognized as a legitimate <Id> (wrongly).

void Id() :
{}
{
  <["a"-"z","A"-"Z"]> ( <["a"-"z","A"-"Z","0"-"9"]> )*
}

Note that in the above definition of non-terminal Id, it is made up of
a sequence of single character tokens (note the location of <...>s),
and hence white space is allowed between these characters.

---------------------------------------------------------------------
</PRE>

</BODY>
</HTML>