rltk 2.2.1 → 3.0.0

data/lib/rltk/ast.rb

@@ -7,54 +7,62 @@
 # Requires #
 ############
 
-# Ruby Language Toolkit
-require 'rltk/util/monkeys'
+# Gems
+require 'filigree/abstract_class'
+require 'filigree/class'
+require 'filigree/match'
+require 'filigree/types'
 
 #######################
 # Classes and Modules #
 #######################
 
-module RLTK # :nodoc:
-	# A TypeMismatch is raised when an object being set as a child or value of
-	# an ASTNode is of the wrong type.
-	class TypeMismatch < StandardError
-		
-		# Instantiates a new TypeMismatch object.
-		#
-		# @param [Class] expected	Expected type.
-		# @param [Klass] actual		Actual type of object.
-		def initialize(expected, actual)
-			@expected	= expected
-			@actual	= actual
-		end
-		
-		# @return [String] String representation of the error.
-		def to_s
-			"Type Mismatch: Expected #{@expected} but received #{@actual}."
-		end
-	end
-	
+module RLTK
 	# This class is a good start for all your abstract syntax tree node needs.
 	class ASTNode
-		# @return [ASTNode] Reference to the parent node.
+		
+		extend Filigree::AbstractClass
+		extend Filigree::Destructurable
+		
+		# @return [ASTNode]  Reference to the parent node.
 		attr_accessor :parent
 		
+		# @return [Hash]  The notes hash for this node.
+		attr_reader :notes
+		
 		#################
 		# Class Methods #
 		#################
 		
 		class << self
 			
+			# Check to make sure a name isn't re-defining a value or child.
+			#
+			# @raise [ArgumentError]  Raised if the name is already used for an existing value or child
+			def check_odr(name)
+				if @child_names.include? name
+					raise ArgumentError, "Class #{self} or one of its superclasses already defines a child named #{name}"
+				end
+				
+				if @value_names.include?(name)
+					raise ArgumentError, "Class #{self} or one of its superclasses already defines a value named #{name}"
+				end
+			end
+			
 			# Installs instance class varialbes into a class.
 			#
 			# @return [void]
 			def install_icvars
 				if self.superclass == ASTNode
 					@child_names = Array.new
+					@child_types = Array.new
 					@value_names = Array.new
+					@value_types = Array.new
 				else
 					@child_names = self.superclass.child_names.clone
+					@child_types = self.superclass.child_types.clone
 					@value_names = self.superclass.value_names.clone
+					@value_types = self.superclass.value_types.clone
 				end
 			end
 			protected :install_icvars
@@ -62,7 +70,7 @@ module RLTK # :nodoc:
 			# Called when the Lexer class is sub-classed, it installes
 			# necessary instance class variables.
 			#
-			# @param [Class] klass The class is inheriting from this class.
+			# @param [Class]  klass  The class is inheriting from this class.
 			#
 			# @return [void]
 			def inherited(klass)
@@ -74,11 +82,13 @@ module RLTK # :nodoc:
 			# methods that include type checking.  The type of this
 			# child must be a subclass of the ASTNode class.
 			#
-			# @param [String, Symbol]	name Name of child node.
-			# @param [Class]			type Type of child node.  Must be a subclass of ASTNode.
+			# @param [String, Symbol]  name  Name of child node.
+			# @param [Class]           type  Type of child node.  Must be a subclass of ASTNode.
 			#
 			# @return [void]
 			def child(name, type)
+				check_odr(name)
+				
 				if type.is_a?(Array) and type.length == 1
 					t = type.first
 				
@@ -96,20 +106,26 @@ module RLTK # :nodoc:
 				end
 				
 				@child_names << name
+				@child_types << type
 				define_accessor(name, type, true)
 			end
 			
-			# @return [Array<Symbol>] Array of the names of this node class's children.
+			# @return [Array<Symbol>]  Array of the names of this node class's children
 			def child_names
 				@child_names
 			end
 			
+			# @return [Array]  Array of types of this node class's children
+			def child_types
+				@child_types
+			end
+			
 			# This method defines a type checking accessor named *name*
 			# with type *type*.
 			#
-			# @param [String, Symbol]	name			Name of accessor.
-			# @param [Class]			type			Class used for type checking.
-			# @param [Boolean]			set_parent	Set the parent variable or not.
+			# @param [String, Symbol]  name        Name of accessor
+			# @param [Class]           type        Class used for type checking
+			# @param [Boolean]         set_parent  Set the parent variable or not
 			#
 			# @return [void]
 			def define_accessor(name, type, set_parent = false)
@@ -122,48 +138,26 @@ module RLTK # :nodoc:
 				if type.is_a?(Class)
 					if set_parent
 						define_method((name.to_s + '=').to_sym) do |value|
-							if value.is_a?(type) or value == nil
-								self.instance_variable_set(ivar_name, value)
-							
-								value.parent = self if value
-							else
-								raise TypeMismatch.new(type, value.class)
-							end
+							self.instance_variable_set(ivar_name, check_type(value, type, nil, true))
+							value.parent = self if value
 						end
 						
 					else
 						define_method((name.to_s + '=').to_sym) do |value|
-							if value.is_a?(type) or value == nil
-								self.instance_variable_set(ivar_name, value)
-								
-							else
-								raise TypeMismatch.new(type, value.class)
-							end
+							self.instance_variable_set(ivar_name, check_type(value, type, nil, true))
 						end
 					end
 					
 				else
-					type = type.first
-					
 					if set_parent
 						define_method((name.to_s + '=').to_sym) do |value|
-							if value.inject(true) { |m, o| m and o.is_a?(type) }
-								self.instance_variable_set(ivar_name, value)
-							
-								value.each { |c| c.parent = self }
-							else
-								raise TypeMismatch.new(type, value.class)
-							end
+							self.instance_variable_set(ivar_name, check_array_type(value, type.first, nil, true))
+							value.each { |c| c.parent = self }
 						end
 						
 					else
 						define_method((name.to_s + '=').to_sym) do |value|
-							if value.inject(true) { |m, o| m and o.is_a?(type) }
-								self.instance_variable_set(ivar_name, value)
-								
-							else
-								raise TypeMismatch.new(type, value.class)
-							end
+							self.instance_variable_set(ivar_name, check_array_type(value, type.first, nil, true))
 						end
 					end
 				end
@@ -172,14 +166,15 @@ module RLTK # :nodoc:
 			
 			# Defined a value for this AST class and its subclasses.
 			# The name of the value will be used to define accessor
-			# methods that include type checking.  The type of this
-			# value must NOT be a subclass of the ASTNode class.
+			# methods that include type checking.
 			#
-			# @param [String, Symbol]	name Name of value.
-			# @param [Class]			type Type of value.  Must NOT be a subclass of ASTNode.
+			# @param [String, Symbol]  name  Name of value
+			# @param [Class]           type  Type of value
 			#
 			# @return [void]
 			def value(name, type)
+				check_odr(name)
+				
 				if type.is_a?(Array) and type.length == 1
 					t = type.first
 				
@@ -190,20 +185,20 @@ module RLTK # :nodoc:
 					raise 'Child and Value types must be a class name or an array with a single class name element.'
 				end
 				
-				# Check to make sure that type is NOT a subclass of
-				# ASTNode.
-				if t.subclass_of?(ASTNode)
-					raise "A value's type specification must NOT be a subclass of ASTNode."
-				end
-				
 				@value_names << name
+				@value_types << type
 				define_accessor(name, type)
 			end
 			
-			# @return [Array<Symbol>] Array of the names of this node class's values.
+			# @return [Array<Symbol>]  Array of the names of this node class's values
 			def value_names
 				@value_names
 			end
+			
+			# @return [Array<Symbol>]  Array of the types of this node class's values
+			def value_types
+				@value_types
+			end
 		end
 		
 		####################
@@ -214,14 +209,14 @@ module RLTK # :nodoc:
 		# nodes are of the same class and all of their values and children
 		# are equal.
 		#
-		# @param [ASTNode] other The ASTNode to compare to.
+		# @param [ASTNode]  other  The ASTNode to compare to
 		#
 		# @return [Boolean]
 		def ==(other)
 			self.class == other.class and self.values == other.values and self.children == other.children
 		end
 		
-		# @return [Object] Note with the name *key*.
+		# @return [Object]  Note with the name *key*
 		def [](key)
 			@notes[key]
 		end
@@ -231,31 +226,71 @@ module RLTK # :nodoc:
 			@notes[key] = value
 		end
 		
-		# @return [Array<ASTNode>] Array of this node's children.
-		def children
-			self.class.child_names.map { |name| self.send(name) }
+		# This method allows ASTNodes to be destructured for pattern matching.
+		def call(arity)
+			if arity == self.values.length
+				self.values
+			else
+				[*self.values, *self.children]
+			end
+		end
+		
+		# @param [Class] as The type that should be returned by the method.  Must be either Array or hash.
+		#
+		# @return [Array<ASTNode>, Hash{Symbol => ASTNode}] Array or Hash of this node's children.
+		def children(as = Array)
+			if as == Array
+				self.class.child_names.map { |name| self.send(name) }
+			
+			elsif as == Hash
+				self.class.child_names.inject(Hash.new) { |h, name| h[name] = self.send(name); h }
+			
+			else
+				raise 'Children can only be returned as an Array or a Hash.'
+			end
 		end
 		
-		# Assigns an array of AST nodes as the children of this node.
+		# Assigns an array or hash of AST nodes as the children of this node.
+		# If a hash is provided as an argument the key is used as the name of
+		# the child a object should be assigned to.
 		#
-		# @param [Array<ASTNode>] children Children to be assigned to this node.
+		# @param [Array<ASTNode>, Hash{Symbol => ASTNode}] children Children to be assigned to this node.
 		#
 		# @return [void]
 		def children=(children)
-			if children.length != self.class.child_names.length
-				raise 'Wrong number of children specified.'
-			end
+			case children
+			when Array
+				if children.length != self.class.child_names.length
+					raise 'Wrong number of children specified.'
+				end
 			
-			self.class.child_names.each_with_index do |name, i|
-				self.send((name.to_s + '=').to_sym, children[i])
+				self.class.child_names.each_with_index do |name, i|
+					self.send((name.to_s + '=').to_sym, children[i])
+				end
+				
+			when Hash
+				children.each do |name, val|
+					if self.class.child_names.include?(name)
+						self.send((name.to_s + '=').to_sym, val)
+					else
+						raise "ASTNode subclass #{self.class.name} does not have a child named #{name}."
+					end
+				end
 			end
 		end
 		
+		# Produce an exact copy of this tree.
+		#
+		# @return [ASTNode] A copy of the tree.
+		def copy
+			self.map { |c| c }
+		end
+		
 		# Removes the note *key* from this node.  If the *recursive* argument
 		# is true it will also remove the note from the node's children.
 		#
-		# @param [Object]	key		The key of the note to remove.
-		# @param [Boolean]	recursive	Do a recursive removal or not.
+		# @param [Object]   key        The key of the note to remove
+		# @param [Boolean]  recursive	 Do a recursive removal or not
 		def delete_note(key, recursive = true)
 			if recursive
 				self.children.each do |child|
@@ -276,16 +311,17 @@ module RLTK # :nodoc:
 		# to serialize an AST.  You can use Marshal.load to reconstruct a
 		# serialized AST.
 		#
-		# @param [nil, IO, String]	dest		Where the serialized version of the AST will end up.  If nil, this method will return the AST as a string.
-		# @param [Fixnum]			limit	Recursion depth.  If -1 is specified there is no limit on the recursion depth.
+		# @param [nil, IO, String]  dest   Where the serialized version of the AST will end up.  If nil,
+		#                                  this method will return the AST as a string.
+		# @param [Fixnum]           limit  Recursion depth.  If -1 is specified there is no limit on the recursion depth.
 		#
-		# @return [void, String] String if *dest* is nil, void otherwise.
+		# @return [void, String]  String if *dest* is nil, void otherwise.
 		def dump(dest = nil, limit = -1)
 			case dest
-			when nil		then Marshal.dump(self, limit)
-			when String	then File.open(dest, 'w') { |f| Marshal.dump(self, f, limit) }
-			when IO		then Marshal.dump(self, dest, limit)
-			else	raise TypeError, "AST#dump expects nil, a String, or an IO object for the dest parameter."
+			when nil    then Marshal.dump(self, limit)
+			when String then File.open(dest, 'w') { |f| Marshal.dump(self, f, limit) }
+			when IO     then Marshal.dump(self, dest, limit)
+			else	            raise TypeError, "AST#dump expects nil, a String, or an IO object for the dest parameter."
 			end
 		end
 		
@@ -296,16 +332,18 @@ module RLTK # :nodoc:
 		# * Post-order (:post)
 		# * Level-order (:level)
 		#
+		# @param [:pre, :post, :level]  order  The order in which to iterate over the tree
+		#
 		# @return [void]
 		def each(order = :pre, &block)
 			case order
 			when :pre
 				yield self
 				
-				self.children.compact.each { |c| c.each(:pre, &block) }
+				self.children.flatten.compact.each { |c| c.each(:pre, &block) }
 				
 			when :post
-				self.children.compact.each { |c| c.each(:post, &block) }
+				self.children.flatten.compact.each { |c| c.each(:post, &block) }
 				
 				yield self
 				
@@ -315,7 +353,7 @@ module RLTK # :nodoc:
 				while node = level_queue.shift
 					yield node
 					
-					level_queue += node.children.compact
+					level_queue += node.children.flatten.compact
 				end
 			end
 		end
@@ -334,25 +372,31 @@ module RLTK # :nodoc:
 		# the order they were declared).
 		#
 		# If a node has 2 values and 2 children and is passed only a single
-		# value the remaining values and children are assumed to be nil.
+		# value the remaining values and children are assumed to be nil or
+		# empty arrays, depending on the declared type of the value or
+		# child.
 		#
-		# @param [Array<Object>] objects The values and children of this node.
-		def initialize(*objects)
-			if self.class == RLTK::ASTNode
-				raise 'Attempting to instantiate the RLTK::ASTNode class.'
-			else
-				@notes	= Hash.new()
-				@parent	= nil
-				
-				# Pad out the objects array with nil values.
-				max_args = self.class.value_names.length + self.class.child_names.length
-				objects.fill(nil, objects.length...max_args)
-				
-				pivot = self.class.value_names.length
-				
-				self.values	= objects[0...pivot]
-				self.children	= objects[pivot..-1]
-			end
+		# If a block is passed to initialize the block will be executed in
+		# the conext of the new object.
+		#
+		# @param [Array<Object>]  objects  Values and children of this node
+		def initialize(*objects, &block)
+			@notes  = Hash.new()
+			@parent = nil
+			
+			# Pad out the objects array with nil values and empty
+			# arrays.
+			all_types       = self.class.value_types + self.class.child_types
+			remaining_types = all_types[objects.length..-1]
+			
+			objects += remaining_types.map { |type| type.is_a?(Array) ? [] : nil }
+			
+			pivot = self.class.value_names.length
+			
+			self.values   = objects[0...pivot]
+			self.children = objects[pivot..-1]
+			
+			self.instance_exec(&block) if not block.nil?
 		end
 		
 		# Create a new tree by using the provided Proc object to map the
@@ -362,10 +406,21 @@ module RLTK # :nodoc:
 		#
 		# @note This does not modify the current tree.
 		#
-		# @return [Object] The result of calling the given block on the root node.
+		# @return [Object]  Result of calling the given block on the root node
 		def map(&block)
-			new_children	= self.children.map { |c| if c.nil? then block.call(c) else c.map(&block) end }
-			new_node		= self.class.new(*self.values, *new_children)
+			new_values = self.values.map { |v| v.clone }
+			
+			new_children =
+			self.children.map do |c0|
+				case c0
+				when Array    then c0.map { |c1| c1.map(&block) }
+				when ASTNode  then c0.map(&block)
+				when NilClass then nil
+				end
+			end
+			
+			new_node		= self.class.new(*new_values, *new_children)
+			new_node.notes = self.notes
 			
 			block.call(new_node)
 		end
@@ -378,33 +433,73 @@ module RLTK # :nodoc:
 		#	calling the provided block on the root node is used as the
 		#	return value.
 		#
-		# @return [Object] The result of calling the given block on the root node.
+		# @return [Object]  Result of calling the given block on the root node
 		def map!(&block)
-			self.children = self.children.map { |c| if c.nil? then block.call(c) else c.map!(&block) end }
+			self.children =
+			self.children.map do |c0|
+				case c0
+				when Array    then c0.map { |c1| c1.map!(&block) }
+				when ASTNode  then c0.map!(&block)
+				when NilClass then nil
+				end
+			end
 			
 			block.call(self)
 		end
 		
+		# Set the notes for this node from a given hash.
+		#
+		# @param [Hash]  new_notes  The new notes for this node.
+		#
+		# @return [void]
+		def notes=(new_notes)
+			@notes = new_notes.clone
+		end
+		
 		# @return [ASTNode] Root of the abstract syntax tree.
 		def root
 			if @parent then @parent.root else self end
 		end
 		
-		# @return [Array<Object>] Array of this node's values.
-		def values
-			self.class.value_names.map { |name| self.send(name) }
+		# @param [Class]  as  The type that should be returned by the method.  Must be either Array or hash.
+		#
+		# @return [Array<Object>, Hash{Symbol => Object}] Array or Hash of this node's values.
+		def values(as = Array)
+			if as == Array
+				self.class.value_names.map { |name| self.send(name) }
+			
+			elsif as == Hash
+				self.class.value_names.inject(Hash.new) { |h, name| h[name] = self.send(name); h }
+			
+			else
+				raise 'Values can only be returned as an Array or a Hash.'
+			end
 		end
 		
-		# Assigns an array of objects as the values of this node.
+		# Assigns an array or hash of objects as the values of this node.  If
+		# a hash is provided as an argument the key is used as the name of
+		# the value an object should be assigned to.
 		#
-		# @param [Array<Object>] values The values to be assigned to this node.
+		# @param [Array<Object>, Hash{Symbol => Object}]  values  The values to be assigned to this node.
 		def values=(values)
-			if values.length != self.class.value_names.length
-				raise 'Wrong number of values specified.'
-			end
+			case values
+			when Array
+				if values.length != self.class.value_names.length
+					raise 'Wrong number of values specified.'
+				end
 			
-			self.class.value_names.each_with_index do |name, i|
-				self.send((name.to_s + '=').to_sym, values[i])
+				self.class.value_names.each_with_index do |name, i|
+					self.send((name.to_s + '=').to_sym, values[i])
+				end
+				
+			when Hash
+				values.each do |name, val|
+					if self.class.value_names.include?(name)
+						self.send((name.to_s + '=').to_sym, val)
+					else
+						raise "ASTNode subclass #{self.class.name} does not have a value named #{name}."
+					end
+				end
 			end
 		end
 	end