rdx 0.9.0.pre

data/lib/rdx/example.rb

@@ -0,0 +1,679 @@
+
+module RDX
+	
+	#
+	# Represents an example in a comment, like the following:
+	#   
+	#   # This in an example:
+	#   def example_method arg
+	#     arg + 1
+	#   end
+	#   example_method(3) #=> 4
+	#
+	class Example < CodeObject::Runnable::Startable
+		
+		include Assertions
+		
+		# The SourceFile this example is into.
+		def source_file
+			comment.source_file
+		end
+		
+		# The Comment this example belongs to.
+		attr_reader :comment
+		alias parent comment
+		
+		# Return +self+.
+		def example
+			self
+		end
+		
+		# The +Array+ of Statement that composes this example.
+		attr_reader :statements
+		alias children statements
+		
+		# The code contained in this example.
+		def code
+			text
+		end
+		
+		def initialize(comment,text,relative_line_no=1) # :nodoc:
+			@comment = comment
+			super(text,relative_line_no)
+			@statements = []
+			@active = nil
+		end
+		
+		#
+		# Has the user seen this example?
+		# This is +true+ if the example will appear on the documentation output or
+		# it won't but is the target of an explicit directive
+		# (according to the limitations of the generator).
+		#
+		def seen?
+			not @active.nil?
+		end
+		
+		# Will this example be runned?
+		def active?
+			@active
+		end
+		
+	#
+	# :section: API
+	#
+		
+		# Returns +true+. This method should be used instead of _section_<tt>.is_a?(Example)</tt>.
+		def example?
+			true
+		end
+		
+		# Returns +false+. This method should be used instead of _section_<tt>.is_a?(PlainText)</tt>.
+		def text?
+			false
+		end
+	
+		#
+		# Activates this example so that it will be run.
+		# If _force_ is +true+ this happens even if the example was previously deactivated.
+		#
+		def activate force=false
+			@active = true if !seen? || force
+			return self
+		end
+		
+		#
+		# Deactivates this example so that it won't be run.
+		# If _force_ is +true+ this happens even if the example was previously activated.
+		#
+		def deactivate force=false
+			@active = false if !seen? || force
+			return self
+		end
+		
+		# Activates this example; #deactivate will no more have effect.
+		def activate!
+			@active = true
+			define_singleton_method(:deactivate){ |*| }
+			return self
+		end
+		
+		# Deactivates this example; #activate will no more have effect.
+		def deactivate!
+			@active = false
+			define_singleton_method(:activate){ |*| }
+			return self
+		end
+		
+		#
+		# Skips the execution of this example and reports it.
+		# If _msg_ is given it will be printed in the report.
+		# If _l_no_ is given it will be used in the report instead of #relative_line_no.
+		#
+		def whole_skip msg=nil, type=nil, l_no=nil
+			activate!
+			l_no ||= relative_line_no
+			super msg, type, comment.location(l_no)
+		end
+		
+		#
+		# Marks this example as deliberately buggy. This means that:
+		# * failures and errors are ordinary: they are not reported;
+		# * successes are unexpected: a warning of type +bug+ will
+		#   be reported along with the success.
+		#
+		def is_buggy
+			activate
+			dont_register = lambda{ |*| }
+			define_singleton_method :build_children do
+				super()
+				define_singleton_method :register_failure, dont_register
+				define_singleton_method :register_error, dont_register
+				define_singleton_method :register_success do |*args|
+					warn 'Bug not detected: the assertion passes', :bug
+					super(*args)
+				end
+				statements.each do |stmnt|
+					stmnt.define_singleton_method :register_error, dont_register
+				end
+				statements.flat_map(&:children).each do |expct|
+					expct.define_singleton_method :register_failure, dont_register
+					expct.define_singleton_method :register_success do |*args|
+						warn 'Bug not detected: the assertion passes', :bug if assertion?
+						super(*args)
+					end
+				end
+			end
+		end
+		
+		# Activates this example and calls +super+.
+		def run_in_tmpdir
+			activate
+			super
+		end
+		
+		# Activates this example and calls #binding=.
+		def set_binding binding
+			activate
+			self.binding = binding
+		end
+		
+		#
+		# Activates this example an calls #set_output passing
+		# it _output_ (which may even be another Example) as the
+		# expected result on <tt>$stdout</tt>.
+		#
+		def produces_on_stdout output, l_no=nil
+			self.activate
+			if output.is_a?(Example)
+				output.deactivate!
+				output = output.text
+			end
+			set_output output, nil, l_no
+		end
+		alias produces produces_on_stdout
+		alias outputs produces_on_stdout
+		
+		#
+		# Activates this example an calls #set_output passing
+		# it _output_ (which may even be another Example) as the
+		# expected result on <tt>$stderr</tt>.
+		# 
+		# #normalize_values is enhanced so that the file name and line number are removed
+		# from warnings: in this way we can have more focus on the content of the message.
+		#
+		def produces_on_stderr output, l_no=nil
+			self.activate
+			if output.is_a?(Example)
+				output.deactivate!
+				output = output.text
+			end
+			orig_level = method(:normalize_values)
+			define_singleton_method :normalize_values do |exp,act,&normalize|
+				if act.is_a?(String)
+					act = act.dup
+					act.gsub! /^#{Regexp.escape file_name}:(\d+): (?=warning: )/ do |matched|
+						line_range.cover?($1.to_i) ? '' : matched
+					end
+				end
+				orig_level.call(exp,act,&normalize)
+			end
+			set_output nil, output, l_no
+		end
+		
+		#
+		# Wraps the run of this example into #assert_output_but, passing it
+		# the expected _stdout_ and _stderr_.
+		# The differences are reduced through Text#normalize_output.
+		# 
+		# If _l_no_ is given it will be used in the report instead of #relative_line_no.
+		#
+		def set_output stdout, stderr, l_no=nil
+			l_no ||= relative_line_no
+			orig_run = method(:run)
+			normalize = Text.method(:normalize_output).to_proc
+			define_singleton_method :run do
+				trace_assertion :multiline_output_literal, comment.location(l_no) do
+					assert_output_but(normalize,stdout,stderr){ orig_run.call }
+				end
+			end
+			return self
+		end
+		
+		#
+		# Activates this example and changes <tt>$stdin</tt> to the given _input_
+		# (which may be a +String+ or another example) during the execution.
+		#
+		def take_input_from input
+			self.activate
+			if input.is_a?(Example)
+				input.deactivate!
+				input = input.text
+			end
+			orig_run = method(:run)
+			define_singleton_method :run do
+				RDX::Util.change_stdin(input){ orig_run.call }
+			end
+			return self
+		end
+		
+		#
+		# Activates this example and expects that it raises the exception contained in _arg_.
+		# This may be:
+		# * an Example in which it's described the exception (its +text+ is processed through
+		#   Text#split_exception_string using +:class_message+ or +:message_class+ as the _mode_);
+		# * an +Exception+ class (or +String+ containing the class' name);
+		# * an +Array+ containing the class and message.
+		# This method uses #assert_msg_raised_but, normalizing the exception message (if given)
+		# through Text#normalize_exception_message. If the exception class is +nil+ it will not
+		# be sent to the assertion method.
+		# 
+		# If _l_no_ is given it will be used in the report instead of #relative_line_no.
+		#
+		def raises arg, l_no=nil
+			self.activate
+			if arg.is_a?(Example)
+				arg.deactivate!
+				arg = arg.text
+				cls,msg = Text.split_exception_string(arg,:class_message)
+				cls,msg = Text.split_exception_string(arg,:message_class) if cls.nil?
+			else
+				cls,msg = arg
+			end
+			cls = toplevel_scope.const_get(cls) if cls.is_a?(String)
+			l_no ||= relative_line_no
+			orig_run = method(:run)
+			normalize = Text.method(:normalize_exception_message).to_proc
+			define_singleton_method :run do
+				trace_assertion :error_literal, comment.location(l_no) do
+					assert_msg_raised_but normalize, msg, false, *cls do
+						orig_run.call
+					end
+				end
+			end
+			return self
+		end
+		
+		#
+		# This example will run only if necessary, that is when the documentation output is required;
+		# otherwise this is skipped through #whole_skip.
+		# 
+		# This is often used if the example is time-consuming:
+		# when the documentation output isn't required the user just wants to run the tests quickly,
+		# so it's better to bypass this hindrance.
+		#
+		def lazy l_no=nil
+			return activate if options.doc_output
+			whole_skip "turn on documentation output", :LAZY, l_no
+		end
+		
+		#
+		# Registers this example as a _setup_ in the #comment, that will run
+		# before every Comment#enclosed_comments.
+		#
+		def use_as_setup
+			deactivate!
+			build
+			comment.def_setup(self)
+			return self
+		end
+		
+		#
+		# Registers this example as a _teardown_ in the #comment, that will run
+		# after every Comment#enclosed_commnets.
+		#
+		def use_as_teardown
+			deactivate!
+			build
+			comment.def_teardown(self)
+			return self
+		end
+		
+		# Run this exemple in a full independent way from the parent comment.
+		def separate_from_comment
+			deactivate!            # will be deleted for sure from the comment
+			build
+			store.add_test self    # because it will be run directly
+			return self
+		end
+		
+		# Activates this example and run it before requiring the full set of libraries.
+		def run_before_require
+			activate
+			@before_require = true
+			separate_from_comment
+			clear_run_hooks!
+			return self
+		end
+		
+		#
+		# Activates this example, runs the whole comment in a temporary directory and
+		# writes the +text+ of this example in the file named _fname_ (avoiding
+		# the whole wrap in a here document and a call to <tt>File.write</tt>).
+		# If a block is given it is yielded the text that will be written, so that
+		# the caller can modify it.
+		# 
+		# If _l_no_ is given it will be used in the report instead of #relative_line_no.
+		# 
+		# Since this example is not executed #check_convention_patterns is called.
+		#
+		def write_to_file fname, l_no=relative_line_no
+			activate
+			fname = Pathname(fname)
+			raise 'Absolute location not allowed' if fname.absolute?
+			l_no ||= relative_line_no
+			check_convention_patterns 'example not executable'
+			comment.run_in_tmpdir
+			skip_building
+			define_singleton_method :run do
+				trace_execution comment.location(l_no) do
+					content = self.text.dup
+					content = yield(content) if block_given?
+					content.rstrip!
+					content << "\n"
+					fname.dirname.expand_path.mkpath
+					File.write fname, content
+				end
+			end
+		end
+		
+		#
+		# Activates this example, runs the whole comment in a temporary directory and
+		# compares the +text+ of this example against the content of the file named _fname_
+		# (avoiding a call to <tt>File.read</tt>).
+		# Differences are reduced through Text#normalize_output.
+		# 
+		# If _l_no_ is given it will be used in the report instead of #relative_line_no.
+		#
+		def check_file_content fname, l_no=nil
+			activate
+			fname = Pathname(fname)
+			raise 'Absolute location not allowed' if fname.absolute?
+			l_no ||= relative_line_no
+			comment.run_in_tmpdir
+			normalize = Text.method(:normalize_output).to_proc
+			skip_building
+			define_singleton_method :run do
+				trace_assertion :file_content, comment.location(l_no) do
+					act = fname.read
+					exp = self.text
+					assert_equal_but normalize, exp, act
+				end
+			end
+		end
+		
+		#
+		# This example is activated and set into floating point mode with _digits_ precision:
+		# * #assert_equal_numeric uses the specified precision as the default _epsilon_;
+		# * #assert_equal relies to +assert_equal_numeric+ if +Numeric+ are involved;
+		# * #normalize_values is enhanced with Text#normalize_floats if +String+ are involved.
+		#
+		def on_float_mode digits
+			activate
+			eps = 10.0 ** -digits
+			define_singleton_method :assert_equal_numeric do |exp,act,epsilon=eps,*args,&blk|
+				super(exp,act,epsilon,*args,&blk)
+			end
+			define_singleton_method :assert_equal do |exp,act,*args,&blk|
+				if exp.is_a?(Numeric) && act.is_a?(Numeric)
+					assert_equal_numeric exp,act,*args,&blk
+				else
+					super(exp,act,*args,&blk)
+				end
+			end
+			orig_level = method :normalize_values
+			define_singleton_method :normalize_values do |exp,act,&normalize|
+				if exp.is_a?(String) && act.is_a?(String)
+					exp = Text.normalize_floats(exp,digits)
+					act = Text.normalize_floats(act,digits)
+				end
+				orig_level.call(exp,act,&normalize)
+			end
+		end
+
+		#
+		# This example is activated and differences in numbers are reduced to minimum.
+		# #normalize_values is enhanced so that:
+		# * +Numeric+ are reduced to <tt>0</tt>;
+		# * Text#generalize_numerics is used on strings.
+		#
+		def on_indicative_numbers_mode
+			activate
+			orig_level = method :normalize_values
+			define_singleton_method :normalize_values do |exp,act,&normalize|
+				if exp.is_a?(Numeric) && act.is_a?(Numeric)
+					exp = act = 0
+				elsif exp.is_a?(String) && act.is_a?(String)
+					exp = Text.generalize_numerics(exp)
+					act = Text.generalize_numerics(act)
+				end
+				orig_level.call(exp,act,&normalize)
+			end
+		end
+		
+		class Bash # :nodoc:
+			require 'open3'
+			class << self
+				# The system +bash+ command used by Directive::bash.
+				attr_accessor :bash
+			end
+			self.bash = 'bash'
+			attr_reader :example, :default_prompt, :continuation_prompt
+			private :example, :default_prompt, :continuation_prompt
+			def initialize example, default_prompt, continuation_prompt
+				@example = example
+				@default_prompt      = build_prompt default_prompt
+				@continuation_prompt = build_prompt continuation_prompt
+			end
+			def parse code
+				result = [] # [input,input_l_no,output,output_l_no]
+				prev_status = nil
+				code.each_line.with_index do |line,l_no|
+					l_no += 1 # line numbers begins from 1
+					current_elem = result.last
+					case status=classify_line(line)
+					when :start_input
+						result << [line,l_no,'',l_no+1]
+					when :cont_input
+						unless [:start_input,:cont_input].include?(prev_status)
+							raise ParseError.new "Default prompt `#{default_prompt}' not detected", l_no
+						end
+						current_elem[0] << line
+						current_elem[3] += 1
+					when :output
+						if nil == prev_status
+							raise ParseError.new "Default prompt `#{default_prompt}' not detected", l_no
+						end
+						current_elem[2] << line
+					end
+					prev_status = status
+				end
+				# Remove useless results:
+				result.delete_if do |elems|
+					elems[0] = '' unless elems[0] =~ /\S/
+					elems[2] = '' unless elems[2] =~ /\S/
+					elems[0].empty? && elems[2].empty?
+				end
+				return result
+			end
+			def run_code code
+				return '' if code.empty?
+				out,err,status = Open3.capture3(Bash.bash, :stdin_data=>code.to_str)
+				out = '' unless out =~ /\S/
+				err = '' unless err =~ /\S/
+				unless status.success?
+					error = SystemCallError.new(status.exitstatus)
+					error.message.insert 0, "In bash input:\n"
+					error.message << "\n#{err}" unless err.empty?
+					raise error
+				end
+				$stderr.print err unless err.empty?
+				return out
+			end
+		private
+			def build_prompt prompt
+				prompt = prompt.is_a?(Regexp) ? prompt.to_s : Regexp.escape(prompt.to_str)
+				return /^#{prompt}/
+			end
+			def classify_line(line)
+				if line.slice!(default_prompt)
+					:start_input
+				elsif line.slice!(continuation_prompt)
+					:cont_input
+				else
+					:output
+				end
+			end
+		end
+		
+		#
+		# Activates this example, runs the whole comment in a temporary directory and
+		# sets this example in bash mode.
+		# 
+		# The execution is interpreted according to the beginning of each line:
+		# * _default_prompt_ starts a new bash command;
+		# * _continuation_prompt_ continues the current command;
+		# * otherwise specifies the output of the current command
+		#   (differences are reduced through Text#normalize_output).
+		#
+		def on_bash_mode default_prompt, continuation_prompt
+			activate
+			comment.run_in_tmpdir
+			bash = Bash.new self, default_prompt, continuation_prompt
+			io = nil
+			define_singleton_method :build_self do
+				io = bash.parse text
+			end
+			normalize = Text.method(:normalize_output).to_proc
+			define_singleton_method :run do
+				return unless io
+				io.each do |input,input_l_no,exp_out,out_l_no|
+					begin
+						act_out = nil
+						trace_assertion :bash_input, location(input_l_no) do
+							act_out = bash.run_code(input)
+						end
+					rescue SystemCallError => err
+						raise err if exp_out.empty?
+						register_error err # expectation -> continue evaluation
+					else
+						if exp_out.empty?
+							$stdout.print act_out # will eventually generate a warning
+						else
+							trace_assertion :bash_output, location(out_l_no) do
+								assert_output_but normalize, exp_out do
+									$stdout.print act_out
+								end
+							end
+						end
+					end
+				end
+			end
+			return self
+		end
+		
+	#
+	# :section: Internal
+	#
+	
+		#
+		# Tries to hide the fact that the code isn't executed in the true toplevel.
+		# This is done removing the fake one (the #toplevel_scope) from the actual and expected
+		# strings (with Text#remove_enclosing_module).
+		# 
+		# Note that this doesn't work if those string aren't compared directly -
+		# for example if they are part of an +Array+ -, but these situations are very rare.
+		# 
+		# The original method is then called.
+		#
+		def normalize_values exp, act, &normalize
+			act = Text.remove_enclosing_module(act,toplevel_scope) if act.is_a?(String)
+			exp = Text.remove_enclosing_module(exp,toplevel_scope) if exp.is_a?(String)
+			exp, act = comment.normalize_values exp, act
+			super
+		end
+		
+		# Filters the backtrace of raised exceptions.
+		def exception_details exc, msg=nil
+			exc.set_backtrace RDX.filter_backtrace(exc.backtrace)
+			super
+		end
+		
+		#
+		# If this example hasn't been #seen? calls #check_convention_patterns.
+		# In absence of explicit directives, this means that the comment
+		# won't be part of the documentation output, hence its examples are not executed.
+		#
+		def check_non_documenting
+			return if seen?
+			deactivate
+			check_convention_patterns 'non-documenting comment'
+		end
+		
+		# Wraps the original method into #check_uncaptured_output and #capture_exceptions.
+		def whole_run(*)
+			capture_exceptions do
+				self.encoding = from_magic_comment
+				check_uncaptured_output{ super }
+			end
+		end
+		
+	private
+		
+		#
+		# The example is parsed and subdivided into toplevel statements (by RubyLex#extract_statements).
+		# Each one generates a Statement object.
+		#
+		def build_self # :doc:
+			RubyLex.extract_statements text do |code,l_no|
+				statements << Statement.new(self,code,l_no)
+			end
+		end
+		
+		#
+		# Generates a warning for each convention is recognized
+		# in a inner comment (or potential one).
+		#
+		def check_convention_patterns section # :doc:
+			comments = begin
+				RubyLex.extract_comments(text)
+			rescue ParseError
+				RubyLex.extract_potential_comments(text)
+			end
+			comments.each do |text,l_no|
+				text = Text.normalize_comment text
+				store.find_convention_in text do |conv|
+					warn "Convention `#{conv.name}' recognized in #{section}",
+						:conventions, location(l_no)
+				end
+			end
+			return self
+		end
+		
+		#
+		# Captures the +Exception+ raised during the execution of this example.
+		# Most of them are rescued and an error is reported, so that it
+		# will not propagate among other examples.
+		#
+		def capture_exceptions # :doc:
+			yield
+		rescue SystemExit => err
+			unless err.backtrace.frozen?
+				# this wasn't generated by evaluation of code
+				raise err	
+			end
+		rescue *Assertions::PASSTHROUGH_EXCEPTIONS
+			raise
+		rescue Exception => err
+			# Most types of errors are catched and doesn't stop the others
+			register_error err
+		end
+		
+		#
+		# Generates a warning if the output of this example isn't captured -
+		# checked with conventions or directives. This applies to both
+		# <tt>$stdout</tt> and <tt>$stderr</tt>.
+		#
+		def check_uncaptured_output &blk # :doc:
+			stdout,stderr = capture_io &blk
+			warn "Uncaptured stdout:\n#{stdout}", :stdout if stdout =~ /\S/
+			warn "Uncaptured stderr:\n#{stderr}", :stderr if stderr =~ /\S/
+		end
+		
+	# :stopdoc:
+		
+		# Override Minitest::Assertions#skip
+		define_method :skip, CodeObject.instance_method(:skip)
+		
+		def from_magic_comment
+			md = text.match Text::REGEXP::MAGIC_COMMENT
+			return unless md
+			l_no = 1 + text[0...md.begin(1)].count("\n")
+			trace_execution location(l_no) do
+				Kernel.eval("#{md[1]}\n__ENCODING__")
+			end
+		end
+		
+	end
+	
+end