rltk 1.2.0 → 2.0.0

data/lib/rltk/parser.rb

@@ -16,158 +16,70 @@ require 'rltk/cfg'
 
 module RLTK # :nodoc:
 	
-	# A BadToken exception indicates that a token was observed in the input
-	# stream that wasn't used in the grammar's definition.
-	class BadToken < Exception
+	# A BadToken error indicates that a token was observed in the input stream
+	# that wasn't used in the grammar's definition.
+	class BadToken < StandardError
+		# @return [String] String representation of the error.
 		def to_s
 			'Unexpected token.  Token not present in grammar definition.'
 		end
 	end
 	
-	# A NotInLanguage exception is raised whenever there is no valid parse tree
+	# A NotInLanguage error is raised whenever there is no valid parse tree
 	# for a given token stream.  In other words, the input string is not in the
 	# defined language.
-	class NotInLanguage < Exception
+	class NotInLanguage < StandardError
+		# @return [String] String representation of the error.
 		def to_s
 			'String not in language.'
 		end
 	end
 	
-	# An exception of this type is raised when the parser encountered a error
-	# that was handled by an error production.
-	class HandledError < Exception
+	# An error of this type is raised when the parser encountered a error that
+	# was handled by an error production.
+	class HandledError < StandardError
 		
 		# The errors as reported by the parser.
+		# 
+		# @return [Array<Object>]
 		attr_reader :errors
 		
-		# The result that would have been returned by the call to _parse_.
+		# The result that would have been returned by the call to *parse*.
 		attr_reader :result
 		
-		# Instantiate a new HandledError object with _errors_.
+		# Instantiate a new HandledError object with *errors*.
+		#
+		# @param [Array<Object>]	errors Errors added to the parsing environment by calls to {Parser::Environment#error}.
+		# @param [Object]		result Object resulting from parsing Tokens before the error occurred.
 		def initialize(errors, result)
 			@errors = errors
 			@result = result
 		end
 	end
 	
-	# Used for errors that occure during parser construction.
-	class ParserConstructionError < Exception; end
+	# Used for exceptions that occure during parser construction.
+	class ParserConstructionException < Exception; end
 	
-	# Used for runtime errors that are the parsers fault.  These should never
-	# be observed in the wild.
-	class InternalParserError < Exception; end
+	# Used for runtime exceptions that are the parsers fault.  These should
+	# never be observed in the wild.
+	class InternalParserException < Exception; end
 	
 	# The Parser class may be sub-classed to produce new parsers.  These
 	# parsers have a lot of features, and are described in the main
 	# documentation.
 	class Parser
+		# @return [Environment] Environment used by the instantiated parser.
+		attr_reader :env
 		
-		# Called when the Parser class is sub-classed, this method adds a
-		# ParserCore to the new class, and installs some needed class and
-		# instance methods.
-		def Parser.inherited(klass)
-			klass.class_exec do
-				@core = ParserCore.new
-				
-				# Returns this class's ParserCore object.
-				def self.core
-					@core
-				end
-				
-				# Routes method calls to the new subclass to the ParserCore
-				# object.
-				def self.method_missing(method, *args, &proc)
-					@core.send(method, *args, &proc)
-				end
-				
-				# Alias for RLTK::Parser::ParserCore.p that needs to be
-				# manually connected.
-				def self.p(*args, &proc)
-					@core.p(*args, &proc)
-				end
-				
-				# Parses the given token stream using a newly instantiated
-				# environment.  See ParserCore.parse for a description of
-				# the _opts_ option hash.
-				def self.parse(tokens, opts = {})
-					opts[:env] ||= self::Environment.new
-					
-					@core.parse(tokens, opts)
-				end
-				
-				# Instantiates a new parser and creates an environment to be
-				# used for subsequent calls.
-				def initialize
-					@env = self.class::Environment.new
-				end
-				
-				# Returns the environment used by the instantiated parser.
-				def env
-					@env
-				end
-				
-				# Parses the given token stream using the encapsulated
-				# environment.  See ParserCore.parse for a description of
-				# the _opts_ option hash.
-				def parse(tokens, opts = {})
-					self.class.core.parse(tokens, {:env => @env}.update(opts))
-				end
-			end
-		end
-		
-		# All actions passed to ParserCore.rule and ParserCore.clause are
-		# evaluated inside an instance of the Environment class or its
-		# subclass (which must have the same name).
-		class Environment
-			# Indicates if an error was encountered and handled.
-			attr_accessor :he
-			
-			# A list of all objects added using the _error_ method.
-			attr_reader :errors
-			
-			# Instantiate a new Environment object.
-			def initialize
-				self.reset
-			end
-			
-			# Adds an object to the list of errors.
-			def error(o)
-				@errors << o
-			end
-			
-			# Returns a StreamPosition object for the symbol at location n,
-			# indexed from zero.
-			def pos(n)
-				@positions[n]
-			end
-			
-			# Reset any variables that need to be re-initialized between
-			# parse calls.
-			def reset
-				@errors	= Array.new
-				@he		= false
-			end
-			
-			# Setter for the _positions_ array.
-			def set_positions(positions)
-				@positions = positions
-			end
-		end
+		#################
+		# Class Methods #
+		#################
 		
-		# The ParserCore class provides mos of the functionality of the Parser
-		# class.  A ParserCore is instantiated for each subclass of Parser,
-		# thereby allowing multiple parsers to be defined inside a single Ruby
-		# program.
-		class ParserCore
-			
-			# The grammar that can be parsed by this ParserCore.  The grammar
-			# is used internally and should not be manipulated outside of the
-			# ParserCore object.
-			attr_reader :grammar
-			
-			# Instantiates a new ParserCore object with the needed data
-			# structures.
-			def initialize
+		class << self
+			# Installs instance class varialbes into a class.
+			#
+			# @return [void]
+			def install_icvars
 				@curr_lhs		= nil
 				@curr_prec	= nil
 				
@@ -212,10 +124,22 @@ module RLTK # :nodoc:
 				end
 			end
 			
-			# If _state_ (or its equivalent) is not in the state list it is
+			# Called when the Lexer class is sub-classed, it installes
+			# necessary instance class variables.
+			#
+			# @return [void]
+			def inherited(klass)
+				klass.install_icvars
+			end
+			
+			# If *state* (or its equivalent) is not in the state list it is
 			# added and it's ID is returned.  If there is already a state
-			# with the same items as _state_ in the state list its ID is
-			# returned and _state_ is discarded.
+			# with the same items as *state* in the state list its ID is
+			# returned and *state* is discarded.
+			#
+			# @param [State] state State to add to the parser.
+			#
+			# @return [Integer] The ID of the state.
 			def add_state(state)
 				if (id = @states.index(state))
 					id
@@ -230,7 +154,9 @@ module RLTK # :nodoc:
 			
 			# Calling this method will cause the parser to pass right-hand
 			# side values as arrays instead of splats.  This method must be
-			# called before ANY calls to ParserCore.production.
+			# called before ANY calls to Parser.production.
+			#
+			# @return [void]
 			def array_args
 				if @grammar.productions.length == 0
 					@args = :array
@@ -262,8 +188,12 @@ module RLTK # :nodoc:
 				end
 			end
 			
-			# Build a hash with the default options for ParserCore.finalize
-			# and then update it with the values from _opts_.
+			# Build a hash with the default options for Parser.finalize
+			# and then update it with the values from *opts*.
+			#
+			# @param [Hash{Symbol => Object}] opts Hash containing options for finalize.
+			#
+			# @return [Hash{Symbol => Object}]
 			def build_finalize_opts(opts)
 				opts[:explain]	= self.get_io(opts[:explain])
 				
@@ -274,33 +204,41 @@ module RLTK # :nodoc:
 					:use			=> false
 				}.update(opts)
 			end
+			private :build_finalize_opts
 			
-			# Build a hash with the default options for ParserCore.parse and
-			# then update it with the values from _opts_.
+			# Build a hash with the default options for Parser.parse and
+			# then update it with the values from *opts*.
+			#
+			# @param [Hash{Symbol => Object}] opts Hash containing options for parse.
+			#
+			# @return [Hash{Symbol => Object}]
 			def build_parse_opts(opts)
 				opts[:parse_tree]	= self.get_io(opts[:parse_tree])
 				opts[:verbose]		= self.get_io(opts[:verbose])
 				
 				{
 					:accept		=> :first,
-					:env			=> Environment.new,
+					:env			=> self::Environment.new,
 					:parse_tree	=> false,
 					:verbose		=> false
 				}.update(opts)
 			end
+			private :build_parse_opts
 			
 			# This method is used to (surprise) check the sanity of the
 			# constructed parser.  It checks to make sure all non-terminals
 			# used in the grammar definition appear on the left-hand side of
 			# one or more productions, and that none of the parser's states
 			# have invalid actions.  If a problem is encountered a
-			# ParserConstructionError is raised.
+			# ParserConstructionException is raised.
+			#
+			# @return [void]
 			def check_sanity
 				# Check to make sure all non-terminals appear on the
 				# left-hand side of some production.
 				@grammar.nonterms.each do |sym|
 					if not @lh_sides.values.include?(sym)
-						raise ParserConstructionError, "Non-terminal #{sym} does not appear on the left-hand side of any production."
+						raise ParserConstructionException, "Non-terminal #{sym} does not appear on the left-hand side of any production."
 					end
 				end
 				
@@ -312,11 +250,11 @@ module RLTK # :nodoc:
 							actions.each do |action|
 								if action.is_a?(Accept)
 									if sym != :EOS
-										raise ParserConstructionError, "Accept action found for terminal #{sym} in state #{state.id}."
+										raise ParserConstructionException, "Accept action found for terminal #{sym} in state #{state.id}."
 									end
 										
 								elsif not (action.is_a?(GoTo) or action.is_a?(Reduce) or action.is_a?(Shift))
-									raise ParserConstructionError, "Object of type #{action.class} found in actions for terminal " +
+									raise ParserConstructionException, "Object of type #{action.class} found in actions for terminal " +
 										"#{sym} in state #{state.id}."
 									
 								end
@@ -328,10 +266,10 @@ module RLTK # :nodoc:
 						else
 							# Here we check actions for non-terminals.
 							if actions.length > 1
-								raise ParserConstructionError, "State #{state.id} has multiple GoTo actions for non-terminal #{sym}."
+								raise ParserConstructionException, "State #{state.id} has multiple GoTo actions for non-terminal #{sym}."
 								
 							elsif actions.length == 1 and not actions.first.is_a?(GoTo)
-								raise ParserConstructionError, "State #{state.id} has non-GoTo action for non-terminal #{sym}."
+								raise ParserConstructionException, "State #{state.id} has non-GoTo action for non-terminal #{sym}."
 								
 							end
 						end
@@ -340,7 +278,13 @@ module RLTK # :nodoc:
 			end
 			
 			# This method checks to see if the parser would be in parse state
-			# _dest_ after starting in state _start_ and reading _symbols_.
+			# *dest* after starting in state *start* and reading *symbols*.
+			#
+			# @param [Symbol]		start	Symbol representing a CFG production.
+			# @param [Symbol]		dest		Symbol representing a CFG production.
+			# @param [Array<Symbol>]	symbols	Grammar symbols.
+			#
+			# @return [Boolean] If the destination symbol is reachable from the start symbol after reading *symbols*.
 			def check_reachability(start, dest, symbols)
 				path_exists	= true
 				cur_state		= start
@@ -365,9 +309,15 @@ module RLTK # :nodoc:
 			end
 			
 			# Declares a new clause inside of a production.  The right-hand
-			# side is specified by _expression_ and the precedence of this
-			# production can be changed by setting the _precedence_ argument
+			# side is specified by *expression* and the precedence of this
+			# production can be changed by setting the *precedence* argument
 			# to some terminal symbol.
+			#
+			# @param [String]	expression	Right-hand side of a production.
+			# @param [Symbol]	precedence	Symbol representing the precedence of this production.
+			# @param [Proc]	action		Action to be taken when the production is reduced.
+			#
+			# @return [void]
 			def clause(expression, precedence = nil, &action)
 				# Use the curr_prec only if it isn't overridden for this
 				# clause.
@@ -378,7 +328,7 @@ module RLTK # :nodoc:
 				# Check to make sure the action's arity matches the number
 				# of symbols on the right-hand side.
 				if @args == :splat and action.arity != production.rhs.length
-					raise ParserConstructionError, 'Incorrect number of arguments to action.  Action arity must match the number of ' +
+					raise ParserConstructionException, 'Incorrect number of arguments to action.  Action arity must match the number of ' +
 						'terminals and non-terminals in the clause.'
 				end
 				
@@ -389,11 +339,12 @@ module RLTK # :nodoc:
 				# last terminal in the production.
 				@production_precs[production.id] = precedence || production.last_terminal
 			end
-			
 			alias :c :clause
 			
 			# Removes resources that were needed to generate the parser but
 			# aren't needed when actually parsing input.
+			#
+			# @return [void]
 			def clean
 				# We've told the developer about conflicts by now.
 				@conflicts = nil
@@ -416,11 +367,15 @@ module RLTK # :nodoc:
 			
 			# This function will print a description of the parser to the
 			# provided IO object.
+			#
+			# @param [IO] io Input/Output object used for printing the parser's explanation.
+			#
+			# @return [void]
 			def explain(io)
 				if @grammar and not @states.empty?
-					io.puts("###############")
-					io.puts("# Productions #")
-					io.puts("###############")
+					io.puts('###############')
+					io.puts('# Productions #')
+					io.puts('###############')
 					io.puts
 					
 					# Print the productions.
@@ -438,9 +393,9 @@ module RLTK # :nodoc:
 						io.puts
 					end
 					
-					io.puts("##########")
-					io.puts("# Tokens #")
-					io.puts("##########")
+					io.puts('##########')
+					io.puts('# Tokens #')
+					io.puts('##########')
 					io.puts
 					
 					@grammar.terms.sort {|a,b| a.to_s <=> b.to_s }.each do |term|
@@ -455,9 +410,9 @@ module RLTK # :nodoc:
 					
 					io.puts
 					
-					io.puts("#####################")
-					io.puts("# Table Information #")
-					io.puts("#####################")
+					io.puts('#####################')
+					io.puts('# Table Information #')
+					io.puts('#####################')
 					io.puts
 					
 					io.puts("\tStart symbol: #{@grammar.start_symbol}")
@@ -476,9 +431,9 @@ module RLTK # :nodoc:
 					io.puts if not @conflicts.empty?
 					
 					# Print the parse table.
-					io.puts("###############")
-					io.puts("# Parse Table #")
-					io.puts("###############")
+					io.puts('###############')
+					io.puts('# Parse Table #')
+					io.puts('###############')
 					io.puts
 					
 					@states.each do |state|
@@ -524,7 +479,7 @@ module RLTK # :nodoc:
 					# Close any IO objects that aren't $stdout.
 					io.close if io.is_a?(IO) and io != $stdout
 				else
-					raise ParserConstructionError, 'Parser.explain called outside of finalize.'
+					raise ParserConstructionException, 'Parser.explain called outside of finalize.'
 				end
 			end
 			
@@ -532,7 +487,7 @@ module RLTK # :nodoc:
 			# of states and their actions, and the resolution of conflicts
 			# using lookahead and precedence information.
 			# 
-			# The _opts_ hash may contain the following options, which are
+			# The *opts* hash may contain the following options, which are
 			# described in more detail in the main documentation:
 			# 
 			# * :explain - To explain the parser or not.
@@ -540,12 +495,16 @@ module RLTK # :nodoc:
 			# * :precedence - To use precedence info for conflict resolution.
 			# * :use - A file name or object that is used to load/save the parser.
 			# 
-			# No calls to ParserCore.production may appear after the call to
-			# ParserCore.finalize.
+			# No calls to {Parser.production} may appear after the call to
+			# Parser.finalize.
+			#
+			# @param [Hash{Symbol => Object}] opts Options describing how to finalize the parser.
+			#
+			# @return [void]
 			def finalize(opts = {})
 				
 				# Get the full options hash.
-				opts = self.build_finalize_opts(opts)
+				opts = build_finalize_opts(opts)
 				
 				# Get the name of the file in which the parser is defined.
 				def_file = caller()[2].split(':')[0]
@@ -557,8 +516,15 @@ module RLTK # :nodoc:
 					(opts[:use].is_a?(File) and opts[:use].mtime > File.mtime(def_file))
 					)
 					
+					file = self.get_io(opts[:use], 'r')
+					
 					# Un-marshal our saved data structures.
-					@lh_sides, @states, @symbols = Marshal.load(self.get_io(opts[:use], 'r'))
+					file.flock(File::LOCK_SH)
+					@lh_sides, @states, @symbols = Marshal.load(file)
+					file.flock(File::LOCK_UN)
+					
+					# Close the file if we opened it.
+					file.close if opts[:use].is_a?(String)
 					
 					# Remove any un-needed data and return.
 					return self.clean
@@ -645,10 +611,24 @@ module RLTK # :nodoc:
 				self.clean
 				
 				# Store the parser's final data structures if requested.
-				Marshal.dump([@lh_sides, @states, @symbols], self.get_io(opts[:use])) if opts[:use]
+				if opts[:use]
+					io = self.get_io(opts[:use])
+					
+					io.flock(File::LOCK_EX) if io.is_a?(File)
+					Marshal.dump([@lh_sides, @states, @symbols], io)
+					io.flock(File::LOCK_UN) if io.is_a?(File)
+					
+					# Close the IO object if we opened it.
+					io.close if opts[:use].is_a?(String)
+				end
 			end
 			
 			# Converts an object into an IO object as appropriate.
+			#
+			# @param [Object] o		Object to be converted into an IO object.
+			# @param [String] mode	String representing the mode to open the IO object in.
+			#
+			# @return [IO, false] The IO object or false if a conversion wasn't possible.
 			def get_io(o, mode = 'w')
 				if o.is_a?(TrueClass)
 					$stdout
@@ -661,6 +641,11 @@ module RLTK # :nodoc:
 				end
 			end
 			
+			# @return [CFG] The grammar that can be parsed by this Parser.
+			def grammar
+				@grammar.clone
+			end
+			
 			# This method generates and memoizes the G' grammar used to
 			# calculate the LALR(1) lookahead sets.  Information about this
 			# grammar and its use can be found in the following paper:
@@ -668,6 +653,8 @@ module RLTK # :nodoc:
 			# Simple Computation of LALR(1) Lookahed Sets
 			# Manuel E. Bermudez and George Logothetis
 			# Information Processing Letters 31 - 1989
+			#
+			# @return [CFG]
 			def grammar_prime
 				if not @grammar_prime
 					@grammar_prime = CFG.new
@@ -699,13 +686,23 @@ module RLTK # :nodoc:
 			end
 			
 			# Inform the parser core that a conflict has been detected.
+			#
+			# @param [Integer]	state_id	ID of the state where the conflict was encountered.
+			# @param [:RR, :SR]	type		Reduce/Reduce or Shift/Reduce conflict.
+			# @param [Symbol]	sym		Symbol that caused the conflict.
+			#
+			# @return [void]
 			def inform_conflict(state_id, type, sym)
 				@conflicts[state_id] << [type, sym]
 			end
 			
-			# This method is used to specify that the symbols in _symbols_
-			# are left associative.  Subsequent calls to this method will
+			# This method is used to specify that the symbols in *symbols*
+			# are left-associative.  Subsequent calls to this method will
 			# give their arguments higher precedence.
+			#
+			# @param [Array<Symbol>] symbols Symbols that are left associative.
+			#
+			# @return [void]
 			def left(*symbols)
 				prec_level = @prec_counts[:left] += 1
 				
@@ -714,8 +711,12 @@ module RLTK # :nodoc:
 				end
 			end
 			
-			# This method is used to specify that the symbols in _symbols_
+			# This method is used to specify that the symbols in *symbols*
 			# are non-associative.
+			#
+			# @param [Array<Symbol>] symbols Symbols that are non-associative.
+			#
+			# @return [void]
 			def nonassoc(*symbols)
 				prec_level = @prec_counts[:non] += 1
 				
@@ -738,9 +739,13 @@ module RLTK # :nodoc:
 			# 
 			# Additional information for these options can be found in the
 			# main documentation.
+			#
+			# @param [Array<Token>] tokens Tokens to be parsed.
+			#
+			# @return [Object, Array<Object>] Result or results of parsing the given tokens.
 			def parse(tokens, opts = {})
 				# Get the full options hash.
-				opts	= self.build_parse_opts(opts)
+				opts	= build_parse_opts(opts)
 				v	= opts[:verbose]
 				
 				if opts[:verbose]
@@ -858,7 +863,7 @@ module RLTK # :nodoc:
 								production_proc, pop_size = @procs[action.id]
 								
 								if not production_proc
-									raise InternalParserError, "No production #{action.id} found."
+									raise InternalParserException, "No production #{action.id} found."
 								end
 								
 								args, positions = stack.pop(pop_size)
@@ -895,7 +900,7 @@ module RLTK # :nodoc:
 									
 									stack.push(goto.id, result, @lh_sides[action.id], pos0)
 								else
-									raise InternalParserError, "No GoTo action found in state #{stack.state} " +
+									raise InternalParserException, "No GoTo action found in state #{stack.state} " +
 										"after reducing by production #{action.id}"
 								end
 								
@@ -956,17 +961,24 @@ module RLTK # :nodoc:
 			end
 			
 			# Adds a new production to the parser with a left-hand value of
-			# _symbol_.  If _expression_ is specified it is taken as the
-			# right-hand side of the production and _action_ is associated
-			# with the production.  If _expression_ is nil then _action_ is
+			# *symbol*.  If *expression* is specified it is taken as the
+			# right-hand side of the production and *action* is associated
+			# with the production.  If *expression* is nil then *action* is
 			# evaluated and expected to make one or more calls to
-			# ParserCore.clause.  A precedence can be associate with this
-			# production by setting _precedence_ to a terminal symbol.
+			# Parser.clause.  A precedence can be associate with this
+			# production by setting *precedence* to a terminal symbol.
+			#
+			# @param [Symbol]		symbol		Left-hand side of the production.
+			# @param [String, nil]	expression	Right-hand side of the production.
+			# @param [Symbol, nil]	precedence	Symbol representing the precedence of this produciton.
+			# @param [Proc]		action		Action associated with this production.
+			#
+			# @return [void]
 			def production(symbol, expression = nil, precedence = nil, &action)
 				
 				# Check the symbol.
 				if not (symbol.is_a?(Symbol) or symbol.is_a?(String)) or not CFG::is_nonterminal?(symbol)
-					riase ParserConstructionError, 'Production symbols must be Strings or Symbols and be in all lowercase.'
+					riase ParserConstructionException, 'Production symbols must be Strings or Symbols and be in all lowercase.'
 				end
 				
 				@grammar.curr_lhs	= symbol.to_sym
@@ -981,11 +993,15 @@ module RLTK # :nodoc:
 				@grammar.curr_lhs	= nil
 				@curr_prec		= nil
 			end
-			
 			alias :p :production
 			
 			# This method uses lookahead sets and precedence information to
 			# resolve conflicts and remove unnecessary reduce actions.
+			#
+			# @param [Boolean] do_lookahead	Prune based on lookahead sets or not.
+			# @param [Boolean] do_precedence	Prune based on precedence or not.
+			#
+			# @return [void]
 			def prune(do_lookahead, do_precedence)
 				terms = @grammar.terms
 				
@@ -1073,7 +1089,7 @@ module RLTK # :nodoc:
 										selected_action	= a
 										
 									elsif prec == max_prec and assoc == :nonassoc
-										raise ParserConstructionError, 'Non-associative token found during conflict resolution.'
+										raise ParserConstructionException, 'Non-associative token found during conflict resolution.'
 										
 									end
 								end
@@ -1088,6 +1104,10 @@ module RLTK # :nodoc:
 			# This method is used to specify that the symbols in _symbols_
 			# are right associative.  Subsequent calls to this method will
 			# give their arguments higher precedence.
+			#
+			# @param [Array<Symbol>] symbols Symbols that are right-associative.
+			#
+			# @return [void]
 			def right(*symbols)
 				prec_level = @prec_counts[:right] += 1
 				
@@ -1097,19 +1117,110 @@ module RLTK # :nodoc:
 			end
 			
 			# Changes the starting symbol of the parser.
+			#
+			# @param [Symbol] symbol The starting symbol of the grammar.
+			#
+			# @return [void]
 			def start(symbol)
 				@grammar.start symbol
 			end
 		end
 		
-		# The ParseStack class is used by a ParserCore to keep track of state
+		####################
+		# Instance Methods #
+		####################
+		
+		# Instantiates a new parser and creates an environment to be
+		# used for subsequent calls.
+		def initialize
+			@env = self.class::Environment.new
+		end
+	
+		# Parses the given token stream using the encapsulated environment.
+		#
+		# @see .parse
+		def parse(tokens, opts = {})
+			self.class.parse(tokens, {:env => @env}.update(opts))
+		end
+		
+		################################
+		
+		# All actions passed to Parser.producation and Parser.clause are
+		# evaluated inside an instance of the Environment class or its
+		# subclass (which must have the same name).
+		class Environment
+			# Indicates if an error was encountered and handled.
+			#
+			# @return [Boolean]
+			attr_accessor :he
+			
+			# A list of all objects added using the *error* method.
+			#
+			# @return [Array<Object>]
+			attr_reader :errors
+			
+			# Instantiate a new Environment object.
+			def initialize
+				self.reset
+			end
+			
+			# Adds an object to the list of errors.
+			#
+			# @return [void]
+			def error(o)
+				@errors << o
+			end
+			
+			# Returns a StreamPosition object for the symbol at location n,
+			# indexed from zero.
+			#
+			# @param [Integer] n Index for symbol position.
+			#
+			# @return [StreamPosition] Position of symbol at index n.
+			def pos(n)
+				@positions[n]
+			end
+			
+			# Reset any variables that need to be re-initialized between
+			# parse calls.
+			#
+			# @return [void]
+			def reset
+				@errors	= Array.new
+				@he		= false
+			end
+			
+			# Setter for the *positions* array.
+			#
+			# @param [Array<StreamPosition>] positions
+			#
+			# @return [Array<StreamPosition>] The same array of positions.
+			def set_positions(positions)
+				@positions = positions
+			end
+		end
+		
+		# The ParseStack class is used by a Parser to keep track of state
 		# during parsing.
 		class ParseStack
+			# @return [Integer] ID of this parse stack.
 			attr_reader :id
+			
+			# @return [Array<Object>] Array of objects produced by {Reduce} actions.
 			attr_reader :output_stack
+			
+			# @return [Array<Integer>] Array of states used when performing {Reduce} actions.
 			attr_reader :state_stack
 			
 			# Instantiate a new ParserStack object.
+			#
+			# @param [Integer]				id			ID for this parse stack.  Used by GLR algorithm.
+			# @param [Array<Object>]			ostack		Output stack.  Holds results of {Reduce} and {Shift} actions.
+			# @param [Array<Integer>]		sstack		State stack.  Holds states that have been shifted due to {Shift} actions.
+			# @param [Array<Integer>]		nstack		Node stack.  Holds dot language IDs for nodes in the parse tree.
+			# @param [Array<Array<Integer>>]	connections	Integer pairs representing edges in the parse tree.
+			# @param [Array<Symbol>]			labels		Labels for nodes in the parse tree.
+			# @param [Array<StreamPosition>]	positions		Position data for symbols that have been shifted.
 			def initialize(id, ostack = [], sstack = [0], nstack = [], connections = [], labels = [], positions = [])
 				@id = id
 				
@@ -1124,12 +1235,16 @@ module RLTK # :nodoc:
 			
 			# Branch this stack, effectively creating a new copy of its
 			# internal state.
+			#
+			# @param [Integer] new_id ID for the new ParseStack.
+			#
+			# @return [ParseStack]
 			def branch(new_id)
 				ParseStack.new(new_id, @output_stack.clone, @state_stack.clone, @node_stack.clone,
 					@connections.clone, @labels.clone, @positions.clone)
 			end
 			
-			# Returns the position of the last symbol on the stack.
+			# @return [StreamPosition] Position data for the last symbol on the stack.
 			def position
 				if @positions.empty?
 					StreamPosition.new
@@ -1139,6 +1254,13 @@ module RLTK # :nodoc:
 			end
 			
 			# Push new state and other information onto the stack.
+			#
+			# @param [Integer]			state	ID of the shifted state.
+			# @param [Object]			o		Value of Token that caused the shift.
+			# @param [Symbol]			node0	Label for node in parse tree.
+			# @param [StreamPosition]	position	Position token that got shifted.
+			#
+			# @return [void]
 			def push(state, o, node0, position)
 				@state_stack	<< state
 				@output_stack	<< o
@@ -1153,8 +1275,11 @@ module RLTK # :nodoc:
 				end
 			end
 			
-			# Pop some number of objects off of the inside stacks, returning
-			# the values popped from the output stack.
+			# Pop some number of objects off of the inside stacks.
+			#
+			# @param [Integer] n Number of object to pop off the stack.
+			#
+			# @return [Array<Array<Object, StreamPosition>>] Values popped from the output and positions stacks.
 			def pop(n = 1)
 				@state_stack.pop(n)
 				
@@ -1168,21 +1293,22 @@ module RLTK # :nodoc:
 			
 			# Fetch the result stored in this ParseStack.  If there is more
 			# than one object left on the output stack there is an error.
+			#
+			# @return [Object] The end result of this parse stack.
 			def result
 				if @output_stack.length == 1
 					return @output_stack.last
 				else
-					raise InternalParserError, "The parsing stack should have 1 element on the output stack, not #{@output_stack.length}."
+					raise InternalParserException, "The parsing stack should have 1 element on the output stack, not #{@output_stack.length}."
 				end
 			end
 			
-			# Return the current state of this ParseStack.
+			# @return [Integer] Current state of this ParseStack.
 			def state
 				@state_stack.last
 			end
 			
-			# Return a string representing the parse tree in the DOT
-			# language.
+			# @return [String] Representation of the parse tree in the DOT langauge.
 			def tree
 				tree  = "digraph tree#{@id} {\n"
 				
@@ -1209,15 +1335,19 @@ module RLTK # :nodoc:
 		# The State class is used to represent sets of items and actions to be
 		# used during parsing.
 		class State
-			# The state's ID.
-			attr_accessor	:id
-			# The CFG::Item objects that comprise this state.
-			attr_reader	:items
-			# The Action objects that represent the actions that should be
-			# taken when various inputs are observed.
-			attr_reader	:actions
+			# @return [Integer] State's ID.
+			attr_accessor :id
+			
+			# @return [Array<CFG::Item>] Item objects that comprise this state.
+			attr_reader :items
+			
+			# @return [Array<Action>] Action objects that represent the actions that should be taken when various inputs are observed.
+			attr_reader :actions
 			
 			# Instantiate a new State object.
+			#
+			# @param [Array<Token>]		tokens	Tokens that represent this state.
+			# @param [Array<CFG::Item>]	items	Items that make up this state.
 			def initialize(tokens, items = [])
 				@id		= nil
 				@items	= items
@@ -1227,11 +1357,19 @@ module RLTK # :nodoc:
 			# Compare one State to another.  Two States are equal if they
 			# have the same items or, if the items have been cleaned, if
 			# the States have the same ID.
+			#
+			# @param [State] other Another State to compare to.
+			#
+			# @return [Boolean]
 			def ==(other)
 				if self.items and other.items then self.items == other.items else self.id == other.id end
 			end
 			
 			# Add a Reduce action to the state.
+			#
+			# @param [Integer] production_id ID of production to add to this state.
+			#
+			# @return [void]
 			def add_reduction(production_id)
 				action = Reduce.new(production_id)
 				
@@ -1239,19 +1377,24 @@ module RLTK # :nodoc:
 				@actions.each { |k, v| if CFG::is_terminal?(k) and k != :ERROR then v << action end }
 			end
 			
-			# Add a new item to this state.
+			# @param [CFG::Item] item Item to add to this state.
 			def append(item)
 				if item.is_a?(CFG::Item) and not @items.include?(item) then @items << item end
 			end
-			
 			alias :<< :append
 			
-			# Clean this State by removing the list of Item objects.
+			# Clean this State by removing the list of {CFG::Item} objects.
+			#
+			# @return [void]
 			def clean
 				@items = nil
 			end
 			
-			# Close this state using _productions_.
+			# Close this state using *productions*.
+			#
+			# @param [Array<CFG::Production>] productions Productions used to close this state.
+			#
+			# @return [vod]
 			def close(productions)
 				self.each do |item|
 					if (next_symbol = item.next_symbol) and CFG::is_nonterminal?(next_symbol)
@@ -1261,9 +1404,13 @@ module RLTK # :nodoc:
 			end
 			
 			# Checks to see if there is a conflict in this state, given a
-			# input of _sym_.  Returns :SR if a shift/reduce conflict is
+			# input of *sym*.  Returns :SR if a shift/reduce conflict is
 			# detected and :RR if a reduce/reduce conflict is detected.  If
 			# no conflict is detected nil is returned.
+			#
+			# @param [Symbol] sym Symbol to check for conflicts on.
+			#
+			# @return [:SR, :RR, nil]
 			def conflict_on?(sym)
 				
 				reductions	= 0
@@ -1289,21 +1436,32 @@ module RLTK # :nodoc:
 			end
 			
 			# Iterate over the state's items.
+			#
+			# @return [void]
 			def each
 				@items.each {|item| yield item}
 			end
 			
-			# Specify an Action to perform when the input token is _symbol_.
+			# Specify an Action to perform when the input token is *symbol*.
+			#
+			# @param [Symbol] symbol Symbol to add action for.
+			# @param [Action] action Action for symbol.
+			#
+			# @return [void]
 			def on(symbol, action)
 				if @actions.key?(symbol)
 					@actions[symbol] << action
 				else
-					raise ParserConstructionError, "Attempting to set action for token (#{symbol}) not seen in grammar definition."
+					raise ParserConstructionException, "Attempting to set action for token (#{symbol}) not seen in grammar definition."
 				end
 			end
 			
 			# Returns that actions that should be taken when the input token
-			# is _symbol_.
+			# is *symbol*.
+			#
+			# @param [Symbol] symbol Symbol we want the actions for.
+			#
+			# @return [Array<Action>] Actions that should be taken.
 			def on?(symbol)
 				@actions[symbol].clone
 			end
@@ -1312,8 +1470,10 @@ module RLTK # :nodoc:
 		# The Action class is used to indicate what action the parser should
 		# take given a current state and input token.
 		class Action
+			# @return [Integer] ID of this action.
 			attr_reader :id
 			
+			# @param [Integer] id ID of this action.
 			def initialize(id = nil)
 				@id = id
 			end
@@ -1322,6 +1482,7 @@ module RLTK # :nodoc:
 		# The Accept class indicates to the parser that it should accept the
 		# current parse tree.
 		class Accept < Action
+			# @return [String] String representation of this action.
 			def to_s
 				"Accept"
 			end
@@ -1330,6 +1491,7 @@ module RLTK # :nodoc:
 		# The GoTo class indicates to the parser that it should goto the state
 		# specified by GoTo.id.
 		class GoTo < Action
+			# @return [String] String representation of this action.
 			def to_s
 				"GoTo #{self.id}"
 			end
@@ -1338,6 +1500,7 @@ module RLTK # :nodoc:
 		# The Reduce class indicates to the parser that it should reduce the
 		# input stack by the rule specified by Reduce.id.
 		class Reduce < Action
+			# @return [String] String representation of this action.
 			def to_s
 				"Reduce by Production #{self.id}"
 			end
@@ -1346,6 +1509,7 @@ module RLTK # :nodoc:
 		# The Shift class indicates to the parser that it should shift the
 		# current input token.
 		class Shift < Action
+			# @return [String] String representation of this action.
 			def to_s
 				"Shift to State #{self.id}"
 			end