climate 0.1.0

data/bin/climate

@@ -0,0 +1,14 @@
+#! /usr/bin/env ruby
+
+require 'climate'
+scriptfile = ARGV.shift or begin
+  $stderr.puts("Path to ruby script expected")
+  $stderr.puts("usage: climate <script> <arguments...>")
+  exit 1
+end
+
+# if climate is used to invoke a script, we can not use $PROGRAM_NAME to
+# identify the script, so we remember it from here
+$CLIMATE_PROGRAM_NAME = scriptfile
+
+load scriptfile

data/lib/climate/argument.rb

@@ -0,0 +1,30 @@
+module Climate
+  class Argument
+
+    attr_reader :name
+    attr_reader :description
+
+    def initialize(name, description, options={})
+      @name        = name
+      @description = description
+      @required    = options.fetch(:required, true)
+    end
+
+    def required? ; @required   ; end
+    def optional? ; ! required? ; end
+
+    def usage
+      string = "<#{name}>"
+
+      if optional?
+        "[#{string}]"
+      else
+        string
+      end
+    end
+
+    def formatted
+       required?? name.to_s.upcase : "[#{name.to_s.upcase}]"
+    end
+  end
+end

data/lib/climate/command.rb

@@ -0,0 +1,154 @@
+module Climate
+
+  #
+  # A {Command} is a unit of work, intended to be invoked from the command line.  It should be
+  # extended to either do something itself by implementing run, or just be
+  # there as a conduit for subcommands to do their work.
+  #
+  # See {ParsingMethods} for details on how to specify options and arguments
+  #
+  class Command
+
+    class << self
+      include ParsingMethods
+
+      # Create an instance of this command class and run it against the given
+      # arguments
+      # @param [Array<String>] arguments A list of arguments, ARGV style
+      # @param [Hash] options see {#initialize}
+      def run(arguments, options={})
+        begin
+          instance = new(arguments, options)
+        rescue Trollop::HelpNeeded
+          raise HelpNeeded.new(self)
+        end
+
+        if subcommands.empty?
+          instance.run
+        else
+          find_and_run_subcommand(instance, options)
+        end
+      end
+
+      def ancestors(exclude_self=false)
+        our_list = exclude_self ? [] : [self]
+        parent.nil?? our_list : parent.ancestors + our_list
+      end
+
+      # Supply a name for this command, or return the existing name
+      def name(name=nil)
+        @name = name if name
+        @name
+      end
+
+      # Register this class as being a subcommand of another {Command} class
+      # @param [Command] parent_class The parent we hang off of
+      def subcommand_of(parent_class)
+        raise DefinitionError, 'can not set subcommand before name' unless @name
+        parent_class.add_subcommand(self)
+      end
+
+      # Set the description for this command
+      # @param [String] string Description/Banner/Help text
+      def description(string=nil)
+        if string
+          @description = string
+        else
+          @description
+        end
+      end
+
+      # Set the parent of this command
+      attr_accessor :parent
+
+      def add_subcommand(subcommand)
+        if cli_arguments.empty?
+          subcommands << subcommand
+          subcommand.parent = self
+          stop_on(subcommands.map(&:name))
+        else
+          raise DefinitionError, 'can not mix subcommands with arguments'
+        end
+      end
+
+      def arg(*args)
+        if subcommands.empty?
+          super(*args)
+        else
+          raise DefinitionError, 'can not mix subcommands with arguments'
+        end
+      end
+
+      def has_subcommands? ; not subcommands.empty?   ; end
+      def subcommands ; @subcommands ||= [] ; end
+
+      private
+
+      def find_and_run_subcommand(parent, options)
+        command_name, *arguments = parent.leftovers
+
+        if command_name.nil?
+          raise MissingArgumentError.new(parent, "command #{parent.class.name}" +
+            " expects a subcommand as an argument")
+        end
+
+        found = subcommands.find {|c| c.name == command_name }
+
+        if found
+          found.run(arguments, options.merge(:parent => parent))
+        else
+          raise UnknownCommandError.new(parent, command_name)
+        end
+      end
+
+    end
+
+    # Create an instance of this command to be run.  You'll probably want to use
+    # {Command.run}
+    # @param [Array<String>] arguments ARGV style arguments to be parsed
+    # @option options [Command] :parent The parent command, made available as {#parent}
+    # @option options [IO] :stdout stream to use as stdout, defaulting to `$stdout`
+    # @option options [IO] :stderr stream to use as stderr, defaulting to `$stderr`
+    # @option options [IO] :stdin stream to use as stdin, defaulting to `$stdin`
+    def initialize(arguments, options={})
+      @parent = options[:parent]
+
+      @stdout = options[:stdout] || $stdout
+      @stderr = options[:stderr] || $stderr
+      @stdin =  options[:stdin]  || $stdin
+
+      @arguments, @options, @leftovers = self.class.parse(arguments)
+    end
+
+    # @return [Hash]
+    # Options that were parsed from the command line
+    attr_accessor :options
+
+    # @return [Hash]
+    # Arguments that were given on the command line
+    attr_accessor :arguments
+
+    # @return [Array]
+    # Unparsed arguments, usually for subcommands
+    attr_accessor :leftovers
+
+    # @return [Command]
+    # The parent command, or nil if this is not a subcommand
+    attr_accessor :parent
+
+    # @return [IO]
+    # a possibly redirected stream
+    attr_accessor :stdout, :stderr, :stdin
+
+    def ancestor(ancestor_class, include_self=true)
+      if include_self && self.class == ancestor_class
+        self
+      elsif parent.nil?
+        raise "no ancestor exists: #{ancestor_class}"
+        nil
+      else
+        parent.ancestor(ancestor_class)
+      end
+    end
+  end
+end

data/lib/climate/errors.rb

@@ -0,0 +1,45 @@
+module Climate
+  class Error < ::StandardError ; end
+
+  # Raised when {Command} class methods are used incorrectly
+  class DefinitionError < Error ; end
+
+  # Raised by an instance of a {Command} when something went wrong during
+  # execution
+  class CommandError < Error
+
+    # The command that raised the error
+    attr_reader :command_class
+
+    def initialize(command_or_class, msg=nil)
+      @command_class = command_or_class.is_a?(Command) ? command_or_class.class :
+        command_or_class
+      super(msg)
+    end
+  end
+
+  # Command instances can raise this error to exit
+  class ExitException < CommandError
+
+    attr_reader :exit_code
+    # some libraries (popen, process?) refer to this as exitcode without a _
+    alias :exitcode :exit_code
+
+    def initialize(command_class, msg, exit_code=1)
+      @exit_code = exit_code
+      super(command_class, msg)
+    end
+  end
+
+  class HelpNeeded < CommandError ; end
+
+  # Raised when a {Command} is run with too many arguments
+  class UnexpectedArgumentError < CommandError ; end
+
+  # Raised when a {Command} is run with insufficient arguments
+  class MissingArgumentError < CommandError ; end
+
+  # Raised when a parent {Command} is asked to run a sub command it does not
+  # know about
+  class UnknownCommandError < CommandError ; end
+end

data/lib/climate/help.rb

@@ -0,0 +1,148 @@
+module Climate
+  class Help
+
+    attr_reader :command_class
+
+    def initialize(command_class, options={})
+      @command_class = command_class
+      @indent = 0
+      @output = options[:output] || $stdout
+    end
+
+    def print
+      print_usage
+      print_description
+      print_options if command_class.has_options? || command_class.has_arguments?
+      print_subcommands if command_class.has_subcommands?
+    end
+
+    def print_usage
+      ancestor_list = command_class.ancestors.map(&:name).join(' ')
+      opts_usage = command_class.cli_options.map {|opt| opt.usage }.join(' ')
+      args_usage =
+        if command_class.has_subcommands?
+          "<subcommand> [<arguments>]"
+        else
+          command_class.cli_arguments.map {|arg| arg.usage }.join(' ')
+        end
+      puts("usage: #{ancestor_list} #{opts_usage} #{args_usage}")
+    end
+
+    def print_description
+      newline
+      puts "Description"
+      indent do
+        puts(command_class.description || '')
+      end
+    end
+
+    def print_subcommands
+      newline
+      puts "Available subcommands:"
+      indent do
+        command_class.subcommands.each do |subcommand_class|
+          puts "#{subcommand_class.name}"
+        end
+      end
+    end
+
+    def print_options
+      newline
+      puts "Options"
+      indent do
+
+        if command_class.has_subcommands?
+          puts "<subcommand>"
+          indent do
+            puts "Name of subcommand to execute"
+          end
+          newline
+          puts "<arguments>"
+          indent do
+            puts "Arguments for subcommand"
+          end
+          newline
+        end
+
+        command_class.cli_arguments.each do |argument|
+          puts "<#{argument.name}>"
+          indent do
+            puts argument.description
+          end
+          newline
+        end
+
+        command_class.cli_options.each do |option|
+          puts "#{option.usage(:with_long => true, :hide_optional => true, :separator => ', ')}"
+          indent do
+            puts option.description
+          end
+          newline
+        end
+      end
+    end
+
+    def indent(&block)
+      @indent += 1
+      yield if block_given?
+      unindent if block_given?
+    end
+
+    def unindent
+      @indent -= 1
+    end
+
+    def spaces
+      @indent * 4
+    end
+
+    def newline
+      @output.puts("\n")
+    end
+
+    def puts(string='')
+      string.split("\n").each do |line|
+        @output.puts((' ' * spaces) + line)
+      end
+    end
+
+    private
+
+    # stolen from trollop
+    def width #:nodoc:
+      @width ||= if $stdout.tty?
+                   begin
+                     require 'curses'
+                     Curses::init_screen
+                     x = Curses::cols
+                     Curses::close_screen
+                     x
+                   rescue Exception
+                     80
+                   end
+                 else
+                   80
+                 end
+    end
+
+    def wrap(string)
+
+      string.split("\n\n").map { |para|
+
+        words = para.split(/[\n ]/)
+        words[1..-1].inject([words.first]) { |m, v|
+          new_last_line = m.last + " " + v
+
+          if new_last_line.length <= (width - spaces)
+            m[0...-1] + [new_last_line]
+          else
+            m + [v]
+          end
+        }.join("\n")
+
+      }.join("\n\n")
+    end
+
+
+  end
+end

data/lib/climate/option.rb

@@ -0,0 +1,61 @@
+module Climate
+  class Option
+
+    attr_reader :name
+    attr_reader :description
+    attr_reader :options
+
+    def initialize(name, description, options={})
+      @name        = name
+      @description = description
+      @options     = options
+    end
+
+    def type    ; spec[:type]    ; end
+    def long    ; spec[:long]    ; end
+    def short   ; spec[:short]   ; end
+    def default ; spec[:default] ; end
+
+    def optional?
+      spec.has_key?(:default)
+    end
+
+    def required? ; ! optional? ; end
+
+    def parser
+      @parser ||= Trollop::Parser.new.tap {|p| add_to(p) }
+    end
+
+    def spec
+      @specs ||= parser.specs[@name]
+    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
+      end
+
+      if optional? && !options.fetch(:hide_optional, false)
+        "[#{help}]"
+      else
+        help
+      end
+    end
+
+    def add_to(parser)
+      parser.opt(@name, @description, @options)
+    end
+  end
+end

data/lib/climate/parser.rb

@@ -0,0 +1,95 @@
+module Climate
+
+  module ParsingMethods
+
+    def arg(*args)
+      raise DefinitionError, "can not define a required argument after an " +
+        "optional one" if cli_arguments.any?(&:optional?)
+
+      cli_arguments << Argument.new(*args)
+    end
+
+    def opt(*args)
+      cli_options << Option.new(*args)
+    end
+
+    def stop_on(args)
+      @stop_on = args
+    end
+
+    def trollop_parser
+      parser = Trollop::Parser.new
+
+      parser.stop_on @stop_on
+
+      if cli_arguments.size > 0
+        parser.banner ""
+        max_length = cli_arguments.map { |h| h.name.to_s.length }.max
+        cli_arguments.each do |argument|
+          parser.banner("  " + argument.name.to_s.rjust(max_length) + " - #{argument.description}")
+        end
+      end
+
+      parser.banner ""
+      cli_options.each do |option|
+        option.add_to(parser)
+      end
+      parser
+    end
+
+    def help_banner(out=$stdout)
+      trollop_parser.educate(out)
+    end
+
+    def check_arguments(args, command=self)
+
+      if args.size > cli_arguments.size
+        raise UnexpectedArgumentError.new(command, "#{args.size} for #{cli_arguments.size}")
+      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)
+        end
+
+        # no arg given is different to an empty arg
+        if arg_value.nil?
+          {}
+        else
+          {argument.name => arg_value}
+        end
+      end.inject {|a,b| a.merge(b) } || {}
+    end
+
+    def parse(arguments)
+      parser = self.trollop_parser
+      options = parser.parse(arguments)
+
+      # 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]
+        else
+          [self.check_arguments(parser.leftovers), []]
+        end
+
+      [arguments, options, leftovers]
+    end
+
+    def cli_options   ; @cli_options ||= []   ; end
+    def cli_arguments ; @cli_arguments ||= [] ; end
+
+    def has_options? ;     not cli_options.empty?   ; end
+    def has_arguments? ;   not cli_arguments.empty? ; end
+
+  end
+
+  class Parser
+    include ParsingMethods
+
+    def initialize(&block)
+      instance_eval(&block) if block_given?
+    end
+  end
+end

data/lib/climate/script.rb

@@ -0,0 +1,43 @@
+module Climate
+
+  # Module that you can extend any object with to turn it in to a climate
+  # script.  See the readme for intended usage, but follows the same pattern
+  # as the command, with the exception that it does not allow subcommands
+  module Script
+
+    def self.extended(othermodule)
+      if @included.nil?
+        @included = true
+        at_exit do
+          Climate.with_standard_exception_handling do
+            othermodule.send(:parse_argv)
+            othermodule.send(:run)
+          end
+        end
+      end
+    end
+
+    include ParsingMethods
+    # Set the description for this script
+    # @param [String] string Description/Banner/Help text
+    def description(string=nil)
+      if string.nil?
+        @description
+      else
+        @description = string
+      end
+    end
+
+    def parse_argv
+      @arguments, @options, @leftovers = self.parse(ARGV)
+    end
+
+    attr_reader :arguments, :options, :leftovers
+
+    def ancestors ; [self] ; end
+    def name ; File.basename($CLIMATE_PROGRAM_NAME || $PROGRAM_NAME) ; end
+
+    def has_subcommands? ; false ; end
+
+  end
+end

data/lib/climate/version.rb

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

data/lib/climate.rb

@@ -0,0 +1,40 @@
+require 'trollop'
+
+module Climate
+  def self.with_standard_exception_handling(&block)
+    begin
+      yield
+    rescue ExitException => e
+      $stderr.puts(e.message)
+      exit(e.exitcode)
+    rescue HelpNeeded => e
+      print_usage(e.command_class)
+    rescue UnknownCommandError => e
+      $stderr.puts("Unknown command: #{e.message}")
+      print_usage(e.command_class)
+    rescue MissingArgumentError => e
+      $stderr.puts("Missing argument: #{e.message}")
+      print_usage(e.command_class)
+    rescue => e
+      $stderr.puts("Unexpected error: #{e.message}")
+      $stderr.puts(e.backtrace)
+    end
+  end
+
+  def self.print_usage(command_class, options={})
+    help = Help.new(command_class)
+
+    help.print
+  end
+
+  def run(&block)
+  end
+end
+
+require 'climate/errors'
+require 'climate/argument'
+require 'climate/option'
+require 'climate/parser'
+require 'climate/command'
+require 'climate/help'
+require 'climate/script'

metadata

@@ -0,0 +1,117 @@
+--- !ruby/object:Gem::Specification 
+name: climate
+version: !ruby/object:Gem::Version 
+  hash: 27
+  prerelease: 
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- Nick Griffiths
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2012-07-15 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: trollop
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: minitest
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: yard
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id003
+description: Library, not a framework, for building command line interfaces to your ruby application
+email: 
+- nicobrevin@gmail.com
+executables: 
+- climate
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/climate/version.rb
+- lib/climate/argument.rb
+- lib/climate/command.rb
+- lib/climate/option.rb
+- lib/climate/parser.rb
+- lib/climate/errors.rb
+- lib/climate/script.rb
+- lib/climate/help.rb
+- lib/climate.rb
+- README
+- bin/climate
+homepage: 
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.8.10
+signing_key: 
+specification_version: 3
+summary: Library for building command line interfaces
+test_files: []
+