README in citrus-2.1.2 vs README in citrus-2.2.0
- old
+ new
@@ -111,50 +111,61 @@
## Terminals
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"
+ /abc/i # match "abc" in any case
+ /\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.
+Also, strings may use backticks instead of quotes to indicate that they should
+match in a case-insensitive manner.
+ `abc` # match "abc" in any case
+
+See [Terminal](api/classes/Citrus/Terminal.html) and
+[StringTerminal](api/classes/Citrus/StringTerminal.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" at least once
- 'abc'? # match "abc" a maximum of once
+ 'abc'* # match "abc" zero or more times
+The `+` and `?` operators are supported as well for the common cases of `1*` and
+`*1` respectively.
+
+ 'abc'+ # match "abc" one or more times
+ 'abc'? # match "abc" zero or one time
+
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
that does not match a given expression.
@@ -176,46 +187,82 @@
See [Sequence](api/classes/Citrus/Sequence.html) for more information.
## Choices
Ordered choice is indicated by a vertical bar that separates two expressions.
-Note that any operator binds more tightly than the bar.
+When using choice, each expression is tried in order. When one matches, the
+rule returns the match immediately without trying the remaining rules.
'a' | 'b' # match "a" or "b"
'a' 'b' | 'c' # match "a" then "b" (in sequence), or "c"
+It is important to note when using ordered choice that any operator binds more
+tightly than the vertical bar. A full chart of operators and their respective
+levels of precedence is below.
+
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
their precedence. A higher precedence indicates tighter binding.
Operator | Name | Precedence
--------- | ------------------------- | ----------
'' | String (single quoted) | 6
"" | String (double quoted) | 6
+`` | String (case insensitive) | 6
[] | Character class | 6
. | Dot (any character) | 6
// | Regular expression | 6
() | Grouping | 6
* | Repetition (arbitrary) | 5
@@ -408,45 +455,55 @@
assert_equal('23', match)
assert_equal(23, match.value)
end
end
-The key here is using the `root`
-[option](api/classes/Citrus/GrammarMethods.html#M000031) when performing the
-parse to specify the name of the rule at which the parse should start. In
-`test_number`, since `:number` was given the parse will start at that rule as if
-it were the root rule of the entire grammar. The ability to change the root rule
-on the fly like this enables easy unit testing of the entire grammar.
+The key here is using the `:root` option when performing the parse to specify
+the name of the rule at which the parse should start. In `test_number`, since
+`:number` was given the parse will start at that rule as if it were the root
+rule of the entire grammar. The ability to change the root rule on the fly like
+this enables easy unit testing of the entire grammar.
Also note that because match objects are themselves strings, assertions may be
made to test equality of match objects with string values.
## Debugging
When a parse fails, a [ParseError](api/classes/Citrus/ParseError.html) object is
generated which provides a wealth of information about exactly where the parse
-failed. Using this object, you could possibly provide some useful feedback to
-the user about why the input was bad. The following code demonstrates one way
-to do this.
+failed including the offset, line number, line text, and line offset. Using this
+object, you could possibly provide some useful feedback to the user about why
+the input was bad. The following code demonstrates one way to do this.
def parse_some_stuff(stuff)
match = StuffGrammar.parse(stuff)
rescue Citrus::ParseError => e
raise ArgumentError, "Invalid stuff on line %d, offset %d!" %
[e.line_number, e.line_offset]
end
-In addition to useful error objects, Citrus also includes a special file that
-should help grammar authors when debugging grammars. To get this extra
-functionality, simply `require 'citrus/debug'` instead of `require 'citrus'`
-when running your code.
+In addition to useful error objects, Citrus also includes a means of visualizing
+match trees in the console via `Match#dump`. This can help when determining
+which rules are generating which matches and how they are organized in the
+match tree.
-When debugging is enabled, you can visualize parse trees in the console as XML
-documents. This can help when determining which rules are generating which
-matches and how they are organized in the output. Also when debugging, each
-match object automatically records its offset in the original input, which can
-also be very helpful in keeping track of which offsets in the input generated
-which matches.
+
+# Extras
+
+
+Several files are included in the Citrus repository that make it easier to work
+with grammar files in various editors.
+
+## TextMate
+
+To install the Citrus [TextMate](http://macromates.com/) bundle, simply
+double-click on the `Citrus.tmbundle` file in the `extras` directory.
+
+## Vim
+
+To install the [Vim](http://www.vim.org/) scripts, copy the files in
+`extras/vim` to a directory in Vim's
+[runtimepath](http://vimdoc.sourceforge.net/htmldoc/options.html#\'runtimepath\').
# Links