rdx 0.9.0.pre

data/lib/rdx/directive.rb

@@ -0,0 +1,1432 @@
+
+module RDX
+
+	#
+	# == When to use directives?
+	# 
+	# Conventions work fine when all the processing steps are no longer than a single statement,
+	# but what if we want to interact with other examples, or in general with other sections of the comment?
+	# 
+	# Perhaps we may want to not execute an example, to interpret one as the output of the
+	# previous, to locally change some of the assertions methods, to run it in a temporary directory,
+	# to simulate a bash environment, and so on...
+	# 
+	# *Directives* allow all of this: they <b>work on a larger scale</b> (usually operate on other examples and
+	# the comment, but can also influence different comments and even other directives!),
+	# <b>making possible to treat your comments, text sections and examples differently from the standard way</b>.
+	# 
+	# == Which directives are available?
+	# 
+	# There are many directives, subdivided for functionality:
+	# * Activation/Deactivation: like ::on, ::off, ::skip, ::if, ::lazy;
+	# * Input/Output/Error: the most useful is ::stdout;
+	# * Context change: they can change the binding, current directory, execution in time
+	#   (like ::setup and ::teardown), simulate a ::bash session;
+	# * Assertion customization: to mention ::float
+	# * Miscellanous: insert comments, ::disable_warnings, ...
+	# All the directives already defined are documented as Directive's class methods
+	# (even if technically they aren't) in the relative sections.
+	# 
+	# If these aren't enough, you can *edit* them or even *define* your own directives
+	# in the Specification.
+	# 
+	# But before this you'll need to know other few things...
+	# 
+	# == How to use directives?
+	# 
+	# Directives come in two flavours: _explicit_ and _implicit_.
+	# 
+	# We can insert an <b>explicit directive</b> in a comment through the <b>documentation generator tool</b>.
+	# First we have to tell it - using its directive syntax - that we have an RDX directive;
+	# the rest (parameter for the generator tool) is parsed by Directive.split, that returns a directive
+	# name and optionally its parameter.
+	# For an example with the +rdoc+ generator see the "Directives" section in ::RDoc.
+	# 
+	# There is also the nice way to insert them *implicitly* in the comment, <b>without the need
+	# of the user to use the specific generator tool</b>. This is done recognizing specific patterns
+	# in plain text sections or examples. For instance ::stdout is automatically inserted if a plain text
+	# section consists - simplifying a bit - of the string 'produces:' (this pattern was so common in the
+	# Ruby Core that I thought implicit directives were a fundamental feature), while ::bash can detect an
+	# example starting with the bash prompt "<tt>$ </tt>" (since it isn't valid ruby syntax).
+	# 
+	# == What are directives?
+	# 
+	# Directives are classes (subclassing Directive), and each appearance in the comments generates
+	# a corresponding instance.
+	# 
+	# For this reason the class methods are used to define the behaviour of the directive
+	# (the most important is ::define), while the instance ones allow to query
+	# informations about their status (the #parameter, if it's #implicit?, some stored #metadata)
+	# and retrive neighbour sections in the comment (the most used is #next_example).
+	#
+	class Directive < CodeObject
+		
+		#
+		# :category: Internal
+		# 
+		# Splits _string_ (which is the parameter of the +rdx+ directive for the generator)
+		# into a directive name and its parameter.
+		# 
+		# The name consists of the first sequence of printable (non-space) characters -
+		# may even be the empty string -; the parameter is anything that follows after the
+		# first spaces - even this may be empty too.
+		#
+		def Directive.split string
+			string.to_str.strip.match(/\A\s*(\S*)\s*(.*)\z/m).captures
+		end
+		
+	# :stopdoc:
+		
+		def Directive.validate_name name
+			name = name.to_str
+			raise "Invalid directive name: `#{name}'" if name =~ /\s/
+			name.downcase
+		end
+		
+		def Directive.join dir, param
+			dir = validate_name dir
+			param = param.to_str
+			return param.empty? ? dir : "#{dir} #{param}"
+		end
+		
+	# :startdoc:
+		
+		class << self
+			
+			# The first name which with the directive is defined (not influenced by aliases).
+			attr_reader :name
+			
+			# Hash of arbitrary metadata. This will be copied into each instance.
+			attr_reader :metadata
+			
+		# :stopdoc:
+			
+			def to_s
+				"RDX::Directive:#{name}"
+			end
+			alias inspect to_s
+			
+			def verify_status
+				public_instance_methods(false).include?(:execute) or
+					raise "Directive behaviour not defined (use `define')"
+			end
+			private :verify_status
+			
+			def has_implicit?
+				!@implicit[:text].empty? or !@implicit[:example].empty?
+			end
+			
+			def find_implicit_in type, text
+				text = text.to_str
+				@implicit[type].each do |pattern|
+					md = text.match(pattern)
+					next unless md
+					param = md[1]
+					l_no = 1 + md.pre_match.count("\n") + md[0][/\A\s*/].count("\n")
+					result = [param, l_no]
+					yield(*result) if block_given?
+					return result
+				end
+				return false
+			end
+			
+		# :startdoc:
+			
+			#
+			# :call-seq:
+			#   define{ ||    ... }
+			#   define{ |dir| ... }
+			# 
+			# Defines the action of the directive: the block will be called from each instance generated from
+			# an occurrence of this directive in a comment.
+			# 
+			# If the block takes no arguments, it directly becomes the body of that instance method
+			# (so that +self+ is that directive instance in the block).
+			# Otherwise it will be yielded the directive instance as a parameter,
+			# without changing the block's context.
+			# 
+			# In both ways, you should use the instance methods of Directive to access its
+			# its status and retrive neighbour sections. At this point you will need the API
+			# provided by the CodeObject class and its descendants - mainly the Example one -
+			# to shape their behaviour to your needs.
+			#
+			def define &execution
+				if execution.arity == 0
+					define_method :execute do
+						trace_execution{ instance_eval(&execution) }
+					end
+				else
+					define_method :execute do
+						trace_execution{ execution.call(self) }
+					end
+				end
+			end
+			
+			#
+			# :category: Internal
+			# 
+			# Registers the given block as a configuration for the implicit recognization:
+			# this centralizes the building procedure, allowing the user to supply
+			# (through ::use_implicit_with) only the desired parameters - often some particular
+			# pattern or word. The block should call ::find_in_text or ::find_in_example.
+			# 
+			# After this ::default_implicit_configuration is called.
+			# 
+			# This configuration can be defined for built-in directives;
+			# user-defined ones often do not need this step.
+			#
+			def configure_implicit &implicit_configuration
+				@implicit_configuration = implicit_configuration
+				default_implicit_configuration
+			end
+			
+			# 
+			# Calls the configuration +Proc+ (if registered through ::configure_implicit)
+			# with the given arguments. In this way you can add new behaviour according to
+			# an existing scheme.
+			# 
+			# This method can be called from the Specification.
+			# 
+			# Returns +self+, allowing to chain other methods.
+			#
+			def use_implicit_with(*args,&blk)
+				if @implicit_configuration
+					@implicit_configuration.call(*args,&blk)
+				elsif !args.empty? || blk
+					raise "#{self} does not accept an implicit configuration"
+				end
+				return self
+			end
+			
+			# Clears the patterns for the implicit search.
+			def clear_implicit_patterns
+				@implicit = { :text=>[], :example=>[] }
+			end
+			
+			#
+			# Restores the default configuration for the implicit recognization of this
+			# directive. First calls ::clear_implicit_patterns, then
+			# calls the block supplied to ::configure_implicit without parameters
+			# (so its arity should allow this).
+			#
+			def default_implicit_configuration
+				clear_implicit_patterns
+				use_implicit_with()
+			end
+			
+			#
+			# Registers the Regexp to match the text of a non-example section.
+			# If there is a match, the directive is implicitly added in the comment
+			# without consuming any text.
+			#
+			def find_in_text regexp
+				raise 'Invalid Regexp pattern' unless regexp.is_a?(Regexp)
+				@implicit[:text] << regexp
+			end
+			
+			#
+			# Registers the Regexp to match the code of an example.
+			# If there is a match, the directive is implicitly added in the comment
+			# without consuming any text.
+			#
+			def find_in_example regexp
+				raise 'Invalid Regexp pattern' unless regexp.is_a?(Regexp)
+				@implicit[:example] << regexp
+			end
+			
+		end
+		
+		#
+		# This module is included into the Specification and allows the interaction
+		# with the Directive objects in use: you can define new ones, create aliases,
+		# remove those already in use or simply modify some of their features.
+		# 
+		# It also extends the Directive class, so that the built-in directives
+		# are defined in the same way.
+		# This provides a good starting point: just look at the core definitions
+		# to learn something very quickly. Anyway in the Directive class
+		# you can find the details on how directive work.
+		#
+		module SpecificationHelper
+			
+		# :stopdoc:
+			
+			attr_reader :directives
+			private     :directives
+			
+			def known_directives
+				directives.dup
+			end
+			
+		# :startdoc:
+			
+			# Returns the Directive with the given _name_ or +nil+ if it isn't defined.
+			def directive_defined? name
+				name = Directive.validate_name name
+				directives[name]
+			end
+			
+			#
+			# Returns the Directive with the given _name_ or raises an exception if it isn't defined.
+			# You can now use class methods of Directive to modify its features.
+			#
+			def directive name
+				directive_defined?(name) or
+					raise Error, "Undefined directive `#{name}'"
+			end
+			
+			#
+			# :call-seq:
+			#   define_directive(name){ || action }   -> directive
+			#   define_directive(name){ |dir_class| setup }   -> directive
+			#   define_directive(name,directive)   -> directive
+			#   
+			# Defines a directive class (subclass of Directive) with the given _name_.
+			# 
+			# In the first form the block (that takes no argument) will be sent to ::define,
+			# thus it directly becomes the action of the directive.
+			# In the second form the block is yielded the directive class itself, allowing
+			# other methods to be called on it (the user must explicitly call +define+).
+			# In the last form associates _name_ to _directive_.
+			# 
+			# In all cases the directive class is returned.
+			# 
+			# If the defined directive name ends with "<tt>!</tt>", and if the corresponding
+			# directive without the trailing bang is already defined these two classes will
+			# share the same #metadata. This strategy is used when the actions they perform
+			# are the same, differing only in the targets on which they operate.
+			#
+			def define_directive name, dir=nil, &definition
+				defined = directive_defined?(name) and
+					raise "Directive `#{defined.name}' already defined!"
+				if definition.nil?
+					raise "Invalid directive: #{dir.inspect}" unless dir.is_a?(Class) && dir < Directive
+				else
+					if name.end_with?('!') && simil_dir=directive_defined?(name.chomp '!')
+						metadata = simil_dir.metadata
+					else
+						metadata = {}
+					end
+					dir = Class.new(Directive) do
+						@name = name.freeze
+						@metadata = metadata # Of the class itself
+						clear_implicit_patterns
+						if definition.arity == 0
+							define &definition
+						else
+							definition.call(self)
+						end
+						verify_status
+					end
+				end
+				return directives[name] = dir
+			end
+			
+			# Creates an alias _new_name_ for the directive named _old_name_.
+			def alias_directive new_name, old_name
+				define_directive new_name, directive(old_name)
+			end
+			
+			# Removes the given _name_ from the list of known directives.
+			def undefine_directive name
+				name = Directive.validate_name name
+				!!directives.delete(name)
+			end
+			
+			# Removes the directive _dir_ (or the one associated to that name) from the list of directives.
+			def remove_directive dir
+				dir = directive(dir) unless dir.is_a?(Class) && dir < Directive
+				!!directives.delete_if{ |_,d| d == dir }
+			end
+			
+		end
+		
+		@directives = {}
+		extend SpecificationHelper
+		class << self # :nodoc:
+			alias known known_directives
+			alias get   directive
+			alias []    directive
+		end
+		
+		def initialize comment, text='', relative_line_no=1 # :nodoc:
+			@comment = comment
+			super(text,relative_line_no) # initializes metadata
+			@metadata.update self.class.metadata
+		end
+		
+		# The +name+ of the class.
+		def name
+			self.class.name
+		end
+		
+		# The SourceFile this directive is into.
+		def source_file
+			comment.source_file
+		end
+		
+		# The Comment this directive is into.
+		attr_reader :comment
+		alias parent comment
+		
+		# Returns +self+
+		def directive
+			self
+		end
+		
+		# Returns +nil+ if it wasn't given, the +String+ otherwise.
+		def parameter
+			text.empty? ? nil : text
+		end
+		alias param parameter
+		
+		#
+		# Split #parameter on spaces, returning an +Array+ of them.
+		# If _remove_commas_ is true, from each parameter is removed the trailing comma
+		# (so that this resembles a list of parameters in a method call).
+		#
+		def parameters remove_commas=true
+			return [] unless parameter
+			result = parameter.split(/\s+/)
+			result.map!{ |param| param.chomp(',') } if remove_commas
+			result
+		end
+		alias params parameters
+		
+		#
+		# Has this directive been detected implicitly?
+		# If _in_sections_ is given, it specifies the sections in which the search takes place.
+		#
+		def implicit?(*in_sections)
+			in_sections = comment.sections if in_sections.empty?
+			# An implicit directive is "over" some other section
+			in_sections.find{ |sec| sec.line_range.cover?(self.line_no) }
+		end
+		
+	#
+	# :section: API
+	#
+		
+		# Uses +:directive+ as the default type of warning.
+		def warn msg=nil, type=:directive, frame=nil
+			super
+		end
+		
+		# Meaningful default values are provided.
+		def eval code, binding=Binding.pseudo_toplevel, filename=file_name, lineno=line_no # :doc:
+			pwd = Dir.pwd
+			Kernel.eval(code,binding,filename,lineno)
+		ensure
+			Dir.chdir(pwd) unless Dir.pwd==pwd
+		end
+		private :eval
+		
+		# Deactivate this directive so that it won't have any effect.
+		def deactivate!
+			define_singleton_method(:execute){}
+		end
+		alias deactivate deactivate!
+		
+	#
+	# :section: Accessing related sections
+	#
+		
+		def section_index # :nodoc:
+			@section_index ||= comment.sections.find_index{ |sec| sec.line_no >= self.line_no } ||
+				comment.sections.size-1
+		end
+		private :section_index
+		
+		# Returns the Comment#enclosed_comments for the #comment.
+		# If a block is given, it's yielded each of them in turn.
+		def all_enclosed_comments(&blk)
+			ary = comment.enclosed_comments
+			ary.each(&blk) if blk
+			ary
+		end
+		
+		# Returns the Comment#sections of the #comment.
+		# If a block is given, it's yielded each of them in turn.
+		def all_sections(&blk)
+			ary = comment.sections
+			if blk
+				warn 'This directive affects also sections before' unless prev_sections.empty?
+				ary.each(&blk)
+			end
+			ary
+		end
+		
+		# Returns the Comment#examples of the #comment.
+		# If a block is given, it's yielded each of them in turn.
+		def all_examples &blk
+			ary = all_sections.select(&:example?)
+			if blk
+				warn 'This directive affects also examples before' unless prev_examples.empty?
+				ary.each(&blk)
+			end
+			ary
+		end
+		
+		# Returns the Comment#plain_texts of the #comment.
+		# If a block is given, it's yielded each of them in turn.
+		def all_texts &blk
+			ary = all_sections.select(&:text?)
+			if blk
+				warn 'This directive affects also texts before' unless prev_texts.empty?
+				ary.each(&blk)
+			end
+			ary
+		end
+		
+		# Returns the +sections+ of the #comment that are before this directive.
+		# If a block is given, it's yielded each of them in turn.
+		def prev_sections(&blk)
+			ary = all_sections.take(section_index)
+			if blk
+				warn 'No sections before this directive' if ary.empty?
+				ary.each(&blk)
+			end
+			ary
+		end
+		
+		# Returns the +examples+ of the #comment that are before this directive.
+		# If a block is given, it's yielded each of them in turn.
+		def prev_examples &blk
+			ary = prev_sections.select(&:example?)
+			if blk
+				warn 'No examples before this directive' if ary.empty?
+				ary.each(&blk)
+			end
+			ary
+		end
+		
+		# Returns the +plain_texts+ of the #comment that are before this directive.
+		# If a block is given, it's yielded each of them in turn.
+		def prev_texts &blk
+			ary = prev_sections.select(&:text?)
+			if blk
+				warn 'No texts before this directive' if ary.empty?
+				ary.each(&blk)
+			end
+			ary
+		end
+		
+		# Returns the +sections+ of the #comment that are after this directive.
+		# If a block is given, it's yielded each of them in turn.
+		def next_sections(&blk)
+			ary = all_sections.drop(section_index)
+			if blk
+				warn 'No sections after this directive' if ary.empty?
+				ary.each(&blk)
+			end
+			return ary
+		end
+		
+		# Returns the +examples+ of the #comment that are after this directive.
+		# If a block is given, it's yielded each of them in turn.
+		def next_examples &blk
+			ary = next_sections.select(&:example?)
+			if blk
+				warn 'No examples after this directive' if ary.empty?
+				ary.each(&blk)
+			end
+			ary
+		end
+		
+		# Returns the +plain_texts+ of the #comment that are after this directive.
+		# If a block is given, it's yielded each of them in turn.
+		def next_texts &blk
+			ary = next_sections.select(&:text?)
+			if blk
+				warn 'No texts after this directive' if ary.empty?
+				ary.each(&blk)
+			end
+			ary
+		end
+		
+		# Returns the +section+ of the #comment just after this directive.
+		def next_section
+			next_sections.first
+		end
+		
+		# Returns the +example+ of the #comment just after this directive.
+		def next_example
+			next_examples.first or
+				raise "Couldn't apply directive, missing example after"
+		end
+		
+		# Returns the +plain_text+ of the #comment just after this directive.
+		def next_text
+			next_texts.first or
+				raise "Couldn't apply directive, missing text after"
+		end
+		
+		# Returns the +section+ of the #comment just before this directive.
+		def prev_section
+			prev_sections.last
+		end
+		
+		# Returns the +example+ of the #comment just before this directive.
+		def prev_example
+			prev_examples.last or
+				raise "Couldn't apply directive, missing example before"
+		end
+		
+		# Returns the +plain_text+ of the #comment just after this directive.
+		def prev_text
+			prev_texts.last or
+				raise "Couldn't apply directive, missing text before"
+		end
+		
+	#
+	# :section: Directives: Activation/Deactivation
+	#
+		
+		##
+		# :singleton-method:
+		# :call-seq:
+		#   on
+		#   "" (empty string)
+		#   
+		# Turns on execution of examples. Often used after an ::off directive.
+		# 
+		# An example (from <tt>array.c</tt>):
+		# :rdx: off
+		#   /*
+		#    *  [...]
+		#    *     a = ["a", "b", "c"]
+		#    *  :rdx: off
+		#    *     a.cycle    { |x| print x }   # prints abcabcabc... forever
+		#    *  :rdx:
+		#    *     a.cycle(2) { |x| print x }   # prints abcabc
+		#    *  [...]
+		#    */
+		#   static VALUE
+		#   rb_ary_cycle(int argc, VALUE *argv, VALUE ary)
+		#   
+		# Note::
+		#   This may also be used in a non-documenting comment (see Comment#documenting),
+		#   with the purpouse of executing additional examples other than the ones in the documentation output.
+		#
+		define_directive 'on' do
+			next_examples{ |ex| ex.activate true }
+		end
+		alias_directive '', 'on'
+		
+		##
+		# :singleton-method:
+		# :call-seq:
+		#   off [-]
+		#   
+		# Turns off execution of examples (see the ::on directive for an example).
+		# 
+		# Note::
+		#   If the parameter is (or starts with) a hypen, only the immediately following
+		#   example is deactivated; the execution will continue regularly,
+		#   according to the effect of other directives after it.
+		#
+		define_directive 'off' do
+			if param && param[0] == '-'
+				next_example.deactivate true
+			else
+				next_examples{ |ex| ex.deactivate true }
+			end
+		end
+		
+		##
+		# :singleton-method:
+		# :call-seq:
+		#   skip [motivation]
+		#   
+		# Skips the execution of the immediately following example (through Example#whole_skip)
+		# reporting the optional _motivation_.
+		# 
+		# The cause (and type) of this skip is a simple +TODO+ in RDX,
+		# in a lighter way than an explicit failure.
+		# 
+		# An example:
+		#   # Sorts a collection in descending order.
+		#   # :rdx: skip write an example
+		#   def reverse_sort enum
+		#     enum.sort.reverse
+		#   end
+		#   
+		# Note::
+		#   This directive may even be used before a text section: in this case nothing is
+		#   really skipped, but it will anyhow be showed in the report.
+		#
+		define_directive 'skip' do
+			sect = next_section
+			msg,type = param,:TODO
+			if sect && sect.example?
+				next_example.whole_skip(msg, type, relative_line_no)
+			else
+				skip msg, type
+			end
+		end
+		
+		##
+		# :singleton-method:
+		# :call-seq:
+		#   bug [details]
+		#   buggy [details]
+		#   is_buggy [details]
+		#   
+		# Signals a bug in the library reporting _details_: use this directive above an example
+		# that _should_ work as declared.
+		# Use this only if you can't fix it, otherwise the explicit failure is better.
+		# 
+		# An example (from <tt>encoding.c</tt>):
+		# :rdx: off
+		#   /*
+		#    * Search the encoding with specified <i>name</i>.
+		#    * <i>name</i> should be a string or symbol.
+		#    *   Encoding.find("US-ASCII")  #=> Encoding::US_ASCII
+		#    * :rdx: bug symbols aren't accepted
+		#    *   Encoding.find(:Shift_JIS)  #=> Encoding::Shift_JIS
+		#    * [...]
+		#    */
+		#   static VALUE
+		#   enc_find(VALUE klass, VALUE enc)
+		# 
+		# Note::
+		#   This works in a way similar to ::skip, but used +BUG+ as the skip type.
+		#
+		define_directive 'bug' do
+			next_example.whole_skip param, :BUG, relative_line_no
+		end
+		alias_directive 'buggy', 'bug'
+		alias_directive 'is_buggy', 'buggy'
+		
+		##
+		# :singleton-method:
+		# :call-seq:
+		#   if condition
+		# 
+		# If _condition_ evals to a true value the next example is executed regularly,
+		# otherwise it's skipped.
+		# 
+		# An example:
+		#   # The code will show a demonstration of +fork+:
+		#   # :rdx: if Process.respond_to? :fork
+		#   #   puts 'In parent'
+		#   #   fork do
+		#   #     puts 'In child'
+		#   #   end
+		#   #   puts 'Back in parent'
+		#   module Kernel; end
+		#     
+		# Note::
+		#   The condition is often platform-dependent,
+		#   in order to make tests portable between different operating systems
+		#   (hence the type of this skip is +LACKING+).
+		#     
+		define_directive 'if' do
+			if eval(param)
+				next_example.activate
+			else
+				next_example.whole_skip param, :LACKING, relative_line_no
+			end
+		end
+		
+		##
+		# :singleton-method:
+		# :call-seq:
+		#   lazy
+		#   is_slow
+		# 
+		# Run the next example only when necessary (see Example#lazy).
+		# This directive is often used when the example shows performance penalities.
+		# 
+		# An example (from <tt>re.rdoc</tt>):
+		# :rdx: off
+		#   == Performance
+		#   Certain pathological combinations of constructs can lead to abysmally bad
+		#   performance.
+		#   [...]
+		#       s = 'a' * 25 + 'd' + 'a' * 4 + 'c'
+		#       #=> "aaaaaaaaaaaaaaaaaaaaaaaaadaaaac"
+		#   [...]
+		#   However, the following pattern takes appreciably longer:
+		#   \:rdx: is_slow
+		#       /(b|a+)*c/ =~ s #=> 26
+		#
+		define_directive 'lazy' do
+			next_example.lazy relative_line_no
+		end
+		alias_directive 'is_slow', 'lazy'
+		
+	#
+	# :section: Directives: Input/Output/Error
+	#
+		
+		##
+		# :singleton-method:
+		# :call-seq:
+		#   stdout
+		#   output
+		# 
+		# Interprets the next example as the expected output of the previuos one
+		# (see Example#produces_on_stdout).
+		# 
+		# Implicit detection::
+		#   Recognized in a text section containing only <tt>produces:</tt>
+		#   (html emphasized tags are allowed).
+		#   
+		#   An example:
+		#     # Kernel#puts writes to <tt>$stdout</tt> its arguments.
+		#     #   puts 'one', 'two', 'three...'
+		#     # produces:
+		#     #   one
+		#     #   two
+		#     #   three...
+		#     module Kernel; end
+		# 
+		# Note::
+		#   If the output is only one line it can be passed as a parameter to this directive
+		#   (and it's probably described in a text section)
+		#
+		define_directive 'stdout' do |dir|
+			dir.define do
+				output = param || next_example
+				prev_example.produces_on_stdout output, relative_line_no
+			end
+			dir.configure_implicit do |base=/[Pp]roduces:?/, allow_emphatized=true|
+				pat = Regexp.union(base)
+				pat = Text.add_html_tags pat, nil, 'em', 'i' if allow_emphatized
+				dir.find_in_text /\A\s*#{pat}\s*\z/
+			end
+		end
+		alias_directive 'output', 'stdout'
+		
+		##
+		# :singleton-method:
+		# :call-seq:
+		#   indicative_output
+		#   
+		# Ignores the next example and the output produced by the previuos one.
+		# 
+		# An example:
+		#   #
+		#   # The following code will output the first 1000 prime numbers.
+		#   #   require 'Prime'
+		#   #   Prime.first(1000).each{ |prime| puts prime }
+		#   # The result:
+		#   # :rdx: indicative_output
+		#   #   2
+		#   #   3
+		#   #   5
+		#   #   7
+		#   #   ... other 994 prime numbers ...
+		#   #   7907
+		#   #   7919
+		#   module Prime; end
+		#
+		define_directive 'indicative_output' do
+			next_example.deactivate!
+			prev_example.outputs //
+		end
+		
+		##
+		# :singleton-method:
+		# :call-seq:
+		#   stderr
+		#   
+		# Interprets the next example as the expected output of the previuos one
+		# (see Example#produces_on_stderr).
+		# 
+		# An example (from <tt>enumerator.c</tt>):
+		# :rdx: off
+		#   /*
+		#    * [...]
+		#    * Use of this form is discouraged.  Use Kernel#enum_for or Kernel#to_enum
+		#    * instead.
+		#    *   e = Enumerator.new(ObjectSpace, :each_object)
+		#    *   #-> ObjectSpace.enum_for(:each_object)
+		#    * produces on stderr:
+		#    * :rdx: stderr
+		#    *   warning: Enumerator.new without a block is deprecated; use Object#to_enum
+		#    * [...]
+		#    */
+		#   static VALUE
+		#   enumerator_initialize(int argc, VALUE *argv, VALUE obj)
+		#
+		define_directive 'stderr' do
+			output = param || next_example
+			prev_example.produces_on_stderr output, relative_line_no
+		end
+		
+		##
+		# :singleton-method:
+		# :call-seq:
+		#   stdin
+		#   input
+		#   
+		# Interprets the previous example as the input for the next one.
+		# 
+		# An example (from <tt>vm_eval.c</tt>):
+		# :rdx: off
+		#   /*
+		#    *  [...]
+		#    *  When the following input
+		#    *     First line given
+		#    *     Second line given
+		#    *     Last line given
+		#    *     Quit!
+		#    *  is given into this program
+		#    *  :rdx: stdin
+		#    *     loop do
+		#    *       line = gets
+		#    *       break if !line or line =~ /^[qQ]/
+		#    *       puts "Got: #{line}"
+		#    *     end
+		#    *  produces:
+		#    *     Got: First line given
+		#    *     Got: Second line given
+		#    *     Got: Last line given
+		#    *  [...]
+		#    */
+		#   static VALUE
+		#   rb_f_loop(VALUE self)
+		#
+		define_directive 'stdin' do
+			input = param || prev_example
+			next_example.take_input_from input
+		end
+		alias_directive 'input', 'stdin'
+		
+		##
+		# :singleton-method:
+		# :call-seq:
+		#   exception
+		#   error
+		#   
+		# :rdx: no_warnings conventions
+		# Interprets the next example as the description of the exception
+		# raised by previous one (see Example#raises).
+		# 
+		# Implicit detection::
+		#   Recognized in a text section containing only <tt>raises the exception:</tt>
+		#   (or simply <tt>raises:</tt>).
+		#   
+		#   An example:
+		#     # Kernel#raise will raise a RuntimeError with the given message:
+		#     #   raise 'Boom!'
+		#     # raises the exception:
+		#     #   Boom! (RuntimeError)
+		#     module Kernel; end
+		#     
+		# Note::
+		#   If the parameter is given it's treated as the exception's class name.
+		#   This can be useful if the message is negligible, but we don't want to
+		#   rely on an error convention.
+		#
+		define_directive 'exception' do |dir|
+			dir.define do
+				error = param || next_example
+				prev_example.raises error, relative_line_no
+			end
+			dir.configure_implicit do |base=/[Rr]aises?(?: the exception)?:?/, allow_emphatized=true|
+				pat = Regexp.union base
+				pat = Text.add_html_tags pat, nil, 'em', 'i' if allow_emphatized
+				dir.find_in_text /\A\s*#{pat}\s*\z/
+			end
+		end
+		alias_directive 'error', 'exception'
+		
+		##
+		# :singleton-method:
+		# :call-seq:
+		#   write_file relative_name
+		# 
+		# Writes the content of the next example to the specified file _relative_name_
+		# (see Example#write_to_file).
+		# 
+		# Implicit detection::
+		#   Recognized in an example beginning with a comment <tt># File: </tt> _relative_name_.
+		# 
+		#   An example:
+		#     # IO.foreach iterates over the lines (according to <tt>$/</tt>) of the given file.
+		#     #   # File: lines.txt
+		#     #   This is line 1
+		#     #   this is line 2
+		#     #   and so on...
+		#     # From the application:
+		#     #   enum = IO.foreach 'lines.txt'
+		#     #   enum.next.chomp #=> "This is line 1"
+		#     #   enum.next.chomp #=> "This is line 2"
+		#     #   enum.next.chomp #=> "and so on..."
+		#     class IO; end
+		#
+		define_directive 'write_file' do |dir|
+			dir.define do
+				next_example.write_to_file param, relative_line_no do |content|
+					content.slice! /\A.*\n/ if implicit?
+					content
+				end
+			end
+			dir.configure_implicit do |base=/(?:[Ii]n +)?[Ff]ile[: ]/, fname=/\S+/|
+				dir.find_in_example /\A\s*#[ \t]*#{base}[ \t]*(#{fname})[ \t]*$/
+			end
+		end
+		
+		##
+		# :singleton-method:
+		# :call-seq:
+		#   check_file relative_name
+		# 
+		# Compares the next example against the content of the specified file _relative_name_
+		# (see Example#check_file_content).
+		# 
+		# An example:
+		#   # IO#puts writes the given argument to +ios+ along with a record separator.
+		#   #   f = File.new 'out', 'w'
+		#   #   f.puts 'line 1'
+		#   #   f.puts 'line 2'
+		#   #   f.puts 'line 1000' # 1,2,3 was boring...
+		#   # Now the file +out+ will contian:
+		#   # :rdx: check_file out
+		#   #   line 1
+		#   #   line 2
+		#   #   line 1000
+		#   class IO; end
+		#
+		define_directive 'check_file' do
+			next_example.check_file_content param, relative_line_no
+		end
+		
+	#
+	# :section: Directives: Context change
+	#
+		
+		##
+		# :singleton-method:
+		# :call-seq:
+		#   new_binding
+		# 
+		# Changes the binding of the following examples to a new empty one
+		# (specifically to Binding.pseudo_toplevel).
+		# 
+		# An example (from <tt>re.c</tt>):
+		# :rdx: off
+		#   /*
+		#    *  [...]
+		#    *  If <code>=~</code> is used with a regexp literal with named captures,
+		#    *  captured strings (or nil) is assigned to local variables named by
+		#    *  the capture names.
+		#    *     /(?<lhs>\w+)\s*=\s*(?<rhs>\w+)/ =~ "  x = y  "
+		#    *     lhs    #=> "x"
+		#    *     rhs    #=> "y"
+		#    *  [...]
+		#    *  :rdx: new_binding
+		#    *  :rdx: # Without this directive those local variables are already defined
+		#    *  The assignment does not occur if the regexp is not a literal.
+		#    *     re = /(?<lhs>\w+)\s*=\s*(?<rhs>\w+)/
+		#    *     re =~ "  x = y  "
+		#    *     lhs    # error: undefined local variable
+		#    *     rhs    # error: undefined local variable
+		#    *  [...]
+		#    */
+		#   VALUE
+		#   rb_reg_match(VALUE re, VALUE str)
+		#
+		define_directive 'new_binding' do
+			new_binding = Binding.pseudo_toplevel
+			next_examples{ |ex| ex.set_binding new_binding }
+		end
+		
+		##
+		# :singleton-method:
+		# :call-seq:
+		#   toplevel
+		# 
+		# The default binding for the execution isn't the true toplevel one
+		# (see CodeObject::Runnable::Startable#prepare_binding),
+		# however some examples don't have sense under this condition.
+		# This directive changes the binding of the following examples to a copy
+		# of the toplevel one (specifically to Binding.toplevel).
+		# 
+		# An example (from <tt>struct.c</tt>):
+		# :rdx: off
+		#   /*	
+		#    *  [...]
+		#    *  <code>Struct::new</code> returns a new <code>Class</code> object,
+		#    *  which can then be used to create specific instances of the new
+		#    *  structure.
+		#    *  [...]
+		#    *  :rdx: toplevel
+		#    *     # Create a structure named by its constant
+		#    *     Customer = Struct.new(:name, :address)     #=> Customer
+		#    *     Customer.new("Dave", "123 Main")           # > #<struct Customer name="Dave", address="123 Main">
+		#    *-- rdx
+		#    *  Without this directive we should write <tt>::Customer</tt> instead of <tt>Customer</tt>;
+		#    *  this can confuse the reader, bacause normally it's not necessary.
+		#    *  Now clean-up step:
+		#    *     Object.send :remove_const, :Customer
+		#    *++
+		#    */
+		#   static VALUE
+		#   rb_struct_s_def(int argc, VALUE *argv, VALUE klass)
+		#   
+		# Note::
+		#   It's user's responsibilty to clean up all the necessary
+		#   (usually using private rdx sections).
+		#
+		define_directive 'toplevel' do
+			toplevel_binding = Binding.toplevel
+			next_examples{ |ex| ex.set_binding toplevel_binding }
+		end
+		
+		##
+		# :singleton-method:
+		# :call-seq:
+		#   before_require
+		# 
+		# Runs the next example before requiring the full set of libraries.
+		# This turns handy if you are modifying the core and you want
+		# to show the differences provided by your patch.
+		# 
+		# An example (from <tt>mathn.rb</tt>):
+		#   # [...]
+		#   # mathn features late rounding and lacks truncation of intermediate results:
+		#   # Without mathn:
+		#   # :rdx: before_require
+		#   #   20 / 9 * 3 * 14 / 7 * 3 / 2 # => 18
+		#   # With mathn:
+		#   #   20 / 9 * 3 * 14 / 7 * 3 / 2 # => 20
+		#   # [...]
+		#   class Numeric; end
+		#
+		define_directive 'before_require' do
+			next_example.run_before_require
+		end
+		
+		##
+		# :singleton-method:
+		# :call-seq:
+		#   setup
+		# 
+		# Uses the next example as a setup for the comment, that will run
+		# before every Comment#enclosed_comments.
+		# 
+		# An example (from <tt>cmath.rb</tt>):
+		#   # [...]
+		#   # In the following examples we assume that CMath is included at toplevel for the sake of clarity:
+		#   # :rdx: setup
+		#   #   include CMath
+		#   # Square root of a negative number is a complex number.
+		#   #   sqrt(-9)  #=> 0+3.0i
+		#   # [...]
+		#   module CMath
+		#     ##
+		#     # Returns the natural logarithm of Complex.  If a second argument is given,
+		#     # it will be the base of logarithm.
+		#     #   log(Complex(0,0)) # > (-Infinity+0.0i)
+		#     #--
+		#     # This works thanks to the above setup
+		#     def log(*args)
+		#       #[...]
+		#     end
+		#   end
+		#
+		define_directive 'setup' do
+			next_example.use_as_setup
+		end
+
+		##
+		# :singleton-method:
+		# :call-seq:
+		#   teardown
+		# 
+		# Uses the next example as a teardown for the comment, that will run
+		# after every Comment#enclosed_comments.
+		# 
+		# See +setup+ for an example.
+		# 
+		define_directive 'teardown' do
+			next_example.use_as_teardown
+		end
+		
+		##
+		# :singleton-method:
+		# :call-seq:
+		#   in_tmpdir
+		# 
+		# Runs the next example in a temporary directory (see Example#run_in_tmpdir).
+		# 
+		# An example (from <tt>encoding.c</tt>):
+		# :rdx: off
+		#   /*
+		#    * [...]
+		#    * While writing the file, the internal encoding is not specified as it is
+		#    * only necessary for reading.  While reading the file both the internal and
+		#    * external encoding must be specified to obtain the correct result:
+		#    * :rdx: in_tmpdir
+		#    *   string = "R\u00E9sum\u00E9"
+		#    *   open("transcoded.txt", "w:ISO-8859-1") do |io|
+		#    *     io.write(string)
+		#    *   end
+		#    *   puts File.binread("transcoded.txt").dump
+		#    * [...]
+		#    * produces:
+		#    *   "R\xE9sum\xE9"
+		#    * [...]
+		#    */
+		#   void
+		#   Init_Encoding(void)
+		# 
+		define_directive 'in_tmpdir' do
+			next_example.run_in_tmpdir
+		end
+		
+		##
+		# :singleton-method:
+		# :call-seq:
+		#   in_tmpdir!
+		# 
+		# Same as ::in_tmpdir, but applies to the whole comment.
+		#
+		define_directive 'in_tmpdir!' do
+			comment.run_in_tmpdir
+		end
+		
+		##
+		# :singleton-method:
+		# :call-seq:
+		#   in_tmpdir!!
+		# 
+		# Same as ::in_tmpdir, but applies to #all_enclosed_comments
+		# (on which operate +setup+ and +teardown+).
+		#
+		define_directive 'in_tmpdir!!' do
+			all_enclosed_comments(&:run_in_tmpdir)
+		end
+		
+		##
+		# :singleton-method:
+		# :call-seq:
+		#   bash default_prompt=/\$\s/, continuation_prompt=/>\s/
+		#   
+		# Interprets the next example as a bash command-line session
+		# (see Example#on_bash_mode).
+		# 
+		# Implicit detection::
+		#   Recognized in an example that begins with the default prompt (the predefined
+		#   isn't syntattically correct in Ruby, so we can safely avoid ambiguous situations).
+		# 
+		#   An example (from <tt>optparse.rb</tt>):
+		#     # [...]
+		#     # We give options from the command line:
+		#     #   $ ruby example.rb -h
+		#     #   Usage: example.rb [options] [arguments...]
+		#     #       -v, --[no-]verbose               Run verbosely
+		#     #   $ ruby example.rb -v
+		#     #   options = {:verbose=>true}
+		#     #   ARGV    = []
+		#     # [...]
+		#     class OptionParser; end
+		#   
+		# Note::
+		#   If the output includes the default or continuation prompt you should change
+		#   them (or supply +nil+ if you don't want) with the explicit directive:
+		#   :rdx: off
+		#     # This is the result in the command line (<tt>" </tt> is the continuation prompt):
+		#     # :rdx: bash nil, '" '
+		#     #   $ ruby <<EOS
+		#     #   " puts "> Hello world!"
+		#     #   " EOS
+		#     #   > Hello world!
+		#     class Shell; end
+		#
+		define_directive 'bash' do |dir|
+			dir.metadata[:default_prompt]      = /\$\s/
+			dir.metadata[:continuation_prompt] = />\s/
+			dir.define do
+				default_prompt,continuation_prompt = param && eval("[#{param}]")
+				default_prompt      ||= metadata[:default_prompt]
+				continuation_prompt ||= metadata[:continuation_prompt]
+				next_example.on_bash_mode default_prompt, continuation_prompt
+			end
+			dir.configure_implicit do |prompt=dir.metadata[:default_prompt]|
+				prompt = prompt.is_a?(Regexp) ? prompt.to_s : Regexp.escape(prompt.to_str)
+				dir.find_in_example /\A\s*^#{prompt}/
+			end
+		end
+		
+	#
+	# :section: Directives: Assertions customization
+	#
+		
+		##
+		# :singleton-method:
+		# :call-seq:
+		#   float digits=3
+		# 
+		# Sets the next example on floating-point mode (see Example#on_float_mode)
+		# passing _digits_ (default to 3, value stored in the #metadata as +:digits+).
+		# 
+		# An example (from <tt>math.c</tt>):
+		# :rdx: off
+		#   /*	
+		#    *  [...]
+		#    *  If +x+ isn't too large we have that:
+		#    *  :rdx: float
+		#    *    log_gamma,sgn_gamma = Math.lgamma(x)
+		#    *    log_gamma #=> Math.log(Math.gamma(x).abs)
+		#    *    sgn_gamma #=> Math.gamma(x) < 0 ? -1 : 1
+		#    *  otherwise Math.gamma(x) will overflow (yielding Infinity),
+		#    *  while Math.lgamma(x) does not
+		#    */
+		#   static VALUE
+		#   math_lgamma(VALUE obj, VALUE x)
+		#   
+		# Note::
+		#   This directive covers the holes leaved by Convention::result_numeric.
+		#
+		define_directive 'float' do |dir_class|
+			dir_class.metadata[:digits] = 3
+			dir_class.define do
+				digits = param ? Integer(param) : metadata[:digits]
+				next_example.on_float_mode(digits)
+			end
+		end
+		
+		##
+		# :singleton-method:
+		# :call-seq:
+		#   float! digits=3
+		#   
+		# Same as ::float but applies to the whole comment.
+		# 
+		define_directive 'float!' do
+			digits = param ? Integer(param) : metadata[:digits]
+			all_examples{ |ex| ex.on_float_mode(digits) }
+		end
+		
+		##
+		# :singleton-method:
+		# :call-seq:
+		#   indicative_numbers
+		# 
+		# Sets the next example on indicative numbers mode
+		# (see Example#on_indicative_numbers_mode).
+		# 
+		# An example (from <tt>benchmark.rb</tt>):
+		# :rdx: off
+		#   # :rdx: indicative_numbers
+		#   #     n = 50000
+		#   #     Benchmark.bm(7) do |x|
+		#   #       x.report("for:")   { for i in 1..n; a = "1"; end }
+		#   #       x.report("times:") { n.times do   ; a = "1"; end }
+		#   #       x.report("upto:")  { 1.upto(n) do ; a = "1"; end }
+		#   #     end
+		#   # Produces:
+		#   #                     user     system      total        real
+		#   #        for:     1.050000   0.000000   1.050000 (  0.503462)
+		#   #        times:   1.533333   0.016667   1.550000 (  0.735473)
+		#   #        upto:    1.500000   0.016667   1.516667 (  0.711239)
+		#   module Benchmark; end
+		#
+		define_directive 'indicative_numbers' do
+			next_example.on_indicative_numbers_mode
+		end
+		
+		##
+		# :singleton-method:
+		# :call-seq:
+		#   indicative_numbers!
+		# 
+		# Same as ::indicative_numbers, but applies to the whole comment.
+		#
+		define_directive 'indicative_numbers!' do
+			all_examples(&:on_indicative_numbers_mode)
+		end
+		
+	#
+	# :section: Directives: Miscellaneous
+	#
+		
+		##
+		# :singleton-method:
+		# :call-seq:
+		#   # comment
+		# 
+		# Insert a comment (probably about some RDX detail).
+		# 
+		# Note::
+		#   For the directive syntax at least one space is required after the hash,
+		#   which happens to be the directive name.
+		#
+		define_directive '#' do end
+		
+		##
+		# :singleton-method:
+		# :call-seq:
+		#   disable_warnings *types
+		#   no_warnings *types
+		# 
+		# Disables the given _types_ of warnings for the next section
+		# (see CodeObject#disable_warnings).
+		# 
+		# An example:
+		# :rdx: off
+		#   # :rdx: no_warnings convention
+		#   # The hash-rocket notation, <tt>#=></tt>, indicates the result of a statement:
+		#   #   1+1 #=> 2
+		#   class Convention; end
+		#
+		define_directive 'disable_warnings' do
+			next_section.disable_warnings *params
+		end
+		alias_directive 'no_warnings', 'disable_warnings'
+		
+		##
+		# :singleton-method:
+		# :call-seq:
+		#   disable_warnings! *types
+		#   no_warnings! *types
+		# 
+		# Same as ::disable_warnings, but applies to the whole comment.
+		#
+		define_directive 'disable_warnings!' do
+			comment.disable_warnings *params
+		end
+		alias_directive 'no_warnings!', 'disable_warnings!'
+		
+		##
+		# :singleton-method:
+		# :call-seq:
+		#   discard_output
+		# 
+		# Ignores the uncaptured output produced by the next example - otherwise a warning will be generated.
+		# 
+		# An example:
+		# :rdx: off
+		#   # The following code will output the first 1000 prime numbers:
+		#   # :rdx: discard_output
+		#   #   require 'Prime'
+		#   #   Prime.first(1000).each{ |prime| puts prime }
+		#   module Prime; end
+		#   
+		# Note::
+		#   This directive actually suppresses the +stdout+ type of warning.
+		# 
+		define_directive 'discard_output' do
+			next_example.disable_warnings 'stdout'
+		end
+		
+		##
+		# :singleton-method:
+		# :call-seq:
+		#   disable_implicit *names
+		# 
+		# Disables the given _names_ of implicit directives in the next section
+		# (see Comment#disable_implicit_directives_in).
+		#
+		define_directive 'disable_implicit' do
+			comment.disable_implicit_directives_in next_section, *params
+		end
+		
+	end
+
+end