rdx 0.9.0.pre

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 4829fee222c87078e0a61f49a92e3fa8aeb72508
+  data.tar.gz: 721963819a469824512101cdcb6cd38e82cf1883
+SHA512:
+  metadata.gz: 879dd564e894198bbd70538468e374c3e8252765355a5b2de018897dd47a0cd7230da6d8dbfc3d0bb255bca6fd73ccd9bf9f39f25d0484c28a0b07c6be5673ee
+  data.tar.gz: 3b5ee5fb739942e3119e06bf6d31d6ca6df28c1831e70134e9d83adf57626958946c36cb2493f47ae55de9be56967d158a65014baa0ce48512a80275c8abf3f1

data/.rdx

@@ -0,0 +1,20 @@
+
+RDX::Specification.new do
+	use_convention :result_indicative
+	use_convention :result_inspect
+	use_convention :numeric_inspect
+  use_convention :output_eval
+	use_convention :error_eval
+	define_convention :pass do
+		build_pattern /[Pp]ass(?:es)?!?/, :END_CODE_IN_LINE
+		process_statement{ |code| lambda{ eval(code) } }
+		dont_process_expectation
+		process_assertion{ |passing_proc| assert_nothing_raised(RDX::Assertion,&passing_proc) }
+	end
+	define_convention :fail do
+		build_pattern /[Ff]ails?!?/, :END_CODE_IN_LINE
+		process_statement{ |code| lambda{ eval(code) } }
+		dont_process_expectation
+		process_assertion{ |failing_proc| assert_raises(RDX::Assertion,&failing_proc) }
+	end
+end

data/README

@@ -0,0 +1,19 @@
+
+= RDX: Ruby Documentation example eXecutor
+
+The aim of RDX is to join the worlds of documentation and testing, which overlap in examples.
+Relying on RDoc and Minitest RDX parses source files, generates documentation, extracts
+examples from comments and executes them as tests.
+In the examples the significant data of a statement - like result, output or raised exception -
+is pointed out with a comment at its end.
+
+The conventions, heart of RDX, map specific patterns into those comments to a way of processing code
+(for instance the hash-rocket convention "#=>" - pioneer from IRB - simply evals both statement and expectation
+and compare those results through assert_equal).
+
+Directives (explicit or implicit) operate on a larger scale: we may want not to execute an example,
+to interpret one as the output of the previous, to change its binding, to run it in a
+temporary directory, to simulate a bash environment, and so on...
+
+Either conventions and directives can be built-in because of their popularity or defined by the user.
+By running those tests, RDX gives formalism to documentation examples, greatly increasing their strength.

data/bin/rdx

@@ -0,0 +1,7 @@
+#! /usr/bin/env ruby
+
+$LOAD_PATH.unshift "#{File.dirname File.dirname File.expand_path __FILE__}/lib"
+
+require 'rdx'
+
+RDX.run(ARGV)

data/examples/minimal/.rdx

@@ -0,0 +1,8 @@
+
+RDX::Specification.new do
+	use_convention :result_indicative
+	use_convention :result_inspect
+	use_convention :numeric_inspect
+	use_convention :output_eval
+	use_convention :error_eval
+end

data/examples/minimal/README

@@ -0,0 +1,10 @@
+
+This directory contains a minimal example that shows the use of RDX.
+
+To begin, launch
+	rake rdx
+from the command line.
+
+There will be many failures during the run: in this way you can see how this works.
+
+You can then try to edit those files and the rakefile...

data/examples/minimal/lib/other_conventions.rb

@@ -0,0 +1,64 @@
+
+#
+# The conventions in these examples are not default:
+# you should add <tt>use_convention</tt> _name_ in the specification.
+#
+class OtherConventions
+	
+	#
+	# Shows the result of +inspect+:
+	# 
+	#   # A success:
+	#   /a/.match "asd" # >   #<MatchData "a">
+	#   
+	#   # A failure:
+	#   /a/.match "asd" # >   #<Match "a">
+	#
+	def result_inspect
+	end
+	
+	#
+	# Shows an indicative result:
+	# 
+	#   # A success:
+	#   rand(100) # -> 58
+	#   
+	#   # A failure:
+	#   rand(100) # -> 0.7845
+	#
+	def result_indicative
+	end
+	
+	#
+	# +eval+ the output:
+	# 
+	#   # A success:
+	#   puts "A line", " another line"
+	#   # >> "A line\n another line\n"
+	#   
+	#   # A success with a Regexp:
+	#   puts "A line", " another line"
+	#   # >> /\sline\s/
+	#   
+	#   # A failure:
+	#   puts "Some spaces:    "
+	#   # >> "Some spaces: "
+	#
+	def output_eval
+	end
+	
+	#
+	# <tt>eval</tt>s the exception message:
+	# 
+	#   # A success:
+	#   raise ArgumentError, "Wrong number of arguments: 0 for (1..2)"
+	#   # ~> ArgumentError: /\AWrong number of arguments: \d for \(\d\.\.\d\)\z/
+	#   
+	#   # A failure:
+	#   raise 'An error occurred!'
+	#   # ~> "An error"
+	#
+	def error_eval
+	end
+	
+end

data/examples/minimal/lib/the_basics.rb

@@ -0,0 +1,94 @@
+#
+# This is the file comment
+# 
+
+#
+# The basics on how RDX works.
+#
+# This comment is documenting (for the class).
+# 
+# This is a text section
+# 
+#   # This is an example
+# 
+# This is another text section.
+# 
+#   # And this is another example
+#
+class TheBasics
+
+	#
+	# A few +result_eval+ conventions:
+	# 
+	#   true #=> true    # this will pass
+	#   true #=> false   # but this one won't...
+	#   
+	# The expectation can begin in the next line:
+	# 
+	#   true
+	#   # => false
+	#   
+	# And you will see this failure. If this is evalued
+	# it can also span across multiple lines:
+	# 
+	#   [1,2,3] #=> [1,
+	#           #    2,
+	#           #    3,
+	#           #    4]
+	#
+	# And even here the failure is reported.
+	#
+	def result_eval
+	end
+
+	#
+	# The +output_literal+ convention:
+	# 
+	#   # A success:
+	#   puts 'Hello world!'    # prints: Hello world!
+	#   
+	#   # A failure:
+	#   puts 'Hello world!'    # prints: HelloWorld!
+	#
+	def output_literal
+	end
+
+	#
+	# The +error_literal+ convention:
+	# 
+	#   # A success specifying the class:
+	#   raise 'Boom!'  # raises: RuntimeError
+	#   
+	#   # A success specifying both the class and message:
+	#   raise 'Boom!'  # raises RuntimeError: Boom!
+	#   
+	#   # This will also succeed if the message is partial:
+	#   raise 'Undefined method "asd" for an object'
+	#   # raises RuntimeError: Undefined method "asd"
+	#
+	def error_literal
+	end
+
+	#
+	# An example won't stop if a failure is encountered:
+	# 
+	#   1 #=> 2
+	#   2 #=> 3
+	#   
+	# You will see both these failures.
+	# 
+	# Neither an error will stop it if there is an expectation:
+	# 
+	#   raise #=> nil    # expectation: the rest is supposed to be runned
+	#   true #=> false   # so this will be reported
+	#   raise            # nothing here -> the error is unexpected, so it terminates this example
+	#   1 #=> 4          # and this won't be executed and reported
+	#   
+	# However the execution will continue in this comment in other example:
+	# 
+	#   1 #=> 5          # this will be seen
+	#
+	def failures
+	end
+
+end

data/examples/minimal/lib/using_directives.rb

@@ -0,0 +1,66 @@
+
+#
+# Let's make things more intresting using some +directive+!
+#
+class UsingDirectives
+	
+	#
+	# Turn on/off RDX processing for examples:
+	# 
+	#   1 #=> 2   # seen
+	# \:rdx: off
+	# :rdx: off
+	#   1 #=> 2   # not seen
+	#   may contain anything!!!
+	# \:rdx: on
+	# :rdx: on
+	#   1 #=> 2   # seen again
+	#
+	def on_off
+	end
+	
+	#
+	# Specifies the output:
+	# 
+	#   puts 'Line 1', 'Line 2'
+	#   # other stuff...
+	#   true #=> true   # an expectation
+	#   puts 'Line 3'
+	# \:rdx: output
+	# :rdx: output
+	#   Line 1
+	#   Line 2
+	#   Line 3
+	#   Line 4 (missing)
+	#   
+	# It's also recognized in a text section that contains only <tt>produces:</tt>.
+	# This allow you to write the comments in this way:
+	# 
+	#   puts 'a'
+	#   puts 'b'
+	#   puts 'c'
+	#   
+	# produces:
+	# 
+	#   a
+	#   b
+	#   d
+	#   
+	# And you will see this in the report
+	#
+	def output
+	end
+	
+	# Simulates a bash session.
+	# This is recognized implicitly:
+	# 
+	#   $ cat > tty_file.rdx <<EOS
+	#   > Hello world!!!
+	#   > EOS
+	#   $ ls | grep "\.rdx$"
+	#   tty_file.rdx
+	#
+	def bash
+	end
+	
+end

data/examples/minimal/rakefile

@@ -0,0 +1,27 @@
+
+require 'rubygems'
+require 'rake'
+require 'rdoc/task'
+
+RDX_ROOT = "#{File.dirname File.dirname File.dirname __FILE__}/lib"
+$LOAD_PATH.unshift RDX_ROOT
+require 'rdx'
+
+rdoc_task = RDoc::Task.new do |rdoc|
+	rdoc.title = "RDX: minimal examples"
+	rdoc.rdoc_files.add 'lib/*.rb'
+end
+
+
+RDX::Task.new do |task|
+	task.rdoc_task = rdoc_task # Import options
+# Uncomment free:
+	#	task.files.exclude /directives/
+	#	task.debug = true
+	#	task.verbose = true
+	#	task.dry_run = true
+	#	task.doc_output = false
+	#	task.full_trace = true
+	#	task.reporter = 'essential'
+	#	task.show << :Success
+end

data/examples/ruby-2.0.0-p0/README

@@ -0,0 +1,7 @@
+
+Install RDX examples for Ruby 2.0.0-p0 with:
+
+  rake install
+
+This will generate two directories "core" and "stdlib".
+See more in their relative READMEs.

data/examples/ruby-2.0.0-p0/install/core/.rdx

@@ -0,0 +1,6 @@
+
+RDX::Specification.new do
+	use_convention :result_indicative
+	use_convention :result_inspect
+	use_convention :numeric_inspect
+end

data/examples/ruby-2.0.0-p0/install/core/README

@@ -0,0 +1,19 @@
+
+Directory structure:
+
+core
+  |- README (this file)
+  |
+  |- orig
+  |    + Original (Ruby 2.0.0p0) files (C sources and documentation ones)
+  |
+  |- patched
+  |    + Patched files (RDX works correctly on these)
+  | 
+  |- rakefile
+  |    Allows an easy interface for running RDX.
+  |    The most useful action is to run
+  |      rake rdx
+  |
+  +- .rdx
+       Contains the RDX::Specification

data/examples/ruby-2.0.0-p0/install/core/Rakefile

@@ -0,0 +1,61 @@
+
+require 'rubygems'
+require 'rake'
+require 'pathname'
+
+OLD = 'orig'
+NEW = 'patched'
+
+RDX_ROOT = Pathname(__FILE__).dirname.dirname.dirname.dirname + 'lib'
+$LOAD_PATH.unshift RDX_ROOT
+require 'rdx'
+
+
+require 'rdoc/task'
+rdoc_task = RDoc::Task.new do |rdoc|
+# Do not touch:
+	rdoc.options << "--root=#{NEW}"
+	rdoc.options << '--all'
+# Files to be parsed (will be passed to RDX):
+	# Base names of C source files:
+	%w[
+		*
+	].each{ |fname| rdoc.rdoc_files.add "#{NEW}/#{fname}.c" }
+	# Base names of documentation files:
+	%w[
+		*
+	].each{ |fname| rdoc.rdoc_files.add "#{NEW}/doc/**/#{fname}.rdoc" }
+	# Base names of C source files to exclude:
+	%w[
+		
+	].each{ |fname| rdoc.rdoc_files.exclude "#{NEW}/#{fname}.c" }
+# Insert what you want here:
+	rdoc.options << '--line-numbers' << '--tab-width=2'
+	rdoc.rdoc_dir = "rdoc"
+end
+
+
+RDX::Task.new do |task|
+# Do not touch:
+	task.name = :rdx_on_orig
+	task.description = 'Run RDX on the original core sources'
+	task.files.add OLD
+# This will show where troubles happen:
+	task.verbose = true
+end
+
+
+RDX::Task.new do |task|
+# Do not touch:
+	task.description = 'Run RDX on the patched core sources'
+	task.rdoc_task = rdoc_task
+	task.require_lib 'continuation'
+	task.require_lib 'fiber'
+# Uncomment free:
+	# task.debug = true
+	# task.verbose = true
+	# task.show << :Skip
+	# task.dry_run = true
+# Comment free:
+	task.doc_output = false
+end

data/examples/ruby-2.0.0-p0/install/core/diffs/array.c.diff

@@ -0,0 +1,166 @@
+--- core/orig/array.c	2015-06-11 07:51:44 +0000
++++ core/patched/array.c	2015-06-25 17:48:02 +0000
+@@ -571,6 +571,7 @@
+  *     Array.try_convert([1])   #=> [1]
+  *     Array.try_convert("1")   #=> nil
+  *
++ *  :rdx: off
+  *     if tmp = Array.try_convert(arg)
+  *       # the argument is an array
+  *     elsif tmp = String.try_convert(arg)
+@@ -1287,7 +1288,7 @@
+  *     a.fetch(-1)              #=> 44
+  *     a.fetch(4, 'cat')        #=> "cat"
+  *     a.fetch(100) { |i| puts "#{i} is out of bounds" }
+- *                              #=> "100 is out of bounds"
++ *                              # prints: 100 is out of bounds
+  */
+ 
+ static VALUE
+@@ -1571,16 +1572,16 @@
+  *  See also Array#push, and Array#unshift.
+  *
+  *     a = Array.new
+- *     a[4] = "4";                 #=> [nil, nil, nil, nil, "4"]
+- *     a[0, 3] = [ 'a', 'b', 'c' ] #=> ["a", "b", "c", nil, "4"]
+- *     a[1..2] = [ 1, 2 ]          #=> ["a", 1, 2, nil, "4"]
+- *     a[0, 2] = "?"               #=> ["?", 2, nil, "4"]
+- *     a[0..2] = "A"               #=> ["A", "4"]
+- *     a[-1]   = "Z"               #=> ["A", "Z"]
+- *     a[1..-1] = nil              #=> ["A", nil]
+- *     a[1..-1] = []               #=> ["A"]
+- *     a[0, 0] = [ 1, 2 ]          #=> [1, 2, "A"]
+- *     a[3, 0] = "B"               #=> [1, 2, "A", "B"]
++ *     a[4] = "4";                    a #=> [nil, nil, nil, nil, "4"]
++ *     a[0, 3] = [ 'a', 'b', 'c' ];   a #=> ["a", "b", "c", nil, "4"]
++ *     a[1..2] = [ 1, 2 ];            a #=> ["a", 1, 2, nil, "4"]
++ *     a[0, 2] = "?";                 a #=> ["?", 2, nil, "4"]
++ *     a[0..2] = "A";                 a #=> ["A", "4"]
++ *     a[-1]   = "Z";                 a #=> ["A", "Z"]
++ *     a[1..-1] = nil;                a #=> ["A", nil]
++ *     a[1..-1] = [];                 a #=> ["A"]
++ *     a[0, 0] = [ 1, 2 ];            a #=> [1, 2, "A"]
++ *     a[3, 0] = "B";                 a #=> [1, 2, "A", "B"]
+  */
+ 
+ static VALUE
+@@ -2422,7 +2423,7 @@
+  *
+  *     ary = [0, 4, 7, 10, 12]
+  *     # try to find v such that 4 <= v < 8
+- *     ary.bsearch {|x| 1 - x / 4 } #=> 4 or 7
++ *     ary.bsearch {|x| 1 - x / 4 } # -> 4 # may be 4 or 7
+  *     # try to find v such that 8 <= v < 10
+  *     ary.bsearch {|x| 4 - x / 2 } #=> nil
+  *
+@@ -3344,8 +3345,8 @@
+  *
+  *     [ 1, 2, 3 ] + [ 4, 5 ]    #=> [ 1, 2, 3, 4, 5 ]
+  *     a = [ "a", "b", "c" ]
+- *     a + [ "d", "e", "f" ]
+- *     a                         #=> [ "a", "b", "c", "d", "e", "f" ]
++ *     a + [ "d", "e", "f" ]     #=> [ "a", "b", "c", "d", "e", "f" ]
++ *     a                         #=> [ "a", "b", "c" ]
+  *
+  *  See also Array#concat.
+  */
+@@ -4325,11 +4326,11 @@
+  *  Returns a new array with elements of +self+ shuffled.
+  *
+  *     a = [ 1, 2, 3 ]           #=> [1, 2, 3]
+- *     a.shuffle                 #=> [2, 3, 1]
++ *     a.shuffle                 #-> [2, 3, 1]
+  *
+  *  The optional +rng+ argument will be used as the random number generator.
+  *
+- *     a.shuffle(random: Random.new(1))  #=> [1, 3, 2]
++ *     a.shuffle(random: Random.new(1))  #-> [1, 3, 2]
+  */
+ 
+ static VALUE
+@@ -4360,8 +4361,8 @@
+  *  The optional +rng+ argument will be used as the random number generator.
+  *
+  *     a = [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 ]
+- *     a.sample         #=> 7
+- *     a.sample(4)      #=> [6, 4, 2, 5]
++ *     a.sample         #-> 7
++ *     a.sample(4)      #-> [6, 4, 2, 5]
+  */
+ 
+ 
+@@ -4502,8 +4503,10 @@
+  *  If no block is given, an Enumerator is returned instead.
+  *
+  *     a = ["a", "b", "c"]
+- *     a.cycle { |x| puts x }     # print, a, b, c, a, b, c,.. forever.
+- *     a.cycle(2) { |x| puts x }  # print, a, b, c, a, b, c.
++ *  :rdx: off
++ *     a.cycle    { |x| print x }   # prints abcabcabc... forever
++ *  :rdx:
++ *     a.cycle(2) { |x| print x }   # prints abcabc
+  *
+  */
+ 
+@@ -5222,7 +5225,7 @@
+  *
+  *     ary = Array.new    #=> []
+  *     Array.new(3)       #=> [nil, nil, nil]
+- *     Array.new(3, true) #=> [0, 0, 0]
++ *     Array.new(3, true) #=> [true, true, true]
+  *
+  *  Note that the second argument populates the array with references to the
+  *  same object.  Therefore, it is only recommended in cases when you need to
+@@ -5242,8 +5245,8 @@
+  *
+  *  An array can also be created by using the Array() method, provided by
+  *  Kernel, which calls  #to_ary or #to_a on it's argument.
+- *
+- *	Array({:a => "a", :b => "b"}) #=> [[:a, "a"], [:b, "b"]]
++ *  
++ *     Array({:a => "a", :b => "b"}) #=> [[:a, "a"], [:b, "b"]]
+  *
+  *  == Example Usage
+  *
+@@ -5275,8 +5278,7 @@
+  *  To raise an error for indices outside of the array bounds or else to
+  *  provide a default value when that happens, you can use #fetch.
+  *
+- *     arr = ['a', 'b', 'c', 'd', 'e', 'f']
+- *     arr.fetch(100) #=> IndexError: index 100 outside of array bounds: -6...6
++ *     arr.fetch(100) # raises IndexError: index 100 outside of array bounds: -6...6
+  *     arr.fetch(100, "oops") #=> "oops"
+  *
+  *  The special methods #first and #last will return the first and last
+@@ -5353,7 +5355,8 @@
+  *  To delete a particular element anywhere in an array, use #delete:
+  *
+  *     arr = [1, 2, 2, 3]
+- *     arr.delete(2) #=> [1, 3]
++ *     arr.delete(2)       #=> 2
++ *     arr                 #=> [1, 3]
+  *
+  *  A useful method if you need to remove +nil+ values from an array is
+  *  #compact:
+@@ -5381,9 +5384,9 @@
+  *  Note that this operation leaves the array unchanged.
+  *
+  *     arr = [1, 2, 3, 4, 5]
+- *     arr.each { |a| print a -= 10, " " }
+- *     # prints: -9 -8 -7 -6 -5
+- *     #=> [1, 2, 3, 4, 5]
++ *     arr.each { |a| print a -= 10, " " } #=> arr
++ *  produces:
++ *     -9 -8 -7 -6 -5
+  *
+  *  Another sometimes useful iterator is #reverse_each which will iterate over
+  *  the elements in the array in reverse order.
+@@ -5413,7 +5416,7 @@
+  *
+  *     arr = [1, 2, 3, 4, 5, 6]
+  *     arr.select { |a| a > 3 }     #=> [4, 5, 6]
+- *     arr.reject { |a| a < 3 }     #=> [4, 5, 6]
++ *     arr.reject { |a| a < 3 }     #=> [3, 4, 5, 6]
+  *     arr.drop_while { |a| a < 4 } #=> [4, 5, 6]
+  *     arr                          #=> [1, 2, 3, 4, 5, 6]
+  *