Permalink
Browse files

Updated syntax docs

  • Loading branch information...
1 parent c5ffff4 commit 42949cf762326befa35b36b3a8bc777a384db869 @mjackson committed Oct 31, 2010
Showing with 110 additions and 50 deletions.
  1. +59 −25 README
  2. +51 −25 doc/syntax.markdown
View
84 README
@@ -113,32 +113,36 @@ already be familiar to Ruby programmers.
Terminals may be represented by a string or a regular expression. Both follow
the same rules as Ruby string and regular expression literals.
- 'abc'
- "abc\n"
- /\xFF/
+ 'abc' # match "abc"
+ "abc\n" # match "abc\n"
+ /\xFF/ # match "\xFF"
Character classes and the dot (match anything) symbol are supported as well for
compatibility with other parsing expression implementations.
[a-z0-9] # match any lowercase letter or digit
[\x00-\xFF] # match any octet
- . # match anything, even new lines
+ . # match any single character, including new lines
See [Terminal](api/classes/Citrus/Terminal.html) for more information.
## Repetition
Quantifiers may be used after any expression to specify a number of times it
-must match. The universal form of a quantifier is N*M where N is the minimum and
-M is the maximum number of times the expression may match.
+must match. The universal form of a quantifier is `N*M` where `N` is the minimum
+and `M` is the maximum number of times the expression may match.
- 'abc'1*2 # match "abc" a minimum of one, maximum
- # of two times
+ 'abc'1*2 # match "abc" a minimum of one, maximum of two times
'abc'1* # match "abc" at least once
'abc'*2 # match "abc" a maximum of twice
-The + and ? operators are supported as well for the common cases of 1* and *1
-respectively.
+Additionally, the minimum and maximum may be omitted entirely to specify that an
+expression may match zero or more times.
+
+ 'abc'* # match "abc" any number of times, including zero
+
+The `+` and `?` operators are supported as well for the common cases of `1*` and
+`*1` respectively.
'abc'+ # match "abc" at least once
'abc'? # match "abc" a maximum of once
@@ -147,12 +151,12 @@ See [Repeat](api/classes/Citrus/Repeat.html) for more information.
## Lookahead
-Both positive and negative lookahead are supported in Citrus. Use the & and !
-operators to indicate that an expression either should or should not match. In
-neither case is any input consumed.
+Both positive and negative lookahead are supported in Citrus. Use the `&` and
+`!` operators to indicate that an expression either should or should not match.
+In neither case is any input consumed.
&'a' 'b' # match a "b" preceded by an "a"
- !'a' 'b' # match a "b" that is not preceded by an "a"
+ 'a' !'b' # match an "a" that is not followed by a "b"
!'a' . # match any character except for "a"
A special form of lookahead is also supported which will match any character
@@ -185,26 +189,56 @@ Note that any operator binds more tightly than the bar.
See [Choice](api/classes/Citrus/Choice.html) for more information.
-## Super
-
-When including a grammar inside another, all rules in the child that have the
-same name as a rule in the parent also have access to the "super" keyword to
-invoke the parent rule.
-
-See [Super](api/classes/Citrus/Super.html) for more information.
-
## Labels
Match objects may be referred to by a different name than the rule that
originally generated them. Labels are created by placing the label and a colon
immediately preceding any expression.
- chars:/[a-z]+/ # the characters matched by the regular
- # expression may be referred to as "chars"
- # in a block method
+ chars:/[a-z]+/ # the characters matched by the regular expression
+ # may be referred to as "chars" in an extension
+ # method
See [Label](api/classes/Citrus/Label.html) for more information.
+## Grouping
+
+As is common in many programming languages, parentheses may be used to override
+the normal binding order of operators.
+
+ 'a' ('b' | 'c') # match "a", then "b" or "c"
+
+## Extensions
+
+Extensions may be specified using either "module" or "block" syntax. When using
+module syntax, specify the name of a module that is used to extend match objects
+in between less than and greater than symbols.
+
+ [a-z0-9]5*9 <CouponCode> # match a string that consists of any lower
+ # cased letter or digit between 5 and 9
+ # times and extend the match with the
+ # CouponCode module
+
+Additionally, extensions may be specified inline using curly braces. Inside the
+curly braces you may embed method definitions that will be used to extend match
+objects.
+
+ # match any digit and return its integer value when calling the
+ # #value method on the match object
+ [0-9] {
+ def value
+ to_i
+ end
+ }
+
+## Super
+
+When including a grammar inside another, all rules in the child that have the
+same name as a rule in the parent also have access to the `super` keyword to
+invoke the parent rule.
+
+See [Super](api/classes/Citrus/Super.html) for more information.
+
## Precedence
The following table contains a list of all Citrus symbols and operators and
View
@@ -10,32 +10,36 @@ already be familiar to Ruby programmers.
Terminals may be represented by a string or a regular expression. Both follow
the same rules as Ruby string and regular expression literals.
- 'abc'
- "abc\n"
- /\xFF/
+ 'abc' # match "abc"
+ "abc\n" # match "abc\n"
+ /\xFF/ # match "\xFF"
Character classes and the dot (match anything) symbol are supported as well for
compatibility with other parsing expression implementations.
[a-z0-9] # match any lowercase letter or digit
[\x00-\xFF] # match any octet
- . # match anything, even new lines
+ . # match any single character, including new lines
See [Terminal](api/classes/Citrus/Terminal.html) for more information.
## Repetition
Quantifiers may be used after any expression to specify a number of times it
-must match. The universal form of a quantifier is N*M where N is the minimum and
-M is the maximum number of times the expression may match.
+must match. The universal form of a quantifier is `N*M` where `N` is the minimum
+and `M` is the maximum number of times the expression may match.
- 'abc'1*2 # match "abc" a minimum of one, maximum
- # of two times
+ 'abc'1*2 # match "abc" a minimum of one, maximum of two times
'abc'1* # match "abc" at least once
'abc'*2 # match "abc" a maximum of twice
-The + and ? operators are supported as well for the common cases of 1* and *1
-respectively.
+Additionally, the minimum and maximum may be omitted entirely to specify that an
+expression may match zero or more times.
+
+ 'abc'* # match "abc" any number of times, including zero
+
+The `+` and `?` operators are supported as well for the common cases of `1*` and
+`*1` respectively.
'abc'+ # match "abc" at least once
'abc'? # match "abc" a maximum of once
@@ -44,12 +48,12 @@ See [Repeat](api/classes/Citrus/Repeat.html) for more information.
## Lookahead
-Both positive and negative lookahead are supported in Citrus. Use the & and !
-operators to indicate that an expression either should or should not match. In
-neither case is any input consumed.
+Both positive and negative lookahead are supported in Citrus. Use the `&` and
+`!` operators to indicate that an expression either should or should not match.
+In neither case is any input consumed.
&'a' 'b' # match a "b" preceded by an "a"
- !'a' 'b' # match a "b" that is not preceded by an "a"
+ 'a' !'b' # match an "a" that is not followed by a "b"
!'a' . # match any character except for "a"
A special form of lookahead is also supported which will match any character
@@ -82,26 +86,48 @@ Note that any operator binds more tightly than the bar.
See [Choice](api/classes/Citrus/Choice.html) for more information.
-## Super
-
-When including a grammar inside another, all rules in the child that have the
-same name as a rule in the parent also have access to the "super" keyword to
-invoke the parent rule.
-
-See [Super](api/classes/Citrus/Super.html) for more information.
-
## Labels
Match objects may be referred to by a different name than the rule that
originally generated them. Labels are created by placing the label and a colon
immediately preceding any expression.
- chars:/[a-z]+/ # the characters matched by the regular
- # expression may be referred to as "chars"
- # in a block method
+ chars:/[a-z]+/ # the characters matched by the regular expression
+ # may be referred to as "chars" in an extension
+ # method
See [Label](api/classes/Citrus/Label.html) for more information.
+## Grouping
+
+As is common in many programming languages, parentheses may be used to override
+the normal binding order of operators.
+
+ 'a' ('b' | 'c') # match "a", then "b" or "c"
+
+## Extensions
+
+Extensions may be specified using either "module" or "block" syntax. When using
+module syntax, specify the name of a module that is used to extend match objects
+in between less than and greater than symbols.
+
+ [a-z0-9]5*9 <CouponCode> # match a string that consists of any lower
+ # cased letter or digit between 5 and 9
+ # times and extend the match with the
+ # CouponCode module
+
+Additionally, extensions may be specified inline using curly braces. Inside the
+curly braces you may embed method definitions that will be used to extend match
+objects.
+
+ # match any digit and return its integer value when calling the
+ # #value method on the match object
+ [0-9] {
+ def value
+ to_i
+ end
+ }
+
## Precedence
The following table contains a list of all Citrus symbols and operators and

0 comments on commit 42949cf

Please sign in to comment.