thunder-1.8.7 0.5.2

data/DESIGN.md

@@ -0,0 +1,20 @@
+This document will document my various design decisions
+
+Option Parsing
+--------------
+Rather than include option parsing as part of the Thunder Core, I farm out the work through an adapter.
+The default adapter is only loaded if no other adapter is specified, and uses the ruby std-lib builtin OptParse library.
+
+Help Formatting
+---------------
+Similar to option parsing in that the functionality is provided via an adapter.
+The default implementation uses a style similar to rake and thor. This was chosen since it is the easiest to parse using regular expressions, barring developer error.
+
+Subcommands
+-----------
+One of the stated design goals was to provide subcommand support, ala svn, git, gem and rails.
+It has occured to me that as a result of the way I farm out option parsing and help formatting, this information is not passed on to the subcommand. As a result, each subcommand would need to declare which formatter to use, if the default one is not desired. This is possible to work around, but it would add an extra parameter or two to the start method, which I'd like to avoid. As there is no other way to solve this without resorting to smelly code, I'm going to put off this decision until it actually becomes relevant (it may in the future, who knows?)
+
+Singleton vs. Instance #start()
+-------------------------------
+Thor runs the start through the class singleton. But it also requires you to inherit from the Thor class. This means that more complex classes cannot be turned into adhoc command line utilities, which I view as a significant limitation against the integration of command line and code. Bridging that gap is exactly what this library is supposed to do.

data/README.md

@@ -0,0 +1,38 @@
+[Thunder](http://stevenkaras.github.com/thunder)
+=======
+Ruby gem for quick and easy command line interfaces
+
+Usage
+-----
+
+    gem install thunder
+
+see '[sample](http://github.com/stevenkaras/thunder/blob/master/sample)' for a quick overview of all features
+
+Philosophy
+----------
+The command line is the most basic interface we have with a computer. It makes sense that we should invest as much time and effort as possible to build tools to work with the command line, and tie into code we write as quickly as possible. Sadly, this has not taken place as much as one would expect. This library steps up to bridge the admittedly small gap between your standard shell and ruby code.
+
+While this is possible, and even easy using existing libraries, they either violate the principle of locality, or provide too many services.
+
+The overarching philosophy here is that a library should do one or two things, and do them extremely well.
+
+Goals
+-----
+Provide a simple, DRY syntatic sugar library that provides the necessary services to create command line mappings to ruby methods. It will not provide any other services.
+
+Notable features as of the current release:
+
+  * options parsing for commands
+  * default commands
+  * subcommands (ala git)
+  * integrated help system
+  * bash completion script generator
+
+Development
+-----------
+If you'd like to contribute, fork, commit, and request a pull. I'll get around to it. No special dependencies, or anything fancy
+
+License
+-------
+MIT License

data/Rakefile

@@ -0,0 +1,25 @@
+require 'rake/testtask'
+
+require File.expand_path("../lib/thunder/version", __FILE__)
+
+Rake::TestTask.new do |t|
+  t.test_files = FileList['test/*_test.rb']
+  t.test_files = FileList['test/test_*.rb']
+  t.test_files = FileList['spec/*_spec.rb']
+  t.test_files = FileList['spec/spec_*.rb']
+  t.libs << 'spec'
+  t.libs << 'test'
+end
+
+desc "Run tests"
+task :default => :test
+
+desc "Build the gem"
+task :build do
+  system "gem build thunder.gemspec"
+end
+
+task :gem => :build do
+  system "gem uninstall -a thunder"
+  system "gem install thunder-#{Thunder::VERSION}.gem"
+end

data/bin/thunder-completion

@@ -0,0 +1,74 @@
+#!/usr/bin/env ruby
+
+require 'thunder'
+require 'erb'
+
+def thunder_commands(bolt)
+  bolt[:commands].map(&:first).map(&:to_s)
+end
+
+def thunder_options(command)
+  return nil unless command[:options]
+
+  result = []
+  command[:options].each do |opt, option|
+    result << "--#{opt}"
+    next unless option[:short]
+    result << "-#{option[:short]}"
+  end
+  return result
+end
+
+module Thunder
+  def start(args=ARGV.dup, options={})
+    template = ERB.new <<-TEMPLATE, nil, "%"
+#!/bin/bash
+
+% progname = File.basename(ARGV.first)
+__<%= progname %>_commands() {
+    echo "<%= thunder_commands(thunder).join(" ") %>"
+}
+% thunder[:commands].each do |name, command|
+%   name = name.to_s
+%   if command[:options]
+
+__<%= progname %>_<%= name %>_options() {
+    echo "<%= thunder_options(command).join(" ") %>"
+}
+%   end
+% end
+
+__<%= progname %>_complete() {
+  local words=""
+    if [[ ${COMP_WORDS[COMP_CWORD]:0:1} == "-" ]]; then
+        if ((COMP_CWORD == 1)); then
+            words=
+        else
+            local command="__<%= progname %>_${COMP_WORDS[1]}_options"
+            words=$($command)
+        fi
+    elif ((COMP_CWORD == 1)); then
+        # display only commands
+        words=$(__<%= progname %>_commands)
+    fi
+    COMPREPLY=($(compgen -W "$words" -- ${COMP_WORDS[COMP_CWORD]}))
+}
+
+complete -o default -o nospace -F __<%= progname %>_complete <%= progname %>
+
+    TEMPLATE
+    context = (proc { |thiz, thunder|
+      binding
+    }).call(self, self.class.thunder)
+    puts template.result(context)
+  end
+end
+
+if ARGV.size != 1
+  puts "Usage: thunder-completion THUNDER_SCRIPT"
+  puts
+  puts "Prints out the suggested template for a bash completion script for the given thunder script"
+  exit 1
+end
+
+load File.expand_path(ARGV.first)

data/bin/thunder-spec

@@ -0,0 +1,27 @@
+#!/usr/bin/env ruby
+
+require 'thunder'
+require 'pp'
+
+module Thunder
+  def start(args=ARGV.dup, options={})
+    spec = self.class.thunder
+    pp renderThunderSpec(spec)
+  end
+end
+
+def renderThunderSpec(spec)
+  spec[:commands].each do |name, command|
+    command[:subcommand] = renderThunderSpec(command[:subcommand].class.thunder) if command[:subcommand]
+  end
+  spec
+end
+
+if ARGV.size != 1
+  puts "Usage: thunder-spec THUNDER_SCRIPT"
+  puts
+  puts "Dumps the thunder spec to the command line for debugging and analysis"
+  exit 1
+end
+
+load File.expand_path(ARGV.first)

data/lib/thunder/help/default.rb

@@ -0,0 +1,94 @@
+module Thunder
+  # Provides an easy to parse help formatter
+  class DefaultHelp
+    class << self
+
+      # @see Thunder#help_command(command_spec)
+      def help_command(command_spec)
+        preamble = determine_preamble
+        footer = ""
+        footer << command_spec[:description] + "\n" if command_spec[:description]
+        footer << command_spec[:long_description] + "\n" if command_spec[:long_description]
+        footer << "\n" + format_options(command_spec[:options]) if command_spec[:options]
+        output = <<-EOS
+Usage:
+  #{preamble} #{command_spec[:usage]}
+
+#{footer.strip}
+        EOS
+        output.rstrip
+      end
+
+      # @see Thunder#help_list(commands)
+      def help_list(commands)
+        preamble = determine_preamble
+        help = []
+        commands.each do |name, command_spec|
+          help << short_help(preamble, command_spec)
+        end
+        render_table(help)
+      end
+
+      private
+
+      # format a set of option specs
+      #
+      # @param options [<Hash>] the option specs to format
+      # @return [String]
+      def format_options(options)
+        data = []
+        options.each do |name, option_spec|
+          data << format_option(option_spec)
+        end
+        "Options:\n" + render_table(data, ": ")
+      end
+
+      # format an option
+      #
+      # @param option_spec [Hash] the option spec to format
+      # @return [(String, String)] the formatted option and its description
+      def format_option(option_spec)
+        usage = "  -#{option_spec[:short]}, --#{option_spec[:name]}"
+        usage << " [#{option_spec[:name].to_s.upcase}]" unless option_spec[:type] == Boolean
+        return usage, option_spec[:desc]
+      end
+
+      # determine the preamble
+      #
+      # @return [String] the preamble
+      def determine_preamble
+        preamble = "#{File.basename($0)}"
+        ARGV.each do |arg|
+          break if arg == "help"
+          preamble << " #{arg}"
+        end
+        preamble
+      end
+
+      # render the short help string for a command
+      #
+      # @param preamble [String] the preamble
+      # @param command_spec [Hash]
+      # @return [String] the short help string for the given command
+      def short_help(preamble, command_spec)
+        return "  #{preamble} #{command_spec[:usage]}", command_spec[:description]
+      end
+
+      # render a two-column table
+      #
+      # @param data [(String,String)]
+      # @param separator [String]
+      # @return [String] a two-column table
+      def render_table(data, separator = " # ")
+        column_width = data.group_by do |row|
+          row.first.size
+        end.max.first
+        "".tap do |output|
+          data.each do |row|
+            output << "%-#{column_width}s#{separator}%s\n" % row
+          end
+        end
+      end
+    end
+  end
+end

data/lib/thunder/options/optparse.rb

@@ -0,0 +1,42 @@
+require 'optparse'
+
+module Thunder
+  # Provides an adapter to the optparse library included in the Ruby std-lib
+  class OptParseAdapter
+    # @see Thunder#process_options
+    def self.process_options(args, command_spec)
+      return {} unless command_spec[:options]
+      options = {}
+      command_spec[:options_processor] ||= OptionParser.new do |parser|
+        command_spec[:options].each do |name, option_spec|
+          opt = []
+          opt << "-#{option_spec[:short]}"
+          opt << if option_spec[:type] == Boolean
+            "--[no-]#{name}"
+          else
+            "--#{name} [#{name.to_s.upcase}]"
+          end
+          opt << option_spec[:type] unless option_spec[:type] == Boolean
+          opt << option_spec[:desc]
+          parser.on(*opt) do |value|
+            options[name] = value
+          end
+        end
+      end
+      command_spec[:options_processor].parse!(args)
+
+      # set default values
+      command_spec[:options].each do |name, option_spec|
+        next if options.has_key? name
+        next unless option_spec[:default]
+        options[name] = option_spec[:default]
+      end
+
+      return options
+    rescue OptionParser::InvalidOption => e
+      puts e
+      puts "Try --help for help."
+      exit 1
+    end
+  end
+end

data/lib/thunder/options/trollop.rb

@@ -0,0 +1,27 @@
+require 'trollop'
+
+module Thunder
+  # provides an adapter to the popular trollop option parsing library (requires trollop.rb be on the load path)
+  class TrollopAdapter
+    # @see Thunder#process_options
+    def self.process_options(args, command_spec)
+      return nil unless command_spec[:options]
+      #TODO: fix the unspecified option bug
+      command_spec[:option_processor] ||= Trollop::Parser.new do
+        command_spec[:options].each do |name, option_spec|
+          opt_options = {}
+          description = option_spec[:desc] || ""
+          type = option_spec[:type]
+          type = :flag if type == Thunder::Boolean
+          opt_options[:type] = type
+          default_value = option_spec[:default]
+          opt_options[:default] = default_value if default_value
+          opt_options[:short] = "-" + option_spec[:short]
+
+          opt name, description, opt_options
+        end
+      end
+      command_spec[:option_processor].parse(args)
+    end
+  end
+end

data/lib/thunder/version.rb

@@ -0,0 +1,4 @@
+module Thunder
+  # Version string for gemspec
+  VERSION = "0.5.2"
+end

data/lib/thunder.rb

@@ -0,0 +1,223 @@
+# Provides a simple, yet powerful ability to quickly and easily tie Ruby methods
+# with command line actions.
+#
+# The syntax is very similar to Thor, so switching over should be extremely easy
+module Thunder
+
+  # Used to indicate a boolean true or false value for options processing
+  class Boolean; end
+
+  # Start the object as a command line program,
+  # processing the given arguments and using the provided options.
+  #
+  # @param args [<String>] the command line arguments [ARGV]
+  # @param options [{Symbol => *}] the default options to use [{}]
+  def start(args=ARGV.dup, options={})
+    command_spec = determine_command(args)
+
+    unless command_spec
+      return
+    end
+
+    if command_spec[:name] == :help && command_spec[:default_help]
+      return get_help(args, options)
+    end
+
+    parsed_options = process_options(args, command_spec)
+    options.merge!(parsed_options) if parsed_options
+    if command_spec[:subcommand]
+      return command_spec[:subcommand].start(args, options)
+    elsif parsed_options
+      #TODO: do arity check
+      args << options
+      return send command_spec[:name], *args
+    else
+      #TODO: do arity check
+      return send command_spec[:name], *args
+    end
+  end
+
+  protected
+  # Determine the command to use from the given arguments
+  #
+  # @param args [<String>] the arguments to process
+  # @return [Hash,nil] the command specification for the given arguments,
+  #         or nil if there is no appropriate command
+  def determine_command(args)
+    if args.empty?
+      return self.class.thunder[:commands][self.class.thunder[:default_command]]
+    end
+    command_name = args.first.to_sym
+    command_spec = self.class.thunder[:commands][command_name]
+    if command_spec
+      args.shift
+    else
+      command_spec = self.class.thunder[:commands][self.class.thunder[:default_command]]
+    end
+    return command_spec
+  end
+
+  # Process command line options from the given argument list
+  #
+  # @param args [<String>] the argument list to process
+  # @param command_spec [Hash] the command specification to use
+  # @return [{Symbol => *},nil] the options
+  def process_options(args, command_spec)
+    return nil unless command_spec[:options]
+
+    unless self.class.thunder[:options_processor]
+      require 'thunder/options/optparse'
+      self.class.thunder[:options_processor] = Thunder::OptParseAdapter
+    end
+    self.class.thunder[:options_processor].process_options(args, command_spec)
+  end
+
+  # get help on the provided subjects
+  #
+  # @param args [<String>] the arguments list
+  # @param options [Hash] any included options
+  def get_help(args, options)
+    unless self.class.thunder[:help_formatter]
+      require 'thunder/help/default'
+      self.class.thunder[:help_formatter] = Thunder::DefaultHelp
+    end
+    if args.size == 0
+      puts help_list(self.class.thunder[:commands])
+    else
+      puts help_command(determine_command(args))
+    end
+  end
+
+  # Render a usage list of the given commands
+  #
+  # @param commands [<Hash>] the commands to list
+  # @return [String] the rendered help
+  def help_list(commands)
+    self.class.thunder[:help_formatter].help_list(commands)
+  end
+
+  # Render detailed help on a specific command
+  #
+  # @param command_spec [Hash] the command to render detailed help for
+  # @return [String] the rendered help
+  def help_command(command_spec)
+    self.class.thunder[:help_formatter].help_command(command_spec)
+  end
+
+  public
+  # @api private
+  # Automatically extends the singleton with {ClassMethods}
+  def self.included(base)
+    base.send :extend, ClassMethods
+  end
+
+  # This module provides methods for any class that includes Thunder
+  module ClassMethods
+
+    # @api private
+    # Get the thunder configuration
+    def thunder
+      @thunder ||= {
+        :default_command => :help,
+        :commands => {
+          :help => {
+            :name => :help,
+            :usage => "help [COMMAND]",
+            :description => "list available commands or describe a specific command",
+            :long_description => nil,
+            :options => nil,
+            :default_help => true
+          },
+        }
+      }
+    end
+
+    # @api private
+    # Registers a method as a thunder task
+    def method_added(method)
+      add_command(method.to_sym)
+      # thunder[:commands][method][:params] = instance_method(method).parameters
+    end
+
+    # Set the options processor.
+    #
+    # @param processor [#process_options]
+    def options_processor(processor)
+      thunder[:options_processor] = processor
+    end
+
+    # Set the help formatter.
+    #
+    # @param formatter [#help_list,#help_command]
+    def help_formatter(formatter)
+      thunder[:help_formatter] = formatter
+    end
+
+    # Set the default command to be executed when no suitable command is found.
+    #
+    # @param command [Symbol] the default command
+    def default_command(command)
+      thunder[:default_command] = command
+    end
+
+    # Describe the next method (or subcommand). A longer description can be given
+    # using the {#longdesc} command
+    #
+    # @param usage [String] the perscribed usage of the command
+    # @param description [String] a short description of what the command does
+    def desc(usage, description="")
+      thunder[:usage], thunder[:description] = usage, description
+    end
+
+    # Provide a long description for the next method (or subcommand).
+    #
+    # @param description [String] a long description of what the command does
+    def longdesc(description)
+      thunder[:long_description] = description
+    end
+
+    # Define an option for the next method (or subcommand)
+    #
+    # @param name [Symbol,String] the long name of this option
+    # @option options :short [String] the short version of the option [the first letter of the option name]
+    # @option options :type [Class] the datatype of this option [Boolean]
+    # @option options :desc [String] the long description of this option [""]
+    # @option options :default [*] the default value
+    #
+    # @example
+    #   option :output_file, type: String
+    #
+    # @example
+    #   option "verbose", desc: "print extra information"
+    def option(name, options={})
+      name = name.to_sym
+      options[:name] = name
+      options[:short] ||= name.to_s[0,1]
+      options[:type] ||= Boolean
+      options[:desc] ||= ""
+      thunder[:options] ||= {}
+      thunder[:options][name] = options
+    end
+
+    # Define a subcommand
+    #
+    # @param command [Symbol,String] the command that transfers processing to the provided handler
+    # @param handler [Thunder] the handler that processes the request
+    def subcommand(command, handler)
+      add_command(command.to_sym)
+      thunder[:commands][command.to_sym][:subcommand] = handler
+    end
+
+    private
+    def add_command(command)
+      attributes = [:usage, :description, :options, :long_description]
+      return unless attributes.reduce(nil) { |a, key| a || thunder[key] }
+      thunder[:commands][command] = {
+        :name => command,
+      }
+      attributes.each do |key|
+        thunder[:commands][command][key] = thunder.delete(key)
+      end
+    end
+  end
+end

data/spec/spec_thunder.rb

@@ -0,0 +1,19 @@
+require 'minitest/autorun'
+
+class ThunderSpec < MiniTest::Spec
+
+  describe "a simple example" do
+    it "should be easy to use" do
+      # test is subjective. Awaiting singularity for objective analysis
+    end
+    it "should pass on arguments" do
+      # TODO: write this test(s)
+    end
+    it "should pass options" do
+      # TODO: write these tests
+    end
+    it "should allow use of subcommands" do
+      # TODO: write some more tests
+    end
+  end
+end

metadata

@@ -0,0 +1,58 @@
+--- !ruby/object:Gem::Specification
+name: thunder-1.8.7
+version: !ruby/object:Gem::Version
+  version: 0.5.2
+  prerelease: 
+platform: ruby
+authors:
+- Steven Karas
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-01-01 00:00:00.000000000 Z
+dependencies: []
+description: Thunder does command line interfaces. Nothing more, nothing less.
+email: steven.karas@gmail.com
+executables:
+- thunder-spec
+- thunder-completion
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/thunder/help/default.rb
+- lib/thunder/version.rb
+- lib/thunder/options/optparse.rb
+- lib/thunder/options/trollop.rb
+- lib/thunder.rb
+- spec/spec_thunder.rb
+- Rakefile
+- DESIGN.md
+- README.md
+- bin/thunder-spec
+- bin/thunder-completion
+homepage: http://stevenkaras.github.com/thunder
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Thunder makes command lines apps easy!
+test_files: []
+has_rdoc: