RubyGems - qed - Versions diffs - 1.1.0 → 1.2 - Mend

qed 1.1.0 → 1.2

Files changed (25) hide show

data/HISTORY +40 -2
data/MANIFEST +7 -12
data/README.rdoc +30 -23
data/bin/qed +1 -147
data/demo/01_spec.qed +82 -53
data/demo/data.txt +1 -0
data/demo/{qed_helper.rb → helper.rb} +1 -0
data/demo/table.yml +5 -0
data/doc/qedoc/index.html +98 -53
data/lib/qed.rb +1 -1
data/lib/qed/command.rb +166 -0
data/lib/qed/document.rb +43 -13
data/lib/qed/reporter/base.rb +12 -5
data/lib/qed/reporter/dotprogress.rb +1 -1
data/lib/qed/reporter/summary.rb +2 -1
data/lib/qed/reporter/verbatim.rb +11 -12
data/lib/qed/script.rb +140 -33
data/meta/description +2 -2
data/meta/homepage +1 -1
data/meta/{package → name} +0 -0
data/meta/repository +1 -0
data/meta/{project → suite} +0 -0
data/meta/version +1 -1
metadata +15 -13
data/demo/01_spec.yaml +0 -4

data/demo/data.txt ADDED Viewed

@@ -0,0 +1 @@

+ Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

data/demo/{qed_helper.rb → helper.rb} RENAMED Viewed

	@@ -1 +1,2 @@
1 1	require 'ae/expect'
2	+

data/demo/table.yml ADDED Viewed

@@ -0,0 +1,5 @@
+---
+- [ try  , TRY ]
+- [ me   , ME  ]
+- [ mc   , MC  ]

data/doc/qedoc/index.html CHANGED Viewed

@@ -1,6 +1,6 @@
 <html>
 <head>
-  <title>QED Overview</title>
+  <title>Demonstration</title>
   <style>
     #container{ margin: 0 auto; width: 800px; }
@@ -89,7 +89,7 @@
     <div id="header">
       <img src="img/icon/book.jpg" align="left" style="padding-right: 10px;" alt=""/>
-      <h1 class="title">QED Overview</h1>
+      <h1 class="title">Demonstration</h1>
       <h1>Table of Contents</h1>
@@ -115,31 +115,30 @@ occur then the code gets a &#8220;pass&#8221;.
 For example, the following passes:
 </p>
 <pre>
-  (2 + 2).assert == 4
+    (2 + 2).assert == 4
 </pre>
 <p>
 While the following would &#8220;fail&#8221;, as indicated by the raising
 of an Assertion error:
 </p>
 <pre>
-  expect Assertion do
-    (2 + 2).assert == 5
-  end
+    expect Assertion do
+      (2 + 2).assert == 5
+    end
 </pre>
 <p>
 And this would have raised a NameError:
 </p>
 <pre>
-  expect NameError do
-    nobody_knows_method
-  end
+    expect NameError do
+      nobody_knows_method
+    end
 </pre>
 <h1>Neutral Code</h1>
 <p>
 There is no means of specifying that a code clause is neutral code, i.e.
-that it should be executed but not tested. So far this such a feature has
-proven to be a YAGNI. Yet we may add such a feature in the future if it is
-ultimately deemed necessary.
+that it should be executed but not tested. Thus far, such a feature has
+proven to be a YAGNI.
 </p>
 <h1>Defining Custom Assertions</h1>
 <p>
@@ -147,30 +146,32 @@ The context in which the QED code is run is a self-extended module, thus
 reusable macros can be created simply by defining a method.
 </p>
 <pre>
-  def assert_integer(x)
-    x.assert.is_a? Integer
-  end
+    def assert_integer(x)
+      x.assert.is_a? Integer
+    end
 </pre>
 <p>
 Now lets try out our new macro definition.
 </p>
 <pre>
-  assert_integer(4)
+    assert_integer(4)
 </pre>
 <p>
 Let&#8217;s prove that it can also fail:
 </p>
 <pre>
-  expect Assertion do
-    assert_integer(&quot;IV&quot;)
-  end
+    expect Assertion do
+      assert_integer(&quot;IV&quot;)
+    end
 </pre>
 <h1>Helper File</h1>
 <p>
-If you create a file called `qed_helper.rb` located in the directory with
-the QED documents you are running via the `qed` command, it will be loaded
-first. You can use that to load optional AE features, or define your own
-specialized assertion methods.
+Helpers can be defined at the bottom of any QED document by placing the
+code after a triple-dash divider (ie. &#8220;&#8212;&#8221;). You can use
+that to load optional AE features, or define your own specialized assertion
+methods. Helpers can be defined in a separate files using <tt>require</tt>
+or <tt>load</tt> in the bottom section to import them. The bottom section
+is run first, before any the steps.
 </p>
 <h1>Before and After Clauses</h1>
 <p>
@@ -183,36 +184,36 @@ We use a <b>before</b> clause if we want to setup some code at the start of
 each step.
 </p>
 <pre>
-  a, z = nil, nil
+    a, z = nil, nil
-  before do
-    a = &quot;BEFORE&quot;
-  end
+    Before do
+      a = &quot;BEFORE&quot;
+    end
 </pre>
 <p>
-And an <b>after</b> clause to tear down objects after a step.
+And an <b>after</b> clause to teardown objects after a step.
 </p>
 <pre>
-  after do
-    z = &quot;AFTER&quot;
-  end
+    After do
+      z = &quot;AFTER&quot;
+    end
 </pre>
 <p>
 Notice we assigned <tt>a</tt> and <tt>z</tt> before the block. This was to
-ensure their visibility in the scope later. Now, lets verify this the
-<b>before</b> and <b>after</b> clause work.
+ensure their visibility in the scope later. Now, lets verify that the
+<b>before</b> and <b>after</b> clauses work.
 </p>
 <pre>
-  a.assert == &quot;BEFORE&quot;
+    a.assert == &quot;BEFORE&quot;
-  a = &quot;A&quot;
-  z = &quot;Z&quot;
+    a = &quot;A&quot;
+    z = &quot;Z&quot;
 </pre>
 <p>
 And now.
 </p>
 <pre>
-  z.assert == &quot;AFTER&quot;
+    z.assert == &quot;AFTER&quot;
 </pre>
 <p>
 There can only be one before or after clause at a time. So if we define a
@@ -223,28 +224,38 @@ replace the current clause(s) in use.
 As a demonstration of this:
 </p>
 <pre>
-  before do
-    a = &quot;BEFORE AGAIN&quot;
-  end
+    Before do
+      a = &quot;BEFORE AGAIN&quot;
+    end
 </pre>
 <p>
 We will see it is the case.
 </p>
 <pre>
-  a.assert == &quot;BEFORE AGAIN&quot;
+    a.assert == &quot;BEFORE AGAIN&quot;
 </pre>
 <p>
 Only use <b>before</b> and <b>after</b> clauses when necessary
 &#8212;specifications are generally more readable without them. Indeed,
 some developers make a policy of avoiding them altogether. YMMV.
 </p>
+<h1>External Data</h1>
+<p>
+When creating testable demonstrations, there are times when sizable chunks
+of data are needed. It is convenient to store such data in a separate file.
+The <tt>Data</tt> method makes is easy to load such files.
+</p>
+<pre>
+    Data('data.txt').assert =~ /dolor/
+</pre>
+<p>
+All files are looked for relative to the location of current document.
+</p>
 <h1>Tabular Steps</h1>
 <p>
-Finally we will demonstrate a tabular step. <tt>table</tt> method is used
-for this. We supply a file name to the method telling QED where to find the
-table data to be used in the test. All table files are looked for relative
-to the location of the document. If no name is given the
-&#8217;<doc-name>.yaml&#8217; is assumed.
+The <tt>Table</tt> method is similar to the <tt>Data</tt> method except
+that it expects a YAML file, and it can take a block to iterate the data
+over. This makes it easy to test tables of examples.
 </p>
 <p>
 The arity of the table block determines the number of columns each row in
@@ -252,20 +263,54 @@ the table should have. Each row is assigned in turn and run through the
 coded step. Consider the following example:
 </p>
 <p>
-Every row in &#8216;table.yaml&#8217; will be assigned to the block
-parameters and run through the following assertion.
+Every row in the <a href="http://table.yml">table.yml table</a> will be
+assigned to the block parameters and run through the subsequent assertion.
 </p>
 <pre>
-  table do |x,y|
-    x.upcase.assert == y
-  end
+    Table 'table.yml' do |x, y|
+      x.upcase.assert == y
+    end
 </pre>
+<h1>Comment Triggers</h1>
+<p>
+QED also supports comment match triggers. With the <tt>When</tt> method one
+can define setup and teardown procedures by matching against comment text.
+For example:
+</p>
+<pre>
+    When 'given a setting @a equal to (((\d+)))' do |n|
+      @a = n.to_i
+    end
+</pre>
+<p>
+Now, @a will be set to 1 whenever a comment like this one contains,
+&#8220;given a setting @a equal to 1&#8221;.
+</p>
+<pre>
+    @a.assert == 1
+</pre>
+<p>
+A string pattern is translated into a regular expression. In fact, you can
+use a regular expression if you need more control over the match. When
+using a string all spaces are converted to <tt>\s+</tt> and anything within
+double-parenthesis is treated as raw regular expression. Since the above
+example has (((\d+))), the actual regular expression contains
+<tt>(\d+)</tt>, so any number can be used. For example, &#8220;given a
+setting @a equal to 2&#8221;.
+</p>
+<pre>
+    @a.assert == 2
+</pre>
+<p>
+Typically you will want to put triggers is helper files, rather then place
+them directly in the demonstration document.
+</p>
 <p>
 This concludes the basic overview of QED&#8217;s specification system,
 which is itself a QED document. Yes, we eat our own dog food.
 </p>
-<p>
-Q.E.D.
+<hr size="1"></hr><p>
+require &#8216;helper&#8217;
 </p>

data/lib/qed.rb CHANGED Viewed

@@ -1,5 +1,5 @@
 module QED
-  VERSION="1.0.0"  #:till: VERSION="<%= version %>"
+  VERSION="1.2"  #:till: VERSION="<%= version %>"
 end
 require 'qed/runner'

data/lib/qed/command.rb ADDED Viewed

@@ -0,0 +1,166 @@
+#!/usr/bin/env ruby
+require 'qed'
+require 'optparse'
+module QED
+  # = QED Commandline Tool
+  #
+  class Command
+    def self.execute
+      new.execute
+    end
+    #
+    attr :format
+    #
+    def initialize
+      @format = nil
+    end
+    # Instance of OptionParser
+    def opts
+      @opts ||= OptionParser.new do |opt|
+        opt.on('--dotprogress', '-d', "use dot-progress reporter [default]") do
+          @format = :summary
+        end
+        opt.on('--verbatim', '-v', "use verbatim reporter") do
+          @format = :verbatim
+        end
+        opt.on('--summary', '-s', "use summary reporter") do
+          @format = :summary
+        end
+        opt.on('--script', "psuedo-reporter") do
+          @format = :script  # psuedo-reporter
+        end
+        opt.on('--loadpath', "-I", "add paths to $LOAD_PATH") do |arg|
+          libs = arg.split(/[:;]/).map{ |dir| File.expand_path(dir) }
+          libs.each{|dir| $LOAD_PATH.unshift(dir)}
+        end
+        opt.on('--verbose', '-V', "extra verbose output") do
+          @verbose = true
+          $VERBOSE = true
+        end
+        opt.on('--debug', "demos will exit on error") do
+          $DEBUG = true
+        end
+        opt.on_tail('--version', "display version") do
+          puts "QED #{VERSION}"
+          exit
+        end
+        opt.on_tail('--copyright', "display copyrights") do
+          puts "Copyright (c) 2008, 2009 Thomas Sawyer, GPL License"
+          exit
+        end
+        opt.on_tail('--help', '-h', "display this help message") do
+          puts opt
+          exit
+        end
+      end
+    end
+    #
+    #def load_rc
+    #  if rcfile = Dir['.config/qed{,rc}{,.rb}'].first
+    #    load(rcfile)
+    #  end
+    #end
+    # TODO: Better way to load helpers?
+    #
+    #def load_helpers
+    #  dirs = spec_files.map{ |file| File.join(Dir.pwd, File.dirname(file)) }
+    #  dirs = dirs.select{ |dir| File.directory?(dir) }
+    #  dirs.each do |dir|
+    #    while dir != '/' do
+    #      helper = File.join(dir, 'qed_helper.rb')
+    #      load(helper) if File.exist?(helper)
+    #      break if Dir.pwd == dir
+    #      dir = File.dirname(dir)
+    #    end
+    #  end
+    #end
+    #
+    def demos
+      demo_files
+    end
+    #
+    def demo_files
+      files = ARGV.map do |pattern|
+        Dir[pattern]
+      end.flatten.uniq
+      files = files.map do |file|
+        if File.directory?(file)
+          Dir[File.join(file,'**','*{.qed,.rd,.rdoc,.md,.markdown}')]
+        else
+          file
+        end
+      end
+      file = files.flatten.uniq
+      #files = files.select do |file|
+      #  %w{.yml .yaml .rb}.include?(File.extname(file))
+      #end
+      files
+    end
+    #
+    def reporter
+      case format
+      when :dotprogress
+        Reporter::DotProgress.new(reporter_options)
+      when :verbatim
+        Reporter::Verbatim.new(reporter_options)
+      when :summary
+        Reporter::Summary.new(reporter_options)
+      else
+        nil
+      end
+    end
+    #
+    def reporter_options
+      { :verbose => @verbose }
+    end
+    #
+    def runner
+      Runner.new(demos, reporter)
+    end
+    #
+    def execute
+      opts.parse!
+      #load_rc
+      #load_helpers
+      case reporter
+      when :script
+        specs.each do |spec|
+          puts spec.to_script
+        end
+      else
+        runner.check
+      end
+    end
+  end
+end

data/lib/qed/document.rb CHANGED Viewed

@@ -12,8 +12,8 @@ module QED
     DEFAULT_TITLE  = "Demonstration"
     DEFAULT_CSS    = nil #"../assets/styles/spec.css"
-    DEFAULT_OUTPUT = "doc/spec"
-    DEFAULT_PATH   = ["spec/**/*"]
+    DEFAULT_OUTPUT = "doc/qedoc"
+    DEFAULT_PATH   = "test/demos"
     attr_accessor :title
     attr_accessor :css
@@ -35,12 +35,15 @@ module QED
       @output ||= DEFAULT_OUTPUT
       @paths  ||= []
-      @paths  = DEFAULT_PATH if @paths.empty?
+      if @paths.empty?
+        dir = Dir['{test/demos,demo,demos}'].first || DEFAULT_PATH
+        @paths  = File.join(dir, '**', '*')
+      end
     end
-    # Specification files.
-    def spec_files
-      @spec_files ||= (
+    # Demo files.
+    def demo_files
+      @demo_files ||= (
         glob = paths.map{ |f| File.directory?(f) ? Dir["#{f}/**/*"] : Dir[f] }.flatten
         glob = glob.select do |f|
           File.file?(f) && f !~ /fixtures\/|helpers\// && f !~ /\.rb$/
@@ -66,7 +69,7 @@ module QED
       #TODO: load .config/qedrc.rb
-      spec_files.each do |file|
+      demo_files.each do |file|
         puts file unless quiet?
         #strio = StringIO.new('')
@@ -76,19 +79,26 @@ module QED
         #iotext = strio.string
         #strio.close
-        case ext = File.extname(file)
+        ext = File.extname(file)
+        txt = File.read(file)
+        if ext == '.qed'
+          ext = file_type(txt)
+        end
+        case ext
         #when '.qed'
         #  require_qedoc
         #  markup = Markup.new(File.read(file))
         #  text << markup.to_html
-        when '.rd', '.rdoc', '.qed'
+        when '.rd', '.rdoc'
           require_rdoc
           markup = RDoc::Markup::ToHtml.new
-          text << markup.convert(File.read(file))
+          text << markup.convert(txt)
           #text << markup.convert(iotext, formatter)
         when '.md', '.markdown'
           require_rdiscount
-          markdown = RDiscount.new(File.read(file))
+          markdown = RDiscount.new(txt)
           text << markdown.to_html
         end
         text << "\n"
@@ -135,6 +145,21 @@ module QED
   private
+    #
+    def file_type(text)
+      rdoc = text.index(/^\=/)
+      markdown = text.index(/^\#/)
+      if markdown && rdoc
+        rdoc < markdown ? '.rdoc' : '.markdown'
+      elsif rdoc
+        '.rdoc'
+      elsif markdown
+        '.markdown'
+      else  # fallback to rdoc
+        '.rdoc'
+      end
+    end
     #
     def require_qedoc
       @require_rdoc ||= (
@@ -146,8 +171,13 @@ module QED
     #
     def require_rdoc
       @require_rdoc ||= (
-        require 'rdoc/markup/to_html'
-        #require 'rdoc/markup/simple_markup'
+        begin
+          require 'rdoc/markup/to_html'
+        rescue LoadError
+          require 'rubygems'
+          gem 'rdoc'
+          retry
+        end
         true
       )
     end