rdx 0.9.0.pre

data/lib/rdx/binding.rb

@@ -0,0 +1,151 @@
+
+module RDX
+	
+	# The _main_ object of the whole application
+	MAIN_OBJECT = TOPLEVEL_BINDING.eval 'self' # :nodoc:
+	
+	#
+	# The methods defined here provide some useful +Binding+ objects, that can be used to execute some code.
+	#
+	module Binding
+		
+		extend self
+		
+	if false # For RDoc, methods will be defined after
+		
+		#
+		# Gives a +clone+ of +TOPLEVEL_BINDING+.
+		# The code executed here can affect very easily the rest of application (only local variables are
+		# not propagated), so care must be taken.
+		# 
+		# :rdx: toplevel
+		# 
+		#   # Some general proprieties:
+		#   b = RDX::Binding.toplevel
+		#   b.eval "local_variables"  # => []     # The binding is initially clear
+		#   b==RDX::Binding.toplevel # => false   # Each binding carries its local variables
+		#   b_self = b.eval "self"    #  > main
+		#   # That self looks like the main...
+		#   self == b_self            # => true   # ...and it is! Instance variables (and singleton methods) will be shared
+		#   b.eval "Module.nesting"   # => []     # Acts like [Object], so toplevel definitions are global (shared)
+		#   
+		#   # Interactions between them:
+		#   b1 = RDX::Binding.toplevel
+		#   b1.eval "local_var = @ivar = CONST = true"
+		#   b2 = RDX::Binding.toplevel
+		#   b1 == b2 #=> false     # Local variables will be different
+		#   b2.eval "local_var"    # raises NameError   # Ok, this isn't seen!
+		#   # But these two are:
+		#   b2.eval "@ivar"        # => true
+		#   b2.eval "CONST"        # => true
+		#   
+		#   # In true toplevel:
+		#   local_var   # raises NameError
+		#   @ivar       # => true
+		#   CONST       # => true
+		#   # Watch out from pollution! Clean up steps:
+		#   remove_instance_variable   :@ivar   # => true
+		#   Object.send :remove_const, :CONST   # => true
+		#
+		def toplevel_binding
+			# see this source file...
+		end
+		alias toplevel toplevel_binding
+		
+		# 
+		# Gives the toplevel +binding+ of a main-like object.
+		# The aim is to emulate the toplevel binding without polluting it too much.
+		# 
+		# Specifically:
+		# * +self+ points to a clone of the main object;
+		# * the _lexical_ _scope_ is set to this main object's singleton class;
+		# * +include+ and +define_method+ are redefined to better reproduce this environment.
+		# 
+		# These lead to the fact that almost all new definitions - intentional top-level constants and global
+		# variables are excluded - are restricted to that binding. All of this without sacrifycing efficiency.
+		# 
+		# :rdx: toplevel
+		# 
+		#   # Some general proprieties:
+		#   b = RDX::Binding.pseudo_toplevel
+		#   b.eval "local_variables"             # => []       # The binding is initially clear
+		#   b==RDX::Binding.pseudo_toplevel      # => false    # So each binding carries its local variables
+		#   b_self = b.eval "self"               #  > main
+		#   # That self looks like the main...
+		#   self == b_self                       # => false    # ...but it isn't! Instance variables will NOT be shared
+		#   b_meta = class << b_self; self; end
+		#   b.eval "Module.nesting"              # => [b_meta] # Constants will be defined inside that (NOT shared)
+		#   
+		#   # Interactions between them:
+		#   b1 = RDX::Binding.pseudo_toplevel
+		#   b1.eval "local_var = @ivar = CONST = true"
+		#   b2 = RDX::Binding.pseudo_toplevel
+		#   b2.eval "local_var"    # raises NameError
+		#   b2.eval "@ivar"        # => nil
+		#   b2.eval "CONST"        # raises NameError   # Constants are also hidden!
+		#   
+		#   # The same is true for the true toplevel:
+		#   local_var   # raises NameError
+		#   @ivar       # => nil
+		#   CONST       # raises NameError
+		#   
+		#   # Intentional polluting:
+		#   b1.eval "::TOP_LEVEL_CONST = $global_var = true"
+		#   TOP_LEVEL_CONST   # => true
+		#   $global_var       # => true
+		#   # Clean up:
+		#   Object.send :remove_const, :TOP_LEVEL_CONST # => true
+		#   $global_var = nil   # Even if it isn't truely removed...
+		# 
+		# These features makes #pseudo_toplevel_binding the favourite by RDX.
+		#
+		def pseudo_toplevel_binding
+			# see this source file...
+		end
+		alias pseudo_toplevel pseudo_toplevel_binding
+		
+	end
+	end
+	
+end
+
+
+
+# :enddoc:
+
+# This is empty for sure - we don't know what it was done with +TOPLEVEL_BINDING+
+RDX::TOPLEVEL_BINDING = binding().clone # :nodoc:
+
+# The use of Module#module_eval and Module.new doesn't pollute Module.nesting
+# for the new binding.
+RDX.module_eval do
+	
+	self::Binding.module_eval do
+		
+		def toplevel_binding
+			RDX::TOPLEVEL_BINDING.clone
+		end
+		alias toplevel toplevel_binding
+		
+		def pseudo_toplevel_binding
+			# The special behaviour of this _main_ object all lives in its singleton class,
+			# so first +clone+ is used on it to ensure all properties (except uniqueness) are copied.
+			RDX::MAIN_OBJECT.clone.instance_eval do
+				# override methods that use +top_wrapper+ (set by Kernel#load) forcing them to use the
+				# lexical scope instead of Object. This works fine in the toplevel, but we cannot gain the
+				# temporary mixin in Object...
+				class << self # :nodoc:
+					alias include extend
+					private :include
+					alias define_method define_singleton_method
+					private :define_method
+				end
+				self # this is +top_self+
+				# instance_eval sets the lexical scope to its singleton class, which is what we want
+			end.instance_eval 'binding' # the block remembers the context...
+		end
+		alias pseudo_toplevel pseudo_toplevel_binding
+		
+	end
+	
+end

data/lib/rdx/code_object.rb

@@ -0,0 +1,598 @@
+
+module RDX
+	
+	#
+	# Files are parsed and subdivided into code objects.
+	# 
+	# Each code object is represented by a class that has CodeObject in its
+	# +ancestors+ list. Here is the inheritance tree structure:
+	# * CodeObject   (abstract)
+	#   * SourceFile
+	#   * PlainText
+	#   * Directive
+	#   * CodeObject::Runnable   (abstract)
+	#     * Statement
+	#     * Expectation
+	#     * CodeObject::Runnable::Startable   (abstract)
+	#       * Comment
+	#       * Example
+	# However this hierarchy is useful only for implementation details.
+	# 
+	# The concrete objects are organized (hence better represented) in the following way,
+	# where each one have one #parent and an +Array+ of #children.
+	# * SourceFile
+	#   * Comment
+	#     * PlainText
+	#     * Directive
+	#     * Example
+	#       * Statement
+	#         * Expectation
+	#
+	class CodeObject
+		
+		include RDX::Util
+		
+		def self.delegate_to_parent name # :nodoc:
+			define_method name do |*args,&blk|
+				parent && parent.__send__(name,*args,&blk)
+			end
+		end
+		private_class_method :delegate_to_parent
+		
+		# +String+ containing the text.
+		attr_reader :text
+		
+		# Absolute line number in the source file.
+		attr_reader :line_no
+		alias first_line_no line_no
+		
+		# +Hash+ of arbitrary metadata.
+		attr_reader :metadata
+		
+		def initialize text, relative_line_no=nil # :nodoc:
+			if @text=text and Object.const_defined?(:Encoding)
+				# Allow representation of multibyte characters in US-ASCII source (eg: "\x80\u3042")
+				# TODO: see the magic comment instead...
+				text.force_encoding('UTF-8') if text.encoding == Encoding::US_ASCII
+			end
+			@line_no = parent.line_no + relative_line_no - 1 if relative_line_no
+			@metadata = {}
+		end
+		
+		# The parent CodeObject (at the top is +nil+).
+		def parent
+		end
+		
+		# The ancestor list of CodeObject, starting from +self+.
+		def ancestors
+			pos = self
+			result = [pos]
+			while pos = pos.parent
+				result << pos
+			end
+			result
+		end
+		
+		# +Array+ of children CodeObject.
+		def children
+			[]
+		end
+		
+		# The absolute path of the source file.
+		def file_name
+			source_file.file_name
+		end
+		
+		# The count of text lines.
+		def line_count
+			text.count("\n")
+		end
+		
+		# The absolute line number of the last line.
+		def last_line_no
+			first_line_no + line_count - 1
+		end
+		
+		# The +Range+ of absolute line number covering the text.
+		def line_range
+			first_line_no .. last_line_no
+		end
+		
+		# Line number relative to the parent code object
+		def relative_line_no
+			self.line_no - parent.line_no + 1
+		end
+		
+		#
+		# Makes the location string <tt>"file_name:line_no"</tt>.
+		# If _l_no_ is given it will be added to #line_no.
+		# If _text_ is given the location string will also contain <tt>":in `text'"</tt>.
+		#
+		def location l_no=nil, text=nil
+			line_no = self.line_no
+			return nil unless file_name && line_no
+			line_no += l_no-1 if l_no
+			text &&= ":in `#{text}'"
+			return "#{file_name}:#{line_no}#{text}"
+		end
+		
+		##
+		# :method:
+		# The Comment of the enclosing lexical scope (may be +nil+).
+		delegate_to_parent :enclosing_comment
+		
+	#
+	# :section: API
+	#
+		
+		# Generates a warning with the given _msg_, _type_ and _frame_.
+		# If the _type_ isn't disabled it will be registered in the report.
+		def warn msg=nil, type=nil, frame=nil
+			msg ||= 'No message given'
+			frame ||= location
+			register Warning.new(msg,type,frame) unless warning_disabled?(type)
+		end
+		
+		# Registers a skip in the report with the given _msg_, _type_ and _frame_.
+		def skip msg=nil, type=nil, frame=nil
+			msg ||= 'No message given'
+			frame ||= location
+			register Skip.new(msg,type,frame)
+		end
+		
+		#
+		# Disables the given _types_ of warning - all of them if types contains +:all+ or it's empty.
+		# The type of a generated warning is showed in the report: once seen, you know
+		# how to disable it if you want.
+		#
+		def disable_warnings *types
+			types.map!{ |s| s.to_s.downcase.to_sym }
+			types << :all if types.empty?
+			(metadata[:disabled_warnings] ||= []).concat types
+		end
+		
+		# Skip the #build phase for this object.
+		def skip_building
+			define_singleton_method(:build){ |*| }
+		end
+		
+	# :stopdoc:
+		
+		undef binding
+		undef eval
+		
+		def location_ary
+			[file_name,line_no]
+		end
+		
+		def <=> other
+			return nil unless other.respond_to?(:location_ary)
+			return self.location_ary <=> other.location_ary
+		end
+		
+		def warning_disabled? type
+			disabled_warnings = metadata[:disabled_warnings]
+			return true if disabled_warnings and
+				disabled_warnings.include?(:all) || disabled_warnings.include?(type)
+			return parent && parent.warning_disabled?(type)
+		end
+		
+		def register reportable
+			source_file.register reportable, self
+		end
+		
+		def register_error err, in_building=true
+			err = UnexpectedError.new(err)
+			err.in_building = in_building
+			register err
+		end
+		
+		def store
+			runner.store
+		end
+		
+		def encoding= enc
+			return unless enc && text
+			text.force_encoding enc
+			children.each{ |child| child.encoding = enc }
+		end
+		
+		delegate_to_parent :starter
+		
+		def to_s
+			"#<%s@%s>" % [self.class, location]
+		end
+		
+		def inspect
+			content = text || ''
+			if content.size > 60
+				content = content[0..60] + '...'
+			end
+			"#<%s:0x%x@%s;%p>" % [self.class, __id__, location, content]
+		end
+		
+	# :startdoc:
+	
+	#
+	# :section: Internal
+	#
+	
+		#
+		# First calls #build_self; if something gets wrong the error
+		# is reported and rescued, so that it will not propagate and
+		# the other brothers can anyhow be built.
+		# Then calls #build_children.
+		#
+		def build
+			build_self
+		rescue *Assertions::PASSTHROUGH_EXCEPTIONS
+			raise
+		rescue Exception => err
+			unless err.backtrace.frozen?
+				klassname = self.class.name.split('::').last.downcase
+				err.message.insert 0, "Error, #{klassname} skipped:\n"
+				l_no = err.line_no if err.is_a?(ParseError)
+				err.backtrace.unshift(location l_no)
+			end
+			register_error err
+			skip_running
+		else
+			build_children
+			return self
+		end
+		
+		# This must set up #children.
+		def build_self # :doc:
+		end
+		private :build_self
+		
+		# Calls #build for each child.
+		def build_children # :doc:
+			children.each(&:build)
+		end
+		private :build_children
+		
+		# Adds _frame_ to the exception raised by the block.
+		def trace_execution frame=location
+			yield
+		rescue Exception => err
+			if !err.is_a?(Assertion) &&        # Backtrace already handled in trace_assertion
+					!err.backtrace.frozen? &&      # Exception raised from the code: already tracked
+					err.backtrace.first != frame   # Redundant mark
+				err.set_backtrace err.backtrace.unshift(frame.to_str)
+			end
+			raise err
+		end
+		protected :trace_execution
+	
+		
+	
+		#
+		# A CodeObject that RDX may run.
+		#
+		class Runnable < self
+			
+			# Delegates to the parent (see Runnable::Startable#binding).
+			def binding
+				parent.respond_to?(:binding) && parent.binding
+			end
+
+			# Delegates to the parent (see Runnable::Startable#toplevel_self).
+			def toplevel_self
+				parent.respond_to?(:toplevel_self) && parent.toplevel_self
+			end
+
+			# Delegates to the parent (see Runnable::Startable#toplevel_scope).
+			def toplevel_scope
+				parent.respond_to?(:toplevel_scope) && parent.toplevel_scope
+			end
+			
+		#
+		# :section: API
+		#
+		
+			# Skip the #run phase for this object.
+			def skip_running
+				define_singleton_method(:run){ |*| }
+			end
+			
+		#
+		# :section: Internal
+		#
+			
+			# Runs in turn each child. This method can be patched and extended with other actions.
+			def run
+				children.each(&:whole_run)
+			end
+			
+			# By default delegates to #run but can be wrapped with other actions.
+			def whole_run
+				run
+			end
+			
+			# Registers _frame_ as a failure if the block fails an assertion;
+			# registers a success otherwise.
+			def trace_assertion conv_name=nil, frame=location
+				trace_execution frame do # handles possible exceptions raised during the assertion
+					begin
+						yield
+					rescue Assertion => fail
+						register_failure fail, conv_name, frame
+						# Assertions do not propagate so that the rest can run
+					else # No failure, no error
+						register_success conv_name, frame
+					end
+				end
+			end
+			protected :trace_assertion
+			
+			# Providing meaningful default values things can stay apparently simple.
+			def eval code, binding=binding, filename=file_name, lineno=line_no # :doc:
+				code = code.to_str
+				filename = filename.to_str
+				lineno = lineno.to_int
+				begin
+					Kernel.eval(code,binding,filename,lineno)
+				rescue Exception => err
+					adjust_exception_backtrace err, code, filename, lineno
+					raise err
+				end
+			end
+			private :eval
+			
+		# :stopdoc:
+		
+			def adjust_exception_backtrace err, code, filename, lineno
+				rdx_frame = "#{filename}:#{lineno}"
+				if err.is_a?(SyntaxError) && md = err.message.match(/:(\d+):\s+/)
+					# The location we want is in the message, not in the backtrace
+					file,line = md.pre_match,md[1].to_i
+					if file==filename && (lineno..lineno+code.chomp("\n").count("\n")).cover?(line)
+						err.message.slice! 0...md.end(0)
+						err.message.slice! /^#{Regexp.escape(file)}:\d.+/m # The first syntax error is enough in the backtrace
+						unless err.backtrace.first==rdx_frame
+							err.set_backtrace err.backtrace.dup if err.backtrace.frozen?
+							err.backtrace.unshift(rdx_frame)
+						end
+					end
+				end
+				# The following deals with artificial backtrace given (or modified) by the user
+				unless err.backtrace.find{ |line| line.start_with?(rdx_frame) }
+					# The information about the exact line number of the error is lost,
+					# but we don't want to lose completely the location of the runnable.
+					err.backtrace.unshift "#{rdx_frame}:in `RDX:indicative_location'"
+				end
+				unless err.backtrace.find{ |line| line.start_with?(__FILE__) }
+					# Will be removed by the backtrace filter if debug flag is off
+					err.backtrace.concat(caller)
+				end
+				err.backtrace.freeze # No more modification
+			end
+			private :adjust_exception_backtrace
+			
+		protected
+
+			def register reportable
+				if [nil,self].include? starter
+					super
+				else
+					starter.register reportable
+				end
+			end
+			
+			def register_error err
+				return super unless starter
+				starter.instance_eval{ super(err,false) }
+			end
+			
+			def register_failure fail, conv_name, frame
+				register Failure.new(fail,conv_name,frame)
+			end
+			
+			def register_success conv_name, frame
+				register Success.new(conv_name,frame)
+			end
+			
+			def remove_magic_comment
+				md = text.match Text::REGEXP::MAGIC_COMMENT
+				return unless md
+				start,finish = md.offset(1)
+				text.slice! start...finish
+			end
+			private :remove_magic_comment
+
+		# :startdoc:
+			
+		end
+	
+	
+
+		#
+		# A Runnable that RDX can start run.
+		#
+		class Runnable::Startable < Runnable
+
+			def initialize(*) # :nodoc:
+				super
+				self.binding = nil
+				@starter = nil
+			end
+			
+			# The +binding+ used to #eval the code.
+			def binding
+				@binding || super
+			end
+			
+			# The value of +self+ at the toplevel of #binding.
+			def toplevel_self
+				return super unless @binding
+				@toplevel_self ||= @binding.eval 'self'
+			end
+
+			# The <em>lexical scope</em> at the toplevel of #binding.
+			def toplevel_scope
+				return super unless @binding
+				@toplevel_scope ||= @binding.eval('::Module.nesting').first || ::Object
+			end
+			
+		#
+		# :section: API
+		#
+			
+			# Sets the #binding to the given _binding_.
+			def binding= binding
+				@binding = binding
+				clear_binding_info
+			end
+			
+			# Skip the whole run and register a Skip in the report.
+			def whole_skip msg=nil, type=nil, frame=nil
+				skip_building
+				define_singleton_method(:whole_run){ |*| skip msg, type, frame }
+			end
+			
+			module InTmpDir # :nodoc:
+				def whole_run(*)
+					prefix = File.basename(self.file_name,'.*') + "_#{self.line_no}-"
+					in_tmpdir(prefix,Dir.pwd){ super }
+				end
+				def normalize_values exp, act, &normalize
+					if exp.is_a?(String) && act.is_a?(String)
+						exp = Text.normalize_path(exp)
+						act = Text.normalize_path(act)
+					end
+					super
+				end
+			end
+			
+			#
+			# Do the whole run with the current directory set to a new temporary directory
+			# (actually the whole RDX process is run in a common temporary directory;
+			# this makes an empty subdirectory and moves into).
+			# #normalize_values is enhanced so that it calls Text#normalize_path
+			# for directly compared strings.
+			# 
+			# When creating files or directories in the example, this directive deletes all
+			# of them for you, avoiding explicit calls to <tt>FileUtils.rm<tt> and friends.
+			#
+			def run_in_tmpdir
+				extend InTmpDir
+			end
+			
+		# :stopdoc:
+		
+			def initialize_started
+				prepare_binding
+			end
+			private :initialize_started
+
+			def prepare_for_testing
+				return false if children.empty?
+				extend Started
+				return true
+			end
+			
+			# Clears cached values related to binding.
+			def clear_binding_info
+				@toplevel_self = nil
+				@toplevel_scope = nil
+			end
+			private :clear_binding_info
+			
+			def starter
+				@starter || super
+			end
+			def started?
+				@starter
+			end
+
+			def whole_run(starter=nil,beginned=false)
+				if @starter=starter and !ancestors.include?(starter)
+					starter.add_caller_frame = true
+				end
+				begin
+					run_setup(self) if beginned
+					super()
+				ensure
+					run_teardown(self) if beginned
+				end
+				starter.add_caller_frame = false if starter
+			end
+
+			delegate_to_parent :run_setup
+
+			delegate_to_parent :run_teardown
+
+			def clear_run_hooks!
+				define_singleton_method(:run_setup){ |*| }
+				define_singleton_method(:run_teardown){ |*| }
+			end
+			
+			def normalize_values exp, act
+				[exp, act]
+			end
+
+		# :startdoc:
+			
+		#
+		# :section: Internal
+		#
+			
+			# The default #binding for executing code is Binding.pseudo_toplevel.
+			# In this way the true toplevel environment is quite protected from contamination.
+			def prepare_binding
+				self.binding ||= Binding.pseudo_toplevel
+			end
+			
+		end
+
+
+
+		module Runnable::Started # :nodoc:
+
+			attr_reader :reportables
+
+			attr_reader :before_require
+
+			attr_accessor :add_caller_frame
+
+			def self.extended startable
+				startable.instance_eval{ initialize_started }
+			end
+
+			def initialize_started
+				super
+				@reportables  = []
+				@before_require ||= nil
+				@add_caller_frame = false
+			end
+			private :initialize_started
+
+			def passed?
+				reportables.none?(&:failure?)
+			end
+
+			def full_run
+				pwd = Dir.pwd
+				whole_run(self,true)
+			ensure
+				Dir.chdir(pwd) unless Dir.pwd==pwd
+			end
+
+			def result_code
+				result = reportables.max_by(&:code_priority) || Success
+				result.result_code
+			end
+
+			def register reportable
+				reportable.before_require = self.before_require
+				reportable.rdx_caller = self.to_s if add_caller_frame
+				reportables << reportable
+				super
+			end
+
+		end
+		
+	end
+
+end