rdx 0.9.0.pre → 0.9.0.pre.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4829fee222c87078e0a61f49a92e3fa8aeb72508
-  data.tar.gz: 721963819a469824512101cdcb6cd38e82cf1883
+  metadata.gz: 7347a46f1423d751c02d5ad1900d302a56c492fd
+  data.tar.gz: ff1cbc6b9ac0a22511e97eb24f9986cff917d02c
 SHA512:
-  metadata.gz: 879dd564e894198bbd70538468e374c3e8252765355a5b2de018897dd47a0cd7230da6d8dbfc3d0bb255bca6fd73ccd9bf9f39f25d0484c28a0b07c6be5673ee
-  data.tar.gz: 3b5ee5fb739942e3119e06bf6d31d6ca6df28c1831e70134e9d83adf57626958946c36cb2493f47ae55de9be56967d158a65014baa0ce48512a80275c8abf3f1
+  metadata.gz: 2fd1a4d3fac453eeb3dfad2dd865bde63b881e59e9d5f6fb27ef672d6ad2fd6173407bd8d95e643d10870f07e4f83465817eafec3a550e24df305873797ca09e
+  data.tar.gz: b7e9ee5856ddf5a190732f93a369fe65e885f29748cc0002d887edb7034c24447b32e7c263b58483462c8e52a948d81fe9ffcf7692ca385d26502677cd98ddea

data/README

@@ -1,19 +1,193 @@
 
 = RDX: Ruby Documentation example eXecutor
+:rdx: off
+
+== Synopsis
 
 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.
+Relying on RDoc 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!<br>
+  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)!<br>
+  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!<br>
+  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 aims to the next step.
+
+* Be Consistent!<br>
+  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 RDX::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,
+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.
+
+== Running RDX
+
+RDX comes with an executable. When installed, try
+  $ rdx --help
+to have a summary of the available options.
+More details are explained in the RDX::Options class.
+
+To process all the source files in the whole current directory tree use
+  $ rdx .
+If you forget to specify any file, the dry-run mode is turned on for security
+(see the Security section).
+
+To run RDX programmatically, use:
+  gem 'rdx'
+  require 'rdx'
+  RDX.run(argv)
+where _argv_ is the array of command-line arguments.
+
+Currently however it's much better to run RDX through rake:
+simply define the +rdx+ task in the rakefile.
+The RDX::Task class allows you to do exactly this;
+start from the rakefiles in the +examples+ subdirectories.
+
+== Using RDX
+
+What follows is a basic illustration of RDX.
+Given this source ruby file
+
+  # File: lib/try_rdx.rb
+
+  # Contains various stuff
+  module Util
+  module_function
+
+    # Always returns +true+
+    #   Util.return_true #=> true
+    def return_true
+      return false # LIBRARY BUG!
+    end
+
+    # Outputs the Fixnum <tt>5</tt>
+    #   Util.print_five # prints: 5
+    #   # DOCUMENTATION BUG (line above)!
+    def print_five
+      print "five"
+    end
+
+    # This raises a +RuntimeError+
+    #   Util.bang! # raises RuntimeError: Boom!
+    #   # All right here...
+    def bang!
+      raise "Boom!"
+    end
+
+  end
+  
+you can run RDX (if installed) from the shell with
+
+  $ rdx -I lib -r try_rdx lib/try_rdx.rb
+
+This will show two errors in the report,
+along with the relative file name and line number location.
+
+The only purpose here is to clearly show how to write the source files,
+even if this leads to a very little, dumb example.
+For more serious examples, see the +examples+ subdirectories:
+* <tt>minimal</tt>: contains still dumb examples,
+  but aims to illustrate the most common features of RDX;
+* <tt>ruby-2.0.0-p0</tt>: try RDX on Ruby itself!
+  Once installed (just follow the README), you'll have the possibility
+  to run RDX on both the Core and the Standard Library.
+  The source files get patched so that RDX should work fine on these
+  (you can anyway run RDX on the original files).
+  These examples are clearly the most useful and realistic ones:
+  the whole RDX application has been built relying on these files.
+
+== The results
+
+When RDX has finished we can see the report of our tests, as if we had manually written all of
+them transforming 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 incredibly 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.
+
+At the end, RDX allows to easily reach the following goals:
+* Found library bugs;
+* Avoid dumb errors in documentation examples;
+* Have a complete documentation that's also very easy to maintain.
+If you have installed the Ruby examples (see examples/ruby-2.0.0-p0/README),
+you can see that these targets have been easily achieved.
+The respective results are reported in these file:
+* <tt>examples/ruby-2.0.0-p0/core/BUGS</tt>
+* <tt>examples/ruby-2.0.0-p0/core/HALL_OF_SHAME</tt>
+* <tt>examples/ruby-2.0.0-p0/stdlib/DOCUMENTATION</tt>
+
+If you find these points helpful, then RDX is for you!
+
+== 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, first you have to scan the files and find the examples.
+The <tt>--dry-run</tt> option (see RDX::Options#dry_run) may help you:
+it protects you from accidental dangerous example, but keep in mind that
+this mode still process RDX directives. A security hole can occur
+if one of these has been written with malicious intentions...
+Once you have found that the code is safe you can give RDX a try.
 
-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).
+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.
 
-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...
+== Common gotchas
 
-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.
+Since the rdx library patches the documentation generator tool,
+it's highly recommend to use +rake+. This because the original
+executable of the generator tool (say, +rdoc+) remains unaffected:
+therefore producing documentation from the command line will lead to
+a slightly different output, that doesn't consider the RDX patch.
+In conclusion, just run
+  $ rake rdoc
+instead of the simpler
+  $ rdoc
+(this is also true for documenting RDX itself).

data/TODO

@@ -0,0 +1,18 @@
+
+Targets to be achieved for the corresponding version:
+
+Step 1) version 0.9.5.pre
+* Finish the source patches, in order to have a complete view
+  on all the potential useful features to be included in RDX
+  (see TODOs in examples/ruby-2.0.0-p0/core and examples/ruby-2.0.0-p0/stdlib)
+
+Step 2) version 0.9.5
+* Write serious tests (at this point I think the internal will be quite stable)
+
+GOAL) version 1.0
+* Release the requirement RDoc::VERSION == 4.0
+* Improve general interface
+
+Successive steps) Future enhancements
+* Add support for YARD
+* Allow backward compatibility for Ruby (perhaps)

data/examples/minimal/.rdx

@@ -3,6 +3,7 @@ RDX::Specification.new do
 	use_convention :result_indicative
 	use_convention :result_inspect
 	use_convention :numeric_inspect
+#	use_convention :result_equal
 	use_convention :output_eval
 	use_convention :error_eval
 end

data/examples/minimal/rakefile

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

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

@@ -0,0 +1,70 @@
+
+RDX can help you find out (and therefore fix) some bugs in the library.
+To prove this, what follows is a collection of the bugs found thanks to examples
+(these bugs can be shown in the report):
+
+
+General bugs:
+
+* In Encoding.find (file encoding.c, line 1072):
+  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
+
+* In Complex.new (file complex.c, line 2082):
+  A complex object is either an exact or an inexact number.
+    Complex(1, 1) / 2    # > ((1/2)+(1/2)*i)
+  :rdx: bug   the result is again ((1/2)+(1/2)*i)
+    Complex(1, 1) / 2.0  # > (0.5+0.5i)
+
+* In Rational.new (file rational.c, line 2422):
+  However, when an expression has inexact factor (numerical value or
+  operation), will produce an inexact result.
+    Rational(10) / 3   #=> 10/3
+  :rdx: bug   the result is again 10/3
+    Rational(10) / 3.0 #=> 3.3333333333333335
+
+
+Platform-specific bugs:
+
+* In File::Stat#nlink (file file.c, line 481):
+  Returns the number of hard links to <i>stat</i>.
+    File.stat("testfile").nlink             #=> 1
+    File.link("testfile", "testfile.bak")   #=> 0
+  :rdx: bug   on x64-mingw32 I obtained 1
+    File.stat("testfile").nlink             #=> 2
+
+* In ObjectSpace (file gc.c, line 4449):
+  ObjectSpace also provides support for object finalizers, procs that will be
+  called when a specific object is about to be destroyed by garbage
+  collection.
+  :rdx: bug   on x64-mingw32 seems that the last object defined (c) isn't garbaged in this cycle...
+  :rdx: indicative_numbers
+    include ObjectSpace
+    a = "A"
+    b = "B"
+    c = "C" 
+    define_finalizer(a, proc {|id| puts "Finalizer one on #{id}" })
+    define_finalizer(b, proc {|id| puts "Finalizer two on #{id}" })
+    define_finalizer(c, proc {|id| puts "Finalizer three on #{id}" })
+    a = b = c = nil; # Now those strings are no more referenced,
+                     # but still alive until the next GC cycle...
+    GC.start # Garbage unreferenced objects now
+  <em>produces (your numbers may vary):</em>
+  :rdx: output
+    Finalizer one on 537763480
+    Finalizer two on 537763460
+    Finalzer three on 537763440
+
+* In documentation (file doc/syntax/calling_methods.rdoc, line 303):
+  If the method definition uses <code>**</code> to gather arbitrary keyword
+  arguments they will not be gathered by <code>*</code>:
+  :rdx: bug   on x64-mingw32 (but not on i386-mingw32) "3"=>4 is not captured by keywords
+    def my_method(*a, **kw)
+      p arguments: a, keywords: kw
+    end
+    my_method(1, 2, '3' => 4, five: 6)
+  Produces:
+    {:arguments=>[1, 2], :keywords=>{"3"=>4, :five=>6}}

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

@@ -0,0 +1,53 @@
+
+RDX can avoid commit errors in documentation examples.
+To prove this, what follows is a collection of the best (worst) mistakes.
+
+
+#7 - In Proc#arity:
+Returns the number of arguments that would not be ignored.
+[...]
+  proc { |x=0, y| }.arity #=> 0            # Epic Fail! (file proc.c, line 652)
+
+
+#6 - In Array.new:
+[...]
+An array can also be created by explicitly calling Array.new with zero, one
+(the initial size of the Array) or two arguments (the initial size and a
+default object).
+[...]
+  Array.new(3, true) #=> [0, 0, 0]         # Epic Fail! (file array.c, line 5225)
+
+
+#5 - In Rational#-:
+Performs subtraction.
+[...]
+  Rational(9, 8) - 4 #=> (23/8)            # Epic Fail! (file rational.c, line 752)
+
+
+#4 - In Hash.new:
+[...]
+Or by using the #default= method:
+  grades = {"Timmy Doe" => 8}
+  grades.default = 0
+Accessing a value in a Hash requires using its key:
+  puts grades["Jane Doe"] # => 10          # Epic Fail! (file hash.c, line 3350)
+
+
+#3 - In Kernel#Hash:
+Converts <i>arg</i> to a <code>Hash</code> by calling
+<i>arg</i><code>.to_hash</code>. Returns an empty <code>Hash</code> when
+<i>arg</i> is <tt>nil</tt> or <tt>[]</tt>.
+  Hash([])  #=> {}
+  Hash(nil) #=> nil                        # Epic Fail! (file object.c, line 2787)
+
+
+#2 - In Rational#floor:
+Returns the truncated value (toward negative infinity).
+[...]
+  Rational(-3, 2).floor  #=> -1            # Epic Fail! (file rational.c, line 1284)
+
+
+#1 - In Rational#+:
+Performs addition.
+[...]
+  Rational(900) + Rational(1) #=> 900/1    # Epic Fail! (file rational.c, line 710)

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

@@ -2,18 +2,28 @@
 Directory structure:
 
 core
+  |
   |- README (this file)
   |
   |- orig
-  |    + Original (Ruby 2.0.0p0) files (C sources and documentation ones)
+  |    + Contains original (Ruby 2.0.0-p0) files (C sources and documentation ones)
   |
   |- 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
+  |
+  +- BUGS
+  |    Contains the list of bugs in the Ruby interpreter found thanks to RDX
+  |  
+  +- HALL_OF_SHAME
+       Contains the list of most relevant mistakes in documentation examples found thanks to RDX

data/examples/ruby-2.0.0-p0/install/core/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'
@@ -35,10 +41,9 @@ rdoc_task = RDoc::Task.new do |rdoc|
 end
 
 
-RDX::Task.new do |task|
-# Do not touch:
-	task.name = :rdx_on_orig
+RDX::Task.new :rdx_on_orig do |task|
 	task.description = 'Run RDX on the original core sources'
+# Do not touch:
 	task.files.add OLD
 # This will show where troubles happen:
 	task.verbose = true
@@ -46,8 +51,8 @@ end
 
 
 RDX::Task.new do |task|
-# Do not touch:
 	task.description = 'Run RDX on the patched core sources'
+# Do not touch:
 	task.rdoc_task = rdoc_task
 	task.require_lib 'continuation'
 	task.require_lib 'fiber'