The mechanically verified Ruby 1.9 changelog

As you probably know, I have been maintaining a list of the differences between Ruby 1.8 and 1.9 for the last two years, summarizing over 50000 lines of changelogs. Ruby 1.9 is to be released real soon now, so it was about time to update it once again.

Since new features come and go constantly, keeping the list up-to-date requires a lot of work: I have to verify that old entries still apply to the latest builds, and correct or remove those that no longer do. The accumulated amount of work increases quadratically with the number of features, so to speak. This is why I've invested several hours to convert the changelog to a format that can be verified mechanically.

The new changelog is a Ruby program that annotates the examples, formats the descriptions and verifies that the entries are still relevant. The code can be found at http://eigenclass.org/repos/ruby-changelog. At some point, I can imagine something like this being included in Ruby's sources.

Each entry encapsulates a description, one or more snippets to be annotated (evaluated under Ruby 1.8, 1.9 or both), and optional assertions that verify that the documentation matches the actual behavior.

Some examples

   new_syntax("Block local variables", :dst_code => <<-CODE, :text => <<-TXT)
     d = 2
     a = lambda{|;d| d = 1}
     a.call()
     d		# => 
   CODE
     You can declare block local variables with this syntax: 
       {|normal args; local variables| ...}
     When a variable is shadowed, ruby1.9 issues a warning.
   TXT

   new_semantics("Block arguments are always local", :code => <<-CODE) do |c|
     a = 1
     10.times{|a| }
     p a
   CODE
     assert_equal(1, dst_eval(c))
     assert_equal(9, src_eval(c))
   end

When you execute the changelog, the above entries are turned into this:

Block local variables

You can declare block local variables with this syntax:

 {|normal args; local variables| ...}

When a variable is shadowed, ruby1.9 issues a warning.

ruby 1.9.0

 d = 2
 a = lambda{|;d| d = 1} # !> shadowing outer local variable - d
 a.call()
 d                # => 2

Block arguments are always local

ruby 1.9.0

 a = 1
 10.times{|a| } # !> shadowing outer local variable - a
 a
 # >> 1

ruby 1.8.6

 a = 1
 10.times{|a| }
 a 
 # >> 9

Very cool idea - Dr Nic (2007-12-25 (Tue) 00:17:43)

Also, it never occurred to me you could piggy back the string expressions <<-EXPR...EXPR on a single line.

grant 2008-03-28 (Fri) 23:31:31

No, no - you're thinking of perl.

# !> syntax - Adam Salter (2008-02-11 (Mon) 22:54:16)

Could the # => documentation syntax be used for 'spec' like testing as well? You could parse the code and do your tests from within the code. it seems to me it would be great to get all of this kind of stuff in one place... documentation, testing etc... Maybe this is already happening... I'm no ruby hacker, just a user ;)