qed 2.4.0 → 2.5.0

data/History.rdoc

@@ -1,5 +1,21 @@
 = RELEASE HISTORY
 
+== 2.5.0 / 2010-11-04
+
+The latest release of QED improves on applique loading, such that each
+demonstrandum gets it's own localized set. The CLI has also been modified
+so that there is no longer a defualt location, the directory or files to run
+must be specified.
+
+Changes:
+
+* Better handling of Applique.
+* Remove Advice class --advice is now stored in Applique.
+* Each applique file is it's own module.
+* Advice from each applique is applied.
+* CLI requires files be specified.
+
+
 == 2.4.0 / 2010-09-02
 
 All engines go! QED has not been tested against 1.8.6, 1.8.7 and 1.9.2.
@@ -141,7 +157,7 @@ Changes:
 * New system of version numbers.
 
 
-== 1.2 / 2009-12-07
+== 1.2.0 / 2009-12-07
 
 This release adds a significant new feature, Comment Matchers.
 These work like Cucumber allowing for background code to
@@ -161,7 +177,7 @@ Changes:
   * Verbatim reporter is literally verbatim.
 
 
-== 1.1 / 2009-09-05
+== 1.1.1 / 2009-09-05
 
 This release 
 
@@ -178,7 +194,7 @@ Changes:
   * Use latest RDoc version.
 
 
-== 1.0 / 2009-06-30
+== 1.0.0 / 2009-06-30
 
 QED has found itself. It took some time to really figure out
 what this project "was" and how it should best be utilized.

data/README.rdoc

@@ -1,9 +1,5 @@
 = Ruby Q.E.D.
 
-     homepage: http://proutils.github.com/qed
-  mailing list: http://groups.google.com/group/proutils
-   development: http://github.com/proutils/qed
-
 
 == Introduction
 
@@ -30,6 +26,13 @@ of abstract, from unit test to systems tests.
 * Documentation tool provides nice output with jQuery-based TOC.
 
 
+== Resources
+
+* homepage: http://rubyworks.github.com/qed
+* mailing list: http://groups.google.com/group/rubyworks
+* development: http://github.com/rubyworks/qed
+
+
 == Synopsis
 
 === Assertion Syntax
@@ -43,7 +46,7 @@ In this example, because 4 != 5, this expression will raise an Assertion
 exception. QED's Runner class is thus just a means of running and capturing
 code blocks containing these assertions.
 
-You can learn more about AE at http://proutils.github.com/ae.
+You can learn more about AE at http://rubyworks.github.com/ae.
 
 === Document Structure
 

data/lib/qed/advice.rb

@@ -1,13 +1,14 @@
-require 'qed/core_ext/instance_exec'
+raise "no needed any more"
+
+require 'qed/core_ext'
 
 module QED
 
   # = Advice
   #
-  # This class tracks advice defined by demonstrandum
-  # and applique. It is instantiated in Scope, so that
-  # the advice methods will have access to the same
-  # local binding as the scripts themselves.
+  # This class tracks advice defined by demonstrandum and applique.
+  # Advice are evaluated in Scope, so that they will have access
+  # to the same local binding as the scripts themselves.
   #
   # There are two types of advice: *pattern matchers*
   # and *event signals*.
@@ -36,13 +37,18 @@ module QED
       @signals  = [{}]
     end
 
+    #
+    #def initialize_copy(other)
+    #  @matchers = other.matchers.dup
+    #  @signals  = other.signals.dup
+    #end
+
     #
     def call(scope, type, *args)
       case type
       when :when
         call_matchers(scope, *args)
       else
-        #@events.call(scope, type, *args)
         call_signals(scope, type, *args)
       end
     end
@@ -122,7 +128,7 @@ module QED
     # contains double parenthesis, such as ((.*?)), then the text within
     # them is treated as in regular expression and kept verbatium.
     #
-    # TODO: Better way to isolate regexp. Maybe "?:(.*?)".
+    # TODO: Better way to isolate regexp. Maybe ?:(.*?) or /(.*?)/.
     #
     # TODO: Now that we can use multi-patterns, do we still need this?
     #

data/lib/qed/applique.rb

@@ -1,62 +1,88 @@
-require 'qed/advice'
-
 module QED
 
-  # The Applique is the environment of libraries required by
-  # and the rules to apply to demonstrandum. The applique is
-  # defined by a set of scripts located in the +applique+ 
-  # directory of the upper-most test directory relative to
-  # the tests run and below the root of a project. All
-  # applique scripts are loaded at the start of a test
-  # session. Thus all demos belong to one and only one
-  # applique, and all the scripts in an applique must be
-  # compatible/consistant. For two demos to have separate
-  # applique they must be kept in separate directores.
-
+  # Applique is a module built per-script from the +applique+ dirctory.
+  # Applique scripts are loaded at the start of a session.
+  #
+  # <i>The Applique</i> is whole collection of applique that apply to given
+  # demonstrandum. The applique that apply are the scripts located in the
+  # directory relative to the demonstrandum script and all such directories
+  # above this upto and the project's root directory.
+  #
+  # All scripts in the Applique must be compatible/consistant. For two demos to
+  # have separate applique must be kept in separate directores.
+  #
   class Applique < Module
 
+    # Load cache.
+    def self.cache
+      @cache ||= {}
+    end
+
+    class << self
+      alias_method :_new, :new
+    end
+
+    # New method caches Applique based-on +file+, if given.
+    #--
+    # TODO: may need to expand file to be absolute path
+    #++
+    def self.new(file=nil)
+      if file
+        cache[file] ||= _new(file)
+      else
+        _new(file)
+      end
+    end
+
     #
-    def initialize
+    def initialize(file=nil)
       super()
       extend self
-      @__advice__ = Advice.new
+
+      @__matchers__ = []
+      @__signals__  = {}
+
+      if file
+        @file = file
+        module_eval(File.read(file), file)
+      end
     end
 
     #
     def initialize_copy(other)
-      @__advice__ = other.__advice__.dup
+      @__matchers__ = other.__matchers__.dup
+      @__signals__  = other.__signals__.dup
     end
 
-    # Redirect missing constants to Object class 
-    # to simulate TOPLEVEL.
-    #
-    # TODO: Clean backtrace when constant is not found.
-    def const_missing(name)
-      Object.const_get(name)
-    end
+    # Array of matchers.
+    attr :__matchers__
 
-    #
-    def __advice__
-      @__advice__
-    end
+    # Hash of signals.
+    attr :__signals__
 
     # Pattern matchers and "upon" events.
     def When(*patterns, &procedure)
       if patterns.size == 1 && Symbol === patterns.first
-        __advice__.add_event(patterns.first, &procedure)
+        type = "#{patterns.first}".to_sym
+        @__signals__[type] = procedure
+        #define_method(type, &procedure)
       else
-        __advice__.add_match(patterns, &procedure)
+        @__matchers__ << [patterns, procedure]
       end
     end
 
     # Before advice.
     def Before(type=:code, &procedure)
-      __advice__.add_event(:"before_#{type}", &procedure)
+      type = "before_#{type}".to_sym
+      @__signals__[type] = procedure
+      #define_method(type, &procedure)
     end
 
     # After advice.
     def After(type=:code, &procedure)
-      __advice__.add_event(:"after_#{type}", &procedure)
+      type = "after_#{type}".to_sym
+      @__signals__[type] = procedure
+      #define_method(type, &procedure)
     end
 
     # Code match-and-transform procedure.
@@ -77,6 +103,14 @@ module QED
     #
     #end
 
+    # Redirect missing constants to Object class 
+    # to simulate TOPLEVEL.
+    #
+    # TODO: Clean backtrace when constant is not found.
+    def const_missing(name)
+      Object.const_get(name)
+    end
+
   end
 
 end

data/lib/qed/command.rb

@@ -1,5 +1,6 @@
 require 'optparse'
 require 'shellwords'
+require 'fileutils'
 
 module QED
 
@@ -7,7 +8,7 @@ module QED
     Command.main(*argv)
   end
 
-  # = QED Commandline Tool
+  # QED Command-line tool.
   #
   # TODO: Merge Command with Session ?
   class Command
@@ -19,18 +20,30 @@ module QED
     # scenarios.
     CONFIG_PATTERN = "{.,.config/,config/}qed"
 
-    # Default location of demonstrations if no specific files
-    # or locations given. This is use in Dir.glob. The default
-    # locations are qed/, demo/ or demos/, searched for in that
-    # order relative to the root directory.
-    DEMO_LOCATION = '{qed,demo,demos}'
+    ## Default location of demonstrations if no specific files
+    ## or locations given. This is use in Dir.glob. The default
+    ## locations are qed/, demo/ or demos/, searched for in that
+    ## order relative to the root directory.
+    ##--
+    ## TODO: deprecate this
+    ##++
+    ##DEMO_LOCATION = '{qed,demo,demos}'
 
     # Glob pattern used to search for project's root directory.
-    ROOT_PATTERN = '{.root,.git,.hg,_darcs}/'
+    ROOT_PATTERN = '{.ruby,.git/,.hg/,_darcs/,.qed/,.config/qed/,config/qed/}'
+
+    # Directory names to omit from automatic selection.
+    OMIT_PATHS = %w{applique helpers support sample samples fixture fixtures}
 
     # Home directory.
     HOME = File.expand_path('~')
 
+    # Default recognized demos file types.
+    DEMO_TYPES = %w{qed rdoc md markdown}
+
+    #
+    CODE_TYPES = %w{rb}
+
     # Instantiate a new Command object and call #execute.
     def self.main(*argv)
       new.execute(argv)
@@ -51,10 +64,10 @@ module QED
     attr :profile
 
     # Command-line options.
-    attr :options
+    #attr :options
 
     # Files to be run.
-    attr :files
+    attr_reader :files
 
     # Ensure files are in a flat list.
     def files=(globs)
@@ -67,83 +80,84 @@ module QED
     # Libraries to be required.
     attr_accessor :requires
 
-    # ?
-    attr_accessor :extension
-
     # Move to root directory?
     attr_accessor :root
 
     # Parse mode.
     attr_accessor :mode
 
+    #
+    attr_accessor :omit
+
     #
     # TODO: Should extension and profile have a common reference?
     def initialize
       @format    = :dotprogress
-      @extension = :default
+      #@extension = :default
       @profile   = :default
       @requires  = []
       @loadpath  = []
       @files     = []
-      @options   = {}
+      #@options   = {}
+
+      @omit      = OMIT_PATHS
     end
 
     # Instance of OptionParser
     def opts
       @opts ||= OptionParser.new do |opt|
+        opt.banner = "Usage: qed [options] <files...>"
 
         opt.separator("Custom Profiles:") unless profiles.empty?
 
         profiles.each do |name, value|
           o = "--#{name}"
           opt.on(o, "#{name} custom profile") do
-            @profile = name
+            self.profile = name
           end
         end
 
         opt.separator("Report Formats (pick one):")
         opt.on('--dotprogress', '-d', "use dot-progress reporter [default]") do
-          @options[:format] = :dotprogress
+          self.format = :dotprogress
         end
         opt.on('--verbatim', '-v', "use verbatim reporter") do
-          @options[:format] = :verbatim
+          self.format = :verbatim
         end
         opt.on('--bullet', '-b', "use bullet-point reporter") do
-          @options[:format] = :bullet
+          self.format = :bullet
         end
         opt.on('--html', '-h', "use underlying HTML reporter") do
-          @options[:format] = :html
-        end
-        opt.on('--format', '-f FORMAT', "use custom reporter") do |format|
-          @options[:format] = format
+          self.format = :html
         end
         #opt.on('--script', "psuedo-reporter") do
-        #  @options[:format] = :script  # psuedo-reporter
+        #  self.format = :script  # psuedo-reporter
         #end
+        opt.on('--format', '-f FORMAT', "use custom reporter") do |format|
+          self.format = format
+        end
         opt.separator("Control Options:")
-        opt.on('--root', '-R', "run command from project's root directory") do
-          @options[:root] = true
+        opt.on('--root', '-R', "run from alternate directory") do |path|
+          self.root = path
         end
         opt.on('--comment', '-c', "Run comment code.") do
-          @options[:mode] = :comment
+          self.mode = :comment
         end
-        opt.on('--ext', '-e NAME', "runtime extension [default]") do |name|
-          @options[:extension] = name
+        opt.on('--profile', '-p NAME', "load runtime profile") do |name|
+          self.profile = name
         end
-        opt.on('--loadpath', "-I PATH", "add paths to $LOAD_PATH") do |arg|
-          @options[:loadpath] ||= []
-          @options[:loadpath].concat(arg.split(/[:;]/).map{ |dir| File.expand_path(dir) })
+        opt.on('--loadpath', "-I PATH", "add paths to $LOAD_PATH") do |paths|
+          self.loadpath = paths.split(/[:;]/).map{|d| File.expand_path(d)}
         end
-        opt.on('--require', "-r LIB", "require library") do |arg|
-          @options[:requires] ||= []
-          @options[:requires].concat(arg.split(/[:;]/)) #.map{ |dir| File.expand_path(dir) })
+        opt.on('--require', "-r LIB", "require library") do |paths|
+          self.requires = paths.split(/[:;]/)
         end
         opt.on('--trace', '-t', "show full backtraces for exceptions") do
-          @options[:trace] = true
+          self.trace = true
         end
         opt.on('--debug', "exit immediately upon raised exception") do
           $VERBOSE = true # wish this were called $WARN
-          $DEBUG = true
+          $DEBUG   = true
         end
         opt.separator("Optional Commands:")
         opt.on_tail('--version', "display version") do
@@ -151,7 +165,7 @@ module QED
           exit
         end
         opt.on_tail('--copyright', "display copyrights") do
-          puts "Copyright (c) 2008, 2009 Thomas Sawyer, GPL License"
+          puts "Copyright (c) 2008 Thomas Sawyer, Apache 2.0 License"
           exit
         end
         opt.on_tail('--help', '-h', "display this help message") do
@@ -161,10 +175,6 @@ module QED
       end
     end
 
-    # Default recognized demos file types.
-    DEMO_TYPES = %w{qed rdoc md markdown}
-    CODE_TYPES = %w{rb}
-
     # Returns a list of demo files. The files returned depends on the
     # +files+ attribute and if none given, then the current run mode.
     def demos
@@ -179,25 +189,23 @@ module QED
 
     # Collect default files to process in normal demo mode.
     def demos_in_normal_mode
-      demos_gather(DEMO_LOCATION, DEMO_TYPES)
+      demos_gather(DEMO_TYPES)
     end
 
     # Collect default files to process in code comment mode.
     #
-    # TODO: Sure removing applique files is the best approach?
-    #
-    # TODO: Either add environment alond with applique or deprecate environment
-    # as an alternate name.
+    # TODO: Sure removing applique files is the best approach here?
     def demos_in_comment_mode
-      files = demos_gather('lib', CODE_TYPES)
+      files = demos_gather(CODE_TYPES)
       files = files.reject{ |f| f.index('applique/') }  # don't include applique files ???
       files
     end
 
-    #
-    def demos_gather(default_location, extensions=DEMO_TYPES)
+    # Gather list of demo files. Uses +omit+ to remove certain files
+    # based on the name of their parent directory.
+    def demos_gather(extensions=DEMO_TYPES)
       files = self.files
-      files << default_location if files.empty?
+      #files << default_location if files.empty?
       files = files.map{|pattern| Dir[pattern]}.flatten.uniq
       files = files.map do |file|
         if File.directory?(file)
@@ -207,6 +215,7 @@ module QED
         end
       end
       files = files.flatten.uniq
+      files = files.reject{ |f| f =~ Regexp.new('\/'+omit.join('|')+'\/') }
       files.map{|f| File.expand_path(f) }.uniq.sort
     end
 
@@ -217,33 +226,39 @@ module QED
       #@files.concat(argv)
       @files = argv
 
-      #if profile
-      if args = profiles[profile]
-        argv = Shellwords.shellwords(args)
-        opts.parse!(argv)
-        @files.concat(argv)
+      if @files.empty?
+        puts "No files."
+        puts opts
+        exit
       end
+
+      #if profile
+      #if args = profiles[profile]
+      #  argv = Shellwords.shellwords(args)
+      #  opts.parse!(argv)
+      #  @files.concat(argv)
+      #end
       #end
 
-      options.each do |k,v|
-        __send__("#{k}=", v)
-      end
+      #options.each do |k,v|
+      #  __send__("#{k}=", v)
+      #end
     end
 
     # Run demonstrations.
     def execute(argv)
       parse(argv)
 
-      jump = @options[:root] ? root_directory : Dir.pwd
+      abort "No documents." if demos.empty?
 
-      Dir.chdir(jump) do
-        abort "No documents." if demos.empty?
+      prepare_loadpath
+      require_libraries
 
-        prepare_loadpath
+      require_profile  # TODO: here or in chdir?
 
-        require_libraries
-        require_profile
+      jump = root || temporary_directory
 
+      Dir.chdir(jump) do
         session.run
       end
     end
@@ -266,8 +281,10 @@ module QED
     # Profile configurations.
     def profiles
       @profiles ||= (
-        file = Dir["#{config_directory}/profile{,s}.{yml,yaml}"].first
-        file ? YAML.load(File.new(file)) : {}
+        files = Dir["#{config_directory}/*.rb"]
+        files.map do |file|
+          File.basename(file).chomp('.rb')
+        end
       )
     end
 
@@ -284,19 +301,31 @@ module QED
     # Require requirement file (from -e option).
     def require_profile
       return unless config_directory
-      if file = Dir["#{config_directory}/#{extension}.rb"].first
+      if file = Dir["#{config_directory}/#{profile}.rb"].first
         require(file)
       end
     end
 
+    #
+    def temporary_directory
+      @temporary_directory ||= (
+        dir = File.join(root_directory, 'tmp', 'qed')
+        FileUtils.mkdir_p(dir)
+        dir
+      )
+    end
+
     # Locate project's root directory. This is done by searching upward
     # in the file heirarchy for the existence of one of the following
     # path names, each group being tried in turn.
     #
-    # * .root/
     # * .git/
     # * .hg/
     # * _darcs/
+    # * .config/qed/
+    # * config/qed/
+    # * .qed/
+    # * .ruby
     #
     # Failing to find any of these locations, resort to the fallback:
     # 
@@ -318,19 +347,26 @@ module QED
       root = lookup('lib/', path)
       return root if root
 
-      abort "Failed to resolve project's root location. Try adding a .root directory."
+      abort "QED failed to resolve project's root location.\n" +
+            "QED looks for following entries to identify the root:\n" +
+            "  .config/qed/\n" +
+            "  config/qed/\n" +
+            "  .qed/\n" +
+            "  .ruby\n" +
+            "  lib/\n" +
+            "Please add one of them to your project to proceed."
     end
 
     # Locate configuration directory by seaching up the 
     # file hierachy relative to the working directory
     # for one of the following paths:
     #
-    # * .qed/
     # * .config/qed/
     # *  config/qed/
+    # * .qed/
     #
     def find_config
-      lookup(CONFIG_PATTERN)
+      Dir[File.join(root_directory,CONFIG_PATTERN)].first
     end
 
     # Lookup path +glob+, searching each higher directory