quickl 0.2.0 → 0.2.1

data/CHANGELOG.md

@@ -1,3 +1,26 @@
+# 0.2.1 / 2011.06.19
+
+* Enhancements
+
+  * Delegator delegates the command execution to an execute(argv) methods,
+    therefore mimicing Single command
+  * Command provides subcommand_by_name (a class method) allowing to resolve 
+    ':' qualified command names easily. Robustness::has_command! has been
+    rewritten to use the latter method, so that it now striclty respects command
+    hierarchy  
+  * Delegator.summarized_subcommands takes an optional argument, allowing
+    to specify the list of commands for which documentation must be summarized. 
+  * The factory methods Quickl::Command and Quickl::Delegator accept an optional 
+    block which is yield with the command builder.
+  * Command::Builder has a command_parent= accessor allowing to bypass the default 
+    (infered) command strategy feature (advanced usage).
+  * Command::Builder accepts callback blocks that are called when a command is 
+    installed (advanced usage).
+
+* On the devel side
+
+  * The project structure is handled by ruby.noe 1.3.0
+
 # 0.2.0 / 2011-01-10
 
 * Enhancements

data/Gemfile

@@ -0,0 +1,2 @@
+source 'http://rubygems.org'
+gemspec :name => "quickl"

data/Gemfile.lock

@@ -0,0 +1,34 @@
+PATH
+  remote: .
+  specs:
+    quickl (0.2.1)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    bluecloth (2.0.9)
+    diff-lcs (1.1.2)
+    rake (0.8.7)
+    rspec (2.4.0)
+      rspec-core (~> 2.4.0)
+      rspec-expectations (~> 2.4.0)
+      rspec-mocks (~> 2.4.0)
+    rspec-core (2.4.0)
+    rspec-expectations (2.4.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.4.0)
+    wlang (0.10.1)
+    yard (0.6.4)
+
+PLATFORMS
+  java
+  ruby
+
+DEPENDENCIES
+  bluecloth (~> 2.0.9)
+  bundler (~> 1.0)
+  quickl!
+  rake (~> 0.8.7)
+  rspec (~> 2.4.0)
+  wlang (~> 0.10.1)
+  yard (~> 0.6.4)

data/LICENCE.md

@@ -0,0 +1,22 @@
+# The MIT Licence
+
+    Copyright (c) 2011 - Bernard Lambeau
+
+    Permission is hereby granted, free of charge, to any person obtaining
+    a copy of this software and associated documentation files (the
+    "Software"), to deal in the Software without restriction, including
+    without limitation the rights to use, copy, modify, merge, publish,
+    distribute, sublicense, and/or sell copies of the Software, and to
+    permit persons to whom the Software is furnished to do so, subject to
+    the following conditions:
+
+    The above copyright notice and this permission notice shall be
+    included in all copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+    EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+    MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+    NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+    LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+    OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+    WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Manifest.txt

@@ -0,0 +1,15 @@
+quickl.gemspec
+quickl.noespec
+.gemtest
+CHANGELOG.md
+Gemfile
+Gemfile.lock
+bin/**/*
+lib/**/*
+LICENCE.md
+Manifest.txt
+Rakefile
+README.md
+spec/**/*
+tasks/**/*
+test/**/*

data/README.md

@@ -91,28 +91,3 @@ Until version 1.0.0, to preserve your application from hurting changes you shoul
 
     gem 'quickl', '< 0.2.0'    # Assuming current version is 0.1.xx
     require 'quickl'
-
-## Licence
-
-    (The MIT License)
-
-    Copyright (c) 2010 Bernard Lambeau <blambeau@gmail.com>
-
-    Permission is hereby granted, free of charge, to any person obtaining
-    a copy of this software and associated documentation files (the
-    'Software'), to deal in the Software without restriction, including
-    without limitation the rights to use, copy, modify, merge, publish,
-    distribute, sublicense, and/or sell copies of the Software, and to
-    permit persons to whom the Software is furnished to do so, subject to
-    the following conditions:
-
-    The above copyright notice and this permission notice shall be
-    included in all copies or substantial portions of the Software.
-
-    THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
-    EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-    MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-    IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
-    CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
-    TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
-    SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/Rakefile

@@ -1,37 +1,23 @@
-# -*- ruby -*-
-require 'rubygems'
-require "rake/testtask"
-require "rspec/core/rake_task"
-require "yard"
-require "rake/gempackagetask"
-
-task :default => :test
-task :test    => [:spec, :examples]
-
-# About yard documentation
-YARD::Rake::YardocTask.new do |t|
-  t.files   = ['lib/**/*.rb', 'examples/**/*.rb']
-  t.options = ['--output-dir', 'doc/api', '-', "README.md", "CHANGELOG.md"]
+begin
+  gem "bundler", "~> 1.0"
+  require "bundler/setup"
+rescue LoadError => ex
+  puts ex.message
+  abort "Bundler failed to load, (did you run 'gem install bundler' ?)"
 end
 
-desc "Lauches unit tests on examples"
-Rake::TestTask.new(:examples) do |test|
-  test.libs       = [ "lib" ]
-  test.test_files = Dir["examples/**/*_test.rb"]
-  test.verbose    =  true
-end
+# Dynamically load the gem spec
+$gemspec_file = File.expand_path('../quickl.gemspec', __FILE__)
+$gemspec      = Kernel.eval(File.read($gemspec_file))
 
-desc "Run all examples"
-RSpec::Core::RakeTask.new(:spec) do |t|
-	t.rspec_opts = %w[--color]
-	t.verbose = false
-end
+# We run tests by default
+task :default => :test
 
-desc "Create the .gem package"
-$spec = Kernel.eval(File.read(File.expand_path('../quickl.gemspec', __FILE__)))
-Rake::GemPackageTask.new($spec) do |pkg|
-	pkg.need_tar = true
+#
+# Install all tasks found in tasks folder
+#
+# See .rake files there for complete documentation.
+#
+Dir["tasks/*.rake"].each do |taskfile|
+  instance_eval File.read(taskfile), taskfile
 end
-
-
-# vim: syntax=ruby

data/lib/quickl/command/builder.rb

@@ -28,6 +28,18 @@ module Quickl
       end
       alias :instance_module instance_modules
       
+      # Sets the parent of the command currently built
+      def command_parent=(p)
+        @parent = p
+      end
+      
+      # Installs a callback block to execute at 
+      # install time
+      def callback(&block)
+        @callbacks ||= []
+        @callbacks << block
+      end
+      
       # Installs on a command subclass
       def run(command)
         # install class and instance methods
@@ -44,11 +56,16 @@ module Quickl
         end
 
         # install hierarchy
-        parent = RubyTools::parent_module(command)
+        parent = @parent || RubyTools::parent_module(command)
         if parent && parent.ancestors.include?(Command)
           command.super_command = parent
           parent.subcommands << command
         end
+        
+        # execute callbacks
+        @callbacks.each do |blk|
+          blk.call(command)
+        end if @callbacks
       
         command
       end

data/lib/quickl/command/delegator.rb

@@ -10,8 +10,10 @@ module Quickl
           my_argv << argv.shift
         end
         parse_options(my_argv)
+        execute(argv)
+      end
       
-        # Run the subcommand now
+      def execute(argv)
         if cmd = argv.shift
           cmd = has_command!(cmd).run(argv, self)
         else
@@ -22,8 +24,8 @@ module Quickl
     end
     module ClassMethods
       
-      def summarized_subcommands
-        doc = subcommands.collect{|cmd| 
+      def summarized_subcommands(subs = subcommands)
+        doc = subs.collect{|cmd| 
           [cmd.command_name, cmd.overview]
         }
         max = doc.inject(0){|memo,pair| 
@@ -46,13 +48,14 @@ module Quickl
       b.document *args
       b.class_module    Command::Delegator::ClassMethods
       b.instance_module Command::Delegator::InstanceMethods
+      yield(b) if block_given?
     end
     Command
   end
   
   # @see Delegator
-  def self.Delegate(*args)
-    self.Delegator(*args)
+  def self.Delegate(*args, &block)
+    self.Delegator(*args, &block)
   end
   
 end # module Quickl

data/lib/quickl/command/robustness.rb

@@ -6,11 +6,10 @@ module Quickl
       # Checks that a command whose name is given exists
       # or raises a NoSuchCommand.
       def has_command!(name, referer = self.class)
-        name.split(':').inject(referer){|cur,look|
-          cur.const_get(command2module(look))
-        }
-      rescue NameError => ex
-        raise NoSuchCommand, "No such command #{name}", ex.backtrace
+        unless cmd = referer.subcommand_by_name(name)
+          raise NoSuchCommand, "No such command #{name}" 
+        end
+        cmd
       end
       
       # Checks that _file_ is a readable file or raises an error.

data/lib/quickl/command/single.rb

@@ -20,6 +20,7 @@ module Quickl
     command_builder do |b|
       b.document *args
       b.instance_module Command::Single
+      yield(b) if block_given?
     end
     Command
   end

data/lib/quickl/command.rb

@@ -17,6 +17,18 @@ module Quickl
         @subcommands ||= []
       end
       
+      # Returns a subcommand by its name, or nil
+      def subcommand_by_name(name)
+        return nil unless has_sub_commands?
+        look  = name.split(':')
+        found = subcommands.find{|cmd| cmd.command_name == look.first}
+        if found.nil? or (look.size == 1)
+          return found 
+        else
+          found.subcommand_by_name(look[1..-1].join(':'))
+        end
+      end
+      
       # Returns true if this command has at least one 
       # subcommand
       def has_sub_commands?

data/lib/quickl/version.rb

@@ -0,0 +1,14 @@
+module Quickl
+  module Version
+  
+    MAJOR = 0
+    MINOR = 2
+    TINY  = 1
+  
+    def self.to_s
+      [ MAJOR, MINOR, TINY ].join('.')
+    end
+  
+  end 
+  VERSION = Version.to_s
+end

data/lib/quickl.rb

@@ -1,3 +1,5 @@
+require 'quickl/loader'
+require 'quickl/version'
 require 'quickl/ext/object'
 require 'quickl/errors'
 require 'quickl/ruby_tools'
@@ -5,9 +7,6 @@ require 'quickl/naming'
 require 'quickl/command'
 module Quickl
 
-  # Quickl's VERSION
-  VERSION = '0.2.0'.freeze
-  
   # Quickl's COPYRIGHT info 
   COPYRIGHT = "(c) 2010, Bernard Lambeau"
   
@@ -44,4 +43,4 @@ module Quickl
     end
   end
   
-end # module Quickl
+end # module Quickl

data/quickl.gemspec

@@ -1,39 +1,190 @@
-$LOAD_PATH.unshift(File.expand_path('../lib', __FILE__))
-require 'rubygems'
-require 'quickl'
+# We require your library, mainly to have access to the VERSION number. 
+# Feel free to set $version manually.
+$LOAD_PATH.unshift File.expand_path('../lib', __FILE__)
+require "quickl/version"
+$version = Quickl::Version.to_s
 
+#
+# This is your Gem specification. Default values are provided so that your library
+# should be correctly packaged given what you have described in the .noespec file.
+#
 Gem::Specification.new do |s|
-  s.name = 'quickl'
-  s.version = Quickl::VERSION.dup
-  s.date = Time.now.strftime('%Y-%m-%d')
+  
+  ################################################################### ABOUT YOUR GEM
+  
+  # Gem name (required) 
+  s.name = "quickl"
+  
+  # Gem version (required)
+  s.version = $version
+  
+  # A short summary of this gem
+  #
+  # This is displayed in `gem list -d`.
+  s.summary = "Helper to create commandline ruby programs"
 
-  s.summary = 'Generate Ruby command line apps quickly'
-  s.description = 'Generate Ruby command line apps quickly'
+  # A long description of this gem (required)
+  #
+  # The description should be more detailed than the summary.  For example,
+  # you might wish to copy the entire README into the description.
+  s.description = "Quickl helps you creating commandline ruby programs. From simple commands \nwith options to complex delegators with subcommands, global and local \noptions."
+  
+  # The URL of this gem home page (optional)
+  s.homepage = "http://github.com/blambeau/quickl"
 
-  s.author = 'Bernard Lambeau'
-  s.email = 'blambeau@gmail.com'
+  # Gem publication date (required but auto)
+  #
+  # Today is automatically used by default, uncomment only if
+  # you know what you do!
+  #
+  # s.date = Time.now.strftime('%Y-%m-%d')
+  
+  # The license(s) for the library.  Each license must be a short name, no
+  # more than 64 characters.
+  #
+  # s.licences = %w{}
 
-  s.require_paths = %w{ lib }
+  # The rubyforge project this gem lives under (optional)
+  #
+  # s.rubyforge_project = nil
 
-  s.files = 
-    Dir['lib/**/*'] +
-    Dir['examples/**/*'] +
-    Dir['templates/**/*'] +
-    Dir['bin/**/*'] +
-    Dir['test/**/*'] +
-    %w{ quickl.gemspec Rakefile README.md CHANGELOG.md }
+  ################################################################### ABOUT THE AUTHORS
+  
+  # The list of author names who wrote this gem.
+  #
+  # If you are providing multiple authors and multiple emails they should be
+  # in the same order.
+  # 
+  s.authors = ["Bernard Lambeau"]
+  
+  # Contact emails for this gem
+  #
+  # If you are providing multiple authors and multiple emails they should be
+  # in the same order.
+  #
+  # NOTE: Somewhat strangly this attribute is always singular! 
+  #       Don't replace by s.emails = ...
+  s.email  = ["blambeau@gmail.com"]
 
+  ################################################################### PATHS, FILES, BINARIES
+  
+  # Paths in the gem to add to $LOAD_PATH when this gem is 
+  # activated (required).
+  #
+  # The default 'lib' is typically sufficient.
+  s.require_paths = ["lib"]
+  
+  # Files included in this gem.
+  #
+  # By default, we take all files included in the Manifest.txt file on root
+  # of the project. Entries of the manifest are interpreted as Dir[...] 
+  # patterns so that lazy people may use wilcards like lib/**/*
+  #
+  here = File.expand_path(File.dirname(__FILE__))
+  s.files = File.readlines(File.join(here, 'Manifest.txt')).
+                 inject([]){|files, pattern| files + Dir[File.join(here, pattern.strip)]}.
+                 collect{|x| x[(1+here.size)..-1]}
+
+  # Test files included in this gem.
+  #
+  s.test_files = Dir["test/**/*"] + Dir["spec/**/*"]
+
+  # The path in the gem for executable scripts (optional)
+  #
   s.bindir = "bin"
-  s.executables = ["quickl"]
 
-  s.add_development_dependency('rake')
-  s.add_development_dependency('rspec', ">= 2.4.0")
-  s.add_development_dependency('yard', ">= 0.6.4")
-  s.add_development_dependency('bluecloth', ">= 0.6.4")
+  # Executables included in the gem.
+  #
+  s.executables = (Dir["bin/*"]).collect{|f| File.basename(f)}
+
+  ################################################################### REQUIREMENTS & INSTALL
+  # Remember the gem version requirements operators and schemes:
+  #   =  Equals version
+  #   != Not equal to version
+  #   >  Greater than version
+  #   <  Less than version
+  #   >= Greater than or equal to
+  #   <= Less than or equal to
+  #   ~> Approximately greater than
+  #
+  # Don't forget to have a look at http://lmgtfy.com/?q=Ruby+Versioning+Policies 
+  # for setting your gem version.
+  #
+  # For your requirements to other gems, remember that
+  #   ">= 2.2.0"              (optimistic:  specify minimal version)
+  #   ">= 2.2.0", "< 3.0"     (pessimistic: not greater than the next major)
+  #   "~> 2.2"                (shortcut for ">= 2.2.0", "< 3.0")
+  #   "~> 2.2.0"              (shortcut for ">= 2.2.0", "< 2.3.0")
+  #
+
+  #
+  # One call to add_dependency('gem_name', 'gem version requirement') for each
+  # runtime dependency. These gems will be installed with your gem. 
+  # One call to add_development_dependency('gem_name', 'gem version requirement')
+  # for each development dependency. These gems are required for developers
+  #
+  s.add_development_dependency("rake", "~> 0.8.7")
+  s.add_development_dependency("bundler", "~> 1.0")
+  s.add_development_dependency("rspec", "~> 2.4.0")
+  s.add_development_dependency("yard", "~> 0.6.4")
+  s.add_development_dependency("bluecloth", "~> 2.0.9")
+  s.add_development_dependency("wlang", "~> 0.10.1")
+  
+
+  # The version of ruby required by this gem
+  #
+  # Uncomment and set this if your gem requires specific ruby versions.
+  #
+  # s.required_ruby_version = ">= 0"
+
+  # The RubyGems version required by this gem
+  #
+  # s.required_rubygems_version = ">= 0"
+
+  # The platform this gem runs on.  See Gem::Platform for details.
+  #
+  # s.platform = nil
+
+  # Extensions to build when installing the gem.  
+  #
+  # Valid types of extensions are extconf.rb files, configure scripts 
+  # and rakefiles or mkrf_conf files.
+  #
+  s.extensions = []
+  
+  # External (to RubyGems) requirements that must be met for this gem to work. 
+  # It’s simply information for the user.
+  #
+  s.requirements = nil
+  
+  # A message that gets displayed after the gem is installed
+  #
+  # Uncomment and set this if you want to say something to the user
+  # after gem installation
+  #
+  s.post_install_message = nil
+
+  ################################################################### SECURITY
+
+  # The key used to sign this gem.  See Gem::Security for details.
+  #
+  # s.signing_key = nil
+
+  # The certificate chain used to sign this gem.  See Gem::Security for
+  # details.
+  #
+  # s.cert_chain = []
+  
+  ################################################################### RDOC
+
+  # An ARGV style array of options to RDoc
+  #
+  # See 'rdoc --help' about this
+  #
+  s.rdoc_options = []
 
-  s.has_rdoc = true
-  s.rdoc_options = %w< --line-numbers --inline-source --title Quickl --main Quickl >
-  s.extra_rdoc_files = %w< README.md >
+  # Extra files to add to RDoc such as README
+  #
+  s.extra_rdoc_files = Dir["README.md"] + Dir["CHANGELOG.md"] + Dir["LICENCE.md"]
 
-  s.homepage = 'http://github.com/blambeau/quickl'
 end

data/quickl.noespec

@@ -0,0 +1,58 @@
+# Noe template for ruby gem libraries (https://github.com/blambeau/noe) - short version
+# Run 'noe show-spec' and 'noe help show-spec' for additional details.
+
+# Don't remove this entry!
+template-info:
+  name: "ruby"
+  version: 1.3.0
+
+# Update to match your own configuration.
+variables:
+  # A ruby lower case project name.
+  lower: 
+    quickl
+
+  # A ruby upper case project name. 
+  upper:
+    Quickl
+
+  # Version of your library
+  version:
+    0.2.1
+    
+  # Project summary (~ 1 line).
+  summary: |-
+    Helper to create commandline ruby programs
+
+  # Project description (~ 5 lines). Project description should be more complete
+  # than the summary and will be used to describe your gem on rubygems.org
+  description: |-
+    Quickl helps you creating commandline ruby programs. From simple commands 
+    with options to complex delegators with subcommands, global and local 
+    options.
+      
+  # Authors of the project (- {name: Bob, email: bob@gmail.com}, ...) 
+  authors: 
+    - { name: "Bernard Lambeau", email: blambeau@gmail.com }
+
+  # Web links for the project (- http://..., - http://...). 
+  links:
+    - http://github.com/blambeau/quickl
+
+  # Gem dependencies. (- {name: ..., version: ..., groups: [...]}, ...)
+  dependencies: 
+    # Rake is required for developers, as usual
+    - {name: rake,      version: "~> 0.8.7", groups: [development]}
+    # Bundler is required for developers and is used by the Rakefile
+    - {name: bundler,   version: "~> 1.0",   groups: [development]}
+    # RSpec is required to run 'rake spec'. See tasks/spec.rake 
+    - {name: rspec,     version: "~> 2.4.0", groups: [development]}
+    # YARD and BlueCloth are required to run 'rake yard'. See tasks/yard.rake 
+    - {name: yard,      version: "~> 0.6.4", groups: [development]}
+    - {name: bluecloth, version: "~> 2.0.9", groups: [development]}
+    # wlang is required to run 'rake debug_mail'. See tasks/debug_mail.rake
+    - {name: wlang, version: "~> 0.10.1",    groups: [development]}
+
+  rake_tasks:
+    unit_test: 
+      pattern: examples/**/*_test.rb

data/spec/command/command_building_spec.rb

@@ -0,0 +1,16 @@
+require File.expand_path('../../spec_helper', __FILE__)
+module Quickl
+  describe "Command building /" do
+    
+    it "should execute callback methods" do
+      MiniClient::Factored.run.should == :hello
+    end
+    
+    it "should install hierarchy correctly when command_parent= is used" do
+      MiniClient::Factored.super_command.should == MiniClient::Requester
+      MiniClient::Requester.subcommands.should include(MiniClient::Factored)
+      lambda{ MiniClient::Requester.new.has_command!("factored") }.should_not raise_error
+    end
+    
+  end # Command::command_name
+end # module Quickl

data/spec/command/command_name_spec.rb

@@ -0,0 +1,16 @@
+require File.expand_path('../../spec_helper', __FILE__)
+module Quickl
+  describe "Command::command_name /" do
+    
+    it "should be installed from inline rdoc" do
+      MiniClient::Say::Hello.command_name.should == "hello"
+      MiniClient::Say::Goodbye.command_name.should == "goodbye"
+    end
+    
+    it "should be accessible on instance" do
+      MiniClient::Say::Hello.new.command_name.should == "hello"
+      MiniClient::Say::Goodbye.new.command_name.should == "goodbye"
+    end
+
+  end # Command::command_name
+end # module Quickl