rdx 0.9.0.pre → 0.9.0.pre.1

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

@@ -1,5 +1,5 @@
 --- core/orig/ruby.c	2015-06-11 07:51:44 +0000
-+++ core/patched/ruby.c	2015-06-20 08:17:17 +0000
++++ core/patched/ruby.c	2015-08-30 08:02:27 +0000
 @@ -1713,12 +1713,12 @@
  	/*
  	 * DATA is a File that contains the data section of the executed file.

data/examples/ruby-2.0.0-p0/install/stdlib/DOCUMENTATION

@@ -0,0 +1,22 @@
+
+Since examples are now treated as tests we can be much more descriptive - with the
+appropriate formalism - in the documentation; meanwhile this reduces the coupling with
+test files, which therefore become smaller. The result is a super-duper documentation
+without the troubles of refactoring comments and duplicated code!
+To prove this, let's consider for instance the following files (patched):
+
+* lib/set.rb
+  The documentation examples were almost missing (no blame!), so almost all the content
+  of the test file has been translated into them succesfully.
+
+* lib/matrix.rb
+  Here most documentation examples has been refactored, according to the RDX formalism:
+  with a simple global-accepted syntax we gain many unit tests for free.
+  Moreover additional examples have been imported from the test files, which can then
+  become much lighter (the examples now cover the vast majority of them).
+
+* lib/optparse.rb
+  It's in this file that the bash directive really shines,
+  since it allows to easily write acceptance tests.
+  The user can clearly see what's the result of a given action,
+  even without actually trying himself to run all those combinations!

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

@@ -2,18 +2,26 @@
 Directory structure:
 
 stdlib
+  |
   |- README (this file)
   |
   |- orig
-  |    + Original (Ruby 2.0.0p0) files (Ruby sources)
+  |    + Contains original (Ruby 2.0.0-p0) files (Ruby sources)
   |
   |- patched
-  |    + Patched files (RDX works correctly on these)
+  |    + Contains patched files (RDX works correctly on these)
   | 
   |- rakefile
   |    Allows an easy interface for running RDX.
-  |    The most useful action is to run
+  |    The most useful action is to run:
   |      rake rdx
+  |    You can also run RDX on the original files, but you'll encounter
+  |    troubles (nothing harmful, anyway). Just use:
+  |      rake rdx_on_orig
   |
   +- .rdx
-       Contains the RDX::Specification
+  |    Contains the RDX::Specification
+  |
+  +- DOCUMENTATION
+       Describes the benefits of an RDX-enhanced documentation, explaining the patches
+       to some files of the Ruby Standard Library

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

@@ -1,4 +1,10 @@
 
+current_ruby = "#{RUBY_VERSION}-p#{RUBY_PATCHLEVEL}"
+build_ruby   = '2.0.0-p0'
+unless current_ruby == build_ruby
+	raise "Run this example with Ruby #{build_ruby} (detected #{current_ruby})"
+end
+
 require 'rubygems'
 require 'rake'
 require 'pathname'
@@ -10,7 +16,6 @@ $LOAD_PATH.unshift RDX_ROOT
 require 'rdx'
 
 
-
 require 'rdoc/task'
 rdoc_task = RDoc::Task.new do |rdoc|
 	%w[
@@ -19,15 +24,14 @@ rdoc_task = RDoc::Task.new do |rdoc|
 	%w[
 		
 	].each{ |fname| rdoc.rdoc_files.exclude "#{NEW}/lib/**/#{fname}.rb" }
+	
 	rdoc.options << '--all' << '--line-numbers' << '--tab-width=2'
 	rdoc.options << "--root=#{NEW}"
 	rdoc.rdoc_dir = "rdoc"
 end
 
 
-
-RDX::Task.new do |task|
-	task.name = :rdx_on_orig
+RDX::Task.new :rdx_on_orig do |task|
 	task.description = 'Run RDX on the original stdlib sources'
 	task.files.add OLD
 	task.lib_dirs << "#{OLD}/lib"
@@ -48,6 +52,7 @@ RDX::Task.new do |task|
 	# task.debug = true
 	# task.verbose = true
 	# task.full_trace = true
-	# task.doc_output = false
+	task.doc_output = false
+	task.reporter = 'docquiet'
 	# task.dry_run = true
 end

data/examples/ruby-2.0.0-p0/install/stdlib/TODO

@@ -0,0 +1,6 @@
+
+For version 0.9.5.pre:
+* Support for building C extensions
+  * pathname
+  * strscan
+  * stringio

data/examples/ruby-2.0.0-p0/install/stdlib/diffs/lib/optparse.rb.diff

@@ -1,6 +1,6 @@
 --- stdlib/orig/lib/optparse.rb	2015-06-11 07:51:45 +0000
-+++ stdlib/patched/lib/optparse.rb	2015-06-11 07:51:48 +0000
-@@ -68,19 +68,35 @@
++++ stdlib/patched/lib/optparse.rb	2015-08-30 23:08:38 +0000
+@@ -68,19 +68,41 @@
  #
  # === Minimal example
  #
@@ -33,13 +33,19 @@
 +#   $ ruby example.rb -v
 +#   options = {:verbose=>true}
 +#   ARGV    = []
++#   $ ruby example.rb --verbose
++#   options = {:verbose=>true}
++#   ARGV    = []
 +#   $ ruby example.rb --no-verbose arg1
 +#   options = {:verbose=>false}
 +#   ARGV    = ["arg1"]
++#   $ ruby example.rb -- --no-verbose
++#   options = {}
++#   ARGV    = ["--no-verbose"]
  #
  # === Complete example
  #
-@@ -88,6 +104,8 @@
+@@ -88,6 +110,8 @@
  # effect of specifying various options.  This is probably the best way to learn
  # the features of +optparse+.
  #
@@ -48,7 +54,7 @@
  #   require 'optparse'
  #   require 'optparse/time'
  #   require 'ostruct'
-@@ -112,7 +130,7 @@
+@@ -112,7 +136,7 @@
  #       options.verbose = false
  #
  #       opt_parser = OptionParser.new do |opts|
@@ -57,7 +63,7 @@
  #
  #         opts.separator ""
  #         opts.separator "Specific options:"
-@@ -197,8 +215,37 @@
+@@ -197,8 +221,43 @@
  #   end  # class OptparseExample
  #
  #   options = OptparseExample.parse(ARGV)
@@ -90,13 +96,27 @@
 +#   Common options:
 +#       -h, --help                       Show this message
 +#           --version                    Show version
++#   $ ./example_app -ibak --delay 3.5 --irs=1 argument
++#   options = #<OpenStruct library=[], inplace=true, encoding="utf8", transfer_type=:auto, verbose=false, extension=".bak", delay=+3.5, record_separator=1>
++#   ARGV = ["argument"]
++#   $ ./example_app --list 1,2,str --type=binary -- -hypenated-arg regular-arg
++#   options = #<OpenStruct library=[], inplace=false, encoding="utf8", transfer_type=:binary, verbose=false, list=["1", "2", "str"]>
++#   ARGV = ["-hypenated-arg", "regular-arg"]
 +#   $ ./example_app -rset -vi --code=sjis an_argument another_argument
 +#   options = #<OpenStruct library=["set"], inplace=true, encoding="shift_jis", transfer_type=:auto, verbose=true, extension="">
 +#   ARGV = ["an_argument", "another_argument"]
  #
  # === Shell Completion
  #
-@@ -618,6 +665,7 @@
+@@ -221,7 +280,6 @@
+   RequiredArgument = [REQUIRED_ARGUMENT = :REQUIRED, true].freeze
+   OptionalArgument = [OPTIONAL_ARGUMENT = :OPTIONAL, false].freeze
+   # :startdoc:
+-
+   #
+   # Keyword completion module.  This allows partial arguments to be specified
+   # and resolved against a list of acceptable values.
+@@ -618,6 +676,7 @@
      # +long_opts+::   List of long style options.
      # +nolong_opts+:: List of long style options with "no-" prefix.
      #
@@ -104,7 +124,7 @@
      #   prepend(switch, short_opts, long_opts, nolong_opts)
      #
      def prepend(*args)
-@@ -634,6 +682,7 @@
+@@ -634,6 +693,7 @@
      # +long_opts+::   List of long style options.
      # +nolong_opts+:: List of long style options with "no-" prefix.
      #
@@ -112,7 +132,7 @@
      #   append(switch, short_opts, long_opts, nolong_opts)
      #
      def append(*args)
-@@ -913,6 +962,7 @@
+@@ -913,6 +973,7 @@
    # +t+::   Argument class specifier, any object including Class.
    # +pat+:: Pattern for argument, defaults to +t+ if it responds to match.
    #
@@ -120,7 +140,7 @@
    #   accept(t, pat, &block)
    #
    def accept(*args, &blk) top.accept(*args, &blk) end
-@@ -925,7 +975,7 @@
+@@ -925,7 +986,7 @@
    # Directs to reject specified class argument.
    #
    # +t+:: Argument class specifier, any object including Class.
@@ -129,7 +149,7 @@
    #   reject(t)
    #
    def reject(*args, &blk) top.reject(*args, &blk) end
-@@ -1097,6 +1147,7 @@
+@@ -1097,6 +1158,7 @@
    #
    # Creates an OptionParser::Switch from the parameters. The parsed argument
    # value is passed to the given block, where it can be processed.
@@ -137,7 +157,7 @@
    #
    # See at the beginning of OptionParser for some full examples.
    #
-@@ -1896,6 +1947,7 @@
+@@ -1896,6 +1958,7 @@
      #
      # Substitution of getopts is possible as follows. Also see
      # OptionParser#getopts.

data/examples/ruby-2.0.0-p0/install/stdlib/diffs/lib/uri/common.rb.diff

@@ -1,5 +1,5 @@
 --- stdlib/orig/lib/uri/common.rb	2015-06-11 07:51:45 +0000
-+++ stdlib/patched/lib/uri/common.rb	2015-06-25 17:34:52 +0000
++++ stdlib/patched/lib/uri/common.rb	2015-08-31 16:14:33 +0000
 @@ -67,6 +67,7 @@
      #
      # == Synopsis
@@ -152,12 +152,13 @@
    #   URI::join(str[, str, ...])
    #
    # == Args
-@@ -765,20 +771,20 @@
+@@ -765,20 +771,21 @@
    #
    #   require 'uri'
    #
 -  #   p URI.join("http://example.com/","main.rbx")
 -  #   # => #<URI::HTTP:0x2022ac02 URL:http://localhost/main.rbx>
++  # :rdx: # Epic Fail!
 +  #   URI.join("http://example.com/","main.rbx")
 +  #   # > #<URI::HTTP:0x2022ac02 URL:http://example.com/main.rbx>
    #
@@ -183,7 +184,7 @@
    #
    #
    def self.join(*str)
-@@ -788,6 +794,7 @@
+@@ -788,6 +795,7 @@
    #
    # == Synopsis
    #
@@ -191,7 +192,7 @@
    #   URI::extract(str[, schemes][,&blk])
    #
    # == Args
-@@ -807,7 +814,7 @@
+@@ -807,7 +815,7 @@
    #   require "uri"
    #
    #   URI.extract("text here http://foo.example.org/bla and here mailto:test@example.com and here also.")
@@ -200,7 +201,7 @@
    #
    def self.extract(str, schemes = nil, &block)
      DEFAULT_PARSER.extract(str, schemes, &block)
-@@ -816,6 +823,7 @@
+@@ -816,6 +824,7 @@
    #
    # == Synopsis
    #
@@ -208,7 +209,7 @@
    #   URI::regexp([match_schemes])
    #
    # == Args
-@@ -831,6 +839,7 @@
+@@ -831,6 +840,7 @@
    #
    # == Usage
    #
@@ -216,7 +217,7 @@
    #   require 'uri'
    #
    #   # extract first URI from html_string
-@@ -961,12 +970,12 @@
+@@ -961,12 +971,12 @@
    #
    # This refers http://www.w3.org/TR/html5/forms.html#url-encoded-form-data
    #

data/examples/ruby-2.0.0-p0/install/stdlib/diffs/lib/weakref.rb.diff

@@ -1,5 +1,5 @@
 --- stdlib/orig/lib/weakref.rb	2015-06-11 07:51:45 +0000
-+++ stdlib/patched/lib/weakref.rb	2015-06-27 15:19:00 +0000
++++ stdlib/patched/lib/weakref.rb	2015-08-30 20:19:22 +0000
 @@ -8,11 +8,12 @@
  # Usage:
  #
@@ -21,7 +21,7 @@
  #   c['qux'] = omg
  #   puts c.inspect
 -#   #=> {"foo"=>"bar", "baz"=>#<Object:0x007f4ddfc6cb48>, "qux"=>"lol"}
-+#   # prints: {"foo"=>"bar", "baz"=>#<Object:0x00000003599888>, "qux"=>"lol"}
++#   # prints: {"foo"=>"bar", "baz"=>#<Object:0x007f4ddfc6cb48>, "qux"=>"lol"}
  #
  #   # Now run the garbage collector
  #   GC.start

data/lib/rdx.rb

@@ -1,106 +1,54 @@
+
+# :main: README
+
 #
-# = RDX: Ruby Documentation example eXecutor
-# 
-# The aim of RDX is to join the worlds of documentation and testing, whose overlap in examples.
-# Relying on the RDoc documentation generator tool and Minitest RDX parses source files,
-# generates documentation, extracts examples from comments and executes them as tests.
-# 
-# == Why RDX?
-# 
-# The whole application is built on these four cornerstones:
-# * Document Well and Right!
-# 
-#   The library should be well documented. The examples can be the most direct way
-#   to explain and show the use of the library - if these have been unit tested and work fine.
-# * DRY (Don't Repeat Yourself)!
-# 
-#   We want to avoid - honestly, we should hate - writing the same things more than once.
-#   It's too tedious to translate back and forth all the examples between documentation and testing.
-# * Join coupled parts!
-# 
-#   Source, documentation and tests are different sides of the same thing - the programmer's idea -.
-#   When some parts are tightly coupled, the more these are close the more straightforward the eventual
-#   fix is. Documentation tools unify documentation with the source, RDX tries to take the next step.
-# * Be Consistent!
-# 
-#   Most scripts of the Ruby Core and many of the Standard Library already have the examples
-#   written in a conformed and accepted way. It was this coherency that allowed (and induced)
-#   me to write RDX: a tool can easily automate tasks if they fit well into a general scheme.
-#   
-# == How RDX works
-# 
-# In order to achieve its goal it first deals with the documentation tool
-# (RDoc is the most commonly used, so currently only its support is built-in) asking to keep
-# track of examples. These are parsed and subdivided into statements: the comment at
-# their end can eventually become an expectation. The tests are build according to
-# conventions and directives.
-# 
-# The *conventions*, heart of RDX, define the rules to accept the ending comments and process the code
-# (for example the historical hash-rocket notation, <tt>#=></tt>, is implemented in Convention::result_eval:
-# it evaluates both the statement and the expectation, then compares those results through +assert_equal+).
-# See more details in the RDX::Convention class.
-# 
-# While conventions affect single statements, the *directives* operate on a larger scale.
-# 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,
+# 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...
-# See the RDX::Directive class for more information about them.
-# 
-# Both the conventions and directives can be either built-in because of their popularity in the
-# Ruby Community or defined for convenience by the user.
-# 
-# Once these tests are built, the only thing left to do is to simply run them.
-# As a bonus, if everything is correct, RDX's signature is added to those made by the generator
-# tool: the user of our library now can know that the examples showed enjoy a high level of trust.
-# All this with a single run, either from the command line or through rake.
-# 
-# == Conclusions
-# 
-# When RDX has finished we can see the report of our tests, as if we had manually written all of
-# them refactoring the comments. In fact, it's even better: if an example has something wrong - if it
-# doesn't work as declared - the error points us to its location in the comment, which is just above
-# the source code. This makes the tracking and fixing steps inceadibly easy.
-# 
-# Through execution, <b>RDX gives formalism to the documentation examples</b>,
-# greatly increasing their strength. It gives all the section of a source file the deserved emphasis,
-# transforming fictitious examples into living ones!
-# 
-# A great point in its favour is that a developer familiar with the Ruby documentation
-# (of course most of them) doesn't have to learn a new DSL or syntax, but just
-# to code and document in the "standard" way, with very few alteration.
 #
-# == Security
-# 
-# The point that +RDX+ evaluates the comments leads to the topic of security.
-# Never run blindly RDX on libraries that haven't been written for that, since it's never
-# a good idea to evaluate unknown code.
-# If you want, fisrt you have to scan the files and find the examples
-# (the <tt>--dry-run</tt> option may help you, though it isn't fully secure).
-# Once you have found that the code is safe you can give RDX a try.
-# 
-# However, if a library has been built RDX-compatible, you can run it
-# from your machine - if you _trust_ the producer. If you don't
-# you must be very careful: even a plain +require+ can be dangerous,
-# with RDX you have to pay an extra attention to the comments.
+# 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.
 #
 # == Roadmap
 #
-# We have already talked about conventions, directives and their relative classes.
-# These are probably the most intresting topics.
-# 
-# If you want to define your own conventions and directives, see the Specification.
-# 
-# If you want to know the available command line options, see Options.
+# The conventions and directives are probably the most interesting topics;
+# check out their relative classes (RDX::Convention and RDX::Directive)
+# to discover their details.
 # 
-# If you want to run RDX through +rake+, see Task.
+# To define your own conventions and directives, see the RDX::Specification.
+#
+# To discover how RDX interacts with +RDoc+ (and the new features brought) see ::RDoc.
+#
+# RDX relies also on the +Minitest+'s assertions: RDX::Assertion shapes these ones to RDX's needs,
+# defining some new assertions.
+#
+# If you want to know the available command line options, see RDX::Options.
+#
+# If you want to run RDX through +rake+, see RDX::Task.
+#
+# To enhance text processing the RDX::Text module provides new useful functions,
+# while RDX::RubyLex allows to process Ruby code.
+#
+# To dig into RDX's internals and discover how RDX organizes the data obtained
+# parsing the files see the RDX::CodeObject class and its descendants.
 # 
-# The role of other classes is explained in these sections.
+# The role of other classes is eventually explained in these sections.
 #
 # == Credits
 #
-# I have ideated RDX and I am developing it. <br>
-# I think this is the best way I have to thank Yukihiro "Matz" Matsumoto
-# for the beatiful language he has designed.
+# I have designed RDX and I am developing it. <br>
+# I think this is the best way I have to thank first Yukihiro "Matz" Matsumoto,
+# for the beautiful language he has developed, and then the Ruby Community for all the work done.
 # 
 # Maurizio Destefanis
 #
@@ -114,6 +62,8 @@ module RDX
 	
 	ROOT = File.dirname(__FILE__).freeze
 	
+	BIN_PATH = File.join(File.dirname(ROOT),'bin','rdx').freeze
+	
 	require 'rdx/version'
 	
 	VERSION_HEADER = "RDX version: #{VERSION}".freeze