Permalink
Browse files

Tweaked some docs

  • Loading branch information...
mjackson committed Jan 17, 2011
1 parent 8d0ff78 commit c2aafec7a93a2edcfa2db4ce2e6727801d05a7d4
Showing with 47 additions and 51 deletions.
  1. +9 −9 README
  2. +9 −9 doc/syntax.markdown
  3. +23 −23 lib/citrus.rb
  4. +6 −10 lib/citrus/file.rb
View
18 README
@@ -206,15 +206,6 @@ levels of precedence is below.
See [Choice](api/classes/Citrus/Choice.html) for more information.
-## Grouping
-
-As is common in many programming languages, parentheses may be used to override
-the normal binding order of operators. In the following example parentheses are
-used to make the vertical bar between `'b'` and `'c'` bind tighter than the
-space between `'a'` and `'b'`.
-
- 'a' ('b' | 'c') # match "a", then "b" or "c"
-
## Labels
Match objects may be referred to by a different name than the rule that
@@ -299,6 +290,15 @@ Operator | Name | Precedence
e1 e2 | Sequence | 2
e1 | e2 | Ordered choice | 1
+## Grouping
+
+As is common in many programming languages, parentheses may be used to override
+the normal binding order of operators. In the following example parentheses are
+used to make the vertical bar between `'b'` and `'c'` bind tighter than the
+space between `'a'` and `'b'`.
+
+ 'a' ('b' | 'c') # match "a", then "b" or "c"
+
# Example
View
@@ -104,15 +104,6 @@ levels of precedence is below.
See [Choice](api/classes/Citrus/Choice.html) for more information.
-## Grouping
-
-As is common in many programming languages, parentheses may be used to override
-the normal binding order of operators. In the following example parentheses are
-used to make the vertical bar between `'b'` and `'c'` bind tighter than the
-space between `'a'` and `'b'`.
-
- 'a' ('b' | 'c') # match "a", then "b" or "c"
-
## Labels
Match objects may be referred to by a different name than the rule that
@@ -196,3 +187,12 @@ Operator | Name | Precedence
`:` | Label | 3
`e1 e2` | Sequence | 2
<code>e1 &#124; e2</code> | Ordered choice | 1
+
+## Grouping
+
+As is common in many programming languages, parentheses may be used to override
+the normal binding order of operators. In the following example parentheses are
+used to make the vertical bar between `'b'` and `'c'` bind tighter than the
+space between `'a'` and `'b'`.
+
+ 'a' ('b' | 'c') # match "a", then "b" or "c"
View
@@ -21,11 +21,13 @@ module Citrus
@cache = {}
- # Returns a map of paths of files that have been loaded via Citrus.load to the
- # result of Citrus.eval on the code in that file. Note: These paths are not
- # absolute unless you pass an absolute path to Citrus.load. That means that
- # if you change the working directory and try to require the same file with
- # a different relative path, it will be loaded twice.
+ # Returns a map of paths of files that have been loaded via #load to the
+ # result of #eval on the code in that file.
+ #
+ # Note: These paths are not absolute unless you pass an absolute path to
+ # #load. That means that if you change the working directory and try to
+ # #require the same file with a different relative path, it will be loaded
+ # twice.
def self.cache
@cache
end
@@ -48,7 +50,7 @@ def self.eval(code, options={})
end
# Evaluates the given expression and creates a new Rule object from it.
- # Accepts the same +options+ as Citrus.eval.
+ # Accepts the same +options+ as #eval.
#
# Citrus.rule('"a" | "b"')
# # => #<Citrus::Rule: ... >
@@ -58,10 +60,10 @@ def self.rule(expr, options={})
end
# Loads the grammar(s) from the given +file+. Accepts the same +options+ as
- # Citrus.eval, plus the following:
+ # #eval, plus the following:
#
- # force:: Normally Citrus.load will not reload a file that is already in
- # Citrus.cache. However, if this option is +true+ the file will be
+ # force:: Normally this method will not reload a file that is already in
+ # the #cache. However, if this option is +true+ the file will be
# loaded, regardless of whether or not it is in the cache. Defaults
# to +false+.
#
@@ -87,10 +89,9 @@ def self.load(file, options={})
@cache[file]
end
- # Searches the +$LOAD_PATH+ for a +file+ with the .citrus suffix and
- # attempts to load it via #load. Returns the path to the file that was
- # loaded on success, +nil+ on failure. Accepts the same +options+ as
- # Citrus.load.
+ # Searches the <tt>$LOAD_PATH</tt> for a +file+ with the .citrus suffix and
+ # attempts to load it via #load. Returns the path to the file that was loaded
+ # on success, +nil+ on failure. Accepts the same +options+ as #load.
#
# path = Citrus.require('mygrammar')
# # => "/path/to/mygrammar.citrus"
@@ -115,7 +116,7 @@ def self.require(file, options={})
found
end
- # A standard error class that all Citrus errors extend.
+ # A base class for all Citrus errors.
class Error < RuntimeError; end
# Raised when a parse fails.
@@ -332,7 +333,7 @@ module Grammar
# created with this method may be assigned a name by being assigned to some
# constant, e.g.:
#
- # Calc = Citrus::Grammar.new {}
+ # MyGrammar = Citrus::Grammar.new {}
#
def self.new(&block)
mod = Module.new { include Grammar }
@@ -381,8 +382,7 @@ def included_grammars
end
# Returns an array of all names of rules in this grammar as symbols ordered
- # in the same way they were defined (i.e. rules that were defined later
- # appear later in the array).
+ # in the same way they were declared.
def rule_names
@rule_names ||= []
end
@@ -520,7 +520,7 @@ def any(*args, &block)
ext(Choice.new(args), block)
end
- # Adds +label+ to the given +rule+.A block may be provided to specify
+ # Adds +label+ to the given +rule+. A block may be provided to specify
# semantic behavior (via #ext).
def label(rule, label, &block)
rule = ext(rule, block)
@@ -564,7 +564,7 @@ def self.for(obj)
end
end
- # The grammar this rule belongs to.
+ # The grammar this rule belongs to, if any.
attr_accessor :grammar
# Sets the name of this rule.
@@ -601,7 +601,7 @@ def extension=(mod)
# The module this rule uses to extend new matches.
attr_reader :extension
- # The default set of options to use when calling #parse or #test.
+ # The default set of options to use when calling #parse.
def default_options # :nodoc:
{ :consume => true,
:memoize => false,
@@ -702,8 +702,8 @@ def extend_match(match) # :nodoc:
# A Proxy is a Rule that is a placeholder for another rule. It stores the
# name of some other rule in the grammar internally and resolves it to the
- # actual Rule object at runtime. This lazy evaluation permits us to create
- # Proxy objects for rules that we may not know the definition of yet.
+ # actual Rule object at runtime. This lazy evaluation permits creation of
+ # Proxy objects for rules that may not yet be defined.
module Proxy
include Rule
@@ -1487,7 +1487,7 @@ def captures_hash
end
class Object
- # A sugar method for creating grammars.
+ # A sugar method for creating Citrus grammars from any namespace.
#
# grammar :Calc do
# end
View
@@ -21,15 +21,6 @@ def module_basename
end
end
- module FileClassMethods # :nodoc:
- # Raises SyntaxError when File.parse fails.
- def parse(*args)
- super
- rescue ParseError => e
- raise SyntaxError, e
- end
- end
-
# A grammar for Citrus grammar files. This grammar is used in Citrus#eval to
# parse and evaluate Citrus grammars and serves as a prime example of how to
# create a complex grammar complete with semantic interpretation in pure Ruby.
@@ -345,5 +336,10 @@ def value
rule :space, zero_or_more(any(:white, :comment))
end
- File.extend(FileClassMethods)
+ def File.parse(*args) # :nodoc:
+ super
+ rescue ParseError => e
+ # Raise SyntaxError when a parse fails.
+ raise SyntaxError, e
+ end
end

0 comments on commit c2aafec

Please sign in to comment.