qed 2.6.0 → 2.6.1

data/.ruby

@@ -1,47 +1,48 @@
 --- 
-spec_version: 1.0.0
-replaces: []
-
-loadpath: 
-- lib
 name: qed
-repositories: 
-  public: git://github.com/proutils/qed.git
-conflicts: []
-
-engine_check: []
-
+version: 2.6.1
 title: QED
-resources: 
-  home: http://proutils.github.com/qed
-  work: http://github.com/proutils/qed
-maintainers: []
-
+summary: Quod Erat Demonstrandum
+description: QED (Quality Ensured Demonstrations) is a TDD/BDD framework utilizing Literate Programming techniques.
+loadpath: 
+- lib
+manifest: MANIFEST
 requires: 
-- group: []
-
-  name: ansi
+- name: ansi
   version: 0+
-- group: []
+  group: []
 
-  name: facets
+- name: facets
   version: 2.8+
-- group: []
+  group: []
 
-  name: ae
+- name: ae
+  version: 1.7+
+  group: []
+
+- name: detroit
   version: 0+
-- group: 
+  group: 
   - build
-  name: syckle
-  version: 0+
-manifest: Manifest
-version: 2.5.1
-licenses: []
+conflicts: []
+
+replaces: []
+
+engine_check: []
 
+organization: RubyWorks
+contact: trans <transfire@gmail.com>
+created: 2006-12-16
 copyright: Copyright (c) 2006 Thomas Sawyer
+licenses: []
+
 authors: 
 - Thomas Sawyer <transfire@gmail.com>
-organization: RubyWorks
-description: QED (Quality Ensured Demonstrations) is a TDD/BDD framework utilizing Literate Programming techniques.
-summary: Quod Erat Demonstrandum
-created: 2006-12-16
+maintainers: []
+
+resources: 
+  home: http://rubyworks.github.com/qed
+  work: http://github.com/rubyworks/qed
+repositories: 
+  public: git://github.com/rubyworks/qed.git
+spec_version: 1.0.0

data/.yardopts

@@ -0,0 +1,6 @@
+--output-dir doc
+--readme README.rdoc
+--title "Q.E.D."
+lib
+-
+[A-Z]*.*

data/HISTORY.rdoc

@@ -1,5 +1,19 @@
 = RELEASE HISTORY
 
+== 2.6.1 / 2011-07-02
+
+A friend insisted QED default the loadpath tolib and
+automatically look for QED demos in default locations
+(sepc, demo, qed) if not files are passed to it on the
+command line. So it is.
+
+Changes:
+
+* Default loadpath option to lib/.
+* Default files to markup files in spec/, demo/ and qed/.
+* Fix website links (you might acutally find things now).
+
+
 == 2.6.0 / 2011-07-01
 
 Thie release fixes some issues with reporters, further refines

data/QED.rdoc

@@ -0,0 +1,454 @@
+= Demonstrations
+
+== Steps
+
+QED demos are light-weight specification documents, highly suitable
+to interface-driven design. The documents are divided up into
+steps separated by blank lines. Steps that are flush to the 
+left margin are always explanatory comments. Indented steps are
+either executable code or plain text samples.
+
+Each step is executed in order of appearance within a rescue wrapper
+that captures any failures or errors. If neither a failure or error
+occur then the step gets a "pass".
+
+For example, the following passes.
+
+    (2 + 2).assert == 4
+
+While the following would "fail", as indicated by the raising of 
+an Assertion error.
+
+    expect Assertion do
+      (2 + 2).assert == 5
+    end
+
+And this would have raised a NameError.
+
+    expect NameError do
+      nobody_knows_method
+    end
+
+== Defining Custom Assertions
+
+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.
+
+    def assert_integer(x)
+      x.assert.is_a? Integer
+    end
+
+Now lets try out our new macro definition.
+
+    assert_integer(4)
+
+Let's prove that it can also fail.
+
+    expect Assertion do
+      assert_integer("IV")
+    end
+
+
+= Advice
+
+Advice are event-based procedures that augment demonstrations.
+They are used to keep demonstrations clean of extraneous,
+repetitive and merely adminstrative code that the reader does
+not need to see over and over.
+
+Typically you will want to put advice definitions is applique
+files, rather then place them directly in the demonstration
+document, but you can do so, as you will see in this document.
+
+== Before and After
+
+QED supports *before* and *after* clauses in a specification
+through the use of Before and After code blocks. These blocks
+are executed at the beginning and at the end of each indicated
+step.
+
+We use a *before* clause if we want to setup some code at the
+start of each code step.
+
+    a, z = nil, nil
+
+    Before do
+      a = "BEFORE"
+    end
+
+And an *after* clause to teardown objects after a code step.
+
+    After do
+      z = "AFTER"
+    end
+
+Notice we assigned +a+ and +z+ before the block. This was to ensure
+their visibility in the scope later. Now, lets verify that the *before*
+and *after* clauses work.
+
+    a.assert == "BEFORE"
+
+    a = "A"
+    z = "Z"
+
+And now.
+
+    z.assert == "AFTER"
+
+There can be more than one before and after clause at a time. If we
+define a new *before* or *after* clause later in the document,
+it will be appended to the current list of clauses in use.
+
+As a demonstration of this,
+
+    b = nil
+
+    Before do
+      b = "BEFORE AGAIN"
+    end
+
+We will see it is the case.
+
+    b.assert == "BEFORE AGAIN"
+
+Only use *before* and *after* clauses when necessary --specifications
+are generally more readable without them. Indeed, some developers
+make a policy of avoiding them altogether. YMMV.
+
+== Caveats of Before and After
+
+Instead of using Before and After clauses, it is wiser to
+define a reusable setup method. For example, in the helper
+if we define a method such as #prepare_example.
+
+  def prepare_example
+    "Hello, World!"
+  end
+
+Then we can reuse it in later code blocks.
+
+  example = prepare_example
+  example.assert == "Hello, World!"
+
+The advantage to this is that it gives the reader an indication
+of what is going on behind the scenes, rather the having
+an object just magically appear.
+
+== Event Targets
+
+There is a small set of advice targets that do not come before or after,
+rather they occur *upon* a particular event. These include +:load+
+and +:unload+ for when a new helper is loaded; +:pass+, +:fail+ and +:error+
+for when a code block passes, fails or raises an error; and +:head+, +:desc:+,
++:code+ and +:data:+ which targets the immediate processing of a text block
+and code excecution.
+
+These event targets can be advised by calling the +When+ method
+with the target type as an argument along with the code block
+to be run when the event is triggered.
+
+  x = []
+
+  When(:text) do |section|
+    section.text.scan(/^\*(.*?)$/) do |m|
+      x << $1.strip
+    end
+  end
+
+Not let see if it worked.
+
+* SampleA
+* SampleB
+* SampleC
+
+So +x+ should now contain these three list samples.
+
+  x.assert == [ 'SampleA', 'SampleB', 'SampleC' ]
+
+== Pattern Matchers
+
+QED also supports comment match triggers. With the +When+ method one can
+define procedures to run when a given pattern matches comment text.
+
+    When 'given a setting @a equal to (((\d+)))' do |n|
+      @a = n.to_i
+    end
+
+Now, @a will be set to 1 whenever a comment like this one contains,
+"given a setting @a equal to 1".
+
+    @a.assert == 1
+
+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, "given a setting @a equal to 2".
+
+    @a.assert == 2
+
+When clauses can also use consecutive pattern matching. For instance
+we could write,
+
+  When 'first match #(((\d+)))', 'then match #(((\d+)))' do |i1, i2|
+    @a = [i1.to_i, i2.to_i]
+  end
+
+So that 'first match #1' will be looked for first, and only after
+that if 'then match #2' is found, will it be condiered a complete match.
+All regular expression slots are collected from all matches and passed to
+the block. We can see that the rule matched this very paragraph.
+
+  @a.assert == [1,2]
+
+This concludes the basic overview of QED's specification system, which
+is itself a QED document. Yes, we eat our own dog food.
+
+
+= Helpers
+
+There are two ways to load advice scripts. Either per
+demonstration or globally. Per demonstration helpers 
+apply only to the current demonstration. Global helpers
+apply to all demonstrations.
+
+== Global Helpers
+
+Global helpers are loaded at the start of a session and
+apply equally to all demonstrations in a suite. Global
+helpers are simply Ruby scripts and are placed in an
++environment+ subdirectory. For instance this document
+is used <a href="environment/env.rb">environment/env.rb</a>.
+
+== Local Helpers
+
+Helper scripts can be written just like demonstration scripts,
+or they can be defined as pure Ruby scripts. Either way
+they are loaded per-demonstration by using specially
+marked links.
+
+For example, because this link, Advice[qed://helpers/advice.rb],
+begins with +qed:+, it will be used to load a global
+helper. We can see this with the following assertion.
+
+  pudding.assert.include?('load advice.rb')
+
+No where in the demonstration have we defined +pudding+, but
+it has been defined for us in the advice.rb helper script.
+
+We can also see that the generic When clause in our advice
+helper is keeping count of decriptive paragraphs. Since the
+helper script was loaded two paragraphs back, the next count
+will be 3.
+
+  count.assert == 3
+
+Helpers are vital to building test-demonstration suites for
+applications. But here again, only use them as necessary.
+The more helpers you use the more difficult your demos will
+be to follow.
+
+
+= Test Samples
+
+== Flat-file Data
+
+When creating testable demonstrations, there are times when sizable
+chunks of data are needed. It is convenient to store such data in
+separate files. The +Data+ method makes is easy to utilize them.
+
+    Data('qed/samples/data.txt').assert =~ /dolor/
+
+The +Data+ method can also take a block which passes the data
+as the block's only argument.
+
+    Data('qed/samples/data.txt') do |data|
+      data.assert =~ /dolor/
+    end
+
+Files are looked-up relative to the location of the current document.
+If not found then they will be looked-up relative to the current
+working directory.
+
+== Tabular Data
+
+The +Table+ method is similar to the +Data+ 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.
+
+The arity of the table block corresponds to the number of columns in
+each row of the table. Each row is assigned in turn and run through
+the coded step. Consider the following example.
+
+Every row in the {table.yml table}[table.yml] will be assigned to
+the block parameters and run through the subsequent assertion.
+
+    Table 'qed/samples/table.yml' do |x, y|
+      x.upcase.assert == y
+    end
+
+Without the block, the +Table+ methods simply returns the sample data.
+
+== Considerations
+
+Both Data and Table are some what "old fashion" approches to sample
+data. New techinques using plain text blocks are more convenient
+in that the data can be stored directly in the demonstration itself.
+However, for especially large data sets and external file is still
+the better option, and +Data+ and +Table+ make them quite easy to
+access.
+
+
+= Quotes
+
+We do not always want verbatim clauses to be interpreted as code.
+Sometimes it would more useful to treat them a plain text to 
+which the preceeding paragraph can make use in a processing rule.
+
+For example let say we want to make an example out of the following
+text...
+
+  The file will contain
+
+  this text
+
+The use of the ellipsis ('...') tells the processor that the next
+segment is a plain text continuation of the current segment, rather
+than example code. If the next segment is varbatim it will be added to
+the end of the arguments list of any applicable processing rule.
+
+Behind the scenes we created a rule to set the text to an instance
+variable called @quote_text, and we can verify it is so.
+
+  @quote_text.assert == "The file will contain\n\nthis text"
+
+Alternately we can use a colon (':') instead of ellipsis. We can repeat
+the same statment as above.
+
+For example let say we want to make an example out of the following
+text:
+
+  The file will contain
+
+  different text
+
+And again we can verify that it did in fact set the @quote_text variable.
+
+  @quote_text.assert == "The file will contain\n\ndifferent text"
+
+
+= Toplevel Simulation
+
+QED simulates Ruby's TOPLEVEL environment in both the Demonstrandum
+and the Applique contexts. This serves two important purposes.
+First, it provides the tester the environment that is most intutive.
+And second, and more importantly, it stays out of the actual
+TOPLEVEL space to prevent any potential interferece with any of 
+the code it is intended to test.
+
+Let's look at some examples. For starters, we have access to a class
+defined at the "toplevel" in the applique.
+
+  ToplevelClass
+
+We can also call a method defined in the toplevel.
+
+  toplevel_method.assert == true
+
+At the demonstrandum level we can define reusable methods.
+
+  def demo_method
+    true
+  end
+
+  demo_method.assert == true
+
+And at the demonstrandum level even singleton methods are accessible.
+
+  def self.singleton_method; true; end
+
+  singleton_method.assert == true
+
+QED uses a self-extend modules to achieve this simulation, so the
+contexts are in fact a bit more capable then even Ruby's TOPLEVEL.
+For instance, #define_method can be used.
+
+  define_method(:named_method){ true }
+
+  named_method.assert == true
+
+
+= Cross-Scripting Setup
+
+We define some variables here to make sure it is
+not visible in the next script.
+
+Let's set two local variables.
+
+  a = 100
+  b = 200
+
+And two instance varaibles.
+
+  @a = 1000
+  @b = 2000
+
+Also let check how it effect constants.
+
+  CROSS_SCRIPT_CONSTANT = "cross?"
+
+And a method.
+
+  def cross_script_method
+    "common"
+  end
+
+
+= Cross-Scripting Check
+
+Make sure local and instance variables from previous
+QED scripts are not visible in this document.
+
+  expect NameError do
+    a.assert = 100
+    b.assert = 200
+  end
+
+And two instance_varaibles
+
+  @a.assert! == 1000
+  @b.assert! == 2000
+
+
+Method definitions also do not cross QED scripts.
+
+  expect NameError do
+    cross_script_method
+  end
+
+Since each demo is encapsulated in a separated class scope, constants also
+do not make their way across.
+
+  expect NameError do
+    CROSS_SCRIPT_CONSTANT
+  end
+
+
+= Missing Constant
+
+If a constant is missing it is because it was not found
+in either the demos scope, the applique or the toplevel.
+
+  begin
+    UnknownConstant
+  rescue => err
+    # no colon means toplevel
+    /[^:]UnknownConstant/ =~ err.message
+  end
+
+A constant defined in the applique is visible.
+
+  APPLIQUE_CONSTANT.assert = true
+
+

data/lib/qed.yml

@@ -1,47 +1,48 @@
 --- 
-spec_version: 1.0.0
-replaces: []
-
-loadpath: 
-- lib
 name: qed
-repositories: 
-  public: git://github.com/proutils/qed.git
-conflicts: []
-
-engine_check: []
-
+version: 2.6.1
 title: QED
-resources: 
-  home: http://proutils.github.com/qed
-  work: http://github.com/proutils/qed
-maintainers: []
-
+summary: Quod Erat Demonstrandum
+description: QED (Quality Ensured Demonstrations) is a TDD/BDD framework utilizing Literate Programming techniques.
+loadpath: 
+- lib
+manifest: MANIFEST
 requires: 
-- group: []
-
-  name: ansi
+- name: ansi
   version: 0+
-- group: []
+  group: []
 
-  name: facets
+- name: facets
   version: 2.8+
-- group: []
+  group: []
 
-  name: ae
+- name: ae
+  version: 1.7+
+  group: []
+
+- name: detroit
   version: 0+
-- group: 
+  group: 
   - build
-  name: syckle
-  version: 0+
-manifest: Manifest
-version: 2.5.1
-licenses: []
+conflicts: []
+
+replaces: []
+
+engine_check: []
 
+organization: RubyWorks
+contact: trans <transfire@gmail.com>
+created: 2006-12-16
 copyright: Copyright (c) 2006 Thomas Sawyer
+licenses: []
+
 authors: 
 - Thomas Sawyer <transfire@gmail.com>
-organization: RubyWorks
-description: QED (Quality Ensured Demonstrations) is a TDD/BDD framework utilizing Literate Programming techniques.
-summary: Quod Erat Demonstrandum
-created: 2006-12-16
+maintainers: []
+
+resources: 
+  home: http://rubyworks.github.com/qed
+  work: http://github.com/rubyworks/qed
+repositories: 
+  public: git://github.com/rubyworks/qed.git
+spec_version: 1.0.0

data/lib/qed/session.rb

@@ -9,6 +9,10 @@ module QED
   #
   class Session
 
+    # If files are not specifies than these directories 
+    # will be searched.
+    DEFAULT_FILES = ['spec', 'demo', 'qed']
+
     # Default recognized demos file types.
     DEMO_TYPES = %w{qed rdoc md markdown}
 
@@ -52,13 +56,14 @@ module QED
     def initialize(files, options={})
       require_reporters
 
-      @files     = [files].flatten
+      @files = [files].flatten
+      @files = DEFAULT_FILES if @files.empty?
 
       @format    = options[:format]   || :dotprogress
       @trace     = options[:trace]    || false
       @mode      = options[:mode]     || nil
       @profile   = options[:profile]  || :default
-      @loadpath  = options[:loadpath] || []
+      @loadpath  = options[:loadpath] || ['lib']
       @requires  = options[:requires] || []
 
       @omit      = OMIT_PATHS  # TODO: eventually make configurable
@@ -93,7 +98,7 @@ module QED
 
     # Returns an Array of Demo instances.
     #--
-    # TODO: Pass settings to demo, so we can get temporary_dirctory.
+    # TODO: Pass settings to demo, so we can get temporary_directory.
     #++
     def demos
       @demos ||= demo_files.map{ |file| Demo.new(file, :mode=>mode, :at=>directory) }
@@ -224,10 +229,10 @@ module QED
 
       files, options = cli_parse(argv)
 
-      if files.empty?
-        puts "No files."
-        exit -1
-      end
+      #if files.empty?
+      #  puts "No files."
+      #  exit -1
+      #end
 
       session = new(files, options)
       session.run

metadata

@@ -2,7 +2,7 @@
 name: qed
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 2.6.0
+  version: 2.6.1
 platform: ruby
 authors: 
 - Thomas Sawyer <transfire@gmail.com>
@@ -42,11 +42,11 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        version: "0"
+        version: "1.7"
   type: :runtime
   version_requirements: *id003
 - !ruby/object:Gem::Dependency 
-  name: syckle
+  name: detroit
   prerelease: false
   requirement: &id004 !ruby/object:Gem::Requirement 
     none: false
@@ -67,6 +67,7 @@ extra_rdoc_files:
 - README.rdoc
 files: 
 - .ruby
+- .yardopts
 - bin/qed
 - bin/qedoc
 - lib/qed/advice.rb
@@ -118,8 +119,9 @@ files:
 - test/integration/topcode.rdoc
 - HISTORY.rdoc
 - README.rdoc
+- QED.rdoc
 - LICENSE.rdoc
-homepage: http://proutils.github.com/qed
+homepage: http://rubyworks.github.com/qed
 licenses: []
 
 post_install_message: