You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@velocity.apache.org by jv...@locus.apache.org on 2000/08/28 10:58:12 UTC
cvs commit: jakarta-velocity/src/java/org/apache/velocity/parser Parser.jjt
jvanzyl 00/08/28 01:58:11
Modified: src/java/org/apache/velocity/parser Parser.jjt
Log:
- add documentation for all node types.
Revision Changes Path
1.4 +178 -75 jakarta-velocity/src/java/org/apache/velocity/parser/Parser.jjt
Index: Parser.jjt
===================================================================
RCS file: /home/cvs/jakarta-velocity/src/java/org/apache/velocity/parser/Parser.jjt,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- Parser.jjt 2000/08/27 22:18:08 1.3
+++ Parser.jjt 2000/08/28 08:58:10 1.4
@@ -106,9 +106,16 @@
import java.util.*;
/**
- * Each ASTNode will have access to an instance of
- * this parser. So we will use the parser as a container
- * for useful information.
+ * This class is responsible for parsing a Velocity
+ * template. This class was generated by JavaCC using
+ * the JJTree extension to produce an Abstract
+ * Syntax Tree (AST) of the template.
+ *
+ * Please look at the Parser.jjt file which is
+ * what controls the generation of this class.
+ *
+ * @author <a href="mailto:jvanzyl@periapt.com">Jason van Zyl</a>
+ * @version $Id: Parser.jjt,v 1.4 2000/08/28 08:58:10 jvanzyl Exp $
*/
public class Parser
{
@@ -370,25 +377,29 @@
}
}
}
-
-/* ------------------------------------------------------------------------
- *
- * Program structuring syntax follows.
- *
- * ------------------------------------------------------------------------- */
+/**
+ * This method is what starts the whole parsing
+ * process. After the parsing is complete and
+ * the template has been turned into an AST,
+ * this method returns the root of AST which
+ * can subsequently be traversed by a visitor
+ * which implements the ParserVisitor interface
+ * which is generated automatically by JavaCC
+ */
SimpleNode process() : {}
{
( Statement() )* <EOF>
{ return jjtThis; }
}
-
-/* ------------------------------------------------------------------------
- *
- * Statement syntax.
- * | Block()
- * ------------------------------------------------------------------------- */
+/**
+ * These are the types of statements that
+ * are acceptable in Velocity templates.
+ * I have not found that the order here
+ * matters much. Someone please correct
+ * me here if I'm wrong.
+ */
void Statement() #void : {}
{
Text()
@@ -407,13 +418,28 @@
}
+/**
+ * This method corresponds to the #stop
+ * directive which just simulates and EOF
+ * so that parsing stops. The #stop directive
+ * is really only useful for debugging
+ * purposes.
+ */
void StopStatement() #void: {}
{
<STOP_DIRECTIVE>
}
/**
- * $dynamicContent
+ * This method corresponds to variable
+ * references in Velocity templates.
+ * The following are examples of variable
+ * references that may be found in a
+ * template:
+ *
+ * $foo
+ * $bar
+ *
*/
void Variable() : {}
{
@@ -421,24 +447,56 @@
}
/**
- * $customer.Title
+ * This method corresponds to property
+ * references in Velocity templates.
+ * The following are examples of property
+ * references that my be found in a
+ * template:
+ *
+ * $foo.Bar
+ *
+ * Say the object $foo corresponds to foo
+ * in the context, then the following
+ * method will be invoked:
+ *
+ * foo.getBar()
+ *
*/
void Property() : {}
{
<PROPERTY>
}
+/**
+ * This method has yet to be fully implemented
+ * but will allow arbitrarily nested method
+ * calls
+ */
void Parameter() : {}
{
<STRING_LITERAL> | <VARIABLE> | <PROPERTY> | Method()
}
+/**
+ * This method has yet to be fully implemented
+ * but will allow arbitrarily nested method
+ * calls
+ */
void Parameters() : {}
{
"(" [ Parameter() ( "," Parameter() )* ] ")"
}
-
+/**
+ * This method corresponds to a method
+ * reference in a Velocity template.
+ * The following are examples of method
+ * references that may be found in a
+ * template:
+ *
+ * $foo.getBar()
+ *
+ */
void Method() : {}
{
<METHOD>
@@ -448,38 +506,51 @@
//"$" <IDENTIFIER> "." <IDENTIFIER> "(" ")"
}
-/* ------------------------------------------------------------------------
- *
- * This has to be seriously expanded to be
- * compatible with WebMacro, and to be generally
- * useful.
- *
+/**
* We're not using this right now, I'm going to look
* at borrowing the expression grammar from one of
* the java grammars, there is also an example
* of it in one of the examples, I'm going to leave
* if out right now to keep things simple for now.
*
- * ------------------------------------------------------------------------- */
-
+ * This will eventually allow constructs like
+ *
+ * #if ($this && $that)
+ *
+ * or
+ *
+ * #if ($that || $that)
+ *
+ * And eventually more complicated constructs.
+ *
+ */
void Expression() : {}
{
Variable()
}
-
-/* ------------------------------------------------------------------------
- * I'm going to have to change the way blocks are detected
- * in order to allow javascript to work correctly.
- * ------------------------------------------------------------------------- */
+/**
+ * This method corresponds to a block in
+ * a Velocity template. Blocks are
+ * currently associated with:
+ *
+ * #if
+ * #foreach
+ * #while (not implemented)
+ *
+ */
void Block() : {}
{
<LBRACKET> ( Statement() )* <RBRACKET>
}
-/* ------------------------------------------------------------------------
+/**
+ * This method corresponds to an #if directive
+ * in a Velocity template. The following are
+ * examples if #if constructs that are
+ * acceptable in a template:
*
- * #if ($customer.owesMoney() && $customer.Name == "Fred")
+ * #if ($customer.owesMoney() && $customer.Name == "Fred") (not implemented)
* {
* Pay up, or else!
* }
@@ -490,14 +561,15 @@
*
* #if ($dynanmicContent)
* {
+ * This is our $dynamicContent
* }
*
* #if ($customer.owesMoney())
* {
+ * You better pay up!
* }
*
- * ------------------------------------------------------------------------- */
-
+ */
void IfStatement() : {}
{
<IF_DIRECTIVE>
@@ -508,11 +580,29 @@
[ LOOKAHEAD(1) <ELSE_DIRECTIVE> Statement() ]
}
-/* ------------------------------------------------------------------------
+/**
+ * This method corresponds to a #foreach
+ * directive in a Velocity template. The
+ * following are examples of #foreach
+ * constructs that are acceptable in
+ * a template:
*
+ * #foreach $element in $list
+ * {
+ * This is the fifth $element
+ * }
*
- * ------------------------------------------------------------------------- */
-
+ * #foreach $element in $foo.List
+ * {
+ * This is the fifth $element
+ * }
+ *
+ * #foreach $element in $foo.getList()
+ * {
+ * This is the fifth $element
+ * }
+ *
+ */
void ForeachStatement() : {}
{
<FOREACH_DIRECTIVE>
@@ -522,29 +612,33 @@
Statement()
}
-/* ------------------------------------------------------------------------
- *
- * This should allow path character, and it should
- * expand macros before processing.
+/**
+ * This method corresponds to an #include
+ * directive in a Velocity template. The
+ * following are examples of #include
+ * constructs that are acceptable in
+ * a template:
*
- * ------------------------------------------------------------------------- */
-
+ * #include "foo.inc"
+ */
void IncludeStatement() #void: {}
{
<INCLUDE_DIRECTIVE>
<STRING_LITERAL>
}
-/* ------------------------------------------------------------------------
+/**
+ * This method corresponds to a #set
+ * directive in a Velocity template. The
+ * following are examples of #set
+ * constructs that are acceptable in
+ * a template:
*
* #set name = "Fred"
* #set $Customer.Name = "Sidney"
- * #set $Database.findItem($partNum).Description = $newDescription
- *
- * I can only do the first right now.
+ * #set $Database.findItem($partNum).Description = $newDescription (not implemented)
*
- * ------------------------------------------------------------------------- */
-
+ */
void SetStatement() : {}
{
<SET_DIRECTIVE>
@@ -553,50 +647,59 @@
( <STRING_LITERAL> | <VARIABLE> | <PROPERTY> | <METHOD> | <TRUE> | <FALSE> )
}
-/* ------------------------------------------------------------------------
- *
- * This should allow path character, and it should
- * expand macros before processing. There is some code
- * on the mailing list for an #include type instruction
- * which is exactly what I need here.
+/**
+ * This method corresponds to a #parse
+ * directive in a Velocity template. The
+ * following are examples of #parse
+ * constructs that are acceptable in
+ * a template:
*
- * ------------------------------------------------------------------------- */
-
+ * #parse "bar.vt"
+ */
void ParseStatement() #void: {}
{
<PARSE_DIRECTIVE> <STRING_LITERAL>
}
-/* ------------------------------------------------------------------------
- *
- * I don't care about this right now, I've never
- * seen anyone use it.
+/**
+ * This method corresponds to a #use
+ * directive in a Velocity template. The
+ * following are examples of #use
+ * constructs that are acceptable in
+ * a template:
+ *
+ * This has not been implemented and may
+ * not need to be because the Velocity
+ * parser doesn't have any problem with
+ * normal text that isn't part of Velocity's
+ * grammar.
*
- * ------------------------------------------------------------------------- */
-
+ */
void UseStatement() : {}
{
<USE_DIRECTIVE>
}
-/* ------------------------------------------------------------------------
+/**
+ * This method corresponds to a #param
+ * directive in a Velocity template. The
+ * following are examples of #param
+ * constructs that are acceptable in
+ * a template:
*
- * #param author = "Joe"
- * #param require = [ "user", "document", "session" ]
+ * #param $language = "en"
*
- * ------------------------------------------------------------------------- */
-
+ */
void ParamStatement() : {}
{
<PARAM_DIRECTIVE> <VARIABLE> <EQUALS> <STRING_LITERAL>
}
-
-/* ------------------------------------------------------------------------
- *
- * How to cleanly extract all the text (including html).
- *
- * ------------------------------------------------------------------------- */
+/**
+ * This method is responsible for allowing
+ * all non-grammar text to pass through
+ * unscathed.
+ */
void Text() : {}
{
<TEXT>