climate 0.1.0 → 0.2.0

data/README.md

@@ -0,0 +1,60 @@
+# Climate
+
+Yet another bloody CLI library for ruby, based on, and inspired by, the
+magnificence that is trollop, with more of a mind for building up a git-like
+CLI to access your application without enforcing a particular style of project
+structure.
+
+Designed for both simple and more complex cases.
+
+# Easy
+
+Useful for one-shot scripts:
+
+    #! /usr/bin/env climate
+    # the shebang is optional, you can just load the script with
+    # `ruby -r rubygems -r climate script.rb`
+    extend Climate::Script
+    description "Do something arbitrary to a file"
+
+    opt :log, "Whether to log to stdout" :default => false
+    arg :path "Path to input file"
+
+    def run
+      file = File.open(arguments[:path], 'r')
+      puts("loaded #{file}") if options[:log]
+    end
+
+# Medium
+
+This style is intended for embedding a CLI in to your existing application.
+
+    class Parent < Climate::Command
+      name 'thing'
+      description "App that does it all, yet without fuss"
+      opt    :log, "Whether to log to stdout" :default => false
+    end
+
+    class Arbitrary < Climate::Command
+      name 'arbitrary'
+      subcommand_of, Parent
+      description "Do something arbitrary to a file"
+      arg    :path "Path to input file"
+
+      def run
+        file = File.open(arguments[:path], 'r')
+        puts("loaded #{file}") if parent.options[:log]
+      end
+    end
+
+    Climate.with_standard_exception_handling do
+      Parent.run(ARGV)
+    end
+
+There is a working example, `example.rb` that you can test out with
+
+    ruby -rrubygems -rclimate example.rb --log /tmp/file
+
+or
+
+    ruby -rrubygems -rclimate example.rb --help

data/lib/climate/argument.rb

@@ -8,19 +8,17 @@ module Climate
       @name        = name
       @description = description
       @required    = options.fetch(:required, true)
+      @multi       = options.fetch(:multi, false)
     end
 
     def required? ; @required   ; end
     def optional? ; ! required? ; end
+    def multi?    ; @multi      ; end
 
     def usage
       string = "<#{name}>"
-
-      if optional?
-        "[#{string}]"
-      else
-        string
-      end
+      string += '...' if multi?
+      optional??  "[#{string}]" : string
     end
 
     def formatted

data/lib/climate/command.rb

@@ -24,7 +24,13 @@ module Climate
         end
 
         if subcommands.empty?
-          instance.run
+          begin
+            instance.run
+          rescue Climate::CommandError => e
+            # make it easier on users
+            e.command_class = self if e.command_class.nil?
+            raise
+          end
         else
           find_and_run_subcommand(instance, options)
         end
@@ -88,8 +94,8 @@ module Climate
         command_name, *arguments = parent.leftovers
 
         if command_name.nil?
-          raise MissingArgumentError.new(parent, "command #{parent.class.name}" +
-            " expects a subcommand as an argument")
+          raise MissingArgumentError.new("command #{parent.class.name}" +
+            " expects a subcommand as an argument", parent)
         end
 
         found = subcommands.find {|c| c.name == command_name }
@@ -97,7 +103,7 @@ module Climate
         if found
           found.run(arguments, options.merge(:parent => parent))
         else
-          raise UnknownCommandError.new(parent, command_name)
+          raise UnknownCommandError.new(command_name, parent)
         end
       end
 

data/lib/climate/errors.rb

@@ -9,9 +9,9 @@ module Climate
   class CommandError < Error
 
     # The command that raised the error
-    attr_reader :command_class
+    attr_accessor :command_class
 
-    def initialize(command_or_class, msg=nil)
+    def initialize(msg=nil, command_or_class=nil)
       @command_class = command_or_class.is_a?(Command) ? command_or_class.class :
         command_or_class
       super(msg)
@@ -23,15 +23,17 @@ module Climate
 
     attr_reader :exit_code
     # some libraries (popen, process?) refer to this as exitcode without a _
-    alias :exitcode :exit_code
+    alias :exitstatus :exit_code
 
-    def initialize(command_class, msg, exit_code=1)
+    def initialize(msg, exit_code=1)
       @exit_code = exit_code
-      super(command_class, msg)
+      super(msg)
     end
   end
 
-  class HelpNeeded < CommandError ; end
+  class HelpNeeded < CommandError
+    def initialize(command_class) ; super(nil, command_class) ; end
+  end
 
   # Raised when a {Command} is run with too many arguments
   class UnexpectedArgumentError < CommandError ; end

data/lib/climate/help/man.rb

@@ -0,0 +1,108 @@
+begin
+  require 'erubis'
+rescue LoadError => e
+  $stderr.puts("erubis gem is required for man output")
+  exit 1
+end
+
+class Climate::Help
+  # can produce a troff file suitable for man
+  class Man
+
+    # Eat my own dog food
+    class Script < Climate::Command
+      name 'man'
+      description 'Creates man/nroff output for a command'
+
+      arg :command_class, "name of class that defines the command, i.e. Foo::Bar::Command",
+      :type => :string, :required => true
+
+      opt :out_file, "Name of a file to write nroff output to.  Defaults to stdout",
+      :type => :string, :required => false
+
+      opt :template, "Path to an alternative template to use.  The default " +
+        "produces output for man/nroff, but you can change it to whatever " +
+        "you like", :required => false, :type => :string
+
+      def run
+        out_file = (of = options[:out_file]) && File.open(of, 'w') || $stdout
+
+        command_class = arguments[:command_class].split('::').
+          inject(Object) {|m,v| m.const_get(v) }
+
+        template_file = options[:template] || File.join(
+          File.dirname(__FILE__), 'man.erb')
+
+        Man.new(command_class, :output => out_file,
+          :template_file => template_file).print
+      end
+    end
+
+    class Presenter
+
+      def self.proxy(method_name)
+        define_method(method_name) do
+          @command_class.send(method_name)
+        end
+      end
+
+      def initialize(command_class)
+        @command_class = command_class
+      end
+
+      attr_reader :command_class
+
+      public :binding
+
+      def full_name
+        stack = []
+        command_ptr = command_class
+        while command_ptr
+          stack.unshift(command_ptr.name)
+          command_ptr = command_ptr.parent
+        end
+
+        stack.join(' ')
+      end
+
+      def short_name
+        command_class.name
+      end
+
+      def date         ; Date.today.strftime('%b, %Y') ; end
+
+      proxy :has_subcommands?
+      proxy :cli_options
+      proxy :cli_arguments
+      proxy :has_options?
+      proxy :has_arguments?
+
+      def paragraphs
+        command_class.description.split("\n\n")
+      end
+
+      def short_description
+        command_class.description.split(".").first
+      end
+
+      def subcommands
+        command_class.subcommands.map {|c| self.class.new(c) }
+      end
+    end
+
+    attr_reader :command_class
+
+    def initialize(command_class, options={})
+      @command_class = command_class
+      @output = options[:output] || $stdout
+      @template_file = options[:template_file]
+    end
+
+    def print
+      template = Erubis::Eruby.new(File.read(@template_file))
+      presenter = Presenter.new(command_class)
+      @output.puts(template.result(presenter.binding))
+    end
+
+  end
+end

data/lib/climate/help.rb

@@ -18,14 +18,14 @@ module Climate
 
     def print_usage
       ancestor_list = command_class.ancestors.map(&:name).join(' ')
-      opts_usage = command_class.cli_options.map {|opt| opt.usage }.join(' ')
+      opts_usage = command_class.cli_options.map {|opt| opt.usage }
       args_usage =
         if command_class.has_subcommands?
-          "<subcommand> [<arguments>]"
+          ["<subcommand> [<arguments>...]"]
         else
-          command_class.cli_arguments.map {|arg| arg.usage }.join(' ')
+          command_class.cli_arguments.map {|arg| arg.usage }
         end
-      puts("usage: #{ancestor_list} #{opts_usage} #{args_usage}")
+      puts("usage: #{ancestor_list} #{(opts_usage + args_usage).join(' ')}")
     end
 
     def print_description

data/lib/climate/option.rb

@@ -16,35 +16,28 @@ module Climate
     def short   ; spec[:short]   ; end
     def default ; spec[:default] ; end
 
-    def optional?
-      spec.has_key?(:default)
-    end
+    def optional? ; spec.has_key?(:default) ; end
+    def required? ; ! optional?             ; end
 
-    def required? ; ! optional? ; end
+    def spec ; @specs ||= parser.specs[@name] ; end
 
     def parser
       @parser ||= Trollop::Parser.new.tap {|p| add_to(p) }
     end
 
-    def spec
-      @specs ||= parser.specs[@name]
+    def long_usage
+      type == :flag ? "--#{long}" : "--#{long}=<#{type}>"
+    end
+
+    def short_usage
+      short && (type == :flag ? "-#{short}" : "-#{short}<#{type}>")
     end
 
     def usage(options={})
-      help =
-        if type == :flag
-          "-#{short}"
-        else
-          "-#{short}<#{type}>"
-        end
-
-      if options[:with_long]
-        help = help + options.fetch(:separator, '|') +
-          if type == :flag
-            "--#{long}"
-          else
-            "--#{long}=<#{type}>"
-          end
+      help = short_usage || long_usage
+
+      if options[:with_long] && (long_usage != help)
+        help = [help, long_usage].compact.join(options.fetch(:separator, '|'))
       end
 
       if optional? && !options.fetch(:hide_optional, false)

data/lib/climate/parser.rb

@@ -3,10 +3,16 @@ module Climate
   module ParsingMethods
 
     def arg(*args)
+
+      arg = Argument.new(*args)
+
+      raise DefinitionError, "can not define more arguments after a multi " +
+        " argument" if cli_arguments.any?(&:multi?)
+
       raise DefinitionError, "can not define a required argument after an " +
-        "optional one" if cli_arguments.any?(&:optional?)
+        "optional one" if cli_arguments.any?(&:optional?) && arg.required?
 
-      cli_arguments << Argument.new(*args)
+      cli_arguments << arg
     end
 
     def opt(*args)
@@ -41,17 +47,36 @@ module Climate
       trollop_parser.educate(out)
     end
 
-    def check_arguments(args, command=self)
+    def parse_arguments(args, command=self)
+
+      arg_list = cli_arguments
+
+      if arg_list.none?(&:multi?) && args.size > arg_list.size
+        raise UnexpectedArgumentError.new("#{args.size} for #{arg_list.size}", command)
+      end
 
-      if args.size > cli_arguments.size
-        raise UnexpectedArgumentError.new(command, "#{args.size} for #{cli_arguments.size}")
+      # mung the last arguments to appear as one for multi args, this is fairly
+      # ugly - thank heavens for unit tests
+      if arg_list.last && arg_list.last.multi?
+        multi_arg = arg_list.last
+        last_args = args[(arg_list.size - 1)..-1] || []
+
+        # depending on the number of args that were supplied, you may get nil
+        # or an empty array because of how slicing works, either way we want nil
+        # if no args were supplied so `required?` detection works below
+        args = args[0...(arg_list.size - 1)] +
+          [last_args.empty?? nil : last_args].compact
       end
 
-      cli_arguments.zip(args).map do |argument, arg_value|
-        if argument.required? && (arg_value.nil? || arg_value.empty?)
-          raise MissingArgumentError.new(command, argument.name)
+      arg_list.zip(args).map do |argument, arg_value|
+
+        if argument.required? && arg_value.nil?
+          raise MissingArgumentError.new(argument.name, command)
         end
 
+        # empty list is nil for multi arg
+        arg_value = [] if argument.multi? && arg_value.nil?
+
         # no arg given is different to an empty arg
         if arg_value.nil?
           {}
@@ -61,17 +86,27 @@ module Climate
       end.inject {|a,b| a.merge(b) } || {}
     end
 
-    def parse(arguments)
+    def parse(arguments, command=self)
       parser = self.trollop_parser
-      options = parser.parse(arguments)
+      begin
+        options = parser.parse(arguments)
+      rescue Trollop::CommandlineError => e
+        if (m = /unknown argument '(.+)'/.match(e.message))
+          raise UnexpectedArgumentError.new(m[1], command)
+        elsif (m = /option (.+) must be specified/.match(e.message))
+          raise MissingArgumentError.new(m[1], command)
+        else
+          raise
+        end
+      end
 
       # it would get weird if we allowed arguments alongside options, so
       # lets keep it one or t'other
       arguments, leftovers =
         if @stop_on
-          [[], parser.leftovers]
+          [{}, parser.leftovers]
         else
-          [self.check_arguments(parser.leftovers), []]
+          [self.parse_arguments(parser.leftovers), []]
         end
 
       [arguments, options, leftovers]

data/lib/climate/version.rb

@@ -1,3 +1,3 @@
 module Climate
-  VERSION = '0.1.0'
+  VERSION = '0.2.0'
 end

data/lib/climate.rb

@@ -6,18 +6,26 @@ module Climate
       yield
     rescue ExitException => e
       $stderr.puts(e.message)
-      exit(e.exitcode)
+      exit(e.exit_code)
     rescue HelpNeeded => e
       print_usage(e.command_class)
+      exit(0)
+    rescue UnexpectedArgumentError => e
+      $stderr.puts("Unknown argument: #{e.message}")
+      print_usage(e.command_class)
+      exit(1)
     rescue UnknownCommandError => e
       $stderr.puts("Unknown command: #{e.message}")
       print_usage(e.command_class)
+      exit(1)
     rescue MissingArgumentError => e
       $stderr.puts("Missing argument: #{e.message}")
       print_usage(e.command_class)
+      exit(1)
     rescue => e
-      $stderr.puts("Unexpected error: #{e.message}")
+      $stderr.puts("Unexpected error: #{e.class.name} - #{e.message}")
       $stderr.puts(e.backtrace)
+      exit(2)
     end
   end
 

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: climate
 version: !ruby/object:Gem::Version 
-  hash: 27
+  hash: 23
   prerelease: 
   segments: 
   - 0
-  - 1
+  - 2
   - 0
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors: 
 - Nick Griffiths
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2012-07-15 00:00:00 Z
+date: 2012-07-23 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   name: trollop
@@ -59,6 +59,20 @@ dependencies:
         version: "0"
   type: :development
   version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: popen4
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id004
 description: Library, not a framework, for building command line interfaces to your ruby application
 email: 
 - nicobrevin@gmail.com
@@ -70,6 +84,7 @@ extra_rdoc_files: []
 
 files: 
 - lib/climate/version.rb
+- lib/climate/help/man.rb
 - lib/climate/argument.rb
 - lib/climate/command.rb
 - lib/climate/option.rb
@@ -78,7 +93,7 @@ files:
 - lib/climate/script.rb
 - lib/climate/help.rb
 - lib/climate.rb
-- README
+- README.md
 - bin/climate
 homepage: 
 licenses: []
@@ -115,3 +130,4 @@ specification_version: 3
 summary: Library for building command line interfaces
 test_files: []
 
+has_rdoc: