rltk 1.2.0 → 2.0.0

data/Rakefile

@@ -7,35 +7,33 @@
 # Rake Tasks #
 ##############
 
+# Gems
 require 'rake/testtask'
 require 'bundler'
 
-begin
-	require 'rdoc/task'
-	
-	RDoc::Task.new do |t|
-		t.title		= 'The Ruby Language Toolkit'
-		t.main		= 'README'
-		t.rdoc_dir	= 'doc'
-	
-		t.rdoc_files.include('README', 'lib/*.rb', 'lib/rltk/*.rb', 'lib/rltk/**/*.rb')
-	end
-
-rescue LoadError
-	warn 'RDoc is not installed.'
-end
+require File.expand_path("../lib/rltk/version", __FILE__)
 
 begin
-	require 'rcov/rcovtask'
-	
-	Rcov::RcovTask.new do |t|
-		t.libs		<< 'test'
-		t.rcov_opts	<< '--exclude gems,ruby'
-		t.test_files	= FileList['test/tc_*.rb']
+	require 'yard'
+
+	YARD::Rake::YardocTask.new do |t|
+		yardlib = File.join(File.dirname(__FILE__), 'yardlib/rltk.rb')
+		
+		t.options	= [
+			'-e',		yardlib,
+			'--title',	'The Ruby Language Toolkit',
+			'-m',		'markdown',
+			'-M',		'redcarpet',
+			'-c',		'.yardoc/cache',
+			'--private'
+		]
+		
+		
+		t.files	= Dir['lib/**/*.rb'] + ['-'] + Dir['examples/kazoo/**/*.md'].sort
 	end
 	
 rescue LoadError
-	warn 'Rcov not installed.'
+	warn 'Yard is not installed. `gem install yard` to build documentation.'
 end
 
 Rake::TestTask.new do |t|
@@ -44,4 +42,141 @@ Rake::TestTask.new do |t|
 	t.test_files = FileList['test/ts_rltk.rb']
 end
 
+if RUBY_VERSION[0..2] == '1.8'
+	begin
+		require 'rcov/rcovtask'
+		
+		Rcov::RcovTask.new do |t|
+			t.libs      << 'test'
+			t.rcov_opts << '--exclude gems,ruby'
+			
+			t.test_files = FileList['test/tc_*.rb']
+		end
+		
+	rescue LoadError
+		warn 'Rcov not installed.'
+	end
+end
+
+# Bundler tasks.
 Bundler::GemHelper.install_tasks
+
+# Rubygems Taks
+begin
+	require 'rubygems/tasks'
+	
+	Gem::Tasks.new do |t|
+		t.console.command = 'pry'
+	end
+	
+rescue LoadError
+	'rubygems-tasks not installed.'
+end
+
+desc 'Generate the bindings for LLVM.'
+task :gen_bindings do
+	require 'ffi_gen'
+	
+	# Generate the standard LLVM bindings.
+	
+	blacklist = [
+		'LLVMGetMDNodeOperand',
+		'LLVMGetMDNodeNumOperands',
+		'LLVMInitializeAllTargetInfos',
+		'LLVMInitializeAllTargets',
+		'LLVMInitializeNativeTarget'
+	]
+	
+	deprecated = [
+		# BitReader.h
+		'LLVMGetBitcodeModuleProviderInContext',
+		'LLVMGetBitcodeModuleProvider',
+		
+		# BitWriter.h
+		'LLVMWriteBitcodeToFileHandle',
+		
+		# Core.h
+		'LLVMCreateFunctionPassManager',
+		
+		# ExectionEngine.h
+		'LLVMCreateExecutionEngine',
+		'LLVMCreateInterpreter',
+		'LLVMCreateJITCompiler',
+		'LLVMAddModuleProvider',
+		'LLVMRemoveModuleProvider'
+	]
+	
+	headers = [
+		'llvm-c/Core.h',
+		
+		'llvm-c/Analysis.h',
+		'llvm-c/BitReader.h',
+		'llvm-c/BitWriter.h',
+		'llvm-c/Disassembler.h',
+		'llvm-c/ExecutionEngine.h',
+		'llvm-c/Initialization.h',
+		'llvm-c/Object.h',
+		'llvm-c/Target.h',
+		
+		'llvm-c/Transforms/IPO.h',
+		'llvm-c/Transforms/Scalar.h'
+	]
+	
+	FFIGen.generate(
+		:module_name	=> 'RLTK::CG::Bindings',
+		:ffi_lib		=> "LLVM-#{RLTK::LLVM_TARGET_VERSION}",
+		:headers		=> headers,
+		:cflags		=> `llvm-config --cflags`.split,
+		:prefixes		=> ['LLVM'],
+		:blacklist	=> blacklist + deprecated,
+		:output		=> 'lib/rltk/cg/generated_bindings.rb'
+	)
+	
+	# Generate the extended LLVM bindings.
+	
+	headers = [
+		'llvm-ecb.h',
+		
+		'llvm-ecb/support.h'
+	]
+	
+	begin
+		FFIGen.generate(
+			:module_name	=> 'RLTK::CG::Bindings',
+			:ffi_lib		=> "LLVM-ECB-#{RLTK::LLVM_TARGET_VERSION}",
+			:headers		=> headers,
+			:cflags		=> `llvm-config --cflags`.split,
+			:prefixes		=> ['LLVM'],
+			:output		=> 'lib/rltk/cg/generated_extended_bindings.rb'
+		)
+	rescue
+	end
+end
+
+desc 'Find LLVM bindings with a regular expression.'
+task :find_bind, :part do |t, args|
+	
+	# Get the task argument.
+	part = Regexp.new(args[:part])
+	
+	# Require the Bindings module.
+	require 'rltk/cg/bindings'
+	
+	syms =
+	Symbol.all_symbols.select do |sym|
+		sym = sym.to_s.downcase
+		
+		sym[0..3] == 'llvm' and sym[4..-1] =~ part
+	end.sort
+	
+	puts
+	if not syms.empty?
+		puts "Matching bindings [#{syms.length}]:"
+		syms.each { |sym| puts "\t#{sym}" }
+	
+	else
+		puts 'No matching bindings.'
+	end
+	puts
+end
+

data/lib/rltk/ast.rb

@@ -3,45 +3,52 @@
 # Date:		2011/01/19
 # Description:	This file provides a base Node class for ASTs.
 
+############
+# Requires #
+############
+
+# Ruby Language Toolkit
+require 'rltk/util/monkeys'
+
+#######################
+# Classes and Modules #
+#######################
+
 module RLTK # :nodoc:
-	# A TypeMismatch is thrown when an object being set as a child or value of
+	# A TypeMismatch is raised when an object being set as a child or value of
 	# an ASTNode is of the wrong type.
-	class TypeMismatch < Exception
+	class TypeMismatch < StandardError
 		
-		# Instantiates a new TypeMismatch object.  The first argument is the
-		# expected type and the second argument is the actual type of the
-		# object.
+		# 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
 		
-		# Converts the exception to a string.
+		# @return [String] String representation of the error.
 		def to_s
 			"Type Mismatch: Expected #{@expected} but received #{@actual}."
 		end
 	end
 	
-	# Returns true if klass0 is a subclass of klass1; false otherwise.
-	def self.subclass_of?(klass0, klass1)
-		begin
-			return true if klass0 == klass1
-		end while klass0 = klass0.superclass
-		
-		return false
-	end
-	
 	# This class is a good start for all your abstract syntax tree node needs.
 	class ASTNode
-		# A reference to the parent node.
+		# @return [ASTNode] Reference to the parent node.
 		attr_accessor :parent
 		
 		#################
 		# Class Methods #
 		#################
 		
-		def ASTNode.inherited(klass)
-			klass.class_exec do
+		class << self
+			
+			# Installs instance class varialbes into a class.
+			#
+			# @return [void]
+			def install_icvars
 				if self.superclass == ASTNode
 					@child_names = Array.new
 					@value_names = Array.new
@@ -49,126 +56,153 @@ module RLTK # :nodoc:
 					@child_names = self.superclass.child_names.clone
 					@value_names = self.superclass.value_names.clone
 				end
+			end
+			protected :install_icvars
+			
+			# Called when the Lexer class is sub-classed, it installes
+			# necessary instance class variables.
+			#
+			# @param [Class] klass The class is inheriting from this class.
+			#
+			# @return [void]
+			def inherited(klass)
+				klass.install_icvars
+			end
+			
+			# Defined a child for this AST class and its subclasses.
+			# The name of the child will be used to define accessor
+			# 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.
+			#
+			# @return [void]
+			def child(name, type)
+				if type.is_a?(Array) and type.length == 1
+					t = type.first
 				
-				# Defined a child for this AST class and its subclasses.
-				# The name of the child will be used to define accessor
-				# methods that include type checking.  The type of this
-				# child must be a subclass of the ASTNode class.
-				def self.child(name, type)
-					if type.is_a?(Array) and type.length == 1
-						t = type.first
+				elsif type.is_a?(Class)
+					t = type
 					
-					elsif type.is_a?(Class)
-						t = type
-						
-					else
-						raise Exception, '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 a subclass of
-					# ASTNode.
-					if not RLTK::subclass_of?(t, ASTNode)
-						raise Exception, "A child's type specification must be a subclass of ASTNode."
-					end
-					
-					@child_names << name
-					self.define_accessor(name, type, true)
+				else
+					raise 'Child and Value types must be a class name or an array with a single class name element.'
 				end
 				
-				# Returns an array of the names of this node's children.
-				def self.child_names
-					@child_names
+				# Check to make sure that type is a subclass of
+				# ASTNode.
+				if not t.subclass_of?(ASTNode)
+					raise "A child's type specification must be a subclass of ASTNode."
 				end
 				
-				# This method defines a type checking accessor named _name_
-				# with type _type_.
-				def self.define_accessor(name, type, set_parent = false)
-					ivar_name = ('@' + name.to_s).to_sym
-					
-					define_method(name) do
-						self.instance_variable_get(ivar_name)
-					end
-					
-					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
-							end
+				@child_names << name
+				define_accessor(name, type, true)
+			end
+			
+			# @return [Array<Symbol>] Array of the names of this node class's children.
+			def child_names
+				@child_names
+			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.
+			#
+			# @return [void]
+			def define_accessor(name, type, set_parent = false)
+				ivar_name = ('@' + name.to_s).to_sym
+				
+				define_method(name) do
+					self.instance_variable_get(ivar_name)
+				end
+				
+				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)
 							
-						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
+								value.parent = self if value
+							else
+								raise TypeMismatch.new(type, value.class)
 							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)
+						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.each { |c| c.parent = self }
-								else
-									raise TypeMismatch.new(type, value.class)
-								end
+							else
+								raise TypeMismatch.new(type, value.class)
 							end
+						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)
 							
-						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
+								value.each { |c| c.parent = self }
+							else
+								raise TypeMismatch.new(type, value.class)
 							end
 						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
+						end
 					end
 				end
+			end
+			private :define_accessor
+			
+			# 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.
+			#
+			# @param [String, Symbol]	name Name of value.
+			# @param [Class]			type Type of value.  Must NOT be a subclass of ASTNode.
+			#
+			# @return [void]
+			def value(name, type)
+				if type.is_a?(Array) and type.length == 1
+					t = type.first
 				
-				# 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.
-				def self.value(name, type)
-					if type.is_a?(Array) and type.length == 1
-						t = type.first
+				elsif type.is_a?(Class)
+					t = type
 					
-					elsif type.is_a?(Class)
-						t = type
-						
-					else
-						raise Exception, '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 RLTK::subclass_of?(t, ASTNode)
-						raise Exception, "A value's type specification must NOT be a subclass of ASTNode."
-					end
-					
-					@value_names << name
-					self.define_accessor(name, type)
+				else
+					raise 'Child and Value types must be a class name or an array with a single class name element.'
 				end
 				
-				# Returns an array of the names of this node's values.
-				def self.value_names
-					@value_names
+				# 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
+				define_accessor(name, type)
+			end
+			
+			# @return [Array<Symbol>] Array of the names of this node class's values.
+			def value_names
+				@value_names
 			end
 		end
 		
@@ -177,31 +211,39 @@ module RLTK # :nodoc:
 		####################
 		
 		# Used for AST comparison, this function will return true if the two
-		# nodes are of the same class and all of their values and children are
-		# equal.
+		# nodes are of the same class and all of their values and children
+		# are equal.
+		#
+		# @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
 		
-		# Returns the note with name _key_.
+		# @return [Object] Note with the name *key*.
 		def [](key)
 			@notes[key]
 		end
 		
-		# Sets the note named _key_ to _value_.
+		# Sets the note named *key* to *value*.
 		def []=(key, value)
 			@notes[key] = value
 		end
 		
-		# Returns an array of this node's children.
+		# @return [Array<ASTNode>] Array of this node's children.
 		def children
 			self.class.child_names.map { |name| self.send(name) }
 		end
 		
 		# Assigns an array of AST nodes as the children of this node.
+		#
+		# @param [Array<ASTNode>] children Children to be assigned to this node.
+		#
+		# @return [void]
 		def children=(children)
 			if children.length != self.class.child_names.length
-				raise Exception, 'Wrong number of children specified.'
+				raise 'Wrong number of children specified.'
 			end
 			
 			self.class.child_names.each_with_index do |name, i|
@@ -209,8 +251,11 @@ module RLTK # :nodoc:
 			end
 		end
 		
-		# Removes the note _key_ from this node.  If the _recursive_ argument
+		# 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.
 		def delete_note(key, recursive = true)
 			if recursive
 				self.children.each do |child|
@@ -228,15 +273,16 @@ module RLTK # :nodoc:
 		end
 		
 		# An iterator over the node's children.
+		#
+		# @return [void]
 		def each
 			self.children.each { |c| yield c }
 		end
 		
-		# Tests to see if a note named _key_ is present at this node.
+		# Tests to see if a note named *key* is present at this node.
 		def has_note?(key)
 			@notes.has_key?(key)
 		end
-		
 		alias :'note?' :'has_note?'
 		
 		# Instantiates a new ASTNode object.  The arguments to this method are
@@ -245,9 +291,11 @@ module RLTK # :nodoc:
 		# pass the values in as the first two arguments (in the order they
 		# were declared) and then the children as the remaining arguments (in
 		# the order they were declared).
+		#
+		# @param [Array<Object>] objects The values and children of this node.
 		def initialize(*objects)
 			if self.class == RLTK::ASTNode
-				raise Exception, 'Attempting to instantiate the RLTK::ASTNode class.'
+				raise 'Attempting to instantiate the RLTK::ASTNode class.'
 			else
 				@notes	= Hash.new()
 				@parent	= nil
@@ -260,24 +308,28 @@ module RLTK # :nodoc:
 		end
 		
 		# Maps the children of the ASTNode from one value to another.
+		#
+		# @return [void]
 		def map
 			self.children = self.children.map { |c| yield c }
 		end
 		
-		# Find the root of an AST.
+		# @return [ASTNode] Root of the abstract syntax tree.
 		def root
 			if @parent then @parent.root else self end
 		end
 		
-		# Returns an array of this node's values.
+		# @return [Array<Object>] Array of this node's values.
 		def values
 			self.class.value_names.map { |name| self.send(name) }
 		end
 		
 		# Assigns an array of objects as the values of this node.
+		#
+		# @param [Array<Object>] values The values to be assigned to this node.
 		def values=(values)
 			if values.length != self.class.value_names.length
-				raise Exception, 'Wrong number of values specified.'
+				raise 'Wrong number of values specified.'
 			end
 			
 			self.class.value_names.each_with_index do |name, i|