quickl 0.1.1

data/CHANGELOG.md

@@ -0,0 +1,9 @@
+# 0.1.1 / 2010-12-24
+
+* Fixed gemspec and binaries problems
+* First official release
+
+# 0.1.0 / 2010-12-22
+
+* Birthday!
+

data/README.md

@@ -0,0 +1,118 @@
+# Quickl
+
+* http://github.com/blambeau/quickl
+
+## Description
+
+Quickl helps you create commandline programs as simply as:
+
+    #
+    # Short description here
+    #
+    # SYNOPSIS
+    #   Usage: ...
+    #
+    # OPTIONS:
+    # #{sumarized_options}
+    #
+    # DESCRIPTION
+    #   Long description here...
+    #
+    class SimpleCommand < Quickl::Command(__FILE__, __LINE__)
+    
+      # install options below
+      options do |opt|
+        # _opt_ is an OptionParser instance
+      end
+      
+      # install the code to run the command
+      def execute(args)
+        # _args_ are non-option command line parameters
+      end
+    
+    end
+    
+Running them as simply as:
+
+    SimpleCommand.run(ARGV)
+    
+From simple command to complex delegate (_ala_ 'git [--version] [--help] COMMAND [cmd options] ARGS...'), Quickl provides (or aims at providing) the following features:
+
+* Simple command creations via simple classes
+* Delegate commands and categories via ruby namespaces and naming conventions
+* Command help and documentation provided through _rdoc_
+* Command options via standard OptionParser
+* Error handling trought special blocks, assertions methods and dedicated Error classes
+* Unit/spec testing of commands, as they are part of the software
+
+## Install
+
+    sudo gem install quickl
+
+## Then?
+
+Try this:
+
+    # have a look at options
+    quickl --help
+  
+    # generate a hello.rb single command
+    quickl --layout=single --options=help,version hello > hello.rb
+  
+    # test your command
+    ruby hello.rb --help
+    ruby hello.rb --version
+    ruby hello.rb bob
+  
+    # see what has been generated
+    cat hello.rb
+  
+Additional examples (see examples folder):
+
+* [hello world example](https://github.com/blambeau/quickl/blob/master/examples/hello_world)
+* [delegate example](https://github.com/blambeau/quickl/blob/master/examples/delegate)
+
+## Version policy
+
+Until version 1.0.0, moditications of public interfaces increase the minor version, while other changes increase the tiny version. After version 1.0.0, same changes will affect major and minor versions, respectively.
+
+    0.1.0 -> 0.1.1    # enhancements and private API changes
+    0.1.0 -> 0.2.0    # broken API on public interfaces
+    
+Public interfaces are:
+
+* Quickl::Command and Quickl::Delegate calls
+* DSL methods used in "subclasses" built by Quickl::Command and Quickl::Delegate
+* RDoc -> command line documentation recognizers (synopsis, overview, documentation, ...)
+* Naming conventions (module <-> command conversions)
+* Default reactions to errors (Quickl::Help, Quickl::Exit, ...)
+
+Until version 1.0.0, to preserve your application from hurting changes you should require quickl as follows:
+
+    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

@@ -0,0 +1,64 @@
+# -*- ruby -*-
+$here = File.dirname(__FILE__)
+require 'rubygems'
+require "rake/testtask"
+require 'spec/rake/spectask'
+require "yard"
+
+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", "HISTORY.md"]
+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
+
+desc "Run all rspec test"
+Spec::Rake::SpecTask.new(:spec) do |t|
+  t.ruby_opts = ['-I.', '-Ilib', '-Itest']
+  t.spec_files = Dir["#{$here}/test/**/*.spec"]
+end
+
+# PACKAGING & INSTALLATION ####################################################
+# Largely inspired from the Citrus project
+
+if defined?(Gem)
+  $spec = eval("#{File.read('quickl.gemspec')}")
+
+  directory 'dist'
+
+  def package(ext='')
+    "dist/#{$spec.name}-#{$spec.version}" + ext
+  end
+
+  file package('.gem') => %w< dist > + $spec.files do |f|
+    sh "gem build quickl.gemspec"
+    mv File.basename(f.name), f.name
+  end
+
+  file package('.tar.gz') => %w< dist > + $spec.files do |f|
+    sh "git archive --format=tar HEAD | gzip > #{f.name}"
+  end
+
+  desc "Build packages"
+  task :package => %w< .gem .tar.gz >.map {|e| package(e) }
+
+  desc "Build and install as local gem"
+  task :install => package('.gem') do |t|
+    sh "gem install #{package('.gem')}"
+  end
+
+  desc "Upload gem to rubygems.org"
+  task :release => package('.gem') do |t|
+    sh "gem push #{package('.gem')}"
+  end
+end
+# vim: syntax=ruby

data/bin/quickl

@@ -0,0 +1,116 @@
+#!/usr/bin/env ruby
+$LOAD_PATH.unshift File.expand_path('../../lib', __FILE__)
+require 'quickl'
+require 'erb'
+
+#
+# Quickl - Generate Ruby command line apps quickly
+#
+# SYNOPSIS
+#   #{program_name} [options] COMMAND_NAME
+#
+# OPTIONS
+# #{summarized_options}
+#
+# DESCRIPTION
+#   This tool helps you generating Ruby command line applications
+#
+class Quickl::Main < Quickl::Command(__FILE__, __LINE__)
+  include Quickl::Naming
+  
+  OPTION_HELPERS = {
+    :version => %q{
+      opt.on_tail('--version', 'Show version and exit'){
+        raise Quickl::Exit, "#{program_name} #{VERSION}"
+      }
+    },
+    :help => %q{
+      opt.on_tail('--help', "Show this help message"){ 
+        raise Quickl::Help 
+      }
+    }
+  }
+  
+  # Name of the command to generate
+  attr_reader :cmd_name
+  
+  # Creates a command instance
+  def initialize
+    @layout = :single
+    @gen_options = [:help, :version]
+  end
+  
+  # Install options
+  options do |opt|
+    
+    opt.on("--layout=LAYOUT", [:single], 
+           "Select specific command layout (single)") do |l|
+      @layout = l
+    end
+    
+    opt.on('--options x,y,z', Array,
+           "Automatically generate options for... (#{OPTION_HELPERS.keys.join(', ')})") do |list|
+      @gen_options = list.collect{|s| s.to_sym}
+      unless (unknown = @gen_options.reject{|s| OPTION_HELPERS.has_key?(s)}).empty?
+        raise Quickl::InvalidOption, "Unknown option helpers: #{unknown.join(',')}"
+      end
+    end
+    
+    # Show the help and exit
+    opt.on_tail("--help", "Show help") do
+      raise Quickl::Help
+    end
+
+    # Show version and exit
+    opt.on_tail("--version", "Show version") do
+      raise Quickl::Exit, "#{program_name} #{Quickl::VERSION} #{Quickl::COPYRIGHT}"
+    end
+    
+  end
+  
+  # Loads template to use
+  def template
+    @template ||= File.expand_path("../../templates/#{@layout}.erb", __FILE__)
+  end
+
+  # Execute the command
+  def execute(args)
+    if args.size == 1
+      @cmd_name = args.shift
+      erb = ERB.new(File.read(template))
+      $stdout.puts erb.result(binding)
+    else
+      raise Quickl::InvalidArgument, "Invalid arguments: #{args.join(' ')}"
+    end
+  end
+
+  ### ERB scoping
+
+  # Class name of the command to generate
+  def cmd_class_name
+    command2module(cmd_name)
+  end
+  
+  def indent(str, offset)
+    if offset >= 0
+      str.gsub(/^/, ' ' * offset)
+    else
+      str.gsub(/^ {0,#{-offset}}/, "")
+    end
+  end
+      
+  def tabto(str, offset)
+    if str =~ /^( *)\S/
+      indent(str, offset - $1.length)
+    else
+      str
+    end
+  end
+
+  # Returns option helpers to include
+  def option_helpers
+    @gen_options.collect{|s| tabto(OPTION_HELPERS[s], 0).strip}
+  end
+  
+end # class Quickl::Command::Main
+Quickl::Main.run(ARGV)

data/examples/delegate/README.md

@@ -0,0 +1,86 @@
+# Quickl example: delegate
+
+This example shows how to delegate commands. Delegate commands are command
+that delegate the actual execution to sub commands (well known example is
+'git'). A delegate command typically has a signature like:
+
+    delegate [main options] COMMAND [cmd options] ARGS...
+
+## Structure
+
+The structure for delegate commands is as follows:
+
+    #
+    # Main command overview
+    #
+    # SYNOPSIS
+    #   Usage: #{command_name} [main options] COMMAND [cmd options] ARGS...
+    #
+    # OPTIONS
+    # #{sumarized_options}
+    #
+    # COMMANDS
+    # #{summarized_commands}
+    #
+    # DESCRIPTION
+    #   Long description here...
+    #
+    # See '#{command_name} help COMMAND' for more information on a specific command.
+    #
+    class DelegateCommand < Quickl::Delegate(__FILE__, __LINE__)
+    
+      # install options below
+      options do |opt|
+        # _opt_ is an OptionParser instance
+      end
+      
+      #
+      # Sub command overview
+      # 
+      # ...
+      #
+      class SubCommand1 < Quickl::Command(__FILE__, __LINE__)
+      
+        # [ ... ]
+      
+      end
+      
+      #
+      # Sub command overview
+      # 
+      # ...
+      #
+      class SubCommand2 < Quickl::Command(__FILE__, __LINE__)
+      
+        # [ ... ]
+      
+      end
+      
+    end 
+    
+    # To run the command, typically in a bin/simple_command 
+    # shell file
+    DelegateCommand.run(ARGV)
+    
+
+## Example
+
+Try the following:
+
+    ./delegate 
+    # => [ ... complete help with subcommands summary ... ]
+    
+    ./delegate --help
+    # => [ ... complete help with subcommands summary ... ]
+    
+    ./delegate help 
+    # => [ ... complete help with subcommands summary ... ]
+    
+    ./delegate help hello-world 
+    # => [ ... help of hello-world's subcommand ... ]
+
+    ./delegate hello-world bob
+    # => Hello bob!
+    
+    ./hello_world --capitalize bob
+    # => Hello Bob!

data/examples/delegate/bin/delegate

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+require File.expand_path('../../../helper', __FILE__)
+
+# Load the delegate tool
+$LOAD_PATH.unshift File.expand_path('../../lib', __FILE__)
+require "delegate"
+
+# Run the command
+Delegate.run(ARGV)

data/examples/delegate/lib/delegate.rb

@@ -0,0 +1,41 @@
+#
+# Delegate execution to a sub command
+#
+# SYNOPSIS
+#   #{program_name} [--version] [--help] [--output=...] COMMAND [cmd opts] ARGS...
+#
+# OPTIONS
+# #{summarized_options}
+#
+# COMMANDS
+# #{summarized_subcommands}
+#
+# DESCRIPTION
+#   This example shows how to write a delegate command, that is, a
+#   command which delegates to a subcommand
+#
+# See '#{program_name} help COMMAND' for more information on a specific command.
+#
+class Delegate < Quickl::Delegate(__FILE__, __LINE__)
+
+  # Single command version
+  VERSION = "0.1.0"
+  
+  # Install options
+  options do |opt|
+    
+    # Show the help and exit
+    opt.on_tail("--help", "Show help") do
+      raise Quickl::Help
+    end
+
+    # Show version and exit
+    opt.on_tail("--version", "Show version") do
+      raise Quickl::Exit, "#{program_name} #{VERSION} (c) 2010, Bernard Lambeau"
+    end
+
+  end
+
+end # class Delegate
+require "help"
+require "hello_world"