rdx 0.9.0.pre

data/lib/rdx/source_file.rb

@@ -0,0 +1,94 @@
+
+module RDX
+	
+	#
+	# Represents a parsed source file.
+	#
+	class SourceFile < CodeObject
+		
+		# Absolute path for file
+		attr_reader :absolute_path
+		alias file_name absolute_path
+		
+		# Conventionally the line number is <tt>1</tt>.
+		def line_no
+			1
+		end
+		
+		# The +Array+ of contained Comments.
+		attr_reader :comments
+		alias children comments
+		
+	# :stopdoc:
+	
+		attr_reader :reportables
+		
+		def initialize(absolute_path)
+			super(nil)
+			@absolute_path = absolute_path
+			@comments = []
+			@reportables = nil
+			@reportables_hash = Hash.new{ |hash,cmt| hash[cmt] = [] } # comment => reportables_ary
+		end
+		
+		def <=> other
+			return nil unless self.class == other.class
+			self.absolute_path <=> other.absolute_path
+		end
+		
+		def add_comment comment
+			@comments << comment
+			return self
+		end
+		def remove_comment comment
+			@comments.delete comment
+			return self
+		end
+		
+		def register reportable, code_object
+			@reportables_hash[code_object.comment] << reportable
+		end
+		
+		def collect_reportables
+			return @reportables if @reportables
+			@reportables = []
+			@reportables_hash.to_a.sort_by(&:first).each do |comment,reportables|
+				@reportables.concat reportables.sort_by(&:line_no)
+			end
+			@reportables_hash = nil
+			@reportables
+		end
+		
+	private
+	
+		def build_self
+			uniq_comments
+		end
+		
+		# Remove RDX comments pointing at the same location
+		# (for example RDoc creates more comments for ruby methods pointing at the same c-function)
+		# TODO: move to generator/rdoc
+		def uniq_comments
+			result = []
+			map = @comments.group_by(&:line_no)
+			map.delete(nil) # line number not set
+			map.each_value do |cmts|
+				if cmts.size == 1 # no conflict
+					result << cmts.first
+				else
+					doc,ndoc = cmts.partition(&:documenting)
+					if doc.empty?
+						result << ndoc.first
+					elsif ndoc.empty? || doc.size==1
+						result << doc.first
+					else # ambiguous situation
+						result << doc.first
+					end
+				end
+			end
+			@comments.replace result
+		end
+		
+	end
+	
+end

data/lib/rdx/specification.rb

@@ -0,0 +1,194 @@
+
+module RDX
+
+	#
+	# Allows you to specify the conventions and directives used in your files.
+	# 
+	# If the root directory of your project has an <tt>.rdx</tt> file,
+	# it's evalued as ruby code: this should return a Specification.
+	# Otherwise (or if there isn't such file) the ::default will be used and
+	# this class falls in the background.
+	# 
+	# In that file you should indeed use <tt>RDX::Specification.new</tt> passing
+	# a block, that is allowed to modify its state (see ::new).
+	#
+	class Specification
+
+		include Convention::SpecificationHelper
+		
+		include Directive::SpecificationHelper
+		
+		#
+		# :category: Internal
+		# 
+		# Loads the Specification from the given _file_ name.
+		# This is by default the <tt>.rdx</tt> file at the top level in the project directory.
+		#
+		def self.load file
+			file &&= file.dup.untaint
+			if file && File.file?(file)
+				opts = Object.const_defined?(:Encoding) ? { :mode => 'r:UTF-8:-' } : {}
+				code = File.read(file,opts).untaint
+				begin
+					spec = eval code, binding, file
+					if Specification === spec
+						spec.file = file.to_s
+						return spec
+					end
+					warn "[#{file}] isn't a #{self} (#{spec.class} instead).\nUsing default settings."
+				rescue SignalException, SystemExit
+					raise
+				rescue SyntaxError, Exception => e
+					warn "Invalid #{self} in [#{file}]: #{e}\nUsing default settings."
+				end
+			end
+			return nil
+		end
+		
+		#
+		# :category: Internal
+		# 
+		# Returns a new specification containing only the default initialization.
+		#
+		def self.default
+			new()
+		end
+		
+		#
+		# :call-seq:
+		#   new{ || ... }
+		#   new{ |spec| ... }
+		#
+		# Creates a new Specification initialized with #default_conventions
+		# and #default_directives.
+		# 
+		# If the block takes no argument it will be executed in the context
+		# of the specification instance, otherwise this will simply be yielded.
+		# 
+		# The instance methods of the Specification allow its customization
+		# (but only during the execution of the block).
+		# These facilities are provided by the included modules
+		# Convention::SpecificationHelper (with a few enhancements) and
+		# Directive::SpecificationHelper.
+		#
+		def initialize(&blk)
+			@file = nil
+			@known_conventions = Convention.list
+			@used_conventions = []
+			default_conventions
+			default_directives
+			if blk
+				if blk.arity == 0
+					instance_eval(&blk)
+				else
+					blk.call(self)
+				end
+			end
+			finalize
+		end
+		
+		def conventions # :nodoc:
+			@known_conventions
+		end
+		private :conventions
+		
+		#
+		# :category: Internal
+		# 
+		# Sets up the list of the default conventions.
+		# It's as if the content of this method would be
+		# at the beginning of each specification.
+		#
+		def default_conventions # :doc:
+			use_convention :eval
+			use_convention :result_eval
+			use_convention :result_same
+			use_convention :result_numeric
+			use_convention :result_string
+			use_convention :result_instance_of
+			use_convention :output_literal
+			use_convention :error_literal
+			use_convention :throws
+		end
+		private :default_conventions
+		
+		#
+		# :category: Internal
+		# 
+		# Sets up the list of the default directives.
+		# All the directives defined are automatically used.
+		#
+		def default_directives # :doc:
+			@directives = Directive.known
+		end
+		private :default_directives
+		
+		#
+		# Returns _conv_ if it's already a Convention; otherwise calls +super+.
+		# You can now use instance methods of Convention to modify its features.
+		#
+		def convention conv
+			conv.is_a?(Convention) ? conv : super
+		end
+		
+		#
+		# Uses the #convention _conv_ during the run, returning this convention.
+		# 
+		# You can than chain some methods to modify its behaviour, such as
+		# Convention#use_with (or better its alias +with+) or
+		# Convention#edit.
+		# 
+		# For example this line in the specification
+		# :rdx: off
+		#   use_convention(:result_eval).with '->'
+		# will associate the <tt>-></tt> prompt to Convention::result_eval.
+		#
+		def use_convention conv
+			conv = convention(conv)
+			@used_conventions << conv unless @used_conventions.include?(conv)
+			return conv
+		end
+		
+		#
+		# Removes the #convention _conv_ during the run.
+		# The convention is still defined and may be restored through #use_convention.
+		#
+		def dont_use_convention conv
+			@used_conventions.delete convention(conv)
+			return nil
+		end
+
+		# Use this convention once it's defined through +super+.
+		def define_convention(*)
+			use_convention super
+		end
+		
+		# Don't use this convention once it's undefined through +super+.
+		def undefine_convention(*)
+			dont_use_convention super
+		end
+		alias remove_convention undefine_convention
+		
+	# :stopdoc:
+		
+		def original?
+			file.nil?
+		end
+		
+		def finalize
+			return self if @used_conventions.frozen?
+			@known_conventions.replace @used_conventions
+			sort_conventions
+			@known_conventions.each(&:freeze).freeze
+			@directives.each(&:freeze).freeze
+			# Now (public) methods available
+			class << self # :nodoc:
+				public :conventions
+				attr_reader :directives
+				attr_accessor :file
+			end
+		end
+		
+	end
+
+end

data/lib/rdx/statement.rb

@@ -0,0 +1,248 @@
+
+module RDX
+	
+	#
+	# Represents a toplevel statement in an example.
+	# 
+	# For instance the following Example is composed by three +Statement+ objects:
+	# 
+	# :rdx: off
+	# 
+	#   statement_1
+	#   statement +
+	#   2
+	#   if true
+	#   else
+	#     statement
+	#     3
+	#   end # ends here
+	#
+	class Statement < CodeObject::Runnable
+		
+		# The SourceFile this statement is into.
+		def source_file
+			comment.source_file
+		end
+		
+		# The Comment this statement belongs to.
+		def comment
+			example.comment
+		end
+		
+		# The Example this statement belongs to.
+		attr_reader :example
+		alias parent example
+		
+		# Returns +self+.
+		def statement
+			self
+		end
+		
+		# The Expectation of this stetement (may be +nil+ if invalid).
+		attr_reader :expectation
+		
+		# Contains only the expectation.
+		def children
+			[expectation].compact
+		end
+		
+		# The code of this statement.
+		def code
+			text
+		end
+
+		def initialize(example,text,relative_line_no=1) # :nodoc:
+			@example = example
+			super(text,relative_line_no)
+			remove_magic_comment # encoding handled in example
+			@expectation = nil
+		end
+		
+		# The Convention associated with the expectation.
+		def convention
+			expectation && expectation.convention
+		end
+		
+		# Does the expectation an #assertion?
+		def assertion?
+			expectation && expectation.assertion?
+		end
+		
+		# Adds the label "top_level_statement" to +super+
+		def location l_no=nil
+			super(l_no,'top_level_statement')
+		end
+		
+	#
+	# :section: Internal
+	#
+		
+		# Computes the #actual_value and passes it to Expectation#run.
+		def run
+			expectation && expectation.run(actual_value)
+		end
+		
+		# Wraps the original method into #capture_exceptions.
+		def whole_run
+			capture_exceptions{ super }
+		end
+		
+	private
+		
+		#
+		# First RubyLex#extract_comments_from_statement is used to extract the comments.
+		# The final one is kept for #build_expectation, while those before are sent to #check_inner_conventions.
+		#
+		def build_self # :doc:
+			comments = RubyLex.extract_comments_from_statement(code)
+			# code must be valid since it was determined through RubyLex.statementize
+			last_comment = comments.pop
+			check_inner_conventions comments
+			build_expectation *last_comment
+		end
+		
+		#
+		# If a convention is determined inside the statement (while it isn't yet complete)
+		# a +ParseError+ will be raised.
+		#
+		def check_inner_conventions comments # :doc:
+			comments.find do |cmt,line_no|
+				cmt = Text.normalize_comment cmt
+				store.find_convention_in cmt do
+					raise ParseError.new 'Incomplete statement', line_no
+				end
+			end
+		end
+		
+		#
+		# First the last comment is normalized through Text#normalize_comment,
+		# then tries to find a convention that can accept this comment
+		# calling Convention#process_comment for the conventions in use.
+		# 
+		# When one convention is found, an Expectation will be associated to this statement;
+		# the result of +process_comment+ will be stored into Expectation#expected_data.
+		# 
+		# If the search fails, Convention.eval will be used
+		# (with the whole normalized comment as +expected_data+).
+		#
+		def build_expectation last_comment, line_no # :doc:
+			last_comment = Text.normalize_comment last_comment
+			conv,processed = store.find_convention_in(last_comment)
+			conv,processed = store.eval_convention,last_comment unless conv
+			@expectation = Expectation.new(self,conv,processed,line_no)
+		end
+		
+		# This is obtained processing the #code through Convention#process_statement.
+		def actual_value # :doc:
+			trace_execution do
+				convention.call_process_statement(self,code)
+			end
+		end
+		
+		#
+		# Rescues the +StandardError+ and subclasses raised during the execution of the statement.
+		# If there is an #assertion? the error is reported
+		# (and it will not propagate, so that other statements of this examples can run).
+		# Otherwise it's re-raised and will be handled by Example#capture_exceptions.
+		#
+		def capture_exceptions # :doc:
+			yield
+		rescue => err
+			raise err unless assertion?
+			register_error err
+		end
+		
+	end
+	
+	
+	
+	#
+	# Represent an expectation of a statement.
+	# This is written as a comment at its end that has been accepted by one of defined conventions.
+	# 
+	# For instance the statement in the next example
+	#   1 + 1 #=> 2
+	# has the expectation associated with the Convention::result_eval.
+	#
+	class Expectation < CodeObject::Runnable
+		
+		# The SourceFile this expectation is into.
+		def source_file
+			comment.source_file
+		end
+		
+		# The Comment this expectation is into.
+		def comment
+			example.comment
+		end
+		
+		# The Example this expectation is into.
+		def example
+			statement.example
+		end
+		
+		# The Statement of this expectation.
+		attr_reader :statement
+		alias parent statement
+		
+		# Returns +self+.
+		def expectation
+			self
+		end
+		
+		#
+		# Does the convention process an assertion?
+		# For example Convention.eval doesn't assert anything.
+		#
+		def assertion?
+			!!convention.process_assertion
+		end
+		
+		# The Convention of this expectation.
+		attr_reader :convention
+		
+		# The result of Convention#process_comment.
+		attr_reader :expected_data
+		
+		def initialize statement, convention, expected_data, relative_line_no=1 # :nodoc:
+			@statement  = statement
+			@convention = convention
+			@expected_data = expected_data
+			super(nil,relative_line_no)
+		end
+		
+	#
+	# :section: API
+	#
+		
+		# The default type is the #convention's name.
+		def warn msg, type=convention.name, frame=nil
+			super
+		end
+		
+	#
+	# :section: Internal
+	#
+		
+		#
+		# Receives Statement#actual_value as _actual_value_, computes #expected_value
+		# and process the assertion through Convention#process_assertion.
+		#
+		def run actual_value
+			act,exp = actual_value,expected_value # compute expected now
+			trace_assertion convention.name do # then do the assertion
+				convention.call_process_assertion example, act, exp
+			end
+		end
+		
+		# This is obtained processing the #expected_data through Convention#process_expectation.
+		def expected_value # :doc:
+			trace_execution do
+				convention.call_process_expectation(self,expected_data)
+			end
+		end
+		private :expected_value
+		
+	end
+
+end