cp 0.0.1.pre1 → 0.0.1

data/README.md

@@ -0,0 +1,55 @@
+CP
+==
+
+Write complex command line scripts simply.
+
+CP provides an API to write command line scripts with nested subcommands
+and switches.
+
+Rather than reinventing the wheel, CP calls on the time tested [CmdParse][] gem
+to do the heavy lifting, wrapping it in an updated API and adding a handful of
+new features.
+
+Roadmap
+-------
+
+CP aims to provide:
+
+  * Automatic help generation
+  * Any number of nested subcommands
+  * Global and command-specific switches
+
+Credit
+------
+
+CP's API was inspired by the Commander gem.
+
+I decided I didn't personally like parts
+of the Commander API.  I forked Commander and began adding features, but found
+it difficult to extend, and started work on CP instead.
+
+[CmdParse]: http://cmdparse.rubyforge.org/
+
+License
+-------
+
+(The MIT License)
+
+Copyright © 2011 Rick Fletcher <fletch@pobox.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/cp.gemspec

@@ -8,7 +8,7 @@ Gem::Specification.new do |s|
   s.platform    = Gem::Platform::RUBY
   s.authors     = ["Rick Fletcher"]
   s.email       = ["fletch@pobox.com"]
-  s.homepage    = ""
+  s.homepage    = "https://github.com/baseballdb/cp"
   s.summary     = %q{An alternative API for CmdParse}
   s.description = %q{CP provides a less verbose API for the CmdParse gem.}
 
@@ -18,5 +18,4 @@ Gem::Specification.new do |s|
   s.require_paths = ["lib"]
 
   s.add_runtime_dependency(%q<cmdparse>, [">= 2.0.2"])
-  s.add_runtime_dependency(%q<cmdparse>, [">= 2.0.2"])
 end

data/examples/net.rb

@@ -1,13 +1,18 @@
 ##
 # A port of the CmdParse tutorial app, net.rb
+#
+# This app doesn't really do much of anything.  It's meant as an example of
+# the difference in API from CmdParse to CP.
+#
 # original: http://cmdparse.rubyforge.org/tutorial.html
 #
 
 $: << File.join( ".", File.dirname( __FILE__ ), "..", "lib" )
 
+require "yaml"
 require "cp"
 
-include CP
+extend CP
 
 $ipaddrs = []
 $verbose = false
@@ -16,18 +21,18 @@ app :name, "net"
 app :version, "0.1.1"
 
 # global options
-option( "--verbose", "Be verbose when outputting info" ) { |t| $verbose = true }
+option "--verbose", "Be verbose when outputting info", lambda { |v| $verbose = true }
 
 # add the top-level "ipaddr" command
 command :ipaddr do |c|
-  # c.allow_partial! # partial commands aren't implemented
+  c.default = true
   c.summary = "Manage IP addresses"
 
   # add the "add" subcommand
   c.command( :add ) do |s|
     s.summary = "Add an IP address"
 
-    s.execute do |*args|
+    s.execute do |opts, args|
       puts "Adding IP addresses: #{args.join(', ')}" if $verbose
       $ipaddrs += args
     end
@@ -39,7 +44,7 @@ command :ipaddr do |c|
 
     s.option( "-a", "--all", "Delete all IP addresses" ){ $deleteAll = true }
 
-    s.execute do |*args|
+    s.execute do |opts, args|
       if $deleteAll
         $ipaddrs = []
       else
@@ -51,7 +56,7 @@ command :ipaddr do |c|
 
   # add the "list" subcommand
   c.command :list do |s|
-#    s.default! # make :list the default subcommand
+    s.default = true
     s.summary = "List all IP addresses"
 
     s.execute do |*args|
@@ -65,7 +70,7 @@ command :ipaddr do |c|
     s.summary = "Show network statistics"
     s.description = "This command shows very useful network statistics - eye catching!!!"
 
-    s.execute do |*args|
+    s.execute do |opts, args|
       puts "Showing network statistics" if $verbose
       puts
       puts "Yeah, I will do something now..."
@@ -77,5 +82,3 @@ command :ipaddr do |c|
     end
   end
 end
-
-run

data/lib/cp.rb

@@ -1,22 +1,36 @@
 require "rubygems"
 require "cmdparse"
+require "optparse"
 
-require "cp/runners/cmd_parse"
-require "cp/commands"
-require "cp/options"
+require "cp/has/commands"
+require "cp/has/options"
+
+require "cp/app"
 require "cp/command"
-require "cp/version"
+require "cp/errors"
 require "cp/option"
-require "cp/app"
+require "cp/options_struct"
+require "cp/runners/cmd_parse"
+require "cp/version"
 
 module CP
-  def self.included( scope )
-    scope.extend( self )
+  def self.included( klass )
+    klass.extend( self )
+    klass.class_eval do
+      def self.run
+        CP::App.run
+      end
+    end
+  end
+
+  def self.extended( instance )
+    is_main = instance.class === Object && instance.inspect === "main"
+    at_exit { CP::App.run } if is_main
   end
 
-  [:app, :command, :option, :run].each do |method|
+  [:app, :command, :option].each do |method|
     define_method( method ) { |*args, &block|
-      App.instance.send( method, *args, &block )
+      CP::App.instance.send( method, *args, &block )
     }
   end
 end

data/lib/cp/app.rb

@@ -4,12 +4,13 @@ module CP
   class App
     include ::Singleton
 
-    include CP::Commands
-    include CP::Options
+    include CP::Has::Commands
+    include CP::Has::Options
 
     attr_accessor :name, :version, :runner
 
     def initialize
+      self.name = File.basename( $0 )
       self.runner = CP::Runners::CmdParse
     end
 
@@ -21,8 +22,21 @@ module CP
       end
     end
 
-    def run
-      self.runner.new( self ).run
+    def fatal( msg )
+      self.error( msg )
+      exit 1
+    end
+
+    def error( msg )
+      $stderr.puts "#{self.name}: #{msg}.  See `#{self.name} --help`."
+    end
+
+    def run( *args )
+      CP::App.instance.runner.new( CP::App.instance ).run( *args )
+    end
+
+    def self.run( *args )
+      CP::App.instance.run( *args )
     end
   end
 end

data/lib/cp/command.rb

@@ -1,23 +1,54 @@
 module CP
   class Command
-    include CP::Commands
-    include CP::Options
+    include CP::Has::Commands
+    include CP::Has::Options
 
-    attr_reader :block, :name
-    attr_accessor :description, :summary
+    attr_reader :block, :name, :parent
+    attr_accessor :default, :description, :summary
 
-    def initialize( name )
+    def initialize( name, parent=nil )
       unless name.respond_to?( :to_sym )
-        raise ArgumentError.new( "parameter must be a Symbol (or respond to .to_sym)")
+        raise ArgumentError.new( "name must be a Symbol (or respond to .to_sym)")
       end
 
+      @parent = parent
       @name = name.to_sym
 
       yield self if block_given?
     end
 
     def execute( &block )
-      @block = block
+      @block = lambda { |args|
+        begin
+          opts = gather_options
+        rescue CP::MissingOptionError => e
+          CP::App.instance.fatal( "'#{e}' is required" )
+        end
+
+        block.call( args, opts )
+      }
+    end
+
+  private
+
+    def gather_options
+      options = []
+
+      current = self
+      begin
+        options += current.options
+        current = current.respond_to?( :parent ) ? current.parent : nil
+      end while current && current.respond_to?( :options )
+
+      option_names = options.map { |o|
+        raise CP::MissingOptionError.new( o.switches.last ) if o.required? && o.value.nil?
+        o.name
+      }.sort.uniq
+
+      struct = CP::OptionsStruct.new( *option_names )
+
+      options.reverse.each { |o| struct[o.name] = o.value }
+      struct
     end
   end
 end

data/lib/cp/errors.rb

@@ -0,0 +1,4 @@
+module CP
+  class CommandError < StandardError; end
+  class MissingOptionError < StandardError; end
+end

data/lib/cp/has/commands.rb

@@ -0,0 +1,34 @@
+module CP
+  module Has
+    module Commands
+      def commands
+        @commands ||= []
+        @commands
+      end
+
+      def command( name )
+        cmd = name.to_s.split( " " ).inject( self ) do |parent, name|
+          subcommand = parent.commands.find { |c| c.name === name.to_sym }
+
+          if subcommand.nil?
+            subcommand = CP::Command.new( name, parent )
+            parent.commands << subcommand
+          end
+
+          subcommand
+        end
+
+        yield cmd if block_given?
+
+        if cmd.default
+          default_cmd = commands.find{ |c| c.default }
+          if default_cmd
+            raise CP::CommandError.new( "only one default command is allowed: #{default_cmd.name}, #{cmd.name}" )
+          end
+        end
+
+        cmd
+      end
+    end
+  end
+end

data/lib/cp/has/options.rb

@@ -0,0 +1,17 @@
+module CP
+  module Has
+    module Options
+      def options
+        @options ||= []
+        @options
+      end
+
+      def option( *args )
+        opt = CP::Option.new( *args )
+        yield opt if block_given?
+        options << opt
+        opt
+      end
+    end
+  end
+end

data/lib/cp/option.rb

@@ -2,11 +2,12 @@ require "optparse"
 
 module CP
   class Option
-    attr_accessor :allowed, :type, :block, :description, :required
-    attr_reader :arg, :short, :long
+    attr_accessor :allowed, :default, :description, :type
+    attr_reader :arg, :block, :short, :long
 
     # see: OptionsParser#make_switch
     def initialize( *args )
+      @required = false
       parsed = parse_args( args )
 
       yield self if block_given?
@@ -19,6 +20,13 @@ module CP
       end
     end
 
+    def block=( block=nil )
+      @block = lambda { |value|
+        @value = value
+        block.call( *( block.arity === 0 ? [] : [value] ) ) if block
+      }
+    end
+
     def long=( val )
       set_switch( :long, val )
     end
@@ -32,6 +40,14 @@ module CP
       name.gsub( "-", "_" ).to_sym
     end
 
+    def required=( val )
+      @required = !!val
+    end
+
+    def required?
+      @required
+    end
+
     def short=( val )
       set_switch( :short, val )
     end
@@ -51,6 +67,10 @@ module CP
       args.find_all { |a| !a.nil? }
     end
 
+    def value
+      @value.nil? ? self.default : @value
+    end
+
   private
 
     def parse_args( args )

data/lib/cp/options_struct.rb

@@ -0,0 +1,7 @@
+module CP
+  class OptionsStruct
+    def self.new( *properties )
+      Struct.new( "Options", *properties ).new
+    end
+  end
+end

data/lib/cp/runners/cmd_parse.rb

@@ -4,21 +4,42 @@ require "cmdparse"
 module CP
   module Runners
     class CmdParse
-      attr_reader :runner
-
       def initialize( app )
         @app = app
       end
 
-      def run
-        @runner = ::CmdParse::CommandParser.new
-        @runner.program_name = @app.name
-        @runner.program_version = @app.version.split( "." )
+      def run( *args )
+        args = args.empty? ? args : [args]
+        command_name = ''
+
+        begin
+          runner.parse( *args ) { |l, c| command_name << "#{c} " if l > 0 }
+
+        rescue ::CmdParse::InvalidCommandError => e
+          command_name << e.message.gsub( /^.*: /, '' )
+          CP::App.instance.fatal( "'#{command_name}' is not a #{CP::App.instance.name} command." )
 
-        add_options( @runner, @app.options )
-        add_commands( @runner, @app.commands )
+        rescue ::CmdParse::InvalidOptionError,
+               ::OptionParser::InvalidOption => e
+          switch = e.message.gsub( /^.*: /, '' )
+          CP::App.instance.fatal( "'#{switch}' is not a valid option." )
+        end
+      end
+
+      def runner
+        runner = ::CmdParse::CommandParser.new
+        runner.program_name = @app.name
+        runner.program_version = @app.version ? @app.version.split( "." ) : nil
+
+        add_options( runner, @app.options )
+        add_commands( runner, @app.commands )
+
+        unless @app.commands.find { |c| c.name === :help }
+          has_default_command = @app.commands.find { |c| c.default }
+          runner.add_command( ::CmdParse::HelpCommand.new, !has_default_command )
+        end
 
-        @runner.parse
+        runner
       end
 
     private
@@ -40,13 +61,13 @@ module CP
             cmd.short_desc = c.summary
 
             cmd.set_execution_block do |args|
-              c.block.call( args ) if c.block
+              c.block.call( args )
             end
 
             add_options( cmd, c.options )
             add_commands( cmd, c.commands )
 
-            target.add_command( cmd )
+            target.add_command( cmd, c.default )
           end
         end
       end