citrus 1.8.0 → 2.0.0

data/README

@@ -56,9 +56,9 @@ A [Rule](api/classes/Citrus/Rule.html) is an object that specifies some matching
 behavior on a string. There are two types of rules: terminals and non-terminals.
 Terminals can be either Ruby strings or regular expressions that specify some
 input to match. For example, a terminal created from the string "end" would
-match any sequence of the characters "e", "n", and "d", in that order. A
-terminal created from a regular expression uses Ruby's regular expression engine
-to attempt to create a match.
+match any sequence of the characters "e", "n", and "d", in that order. Terminals
+created from regular expressions may match any sequence of characters that can
+be generated from that expression.
 
 Non-terminals are rules that may contain other rules but do not themselves match
 directly on the input. For example, a Repeat is a non-terminal that may contain
@@ -85,10 +85,10 @@ similar to Ruby's super keyword.
 ## Matches
 
 Matches are created by rule objects when they match on the input. A 
-[Match](api/classes/Citrus/Match.html) in Citrus is actually a 
-[String](http://ruby-doc.org/core/classes/String.html) with some extra 
-information attached such as the name(s) of the rule(s) which generated the 
-match as well as its offset in the original input string.
+[Match](api/classes/Citrus/Match.html) is actually a 
+[String](http://ruby-doc.org/core/classes/String.html) object with some extra 
+information attached such as the name(s) of the rule(s) from which it was
+generated and any submatches it may contain.
 
 During a parse, matches are arranged in a tree structure where any match may
 contain any number of other matches. This structure is determined by the way in
@@ -97,9 +97,8 @@ match that is created from a non-terminal rule that contains several other
 terminals will likewise contain several matches, one for each terminal.
 
 Match objects may be extended with semantic information in the form of methods.
-These methods can interpret the text of a match using the wealth of information
-available to them including the text of the match, its position in the input,
-and any submatches.
+These methods should provide various interpretations for the semantic value of a
+match.
 
 
 # Syntax
@@ -125,8 +124,7 @@ compatibility with other parsing expression implementations.
     [\x00-\xFF]   # match any octet
     .             # match anything, even new lines
 
-See [FixedWidth](api/classes/Citrus/FixedWidth.html) and
-[Expression](api/classes/Citrus/Expression.html) for more information.
+See [Terminal](api/classes/Citrus/Terminal.html) for more information.
 
 ## Repetition
 
@@ -212,25 +210,25 @@ See [Label](api/classes/Citrus/Label.html) for more information.
 The following table contains a list of all Citrus operators and their 
 precedence. A higher precedence indicates tighter binding.
 
-| Operator    | Name                      | Precedence |
-| ----------- | ------------------------- | ---------- |
-| ''          | String (single quoted)    | 6          |
-| ""          | String (double quoted)    | 6          |
-| []          | Character class           | 6          |
-| .           | Dot (any character)       | 6          |
-| //          | Regular expression        | 6          |
-| ()          | Grouping                  | 6          |
-| *           | Repetition (arbitrary)    | 5          |
-| +           | Repetition (one or more)  | 5          |
-| ?           | Repetition (zero or one)  | 5          |
-| &           | And predicate             | 4          |
-| !           | Not predicate             | 4          |
-| ~           | But predicate             | 4          |
-| :           | Label                     | 4          |
-| <>          | Extension (module name)   | 3          |
-| {}          | Extension (literal)       | 3          |
-| e1 e2       | Sequence                  | 2          |
-| e1 | e2     | Ordered choice            | 1          |
+Operator    | Name                      | Precedence
+----------- | ------------------------- | ----------
+''          | String (single quoted)    | 6
+""          | String (double quoted)    | 6
+[]          | Character class           | 6
+.           | Dot (any character)       | 6
+//          | Regular expression        | 6
+()          | Grouping                  | 6
+*           | Repetition (arbitrary)    | 5
++           | Repetition (one or more)  | 5
+?           | Repetition (zero or one)  | 5
+&           | And predicate             | 4
+!           | Not predicate             | 4
+~           | But predicate             | 4
+:           | Label                     | 4
+<>          | Extension (module name)   | 3
+{}          | Extension (literal)       | 3
+e1 e2       | Sequence                  | 2
+e1 | e2     | Ordered choice            | 1
 
 
 # Example
@@ -282,9 +280,9 @@ Submatches are created whenever a rule contains another rule. For example, in
 the grammar above the number rule matches a string of digits followed by white
 space. Thus, a match generated by the number rule will contain two submatches.
 
-We can use Ruby's block syntax to create a module that will be attached to these
-matches when they are created and is used to lazily extend them when we want to
-interpret them. The following example shows one way to do this.
+We can define methods inside a set of curly braces that will be used to extend
+matches when they are created. This works in similar fashion to using Ruby's
+blocks. Let's extend the `Addition` grammar using this technique.
 
     grammar Addition
       rule additive
@@ -318,25 +316,27 @@ on all match objects that result from matches of those particular rules. It's
 easiest to explain what is going on here by starting with the lowest level
 block, which is defined within the number rule.
 
-The semantic block associated with the number rule defines one method, value.
+The semantic block associated with the number rule defines one method, `value`.
 Inside this method, we can see that the value of a number match is determined to
-be its text value, stripped of white space and converted to an integer. Remember
-that matches are simply strings, so the `strip` method in this case is actually
-`String#strip`.
-
-The `additive` rule also extends its matches with a value method. Notice the use
-of the `term` label within the rule definition. This label allows the match that
-is created by either the additive or the number rule to be retrieved using the
-`term` label. The value of an additive is determined to be the values of its
+be its text value, stripped of white space and converted to an integer.
+[Remember](background.html) that matches are simply strings, so the `strip`
+method in this case is actually
+[String#strip](http://ruby-doc.org/core/classes/String.html#M000820).
+
+The `additive` rule also extends its matches with a `value` method. Notice the
+use of the `term` label within the rule definition. This label allows the match
+that is created by either the additive or the number rule to be retrieved using
+the `term` label. The value of an additive is determined to be the values of its
 `number` and `term` matches added together using Ruby's addition operator.
 
 Since additive is the first rule defined in the grammar, any match that results
 from parsing a string with this grammar will have a `value` method that can be
 used to recursively calculate the collective value of the entire match tree.
 
-To give it a try, save the code for the Addition grammar in a file called
-addition.citrus. Next, assuming you have the Citrus gem installed, try the
-following sequence of commands in a terminal.
+To give it a try, save the code for the `Addition` grammar in a file called
+addition.citrus. Next, assuming you have the Citrus
+[gem](https://rubygems.org/gems/citrus) installed, try the following sequence of
+commands in a terminal.
 
     $ irb
     > require 'citrus'
@@ -350,6 +350,13 @@ following sequence of commands in a terminal.
 
 Congratulations! You just ran your first piece of Citrus code.
 
+One interesting thing to notice about the above sequence of commands is the
+return value of [Citrus#load](api/classes/Citrus.html#M000003). When you use
+`Citrus.load` to
+load a grammar file (and likewise [Citrus#eval](api/classes/Citrus.html#M000004) to evaluate
+a raw string of grammar code), the return value is an array of all the grammars
+present in that file.
+
 Take a look at 
 [examples/calc.citrus](http://github.com/mjijackson/citrus/blob/master/examples/calc.citrus)
 for an example of a calculator that is able to parse and evaluate more complex 

data/benchmark/after.dat

@@ -0,0 +1,192 @@
+12 0
+30 0
+35 0
+1749 9
+1962 9
+2383 10
+3728 19
+3919 19
+3952 19
+3995 30
+4063 19
+4325 20
+4527 29
+4570 20
+4607 20
+4654 19
+4679 19
+4774 29
+4968 20
+5059 30
+5383 19
+5915 29
+6109 30
+6122 20
+6218 39
+6332 49
+6681 29
+7440 50
+7530 30
+7605 40
+8155 60
+8402 49
+8420 60
+8617 50
+8635 69
+8841 60
+8843 40
+8852 70
+9151 59
+9271 50
+9521 70
+9525 49
+9566 40
+9584 60
+9642 40
+10138 40
+10181 70
+10225 49
+10338 49
+10449 70
+10629 60
+10763 69
+10817 50
+11059 50
+11062 70
+11215 60
+11698 50
+11891 89
+11945 89
+11956 49
+12018 50
+12053 89
+12178 69
+12283 70
+12326 70
+12430 79
+12438 80
+12572 60
+12638 70
+12687 80
+12703 80
+12896 89
+12922 90
+12996 70
+13137 80
+13211 80
+13462 69
+13477 59
+13576 80
+13577 70
+13584 89
+13605 80
+13631 80
+14216 99
+14237 70
+14260 89
+14367 80
+14371 80
+14741 110
+14893 89
+14910 89
+14917 70
+14977 70
+15049 89
+15191 89
+15382 89
+15618 100
+15623 89
+15629 70
+15856 100
+16496 100
+16512 109
+16956 110
+17074 99
+17237 89
+17371 80
+17568 120
+17945 80
+18147 100
+18343 99
+18417 89
+18823 89
+18970 109
+19285 89
+19333 120
+19500 109
+19548 109
+19634 120
+19673 120
+19689 109
+19909 109
+20054 110
+20107 120
+20248 109
+20580 120
+20744 109
+20806 120
+20954 120
+21034 120
+21187 100
+21303 119
+21450 129
+21626 139
+21931 129
+21950 100
+22359 119
+22626 119
+22638 120
+22772 130
+22885 119
+22897 160
+23114 150
+23242 120
+23428 150
+23452 110
+23495 159
+23499 120
+23558 140
+23744 120
+23881 120
+23945 130
+24361 149
+24501 119
+24642 139
+24672 139
+24694 160
+24706 150
+24931 129
+25065 130
+25140 130
+25402 160
+25702 150
+25743 140
+27139 160
+27316 129
+27333 149
+27414 170
+27771 139
+27798 139
+28583 150
+28906 160
+29025 179
+29209 160
+29272 179
+29273 150
+29359 140
+29577 160
+30886 189
+31170 169
+31593 199
+32460 230
+32486 180
+32630 179
+33010 199
+33137 189
+33142 189
+33739 180
+39880 229
+39940 220
+42952 269
+43227 240
+52855 290

data/benchmark/before.dat

@@ -0,0 +1,192 @@
+12 0
+30 0
+35 0
+1749 19
+1962 9
+2383 20
+3728 29
+3919 30
+3952 29
+3995 30
+4063 20
+4325 30
+4527 30
+4570 50
+4607 49
+4654 49
+4679 29
+4774 30
+4968 80
+5059 89
+5383 39
+5915 59
+6109 40
+6122 80
+6218 99
+6332 39
+6681 89
+7440 89
+7530 70
+7605 39
+8155 89
+8402 60
+8420 99
+8617 89
+8635 110
+8841 99
+8843 89
+8852 89
+9151 70
+9271 99
+9521 89
+9525 89
+9566 80
+9584 80
+9642 59
+10138 119
+10181 89
+10225 80
+10338 99
+10449 99
+10629 109
+10763 109
+10817 120
+11059 100
+11062 99
+11215 100
+11698 79
+11891 130
+11945 109
+11956 109
+12018 129
+12053 100
+12178 130
+12283 110
+12326 119
+12430 99
+12438 109
+12572 109
+12638 120
+12687 120
+12703 110
+12896 109
+12922 119
+12996 99
+13137 109
+13211 140
+13462 120
+13477 120
+13576 130
+13577 109
+13584 109
+13605 119
+13631 120
+14216 129
+14237 119
+14260 129
+14367 120
+14371 140
+14741 140
+14893 120
+14910 120
+14917 140
+14977 100
+15049 140
+15191 130
+15382 129
+15618 130
+15623 139
+15629 129
+15856 140
+16496 120
+16512 149
+16956 160
+17074 130
+17237 150
+17371 149
+17568 150
+17945 160
+18147 140
+18343 140
+18417 160
+18823 189
+18970 140
+19285 149
+19333 169
+19500 149
+19548 170
+19634 160
+19673 160
+19689 200
+19909 169
+20054 150
+20107 199
+20248 169
+20580 179
+20744 160
+20806 170
+20954 179
+21034 160
+21187 170
+21303 209
+21450 169
+21626 179
+21931 160
+21950 179
+22359 179
+22626 190
+22638 200
+22772 200
+22885 199
+22897 189
+23114 190
+23242 170
+23428 210
+23452 190
+23495 209
+23499 209
+23558 220
+23744 200
+23881 199
+23945 189
+24361 200
+24501 199
+24642 219
+24672 199
+24694 190
+24706 199
+24931 210
+25065 190
+25140 210
+25402 199
+25702 199
+25743 219
+27139 240
+27316 239
+27333 250
+27414 209
+27771 210
+27798 229
+28583 240
+28906 240
+29025 259
+29209 219
+29272 249
+29273 250
+29359 230
+29577 250
+30886 279
+31170 259
+31593 259
+32460 300
+32486 269
+32630 280
+33010 269
+33137 270
+33142 259
+33739 289
+39880 349
+39940 359
+42952 359
+43227 360
+52855 450