rdx 0.9.0.pre

data/lib/rdx/comment.rb

@@ -0,0 +1,338 @@
+
+module RDX
+	
+	#
+	# Represents a comment in a source file.
+	#
+	class Comment < CodeObject::Runnable::Startable
+		
+		# The +String+ containing the text.
+		attr_writer :text
+		
+		# Absolute line number in the source file.
+		attr_writer :line_no
+		
+		# This is +true+ if the comment will appear on the documentation output, +false+ otherwise.
+		attr_accessor :documenting
+		
+		# The SourceFile this comment is into.
+		attr_reader :source_file
+		alias parent source_file
+		
+		# Returns +self+.
+		def comment
+			self
+		end
+		
+		# The +Array+ of CodeObject contained (may contain PlainText, Example and Directive objects).
+		attr_reader :contents
+		
+		# The +Array+ of Example objects contained.
+		def examples
+			contents.grep(Example)
+		end
+		
+		# The +Array+ of PlainText objects contained.
+		def plain_texts
+			contents.grep(PlainText)
+		end
+		
+		# The +Array+ of Directive objects contained.
+		def directives
+			contents.grep(Directive)
+		end
+		
+		# The +Array+ of Directive objects contained that are +implicit?+.
+		def implicit_directives
+			directives.select(&:implicit?)
+		end
+		
+		# Example and PlainText objects are collectively +sections+ in the comment.
+		def sections
+			@sections || contents.reject{ |c| c.is_a?(Directive) }
+		end
+		
+		# The comment for the documentation container.
+		#--
+		# TODO: not always clear...
+		attr_reader :enclosing_comment
+		
+		# The +Array+ of comments in this documentation container (contains +self+).
+		#--
+		# same limitations as above
+		attr_reader :enclosed_comments
+		
+		# The Example that are +active?+.
+		def children
+			examples.select(&:active?)
+		end
+		
+		#
+		# :category: API
+		# 
+		# Disables the directives of the given _names_ that are +implicit?+ in _section_.
+		# If no name is given, all of them are disabled.
+		#
+		def disable_implicit_directives_in section, *names
+			implicit_dirs = directives.select{ |dir| dir.implicit?(section) }
+			unless names.empty?
+				names.map!{ |dir_name| store.directive(dir_name) } # directive classes
+				implicit_dirs.select!{ |dir| names.find{ |type| dir.is_a?(type) } }
+			end
+			implicit_dirs.each(&:deactivate!)
+		end
+		
+		#
+		# :category: API
+		# 
+		# Disables the directives of the given _names_ that are +implicit?+ in this comment.
+		# If no name is given, all of them are disabled.
+		#
+		def disable_implicit_directives! *names
+			disable_implicit_directives_in self, *names
+		end
+		
+	# :stopdoc:
+		
+		def empty?
+			text.nil? || text.empty?
+		end
+		
+		def file_name= file_name
+			@source_file.remove_comment(self) if @source_file
+			@source_file = if file_name
+				store.find_source_file(file_name).add_comment(self) unless empty?
+			else
+				nil
+			end
+		end
+
+		def initialize text=nil, file_name=nil, line_no=nil
+			super(text,nil)
+			self.file_name = file_name
+			@line_no = line_no
+			@documenting = false
+			@normalized = false
+			@enclosing_comment = nil
+			@enclosed_comments = [self] # for convenience
+			@contents = []
+			clear_run_hooks
+		end
+		
+		def inspect
+			parent_info = enclosing_comment && enclosing_comment.location
+			parent_info &&= "(<#{parent_info})"
+			content = text
+			if content.size > 60
+				content = content[0..60] + '...'
+			end
+			"<%s:0x%x(%s)@%s%s;%p>" % [self.class, __id__, documenting, location, parent_info, content]
+		end
+		
+		def enclosing_comment= comment
+			return self if comment.nil?
+			raise unless comment.is_a?(Comment)
+			@enclosing_comment = comment
+			comment.enclosed_comments << self
+			self
+		end
+		
+		attr_accessor :setup
+		protected :setup, :setup=
+		
+		attr_accessor :teardown
+		protected :teardown, :teardown=
+		
+		def def_setup example
+			enclosed_comments.each{ |cmt| cmt.setup = example }
+		end
+
+		def def_teardown example
+			enclosed_comments.each{ |cmt| cmt.teardown = example }
+		end
+		
+		def clear_run_hooks
+			self.setup = self.teardown = nil
+			self
+		end
+			
+		def run_setup starter
+			return unless setup
+			setup.binding = starter.binding
+			setup.whole_run(starter)
+		end
+		
+		def run_teardown starter
+			return unless teardown
+			teardown.binding = starter.binding
+			teardown.whole_run(starter)
+		end
+		
+		attr_reader :normalized
+		
+		def normalize
+			return self if normalized
+			@text = Text.normalize_comment(text,true) # remove consecutive #
+			@normalized = true
+			self
+		end
+		
+		def build
+			super
+			store.add_test self
+		end
+		
+	private
+		
+		def build_self
+			normalize
+			determine_contents
+			execute_directives
+			check_missing_conventions
+		end
+		
+		def extract_directives
+			directives = []
+			text.gsub! generator.directive_rgxp do |matched|
+				md = Regexp.last_match
+				init_nl = matched[/\A\s*/].count("\n")
+				dir,param = md[1].downcase,md[2]
+				if dir == 'rdx'
+					l_no = 1 + md.pre_match.count("\n") + init_nl
+					directives << [param.strip, l_no]
+				end
+				Text.collect_newlines(matched) # remove it
+			end
+			text.replace Text.flush_left(text) # The directives haven't effect on indentation
+			directives.map{ |cnt| [:directive,*cnt] }
+		end
+		
+		def divide_examples_texts
+			examples = []
+			texts = []
+			lines = text.lines("\n")
+			generator.recognize_examples(text).each do |ex,line_no|
+				examples << [ex,line_no]
+				line_no_f = line_no + ex.count("\n") - 1
+				line_no.upto(line_no_f){ |i| lines[i-1] = nil }
+			end
+			chunks = lines.chunk(&:nil?).map(&:last)
+			chunks.reduce(1) do |line_no,lines|
+				unless lines.first.nil?
+					txt = lines.join ''
+					texts << [txt,line_no]
+				end
+				line_no + lines.size
+			end
+			examples.map!{ |cnt| [:example,*cnt] }
+			texts.map!{ |cnt| [:text,*cnt] }
+			[examples,texts]
+		end
+		
+		def determine_contents
+			directives = extract_directives
+			examples,texts = divide_examples_texts
+			pseudo_contents = (examples+texts).sort_by(&:last)
+			directives.each do |directive|
+				l_no = directive.last
+				index = (pseudo_contents.find_index{ |_,_,n| n > l_no } || 0) - 1
+				pseudo_content = pseudo_contents[index]
+				pseudo_contents[index,1] = split_content(pseudo_content,directive,true)
+			end
+			pseudo_contents = add_implicit_directives pseudo_contents
+			finalize_contents pseudo_contents
+		end
+		
+		def split_content content, directive_cnt, remove_line
+			type,text,l_no_before = content
+			lines = text.lines "\n"
+			l_no_after = directive_cnt[2]
+			l_no_after += 1 if remove_line # exclude the line with directive - not for implicit ones
+			cnt_before = lines.take(directive_cnt[2]-l_no_before).join ''
+			cnt_after  = lines.drop(l_no_after-l_no_before).join ''
+			result = []
+			result << [type,cnt_before,l_no_before] if cnt_before =~ /\S/
+			result << directive_cnt
+			result << [type,cnt_after,l_no_after] if cnt_after =~ /\S/
+			return result
+		end
+		
+		def add_implicit_directives pseudo_contents
+			result = []
+			pseudo_contents.each do |pseudo_content|
+				result << pseudo_content
+				type,text,line_no = pseudo_content
+				next if type == :directive
+				store.scan_for_implicit_directives(type,text).each do |directive|
+					directive[2] += line_no - 1
+					result.concat split_content(result.pop,directive,false)
+				end
+			end
+			return result
+		end
+		
+		def finalize_contents pseudo_contents
+			pseudo_contents.each do |type,txt,l_no|
+				case type
+				when :example
+					contents << Example.new(self,txt,l_no)
+				when :text
+					contents << PlainText.new(self,txt,l_no)
+				when :directive
+					contents << new_directive(txt,l_no)
+				end
+			end
+			@sections = self.sections
+		end
+		
+		def new_directive dir_string, l_no
+			# dir_string: rdx string directive, containing its own directive and param
+			dir,param = Directive.split(dir_string)
+			directive = nil
+			trace_execution location(l_no) do
+				directive = store.directive(dir)
+			end
+			directive.new(self,param,l_no)
+		end
+	
+	# :startdoc:
+		
+	#
+	# :section: Internal
+	#
+		
+		#
+		# Executes the directives.
+		# If the comment won't be part of the documentation output only explicit directives
+		# get executed: a warning will be generated for recognized implicit ones.
+		#
+		def execute_directives # :doc:
+			prepare_binding
+			if documenting
+				examples.each(&:activate)
+			else
+				implicit_directives.each do |dir|
+					dir.warn "Found pattern for implicit directive `#{dir.name}' in non-documenting comment"
+					dir.deactivate!
+				end
+			end
+			directives.each(&:execute)
+		end
+		
+		#
+		# Every commment seen by the parser is checked for the presence of conventions:
+		# if they are in places where they will not be executed a warning will be generated.
+		# This is done in text sections (see PlainText#check_missing_conventions) and in
+		# examples that won't be part of the documentation output (see Example#check_non_documenting).
+		#
+		def check_missing_conventions # :doc:
+			examples.each(&:check_non_documenting)
+			plain_texts.each do |text|
+				text.check_missing_conventions
+			end
+			return self
+		end
+		
+	end
+
+end

data/lib/rdx/convention.rb

@@ -0,0 +1,1174 @@
+
+module RDX
+
+	#
+	# == Introduction
+	# 
+	# Let's start taking an example:
+	# 
+	#   my_array = [1,2,3]
+	#   my_array.pop         # => 3
+	#   my_array             # => [1,2]
+	# 
+	# One of the main advantages of *examples* is that they <b>are written as ruby code ready to work:
+	# the effort made by the user to understand and reuse them is often minimum</b>.
+	# The key point here is that the significant data of a statement - such as result
+	# returned, produced output, raised exception - is pointed out with a comment at its end.
+	# In this way the example can keep its whole consistence: since expectations are commented out
+	# they don't interfere with the logical flux of statements.
+	# 
+	# The *conventions* really constitute the heart of RDX: they can <b>map specific patterns into
+	# those comments to a way of processing code</b>. In other words, they <b>are the bridge
+	# between documentation and testing</b>. Choosing intuitive and commonly accepted patterns
+	# will lead to examples very easy to write and understand, which are also consistent.
+	# 
+	# == A tour on the existing conventions
+	# 
+	# The most important *default* conventions (and some derivates for literals) currently are:
+	# * ::result_eval: checks the result
+	#     [1,2,3].pop(2)        # => [2,3]
+	# * ::output_literal: checks the output
+	#     puts "Hello world!"   # prints: Hello world!
+	# * ::error_literal: checks the raised exception
+	#     "a string" + 1        # raises TypeError: no implicit conversion of Fixnum into String
+	# These are the most common, so often they are more than enough for your needs.
+	# The list of default conventions is available in Specification#default_conventions.
+	# 
+	# RDX defines other *useful* conventions (but they are not used by default,
+	# since there isn't a common acceptance). Some of these are:
+	# * ::result_inspect:
+	#     /\d/.match "x = 3"    #  > #<MatchData "3">
+	# * ::result_indicative:
+	#     rand                  # -> 0.78215412345
+	# * ::output_eval:
+	#     puts "Hello world!"   # >> "Hello world!\n"
+	# * ::error_eval:
+	#     "a string" + 1        # ~> TypeError: "no implicit conversion of Fixnum into String"
+	# All the conventions already defined are documented as Convention'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 conventions
+	# in the Specification.
+	# 
+	# But before this you'll need to know how the conventions work:
+	# this is explained in the next section.
+	# 
+	# == How conventions work
+	# 
+	# Let's start from an Example:
+	# 
+	#   (1..10).all? do |i|
+	#     i > 0 and i < 15
+	#   end #=> true
+	# 
+	# Here is the background:
+	# :rdx: no_warnings conventions
+	# * First the example is *parsed* and subdivided into Statement objects
+	#   (in RubyLex#extract_statements). Here we have only one statement.
+	# * For each statement is *extracted* the comment at its end
+	#   (in RubyLex#extract_comments_from_statement).
+	#   In this case we have the +String+ <tt>"#=> true"</tt>.
+	# * This comment is then *normalized* (through Text#normalize_comment).
+	#   For this example we end up with <tt>"=> true"</tt>.
+	# 
+	# Then the *conventions* come into play. There are four +Proc+ objects that does the full work:
+	# * The first step is to *associate* a convention to that comment.
+	#   This is done in #process_comment, which is called for every convention in use until
+	#   the right one is found: now we have an Expectation.
+	#   In this case it's recognized (and removed) the prompt <tt>=></tt> of the
+	#   ::result_eval convention, leaving <tt>"true"</tt> in the +expected_data+.
+	# * Then the code of the *statement* is processed through #process_statement of the
+	#   determined convention (which often simply evaluates it). In this case the string
+	#   <tt>"(1..10).all? do |i|\n  i > 0 and i < 15\nend"</tt> is evalued, returning +true+.
+	#   This is the +actual_value+.
+	# * Next the useful data of the *expectation* extracted previously is send to
+	#   #process_expectation: the result is the +expected_value+.
+	#   In this case we obtain +true+ (because +result_eval+ _evaluates_ the expected data).
+	# * Finally we can do the *assertion*: the actual and expected values (in this order)
+	#   are sent to #process_assertion, which provides full access to Minitest's assertions.
+	#   Since +result_eval+ does an +assert_equal+ we see that this assertion passes.
+	#   
+	# To sum up, the ::result_eval convention maps the <tt>=></tt>
+	# prompt in documentation examples to an +assert_equal+ of the +Minitest+ framework.
+	# 
+	# According to the defined conventions RDX builds the tests for the user,
+	# which only has to check the report.
+	#
+	class Convention
+		
+		include Text
+		extend Text
+
+		def self.define_processor name # :nodoc:
+			ivar = "@#{name}".freeze
+			define_method name do |&definition|
+				return instance_variable_get(ivar) unless definition
+				instance_variable_set(ivar,definition)
+			end
+			define_method "dont_#{name}" do
+				instance_variable_set(ivar,false)
+			end
+			define_method "call_#{name}" do |context,*args|
+				processor = instance_variable_get(ivar)
+				if processor
+					if context
+						context.instance_exec(*args,&processor)
+					else
+						processor.call(*args)
+					end
+				else
+					args.size==1 ? args.first : args
+				end
+			end
+		end
+		private_class_method :define_processor
+		
+		##
+		# :call-seq:
+		#   process_comment{ |normalized_comment| ... }
+		#   process_comment -> proc or nil
+		#
+		# If a block is given, it's registered as the processor.
+		# Otherwise returns the registered +Proc+ (or +nil+ if it hasn't been registered yet).
+		# 
+		# The +Proc+ will receive the normalized comment at the end of a statement as a parameter
+		# and processes it. What happens next depends on the result of the block:
+		# * If it returns +false+ or +nil+ this convention isn't associated with the statement
+		#   (and other conventions are tried in turn);
+		# * otherwise this convention is associated with the statement and we have an _expectation_.
+		#   The result (often the string containing the useful portion of that comment)
+		#   will be successively sent to #process_expectation.
+		#   
+		# Often a simple +Regexp+ is enough to extract text from the comment:
+		# use #pattern= for this.
+		#
+		define_processor :process_comment
+		
+		#
+		# Builds #process_comment so that it matches the given +Regexp+ _pattern_.
+		# What will be send to #process_expectation depends on the number of capturing group of the pattern:
+		# * 0 => the portion of string matched by the full +Regexp+ (<tt>$&</tt>);
+		# * 1 => the portion of string matched by the capturing group (<tt>$1</tt>);
+		# * more => the array of captured groups (<tt>$~.captures</tt>).
+		# 
+		# Often the pattern just consists of some prompts and a sequence of other patterns:
+		# use #build_pattern for this.
+		#
+		def pattern= pattern
+			process_comment do |text|
+				next false unless md = text.match(pattern)
+				case md.size
+				when 1
+					next md[0]
+				when 2
+					next md[1]
+				else
+					next md.captures
+				end
+			end
+		end
+		
+		#
+		# Builds and sets (through #pattern=) a +Regexp+ that matches one of the given
+		# _prompts_ and the other _parts_ in sequence. First the array _prompts_ is sent to Text#build_prompt;
+		# this result, along with the other _parts_ are sent to Text#build_pattern.
+		# 
+		# If the last part is <tt>:STATEMENT</tt> the data extracted is the first statement:
+		# it can span across multiple lines and additional ones can contain arbitrary text;
+		# this is useful if we want to evaluate the expectation.
+		# 
+		# If all that matters is what follows the prompt you can use #set_prompts.
+		#
+		def build_pattern prompts, *parts
+			prompts = Array(prompts).flatten
+			return dont_process_comment if prompts.empty?
+			prompt = build_prompt(prompts)
+			if parts.last == :STATEMENT
+				stmnt = true
+				parts[-1] = /(.*)/m
+			end
+			pattern = super(prompt,*parts)
+			unless stmnt
+				self.pattern = pattern
+			else
+				process_comment do |text|
+					md = text.match pattern
+					next unless md
+					begin
+						RubyLex.extract_first_statement md[-1]
+					rescue ParseError
+						text # the error will be found later...
+					end
+				end
+			end
+		end
+		
+		#
+		# Uses #build_pattern so that the rest of line after one of the given _prompts_ is captured.
+		#
+		def set_prompts *prompts
+			build_pattern prompts, /(.*)/
+		end
+		
+		#
+		# Calls #set_prompts with a single _prompt_
+		#
+		def set_prompt prompt
+			set_prompts prompt
+		end
+		
+		##
+		# :call-seq:
+		#   process_statement{ |statement_code| ... }
+		#   process_statement -> proc or nil
+		#   dont_process_statement -> false
+		#
+		# If a block is given, it's registered as the processor.
+		# Otherwise returns the registered +Proc+ (or +nil+ if it hasn't been registered yet).
+		# 
+		# The block is executed in the context of (with +self+ as) that Statement, receiving
+		# its code as a parameter.
+		# The result of the block is the _actual_ value, that will be the first parameter to
+		# #process_assertion.
+		# 
+		# +dont_process_statement+ leaves the parameter unchanged, making it directly the actual value:
+		# it's like using <tt>process_statement{ |statement_code| statement_code }</tt>.
+		#
+		define_processor :process_statement
+
+		##
+		# :call-seq:
+		#   process_expectation{ |expectation_code| ... }
+		#   process_expectation -> proc or nil
+		#   dont_process_expectation -> false
+		#
+		# If a block is given, it's registered as the processor.
+		# Otherwise returns the registered +Proc+ (or +nil+ if it hasn't been registered yet).
+		# 
+		# The block is executed in the context of (with +self+ as) that Expectation, receiving
+		# the _expectation_code_ (result of #process_comment) as a parameter.
+		# The result of the block is the _expected_ value, that will be the second parameter to
+		# #process_assertion.
+		# 
+		# +dont_process_expectation+ leaves the parameter unchanged, making it directly the expected value:
+		# <tt>process_expectation{ |expectation_code| expectation_code }</tt>.
+		#
+		define_processor :process_expectation
+		
+		##
+		# :call-seq:
+		#   process_assertion{ |actual,expected| ... }
+		#   process_assertion -> proc or nil
+		#   dont_process_assertion -> false
+		#
+		# If a block is given, it's registered as the processor.
+		# Otherwise returns the registered Proc (or +nil+ if it hasn't been registered yet).
+		# +dont_process_assertion+ does nothing, it's like using <tt>process_assertion{ |*| }</tt>.
+		# 
+		# The block will receive the _actual_ and _expected_ values (obtained respectively from
+		# #process_statement and #process_expectation) and is executed in the context of
+		# (with +self+ as) the corresponding Example - class that includes the Assertion module,
+		# providing full access to Minitest framework. This allows to customize the assertion methods
+		# for only some examples (through some directives), but mantains an unified and coherent
+		# behaviour between statements inside it.
+		#
+		define_processor :process_assertion
+
+		#
+		# :category: Internal
+		# 
+		# Registers the given block as a configuration for the convention:
+		# this centralizes the building procedure, allowing the user to supply
+		# (through #use_with) only the desired parameters - often the prompts.
+		# 
+		# After this #default_configuration is called.
+		# 
+		# The configuration is defined for built-in conventions;
+		# user-defined ones often do not need this step.
+		#
+		def configure &configuration
+			@configuration = configuration
+			default_configuration
+		end
+		
+		#
+		# Restores the default configuration for this convention calling
+		# the block supplied to #configure without parameters
+		# (so its arity should allow this).
+		#
+		def default_configuration
+			use_with()
+		end
+		
+		# 
+		# Calls the configuration +Proc+ (if registered through #configure) with the given arguments.
+		# This method can be called from the Specification.
+		# 
+		# Returns +self+, allowing to chain other methods.
+		#
+		def use_with(*args,&blk)
+			if @configuration
+				@configuration.call(*args,&blk)
+			elsif !args.empty? || blk
+				raise "#{self} does not accept a configuration"
+			end
+			return self
+		end
+		alias with use_with
+
+		# Name of the convention as a +Symbol+.
+		attr_reader :name
+		attr_writer :name # :nodoc:
+		protected :name=  # :nodoc:
+		
+		# +Hash+ of arbitrary metadata
+		attr_reader :metadata
+		attr_writer :metadata # :nodoc:
+		protected  :metadata= # :nodoc:
+
+		#
+		# Priority of the convention (0 by default). The higher it is, the earlier this convention
+		# will be recognized in the comments.
+		# 
+		# If a comment can be accepted by more than one convention - for example when one pattern
+		# is a subset of the other - it's better to make their priorities differ.
+		# Otherwise the convention defined lastly takes the precedence.
+		#
+		attr_accessor :priority
+			
+		#
+		# Creates a +Convention+ object with the +name+ _name_.
+		# The block is supplied to #edit and must define the convention behaviour
+		# (through #process_comment, #process_statement, #process_expectation, #process_assertion).
+		#
+		def initialize(name,&blk)
+			@name = name.to_sym
+			@metadata = {}
+			@priority = 0
+			edit &blk
+			verify_status
+		end
+		
+		#
+		# :call-seq:
+		#   edit{ ||     ... }
+		#   edit{ |conv| ... }
+		# 
+		# The block given can edit the convention behaviour through its methods.
+		# If it takes no arguments that block is executed in the context of +self+,
+		# otherwise it is yielded this convention object.
+		# 
+		# Returns +self+, allowing to chain other methods.
+		#
+		def edit &blk
+			return self unless blk
+			if blk.arity == 0
+				instance_eval(&blk)
+			else
+				blk.call(self)
+			end
+			return self
+		end
+		
+	# :stopdoc:
+		
+		def verify_status
+			process_comment.nil? and
+				raise "Convention behaviour not defined (use `process_comment{ ... }')"
+			process_statement.nil? and
+				raise "Convention behaviour not defined (use `process_statement{ ... }')"
+			process_expectation.nil? and
+				raise "Convention behaviour not defined (use `process_expectation{ ... }')"
+			process_assertion.nil? and
+				raise "Convention behaviour not defined (use `process_assertion{ ... }')"
+		end
+		private :verify_status
+		
+		def copy new_name, &edit
+			conv = self.dup
+			conv.name = new_name.to_sym
+			conv.metadata = self.metadata.dup
+			conv.edit(&edit)
+		end
+		
+		def to_s
+			"#<#{self.class}:#{name}>"
+		end
+		alias inspect to_s
+		
+	# :startdoc:
+		
+		#
+		# This module is included into the Specification and allows the interaction
+		# with the Convention objects in use: you can define new ones, remove
+		# those already in use or simply modify some of their features.
+		# 
+		# It also extends the Convention class, so that the built-in conventions
+		# 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 Convention class
+		# you can find the details on how conventions work.
+		#
+		module SpecificationHelper
+			
+		# :stopdoc:
+			
+			attr_reader :conventions
+			private :conventions
+			
+			def sort_conventions
+				conventions.sort_by!.with_index{ |cnv,i| [-cnv.priority,-i] }
+			end
+			private :sort_conventions
+			
+			def convention_list
+				sort_conventions
+				conventions.dup
+			end
+			
+		# :startdoc:
+			
+			# Returns the Convention with the given _name_ or +nil+ if it isn't defined.
+			def convention_defined? name
+				name = name.to_sym
+				conventions.find{ |conv| conv.name == name }
+			end
+			
+			# Returns the Convention with the given _name_ or raises an exception if it isn't defined.
+			def convention name
+				convention_defined?(name) or
+					raise Error, "Undefined convention `#{name}'"
+			end
+		
+			#
+			# Defines a convention with the given _name_ and the block _definition_ (sent to Convention.new).
+			# If _template_ (name or Convention object) is given, it is copied and used
+			# as the starting point of definition.
+			# Returns the defined convention.
+			#
+			def define_convention name, template=nil, &definition
+				convention_defined?(name) and
+					raise "Convention `#{name}' already defined!"
+				conv = if template.nil?
+					Convention.new(name,&definition)
+				else
+					template = convention(template) unless template.is_a?(Convention)
+					template.copy(name,&definition)
+				end
+				conventions << conv
+				sort_conventions
+				return conv
+			end
+			
+			#
+			# Removes _conv_ (name or Convention object) from the list of defined conventions.
+			# Returns +true+ if it was defined, +false+ otherwise.
+			#
+			def remove_convention conv
+				conv = convention(conv) unless conv.is_a?(Convention)
+				!!conventions.delete(conv)
+			end
+			alias undefine_convention remove_convention
+			
+		end
+		
+		@conventions = []
+		extend SpecificationHelper
+		class << self # :nodoc:
+			alias list convention_list 
+			alias get  convention
+			alias []   convention
+		end
+		
+	#
+	# :section: Conventions: Result
+	#
+		
+		##
+		# :singleton-method:
+		# 
+		# This is the most common convention. Historically introduced by +IRB+ as the result
+		# prompt <tt>"=>"</tt>, it's now used in almost all documentation examples
+		# in the flavour of _hash_-rocket notation <tt>#=></tt>.
+		# 
+		# Expectation format::
+		#   <tt>=></tt> _result_code_
+		# 
+		# Description::
+		#   Evaluates the statement and the (first statement of) expectation;
+		#   these values are compared through +assert_equal+.
+		#     Regexp.compile '///'  #=> %r%///%   # equivalent to /\/\/\// but more readable
+		#     options = {}
+		#     options[:a] = 1
+		#     options[:b] = 2
+		#     options
+		#     # => {
+		#     #   :a => 1,
+		#     #   :b => 2
+		#     # }
+		#     # statement complete; this comment is ignored
+		#     [5,4,3,2,1].reverse  #=> (1..5).to_a
+		#     animals = ["monkey", "cat", "ant", "lion", "bee", "dog"]
+		#     animals.select{ |s| s.length == 3 }.sort   # => %w[ ant bee cat dog ]
+		#   
+		# Note::
+		#   Since the expectation is evalued we can include additional details with comments,
+		#   it can can span across multiple lines and once the statement is complete the rest is ignored.
+		#   
+		# Configuration::
+		#   The user can supply its chosen prompts.
+		#
+		define_convention :result_eval do
+			configure do |*prompts|
+				prompts << '=>' if prompts.empty?
+				build_pattern prompts, :STATEMENT
+			end
+			process_statement{ |code| eval(code) }
+			process_expectation &process_statement
+			process_assertion{ |act,exp| assert_equal(exp,act) }
+			self.priority = 100 # most common => tried early for efficiency
+		end
+		
+		##
+		# :singleton-method:
+		# 
+		# Derived from ::result_eval::
+		#   Consider the following:
+		#   
+		#     a = "A string"
+		#     b = "Another string"
+		#     b.slice! /nother/
+		#   :rdx: off
+		#     b #=> a
+		#     
+		#   Both the strings +a+ and +b+ have the same content;
+		#   if the <tt>=></tt> prompt always maps to an +assert_equal+ the assertion would pass...
+		#   But it's really what we mean, what we want to bring out from the example?
+		#   That sounds much more like "it returns the object _labelled_ +a+"
+		#   then "it returns an object _equal_ _to_ +a+".
+		# 
+		# Expectation format::
+		#   <tt>=></tt> _fetch_instruction_
+		# 
+		# Description::
+		#   This convention recognizes a plain "fetching" (according to Text::REGEXP::FETCH)
+		#   expectation - in the most common case a local variable - and compares the values
+		#   through +assert_same+.
+		#   
+		# Configuration::
+		#   The user can supply its chosen prompts.
+		#
+		define_convention :result_same, :result_eval do
+			configure do |*prompts|
+				prompts << '=>' if prompts.empty?
+				build_pattern prompts, :CAPTURE_FETCH, :END_CODE_IN_LINE
+			end
+			process_assertion{ |act,exp| assert_same(exp,act) }
+			self.priority = 110
+		end
+	
+		##
+		# :singleton-method:
+		# 
+		# Derived from ::result_eval::
+		#   Consider how Numerics are *obtained*:
+		#   
+		#     1.quo 2      #=> 1/2
+		#     Complex(1,1) #=> 1+1i
+		#     
+		#   * The first expectation evals to 0 (unless +mathn+ is required),
+		#     but that doesn't seem its goal: there is no need to point out an
+		#     Integer as a ratio between two literal numbers.
+		#   * The second expectation would raise a SyntaxError (due to +i+):
+		#     of course this isn't what we mean.
+		#     
+		#   The point is that _evaluate_ a string isn't the best way to get
+		#   a number: the _conversion_ is usually better.
+		#   
+		#   Now consider how numeric are *compared*:
+		#   
+		#   :rdx: off -
+		#     1.0 + 2.0    #=> 3
+		#     Math.log(14) #=> 2.6390573296152584
+		#     
+		#   * The result of the first statement is the Float <tt>3.0</tt>, but the expectation
+		#     alludes to a Fixnum... Can we still consider those numbers _equals_?
+		#   * Are all of those float digits really necessary? In most situations the answer is no,
+		#     however the floating-point comparison does care about it - and the result is often
+		#     machine-depending.
+		#     
+		#   This means that in these situations +assert_equal+ is inappropriate: we have to
+		#   enforce type checking and loosen the accuracy for inexact floats.
+		# 
+		# Expectation format::
+		#   <tt>=></tt> _literal_numeric_ (obtainable with Numeric#to_s)
+		#   
+		# Description::
+		#   Obtains the Numeric through Text#numeric_from_str and makes the assertion with
+		#   Assertions#assert_equal_numeric (the default relative error allowed
+		#   for floats is <tt>1e-6</tt>, value stored in the #metadata as +:epsilon+).
+		#   
+		# Note::
+		#   This is suitable enough for the vast majority of the examples;
+		#   if all digits are important we should move to more accurate types - such as +BigDecimal+.
+		# 
+		#   If the value isn't literal (but calculated, for example) the +float+ directive
+		#   can - among other things - force the use of this approximation in the comparison
+		#   (see Directive::float for an example).
+		#   
+		# Configuration::
+		#   The user can supply its chosen prompts and the epsilon.
+		#
+		define_convention :result_numeric, :result_eval do
+			md = self.metadata
+			configure do |*args|
+				md[:epsilon] = args.find{ |arg| arg.is_a?(Numeric) } || 1e-6
+				args.delete(md[:epsilon])
+				args << '=>' if args.empty?
+				build_pattern args, :CAPTURE_NUMERIC, :END_CODE_IN_LINE
+			end
+			process_expectation &Text.method(:numeric_from_str)
+			process_assertion do |act,exp|
+				assert_equal_numeric exp, act, md[:epsilon]
+			end
+			self.priority = 110
+		end
+		
+		##
+		# :singleton-method:
+		# 
+		# Derived from ::result_eval::
+		#   Consider the following (from <tt>encoding.c</tt>):
+		#     
+		#     string = "R\xC3\xA9sum\xC3\xA9"
+		#     string.encoding #=> Encoding::UTF_8
+		#     string.force_encoding(Encoding::ISO_8859_1)
+		#     #=> "R\xC3\xA9sum\xC3\xA9"
+		#     # same bytes!
+		#  
+		#   The point is that with a literal string we have no way to specify its encoding
+		#   (other than the magic comment, but it's a little odd at the top of the example
+		#   if used only for this reason). Therefore the intention is to show the actual bytes
+		#   in the string, regardless of the encoding in which it's represented. This is good
+		#   as a general rule: if it's not the case it should be pointed out - like in some
+		#   examples in <tt>transcode.c</tt>:
+		#   
+		#     ec = Encoding::Converter.new("utf-8", "iso-2022-jp")
+		#     ec.convert("\xE3")       #=> "".force_encoding("ISO-2022-JP")
+		#     ec.convert("\x81")       #=> "".force_encoding("ISO-2022-JP")
+		#     ec.convert("\x82")       #=> "\e$B$\"".force_encoding("ISO-2022-JP")
+		#     ec.finish                #=> "\e(B".force_encoding("ISO-2022-JP")
+		# 
+		# Expectation format::
+		#   <tt>=></tt> _literal_string_
+		#   
+		# Description::
+		#   The string encoding is ignored (converted to +BINARY+) in the comparison.
+		#   
+		# Note::
+		#   This is actually true for all types of literal strings,
+		#   however only double-quoted ones (without interpolation) are recognized.
+		#   This is because here we can insert actual bytes easily.
+		#   
+		# Configuration::
+		#   The user can supply its chosen prompts.
+		#
+		define_convention :result_string, :result_eval do
+			configure do |*prompts|
+				prompts << '=>' if prompts.empty?
+				build_pattern prompts, :CAPTURE_DQ_STRING, :END_CODE_IN_LINE
+			end
+			level = lambda do |obj|
+				obj.dup.force_encoding('BINARY') if obj.is_a?(String)
+			end
+			process_assertion{ |act,exp| assert_equal_but level, exp, act }
+			self.priority = 110
+		end
+		
+		# This way RDoc recognizes the ghost method properly...
+		undefine_convention :result_string unless Object.const_defined?(:Encoding)
+		
+		##
+		# :singleton-method:
+		# 
+		# Derived from ::result_eval::
+		#   Consider the following:
+		#   
+		#     class Klass
+		#       # ...
+		#     end
+		#     inst = Klass.new
+		#     inst #=> #<Klass:0x00074532>
+		#     
+		#   This notation is due to the fact that +IRB+ uses the +inspect+ method and usually
+		#   it returns a string formatted in that way. Since it's unlikely to start a statement
+		#   (intended to be evalued) like that, we can interpret it differently.
+		#   The only thing we want to exalt is that +inst+ is an *instance* of +Klass+.
+		# 
+		# Expectation format::
+		#   <tt>=> #<</tt>_class_ [:_object_adress_] [_other_data_]<tt>></tt>
+		#   
+		# Description::
+		#   The class is extracted from the expectation; it's then send to
+		#   +assert_instance_of+ along with the result of the statement.
+		#   
+		# Note::
+		#   The _object_adress_ is optional. If there is other extraneous data a warning will
+		#   be generated (because it won't be used): to check that data ::result_inspect
+		#   is probably the solution.
+		#   
+		# Note::
+		#   We don't want to rely on the +inspect+ method (either via explicit call or
+		#   by the ::result_inspect convention), since that string can carry on other
+		#   data or may even not contain the class at all (like +Time+ objects).
+		#   
+		# Configuration::
+		#   The user can supply its chosen prompts.
+		#
+		define_convention :result_instance_of, :result_eval do
+			configure do |*prompts|
+				prompts << '=>' if prompts.empty?
+				build_pattern prompts, /#?<(.*)>/m, :END_CODE_IN_LINE
+			end
+			process_expectation do |content|
+				# Validation:
+				md = content.match /^
+					( #{REGEXP::CLASS} )  # Literal class
+					(?: :0[Xx]\h+ )?      # Optional object id - discarded
+					( (?m:.*) )           # All the rest: should be empty
+				/ox
+				raise 'Missing literal class!' unless md
+				klass_name,other_content = md.captures
+				klass = toplevel_scope.const_get(klass_name)
+				warn "Data unused by this convention: #{other_content.inspect}" unless other_content.empty?
+				klass
+			end
+			process_assertion{ |obj,klass| assert_instance_of(klass,obj) }
+			self.priority = 110
+		end
+		
+		##
+		# :singleton-method:
+		#
+		# This convention is for values that are uncertain.
+		# It does a sort of _weak_ _assertion_, testing that values are "similar".
+		# Fields of application include randomness, time objects, system and context-dependent issues.
+		#
+		# Expectation format::
+		#   <tt>-></tt> _result_code_
+		#   
+		# Description::
+		#   Both the statement and the expectation are evalued; the respective results are
+		#   compared through Assertions#assert_same_type.
+		#   
+		#   An example (from <tt>random.c</tt>):
+		#   
+		#     rand(-100) # -> 87
+		#     rand(-0.5) # -> 0.8130921818028143
+		#     rand(1.9)  # => 0 # equivalent to rand(1), which is always 0
+		#   
+		# Note::
+		#   When an indicative test makes sense, it's surely better than nothing:
+		#   try this convention before leaving to the ::eval one.
+		#   
+		# Configuration::
+		#   The user can supply its chosen prompts.
+		#
+		define_convention :result_indicative do
+			configure do |*prompts|
+				prompts << '->' if prompts.empty?
+				build_pattern prompts, :STATEMENT
+			end
+			process_statement{ |code| eval(code) }
+			process_expectation &process_statement
+			process_assertion{ |act,exp| assert_same_type(exp,act) }
+		end
+		
+		##
+		# :singleton-method:
+		#
+		# This convention is highly coupled with the ::result_eval one:
+		# since in some situations they lead to the same result, 
+		# the difference between the two conventions may be a little subtle
+		# (see the Note for details).
+		#
+		# Expectation format::
+		#   <tt>></tt> _string_representation_
+		#   
+		# Description::
+		#   Evaluates the statement and treats the expectation as its literal string representation
+		#   obtained with +inspect+. The strings are stripped and object ids are generalized,
+		#   so that +assert_equal+ sees only the essential differences.
+		#     
+		#     /\d+\.\d+/.match "pi = 3.17"   # > #<MatchData "3.17">
+		#     # inline comments not allowed (the string is taken literally)
+		#     # Rubyday 2015:
+		#     Time.utc 2015, 11, 13          # > 2015-11-13 00:00:00 UTC
+		#     1/0.0                          # > Infinity
+		#     o = Object.new
+		#     o.instance_variable_set :@a, 1
+		#     o                              # > #<Object:0x000045a8 @a=1>
+		#     # Put the adress that you want, it doesn't matter...
+		#   
+		# Note::
+		#   +result_eval+'s approach is to assert <tt>object == eval(string)</tt>,
+		#   while +result_inspect+ asserts <tt>object.inspect == string</tt>.
+		#   These are the two sides of the same coin if +eval+ is the _inverse_
+		#   of +inspect+ for that +object+.
+		#   
+		#   In fact, there is an issue hidden under the rug: the <tt>=></tt> prompt in +IRB+
+		#   actually shows the string representation of an object (the result of a statement)!
+		#   However that prompt isn't associated with the +result_inspect+ convention
+		#   for a matter of convenience.
+		#   
+		#   Examples must be written and read in the simplest - but formal - way,
+		#   without loosing time on tiny and unnecessary details.
+		#   The fact that the expectation is evalued offers some advantages in terms of freedom:
+		#   * we can be more concise and clear by using <b>alternative syntax</b> and *expressions*;
+		#   * we can insert <b>values at runtime</b> - depending on the context - rather then
+		#     hard-coding them in a predetermined way.
+		#   The next example is composed by statements that will fail if +result_inspect+ would have
+		#   the <tt>=></tt> prompt:
+		#   
+		#     [1,2] #=> [1,2]                         # missing space: [1, 2]
+		#     "a string".inspect #=> %Q{"a string"}   # inspect uses double quotes: "\"a string\""
+		#     Hash('a'=>2,'b'=>1) #=> {
+		#     #   'b' => 1,
+		#     #   'a' => 2
+		#     # }   # does these spaces really matter? And the order in which pairs are listed?
+		#     File.expand_path 'a' #=> "#{Dir.pwd}/a" # interpolation of values not allowed
+		#     (1..1000).first 100  #=> (1..100).to_a  # shorthands not allowed
+		#     "abc \0\0".unpack('a3a3') #=> ["abc", " \000\000"]
+		#                                             # the second string should be: " \0\0"
+		#     
+		#   Because such situations are far from being rare - the first twos explain
+		#   43 failures only in <tt>array.c</tt> - the choice is quite clear:
+		#   this convention is associated to a different prompt, leaving the hash-rocket
+		#   for +result_eval+.
+		#   
+		#   For these reasons, if these two alternatives are equivalent +result_eval+ is often preferred.
+		#   Otherwise - for objects whose +eval+ isn't the inverse of +inspect+ - this convention turns
+		#   handy: showing the results above without will explicitly force the use of +inspect+
+		#   on the receiver (and the expected string is evalued). These may divert attention
+		#   from the true aim of the example to the behaviour of the +inspect+ method.
+		#   
+		# Configuration::
+		#   The user can supply its chosen prompts.
+		#
+		define_convention :result_inspect do
+			configure do |*prompts|
+				prompts << '>' if prompts.empty?
+				set_prompts prompts
+			end
+			process_statement{ |code| eval(code).inspect }
+			dont_process_expectation
+			level = lambda{ |txt| generalize_object_ids(txt.strip) }
+			process_assertion{ |act,exp| assert_equal_but(level,exp,act) }
+		end
+		
+		##
+		# :singleton-method:
+		#
+		# Derived from ::result_inspect::
+		#   The aim is to reduce discrepances due to float calculations and representations,
+		#   one of the things that ::result_numeric does for ::result_eval (but
+		#   here this is done in strings).
+		#
+		# Expectation format::
+		#   <tt>></tt> _numeric_representation_ (obtainable with Numeric#inspect)
+		#   
+		# Description::
+		#   At most 6 (value stored in the #metadata as +:digits+) digits are significant -
+		#   thus considered - for floats.
+		#     
+		#     Complex.polar(2, 3)  # > (-1.9799849932008908+0.2822400161197344i)
+		#     # same as:
+		#     Complex.polar(2, 3)  # > (-1.9799849+0.2822400i)
+		#   
+		# Configuration::
+		#   The user can supply its chosen prompts and the digits.
+		#
+		define_convention :numeric_inspect, :result_inspect do
+			md = self.metadata
+			configure do |*args|
+				md[:digits] = args.find{ |arg| arg.is_a?(Fixnum) } || 6
+				args.delete(md[:digits])
+				args << '>' if args.empty?
+				build_pattern args, :CAPTURE_NUMERIC_P, /$/ # no comment allowed for coherence
+			end
+			level = lambda{ |txt| Text.normalize_floats(txt,md[:digits]) }
+			process_assertion{ |act,exp| assert_equal_but(level,exp,act) }
+			self.priority = 10
+		end
+		
+	#
+	# :section: Conventions: Output
+	#
+		
+		##
+		# :singleton-method:
+		# 
+		# Expectation format::
+		#   <tt>prints:</tt> _output_
+		#   
+		# Description::
+		#   Indicates the output (send to <tt>$stdout</tt>) of the statement; this output is
+		#   taken _literally_, without any evaluation, and sent to +assert_output+. Because of this,
+		#   in order to avoid failures for minor issues, the comparison is made through Text#normalize_output.
+		#     
+		#     print "Hello!"                  # prints: Hello!
+		#     # literal == straightforward:
+		#     print "\"A quoted string\""     # prints: "A quoted string"
+		#     # lost of (often meaningless) information:
+		#     print " spaces\n\n"             # prints: spaces
+		#     
+		# Note::
+		#   This convention is really powerful when expressing strings containing many special characters,
+		#   that have otherwise to be escaped - but beware of Text#normalize_output.
+		#   This is illustrated by the following example (from <tt>re.c</tt>): 
+		#   
+		#     puts Regexp.escape('\*?{}.')   # prints: \\\*\?\{\}\.
+		#     
+		#   Here are some alternatives, clearly more confusing because we have to consider also the
+		#   escaping step for the string itself:
+		#   
+		#     str = Regexp.escape('\*?{}.')
+		#     str # => '\\\\\*\?\{\}\.'   # not to talk about "\\\\\*\\?\\{\\}\\."
+		#     str # =>
+		#         # <<'EOS'.strip
+		#         # \\\*\?\{\}\.
+		#         # EOS
+		#         
+		# Note::
+		#   The main limitation for this convention is that the visible output cannot fill more
+		#   than one line (otherwise we may include extraneous comment, like the ones in the first example):
+		#   this issue can be solved by the use of Directive::stdout, which also does the
+		#   same levelling on the output.
+		#   
+		# Note::
+		#   Simplicity means less exactness. This often isn't a problem, but sometimes we may
+		#   want more precision. A more formal approach is offered by
+		#   ::output_eval which - among other things - avoids the levelling through evaluation.
+		#   
+		# Configuration::
+		#   The user can supply its chosen prompts.
+		#
+		define_convention :output_literal do
+			configure do |*prompts|
+				prompts << /[Pp]rints:?/ if prompts.empty?
+				set_prompts prompts
+			end
+			process_statement{ |code| lambda{ eval(code) } }
+			dont_process_expectation
+			level = method(:normalize_output).to_proc
+			process_assertion do |verbose_proc,stdout|
+				assert_output_but level, stdout, &verbose_proc
+			end
+		end
+
+		##
+		# :singleton-method:
+		# 
+		# Expectation format::
+		#   <tt>>></tt> _output_code_
+		#   
+		# Description::
+		#   Indicates the output (send to <tt>$stdout</tt>) of the statement; this output is
+		#   _evalued_ and sent to +assert_output+. Since there cannot be ambiguity
+		#   the comparison is by default made without applying any trick, allowing a more formal
+		#   approach in contrast to ::output_literal.
+		#   
+		#     print "a string"     # >> "a string"        # as is   (comment allowed)
+		#     puts  "a string"     # >> "a string\n"      # newline appended
+		#     puts  "a string\n"   # >> "a string\n"      # newline not appended if already there
+		#     p     "a string"     # >> %Q("a string"\n)  # calls inspect
+		#     puts "This is ", "the time"
+		#                     # >> "This is \n"  +
+		#                     #    "the time\n"
+		#                     # multiline expectation
+		#     alphabet = "abcdefghijklmnopqrstuvwxyz"
+		#     print alphabet  # >> ('a'..'z').to_a.join  # Expressions allowed
+		#     
+		# Note::
+		#   The evaluation makes also possible to return a +Regexp+. In this way we
+		#   can use the full power of +assert_output+:
+		#     puts "c"*500   # >> /\A C{500} \Z/ix     # Regexp match assertion
+		#   
+		# Configuration::
+		#   The user can supply its chosen prompts.
+		#
+		define_convention :output_eval do
+			configure do |*prompts|
+				prompts << '>>' if prompts.empty? # Inspired by "Using JRuby", Pragmatic Programmers
+				build_pattern prompts, :STATEMENT
+			end
+			process_statement{ |code| lambda{ eval(code) } }
+			process_expectation{ |code| eval(code) }
+			process_assertion do |verbose_proc,output|
+				assert_output output, &verbose_proc
+			end
+		end
+	
+	#
+	# :section: Conventions: Error
+	#
+		
+		##
+		# :singleton-method:
+		# 
+		# Expectation format::
+		#   <tt>raises</tt> [_exception_class_] [<tt>:</tt>] [_exception_message_]
+		# 
+		# Description::
+		#   Recognizes the class and the message of the exception raised by the statement.
+		#   The message is interpreted literally, without any evaluation:
+		#   to remove little discrepances Text#normalize_exception_message is used.
+		#   The class (if given), message and +false+ are sent to Assertions#assert_msg_raised.
+		#   
+		#     1.odd?(true)       # raises ArgumentError: wrong number of arguments (1 for 0)
+		#     "a string".meth    # raises NoMethodError: undefined method `meth'
+		#                        # the message continues with 'for "a string":String', but that doesn't add much...
+		#     "a string" + 1     # Raises! # it doesn't matter if it's a TypeError or ArgumentError,
+		#                                  # as long as the action is illegal.
+		#     [1].freeze.shift   # raises: frozen
+		#                        # this works, but it's probably too concise...
+		#   
+		# Configuration::
+		#   The user can supply its chosen prompts.
+		#
+		define_convention :error_literal do
+			configure do |*prompts|
+				prompts << /[Rr]aises[:!]?/ if prompts.empty?
+				build_pattern prompts, /(#{REGEXP::CLASS})?:?/o, /#{REGEXP::END_CODE_IN_LINE}|(.*)/o
+			end
+			process_statement{ |code| lambda{ eval(code) } }
+			process_expectation do |(cls,msg)|
+				cls &&= toplevel_scope.const_get(cls)
+				[cls,msg]
+			end
+			level = method(:normalize_exception_message).to_proc
+			process_assertion do |raising_proc,(exc_class,exc_message)|
+				assert_msg_raised_but level, exc_message, false, *exc_class, &raising_proc
+			end
+		end
+	
+		##
+		# :singleton-method:
+		# 
+		# Expectation format::
+		#   <tt>~></tt> [_exception_class_] [<tt>:</tt> _code_message_]
+		# 
+		# Description::
+		#   Recognizes the class and the message of the exception raised by the statement.
+		#   The message is evalued, thus avoiding any sort of levellation: this enables
+		#   a more formal approach in contrast to ::error_literal.
+		#   The class (if given) and message are sent to Assertions#assert_msg_raised.
+		#   
+		#     [1].freeze.shift   # ~> /frozen/
+		#     1.odd?(true)       # ~> ArgumentError: "wrong number of arguments (1 for 0)"
+		#     "a string".meth    # ~> NoMethodError: %q{undefined method `meth' for "a string":String}
+		#   
+		# Configuration::
+		#   The user can supply its chosen prompts.
+		#
+		define_convention :error_eval do
+			configure do |*prompts|
+				prompts << '~>' if prompts.empty? # Inspired by "Using JRuby", Pragmatic Programmers
+				build_pattern prompts, /(.+)/m
+			end
+			process_statement{ |code| lambda{ eval(code) } }
+			process_expectation do |content|
+				cls,msg = Text.split_exception_string(content,:class_message)
+				# :message_class is not allowed, since a valid statement can end with a parhentesis...
+				cls &&= toplevel_scope.const_get(cls)
+				msg &&= eval(msg)
+				[cls,msg]
+			end
+			process_assertion do |raising_proc,(exc_class,exc_message)|
+				assert_msg_raised exc_message, *exc_class, &raising_proc
+			end
+		end
+		
+	#
+	# :section: Conventions: Others
+	#
+
+		##
+		# :singleton-method:
+		# 
+		# Expectation format::
+		#   <tt>Throws</tt> _symbol_
+		# 
+		# Description::
+		#   The statement must +throw+ the given _symbol_.
+		#   
+		#     def this_will_throw sym
+		#       throw sym
+		#     end
+		#     this_will_throw :symbol # Throws :symbol
+		#   
+		# Configuration::
+		#   The user can supply its chosen prompts.
+		#
+		define_convention :throws do
+			configure do |*prompts|
+				prompts << /[Tt]hrows:?/ if prompts.empty?
+				build_pattern prompts, /:(\w+)/, :END_CODE_IN_LINE
+			end
+			process_statement{ |code| lambda{ eval(code) } }
+			process_expectation &:to_sym
+			process_assertion do |throwing_proc,catch|
+				assert_throws catch, &throwing_proc
+			end
+		end
+		
+		##
+		# :singleton-method:
+		# 
+		# This convention is triggered as the last resource, if any of the others isn't.
+		# 
+		# Description::
+		#   Evaluates the statement. Nothing else.
+		#   
+		# Note::
+		#   This convention generates a warning if the expectation begins with a non-word
+		#   character, which is probably part of a prompt whose convention is not defined.
+		# 
+		# Note::
+		#   Basically, this convention kicks in when:
+		#   * we don't care about the result obtained, but we have anyhow to evaluate the code;
+		#   * we do care about it, but other conventions aren't suitable in these circumstances.
+		# 
+		#   The latter situation is more intresting.
+		#   Consider the following (from <tt>time.c</tt>):
+		#   
+		#     t = Time.now   # 2007-11-19 08:18:31 -0600
+		#     t.gmt?         #=> false
+		#     t.gmtime       # 2007-11-19 14:18:31 UTC
+		#     t.gmt?         #=> true
+		#     
+		#   Since time and local zone may vary, it's hard to write an expectation.
+		#   On the other hand not writing a comment at all may leave some issues:
+		#   is the time converted or simply interpreted differently?
+		#   Of course, the documentation explains this issue - but then the example
+		#   becomes quite useless...
+		#   
+		#   Remember that <b>the aim of the examples is to be clear and straightforward,
+		#   not to build solid but incomprehensible tests</b>: for this reason
+		#   a plain comment can sometimes suffice this need.
+		#   
+		# Configuration::
+		#   Not allowed.
+		#   
+		define_convention :eval do
+			set_prompts []
+			process_statement{ |code| eval(code) }
+			process_expectation do |code|
+				warn "Unknown prompt, #{convention} triggered" if code =~ /\A\s*\W/
+			end
+			dont_process_assertion
+		end
+		
+	end
+
+end