dfect 2.0.0 → 2.1.0

data/HISTORY

@@ -3,6 +3,27 @@
 %#          opening ./doc/index.html in your favorite Web browser.          #%
 %#                                                                          #%
 
+%#----------------------------------------------------------------------------
+%| section "Version 2.1.0 (2010-03-31)"
+%#----------------------------------------------------------------------------
+
+  This release adds a <%= xref "Shell command", "command-line test runner" %>
+  and performs some minor housekeeping.
+
+  %#--------------------------------------------------------------------------
+  %| paragraph "New features"
+  %#--------------------------------------------------------------------------
+
+    * Add `bin/dfect` executable as command-line interface to this library.
+
+  %#--------------------------------------------------------------------------
+  %| paragraph "Housekeeping"
+  %#--------------------------------------------------------------------------
+
+    * Do not `require 'rubygems'` before loading the "ruby-debug" library.
+
+    * Upgrade to Inochi 2.0.0-rc2 for managing this project.
+
 %#----------------------------------------------------------------------------
 %| section "Version 2.0.0 (2010-03-21)"
 %#----------------------------------------------------------------------------
@@ -96,7 +117,7 @@
   %| paragraph "Housekeeping"
   %#--------------------------------------------------------------------------
 
-    * Upgrade to Inochi 2.0.0 for managing this project.
+    * Upgrade to Inochi 2.0.0-rc1 for managing this project.
 
     * Make emulation libraries modify Dfect module instead of Kernel.
 
@@ -237,9 +258,9 @@
   %| paragraph "New features"
   %#--------------------------------------------------------------------------
 
-      * Added <%= xref "Negation", "negation (m!)" %> and <%=
-        xref "Sampling", "sampling (m?)" %> variations to <%=
-        xref "Assertions", "assertion methods" %>.
+    * Added <%= xref "Negation", "negation (m!)" %> and <%=
+      xref "Sampling", "sampling (m?)" %> variations to <%=
+      xref "Assertions", "assertion methods" %>.
 
       These new methods implement assertion functionality missing so far
       (previously we could not assert that a given exception was NOT thrown)

data/MANUAL

@@ -0,0 +1,23 @@
+%#                                                                          #%
+%#             You can read this document in its full glory by              #%
+%#          opening ./doc/index.html in your favorite Web browser.          #%
+%#                                                                          #%
+
+% api_reference_url = 'api/index.html'
+% api_reference     = "[API reference](#{api_reference_url})"
+% source_code_tool  = '[Git](http://git-scm.com)'
+% source_code_url   = 'http://github.com/sunaku/dfect'
+% issue_tracker_url = 'http://github.com/sunaku/dfect/issues'
+
+%|part "Welcome"
+  %+ "README"
+
+%|part "Setup"
+  %+ "INSTALL"
+
+%|part "Usage"
+  %+ "USAGE"
+
+%|part "History"
+  %|project_history
+    %+ "HISTORY"

data/USAGE

@@ -3,134 +3,74 @@
 %#          opening ./doc/index.html in your favorite Web browser.          #%
 %#                                                                          #%
 
-% def example_dfect_test *example_node_args, &block_containing_code_to_run
-  % code_to_run = __block_content__(&block_containing_code_to_run).join
-  % code_to_run.insert 0, "require 'dfect/auto'\n\n"
+%#----------------------------------------------------------------------------
+%| section "Shell command"
+%#----------------------------------------------------------------------------
 
-  %|example! *example_node_args
-    When the following test is run:
+  %|command! "dfect --help" do |node|
+    %|text
+      %= verbatim `ruby bin/#{node.title}`
 
-    <%
-      code :ruby do
-        code_to_run
-      end
-    %>
+%#----------------------------------------------------------------------------
+%| section "Ruby library"
+%#----------------------------------------------------------------------------
+
+  % def example_dfect_test *example_node_args, &block_containing_code_to_run
+    % code_to_run = __block_content__(&block_containing_code_to_run).join
+    % code_to_run.insert 0, "require 'dfect/auto'\n\n"
 
-    Dfect will output the following:
+    %|example! *example_node_args
+      When the following test is run:
 
-    <%
-      text do
-        IO.popen('ruby -Ilib 2>&1', 'w+') do |ruby|
-          ruby.write code_to_run
-          ruby.close_write
-          ruby.read
+      <%
+        code :ruby do
+          code_to_run
         end
-      end
-    %>
+      %>
 
-Begin by loading Dfect into your program:
+      Dfect will output the following:
 
-%|code :ruby
-  require 'rubygems' # only necessary if you are using Ruby 1.8
-  require 'dfect'
+      <%
+        text do
+          IO.popen('ruby -Ilib 2>&1', 'w+') do |ruby|
+            ruby.write code_to_run
+            ruby.close_write
+            ruby.read
+          end
+        end
+      %>
 
-You now have access to the `Dfect` module, which provides methods that can be
-either mixed-in or called directly, according to your preference:
+  Begin by loading Dfect into your program:
 
-%|code :ruby
-  Dfect.D "hello" do  # D() is a class method
-    puts "world"
-  end
+  %|code :ruby
+    require 'rubygems' # only necessary if you are using Ruby 1.8
+    require 'dfect'
 
-  # the above is same as:
+  You now have access to the `Dfect` module, which provides methods that can
+  be either mixed-in or called directly, according to your preference:
 
-  include Dfect       # mix-in the Dfect API
+  %|code :ruby
+    Dfect.D "hello" do  # D() is a class method
+      puts "world"
+    end
 
-  D "hello" do        # D() is an instance method
-    puts "world"
-  end
+    # the above is same as:
 
-%#----------------------------------------------------------------------------
-%| section "Assertions"
-%#----------------------------------------------------------------------------
+    include Dfect       # mix-in the Dfect API
 
-  The following methods accept a block parameter and assert something about
-  the result of executing that block.  They also accept an optional message,
-  which is shown in <%= xref "Failures", "failure reports" %> if they fail.
-
-  See the <%= api_reference %> for more details and examples.
-
-  %|table
-    %|thead
-      %|tr
-        %|th
-          Method
-        %|th
-          Description
-    %|tbody
-      %|tr
-        %|td
-          T
-        %|td
-          assert true (not `nil` and not `false`)
-      %|tr
-        %|td
-          F
-        %|td
-          assert not true (`nil` or `false`)
-      %|tr
-        %|td
-          E
-        %|td
-          assert that an execption is raised
-      %|tr
-        %|td
-          C
-        %|td
-          assert that a symbol is thrown
+    D "hello" do        # D() is an instance method
+      puts "world"
+    end
 
   %#--------------------------------------------------------------------------
-  %| section "Negation"
+  %| section "Assertions"
   %#--------------------------------------------------------------------------
 
-    These methods are the *opposite* of
-    <%= xref "Assertions", "normal assertions" %>.
-
-    %|table
-      %|thead
-        %|tr
-          %|th
-            Method
-          %|th
-            Description
-      %|tbody
-        %|tr
-          %|td
-            T!
-          %|td
-            same as F
-        %|tr
-          %|td
-            F!
-          %|td
-            same as T
-        %|tr
-          %|td
-            E!
-          %|td
-            assert that an exception is *not* raised
-        %|tr
-          %|td
-            C!
-          %|td
-            assert that a symbol is *not* thrown
-
-  %#--------------------------------------------------------------------------
-  %| section "Sampling"
-  %#--------------------------------------------------------------------------
+    The following methods accept a block parameter and assert something about
+    the result of executing that block.  They also accept an optional message,
+    which is shown in <%= xref "Failures", "failure reports" %> if they fail.
 
-    These methods allow you to *check the outcome* of an assertion without
-    recording a success or failure for that assertion in the execution report.
+    See the <%= api_reference %> for more details and examples.
 
     %|table
       %|thead
@@ -142,252 +82,325 @@ either mixed-in or called directly, according to your preference:
       %|tbody
         %|tr
           %|td
-            T?
+            T
           %|td
-            returns `true` if T passes; `false` otherwise
+            assert true (not `nil` and not `false`)
         %|tr
           %|td
-            F?
+            F
           %|td
-            returns `true` if F passes; `false` otherwise
+            assert not true (`nil` or `false`)
         %|tr
           %|td
-            E?
+            E
           %|td
-            returns `true` if E passes; `false` otherwise
+            assert that an execption is raised
         %|tr
           %|td
-            C?
+            C
           %|td
-            returns `true` if C passes; `false` otherwise
+            assert that a symbol is thrown
 
-  %#--------------------------------------------------------------------------
-  %| section "Failures"
-  %#--------------------------------------------------------------------------
+    %#------------------------------------------------------------------------
+    %| section "Negation"
+    %#------------------------------------------------------------------------
 
-    When an assertion fails, details about the failure will be shown:
-
-        - fail: block must yield true (!nil && !false)
-          code: |-
-            [12..22] in test/simple.rb
-               12
-               13     D "with more nested tests" do
-               14       x = 5
-               15
-               16       T { x > 2 }   # passes
-            => 17       F { x > 2 }   # fails
-               18       E { x.hello } # passes
-               19     end
-               20   end
-               21
-               22   # equivalent of before(:each) or setup()
-          vars:
-            x: 5
-            y: 83
-          call:
-          - test/simple.rb:17
-          - test/simple.rb:3
-
-    You will then be placed into a debugger to investigate the failure if the
-    `:debug` option is enabled in the `Dfect.options` hash.
-
-    Details about all assertion failures and a trace of all tests executed are
-    stored by Dfect and provided by the `Dfect.report()` method.
+      These methods are the *opposite* of
+      <%= xref "Assertions", "normal assertions" %>.
+
+      %|table
+        %|thead
+          %|tr
+            %|th
+              Method
+            %|th
+              Description
+        %|tbody
+          %|tr
+            %|td
+              T!
+            %|td
+              same as F
+          %|tr
+            %|td
+              F!
+            %|td
+              same as T
+          %|tr
+            %|td
+              E!
+            %|td
+              assert that an exception is *not* raised
+          %|tr
+            %|td
+              C!
+            %|td
+              assert that a symbol is *not* thrown
 
-  %#--------------------------------------------------------------------------
-  %| section "Emulation"
-  %#--------------------------------------------------------------------------
+    %#------------------------------------------------------------------------
+    %| section "Sampling"
+    %#------------------------------------------------------------------------
 
-    Dfect provides emulation layers for several popular testing libraries:
+      These methods allow you to *check the outcome* of an assertion without
+      recording a success or failure for that assertion in the execution
+      report.
+
+      %|table
+        %|thead
+          %|tr
+            %|th
+              Method
+            %|th
+              Description
+        %|tbody
+          %|tr
+            %|td
+              T?
+            %|td
+              returns `true` if T passes; `false` otherwise
+          %|tr
+            %|td
+              F?
+            %|td
+              returns `true` if F passes; `false` otherwise
+          %|tr
+            %|td
+              E?
+            %|td
+              returns `true` if E passes; `false` otherwise
+          %|tr
+            %|td
+              C?
+            %|td
+              returns `true` if C passes; `false` otherwise
 
-    * <tt>dfect/unit</tt> --- Test::Unit
-    * <tt>dfect/mini</tt> --- Minitest
-    * <tt>dfect/spec</tt> --- RSpec
+    %#------------------------------------------------------------------------
+    %| section "Failures"
+    %#------------------------------------------------------------------------
 
-    Simply `require()` one of these emulation layers into your test suite and
-    you can write your tests using the familiar syntax of that testing
-    library.  See [their source code](<%= source_code_url
-    %>/tree/master/lib/dfect/) for more details.
+      When an assertion fails, details about the failure will be shown:
+
+          - fail: block must yield true (!nil && !false)
+            code: |-
+              [12..22] in test/simple.rb
+                 12
+                 13     D "with more nested tests" do
+                 14       x = 5
+                 15
+                 16       T { x > 2 }   # passes
+              => 17       F { x > 2 }   # fails
+                 18       E { x.hello } # passes
+                 19     end
+                 20   end
+                 21
+                 22   # equivalent of before(:each) or setup()
+            vars:
+              x: 5
+              y: 83
+            call:
+            - test/simple.rb:17
+            - test/simple.rb:3
+
+      You will then be placed into a debugger to investigate the failure if
+      the `:debug` option is enabled in the `Dfect.options` hash.
+
+      Details about all assertion failures and a trace of all tests executed
+      are stored by Dfect and provided by the `Dfect.report()` method.
 
-%#----------------------------------------------------------------------------
-%| section "Tests"
-%#----------------------------------------------------------------------------
+    %#------------------------------------------------------------------------
+    %| section "Emulation"
+    %#------------------------------------------------------------------------
 
-  The `D()` method defines a new Dfect **test**, which is analagous to the
-  concept of **test case** in xUnit or **describe** in rSpec.  A test may
-  contain nested tests.
+      Dfect provides emulation layers for several popular testing libraries:
 
-  %|code :ruby
-    D "outer test" do
-      # assertions and logic here
+      * <tt>dfect/unit</tt> --- Test::Unit
+      * <tt>dfect/mini</tt> --- Minitest
+      * <tt>dfect/spec</tt> --- RSpec
 
-      D "inner test" do
-        # more assertions and logic here
-      end
-    end
+      Simply `require()` one of these emulation layers into your test suite
+      and you can write your tests using the familiar syntax of that testing
+      library.  See [their source code](<%= source_code_url
+      %>/tree/master/lib/dfect/) for more details.
 
   %#--------------------------------------------------------------------------
-  %| section "Execution"
+  %| section "Tests"
   %#--------------------------------------------------------------------------
 
-    Tests are executed in depth-first order.
-
-    You can configure the test execution process using:
+    The `D()` method defines a new Dfect **test**, which is analagous to the
+    concept of **test case** in xUnit or **describe** in rSpec.  A test may
+    contain nested tests.
 
     %|code :ruby
-      Dfect.options = your_options_hash
+      D "outer test" do
+        # assertions and logic here
+
+        D "inner test" do
+          # more assertions and logic here
+        end
+      end
 
-    You can execute all tests defined thus far using:
+    %#------------------------------------------------------------------------
+    %| section "Execution"
+    %#------------------------------------------------------------------------
 
-    %|code :ruby
-      Dfect.run
+      Tests are executed in depth-first order.
 
-    You can stop the execution at any time using:
+      You can configure the test execution process using:
 
-    %|code :ruby
-      Dfect.stop
+      %|code :ruby
+        Dfect.options = your_options_hash
 
-    You can view the results of execution using:
+      You can execute all tests defined thus far using:
 
-    %|code :ruby
-      puts Dfect.report.to_yaml
+      %|code :ruby
+        Dfect.run
 
-    See the <%= api_reference %> for details and examples.
+      You can stop the execution at any time using:
 
-    %#------------------------------------------------------------------------
-    %| paragraph "Automatic test execution"
-    %#------------------------------------------------------------------------
+      %|code :ruby
+        Dfect.stop
 
-      To mix-in the `Dfect` module into your program and execute all tests
-      defined by your program before it terminates, simply add the following
-      line at the top of your program:
+      You can view the results of execution using:
 
       %|code :ruby
-        require 'dfect/auto'
+        puts Dfect.report.to_yaml
 
-    %#------------------------------------------------------------------------
-    %| section "Hooks"
-    %#------------------------------------------------------------------------
+      See the <%= api_reference %> for details and examples.
 
-      The `D()` method provides several entry points (hooks) into the test
-      execution process:
+      %#----------------------------------------------------------------------
+      %| paragraph "Automatic test execution"
+      %#----------------------------------------------------------------------
 
-      %|code :ruby
-        D "outer test" do
-          D .<  { puts "before each nested test" }
-          D .>  { puts "after  each nested test" }
-          D .<< { puts "before all nested tests" }
-          D .>> { puts "after  all nested tests" }
-
-          D "inner test" do
-            # assertions and logic here
-          end
-        end
+        To mix-in the `Dfect` module into your program and execute all tests
+        defined by your program before it terminates, simply add the following
+        line at the top of your program:
 
-      A hook method may be called multiple times.  Each call registers
-      additional logic to execute during the hook:
+        %|code :ruby
+          require 'dfect/auto'
 
-      %|code :ruby
-        D .< { puts "do something" }
-        D .< { puts "do something more!" }
+      %#----------------------------------------------------------------------
+      %| section "Hooks"
+      %#----------------------------------------------------------------------
 
-    %#------------------------------------------------------------------------
-    %| section "Logging"
-    %#------------------------------------------------------------------------
+        The `D()` method provides several entry points (hooks) into the test
+        execution process:
 
-      The `L()` method lets you insert log messages, composed of arbitrary
-      Ruby objects, into the test execution report.
+        %|code :ruby
+          D "outer test" do
+            D .<  { puts "before each nested test" }
+            D .>  { puts "after  each nested test" }
+            D .<< { puts "before all nested tests" }
+            D .>> { puts "after  all nested tests" }
 
-      %|example_dfect_test "Logging information in the execution report"
-        D 'Wizard' do
-          L 'Preparing spell to defeat mortal foes...'
-        end
+            D "inner test" do
+              # assertions and logic here
+            end
+          end
 
-        D 'Magician' do
-          L 'Preparing rabbits to pull from hat...', rand(15)
-        end
+        A hook method may be called multiple times.  Each call registers
+        additional logic to execute during the hook:
 
-        D 'Calculator' do
-          L Math::PI, [1, 2, 3, ['a', 'b', 'c']], {:foo => 'bar!'}
-        end
+        %|code :ruby
+          D .< { puts "do something" }
+          D .< { puts "do something more!" }
 
-  %#--------------------------------------------------------------------------
-  %| section "Sharing"
-  %#--------------------------------------------------------------------------
+      %#----------------------------------------------------------------------
+      %| section "Logging"
+      %#----------------------------------------------------------------------
+
+        The `L()` method lets you insert log messages, composed of arbitrary
+        Ruby objects, into the test execution report.
+
+        %|example_dfect_test "Logging information in the execution report"
+          D 'Wizard' do
+            L 'Preparing spell to defeat mortal foes...'
+          end
+
+          D 'Magician' do
+            L 'Preparing rabbits to pull from hat...', rand(15)
+          end
 
-    The `S()` method is a mechanism for sharing code.  When called with a
-    block, it shares the given block (under a given identifier) for injection
-    into other tests.  When called without a block, it injects a previously
-    shared block (under a given identifier) into the environment where it is
-    called.
+          D 'Calculator' do
+            L Math::PI, [1, 2, 3, ['a', 'b', 'c']], {:foo => 'bar!'}
+          end
 
-    The `S!()` method is a combination of the two uses of the `S()` method: it
-    lets you simultaneously share a block of code while injecting it into the
-    environment where that method is called.
+    %#------------------------------------------------------------------------
+    %| section "Sharing"
+    %#------------------------------------------------------------------------
 
-    The `S?()` method simply checks whether any code has been shared under a
-    given identifier.
+      The `S()` method is a mechanism for sharing code.  When called with a
+      block, it shares the given block (under a given identifier) for
+      injection into other tests.  When called without a block, it injects a
+      previously shared block (under a given identifier) into the environment
+      where it is called.
 
-    %|example_dfect_test "Sharing code between tests"
-      S :knowledge do
-        L 'Knowledge is power!'
-      end
+      The `S!()` method is a combination of the two uses of the `S()` method:
+      it lets you simultaneously share a block of code while injecting it into
+      the environment where that method is called.
 
-      D 'Healer' do
-        S :knowledge
-      end
+      The `S?()` method simply checks whether any code has been shared under a
+      given identifier.
 
-      D 'Warrior' do
-        S! :strength do
-          L 'Strength is power!'
+      %|example_dfect_test "Sharing code between tests"
+        S :knowledge do
+          L 'Knowledge is power!'
         end
-      end
 
-      D 'Wizard' do
-        S :knowledge
-        S :strength
-      end
+        D 'Healer' do
+          S :knowledge
+        end
 
-      D 'King' do
-        T { S? :knowledge }
-        T { S? :strength }
-        F { S? :power }
-        L 'Power is power!'
-      end
+        D 'Warrior' do
+          S! :strength do
+            L 'Strength is power!'
+          end
+        end
 
-  %#--------------------------------------------------------------------------
-  %| section "Insulation"
-  %#--------------------------------------------------------------------------
+        D 'Wizard' do
+          S :knowledge
+          S :strength
+        end
 
-    The `D!()` method defines a new test that is explicitly insulated from the
-    tests that contain it and also from the top-level Ruby environment.
-    Root-level calls to the `D()` method are insulated by default.
+        D 'King' do
+          T { S? :knowledge }
+          T { S? :strength }
+          F { S? :power }
+          L 'Power is power!'
+        end
+
+    %#------------------------------------------------------------------------
+    %| section "Insulation"
+    %#------------------------------------------------------------------------
 
-    Inside an insulated test, you are free to:
-    * mix-in any modules your test logic needs
-    * define your own constants, methods, and classes
+      The `D!()` method defines a new test that is explicitly insulated from
+      the tests that contain it and also from the top-level Ruby environment.
+      Root-level calls to the `D()` method are insulated by default.
 
-    %|example_dfect_test "Insulated and uninsulated tests"
-      D "a root-level test" do
-        @outside = 1
-        T { defined? @outside }
-        T { @outside == 1 }
+      Inside an insulated test, you are free to:
+      * mix-in any modules your test logic needs
+      * define your own constants, methods, and classes
 
-        D "an inner, non-insulated test" do
+      %|example_dfect_test "Insulated and uninsulated tests"
+        D "a root-level test" do
+          @outside = 1
           T { defined? @outside }
           T { @outside == 1 }
-        end
 
-        D! "an inner, insulated test" do
-          F { defined? @outside }
-          F { @outside == 1 }
+          D "an inner, non-insulated test" do
+            T { defined? @outside }
+            T { @outside == 1 }
+          end
 
-          @inside = 2
-          T { defined? @inside }
-          T { @inside == 2 }
-        end
+          D! "an inner, insulated test" do
+            F { defined? @outside }
+            F { @outside == 1 }
 
-        F { defined? @inside }
-        F { @inside == 2 }
-      end
+            @inside = 2
+            T { defined? @inside }
+            T { @inside == 2 }
+          end
+
+          F { defined? @inside }
+          F { @inside == 2 }
+        end