thunder 0.4.0

data/CHANGELOG

@@ -0,0 +1,11 @@
+v0.4.0
++ add help formatter
+
+v0.3.0
++ provide facility for defining options
+
+v0.2.0
++ pass leftover arguments to the command
+
+v0.1.0
++ call specified command

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,29 @@
+Thunder
+=======
+Ruby gem for quick and easy command line interfaces
+
+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.
+
+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.
+
+Phase 1: call a method from the command line
+Phase 2: provide options and arguments 
+Phase 3: provide help/banner formatter
+Phase 4: provide yardoc integration
+Phase 5: provide a bash-completion script.
+Phase 6: ???
+Phase 7: Profit!
+
+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/lib/thunder.rb

@@ -0,0 +1,212 @@
+# 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, 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
+
+    options.merge!(process_options(args, command_spec))
+    if command_spec[:subcommand]
+      return command_spec[:subcommand].start(args, options)
+    elsif options
+      #TODO: do arity check
+      return send command_spec, *args, options
+    else
+      #TODO: do arity check
+      return send command_spec, *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]
+    args.shift if command_spec
+    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 => *}] 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",
+            options: nil,
+            default_help: true
+          },
+        }
+      }
+    end
+
+    # @api private
+    # Registers a method as a thunder task
+    def method_added(method)
+      attributes = [:usage, :description, :options, :long_description]
+      return unless attributes.reduce { |a, key| a || thunder[key] }
+      thunder[:commands][method] = {
+        name: method,
+      }
+      attributes.each do |key|
+        thunder[:commands][method][key] = thunder[key]
+        thunder[key] = nil
+      end
+    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 [""]
+    #
+    # @example
+    #   option :output_file, type: String
+    #
+    # @example
+    #   option "verbose", desc: "print extra information"
+    def option(name, options={})
+    #TODO: have this generate YARDoc for the option (as it should match a method option)
+      name = name.to_sym
+      options[:name] = name
+      options[:short] ||= name[0]
+      options[:type] ||= Boolean
+      options[:description] ||= ""
+      thunder[:options] ||= {}
+      thunder[:options][name] = options
+    end
+
+    # Define a subcommand
+    #
+    # @param command [String] the command that transfers processing to the provided handler
+    # @param handler [Thunder] the handler that processes the request
+    def subcommand(command, handler)
+      method_added(command)
+      thunder[:commands][command][:subcommand] = handler
+    end
+
+  end
+end

data/lib/thunder/help/default.rb

@@ -0,0 +1,69 @@
+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
+        #TODO: add options to output
+        output = <<-EOS
+Usage:
+  #{preamble} #{command_spec[:usage]}
+
+#{command_spec[:description]}
+#{command_spec[:long_description]}
+        EOS
+        output.chomp
+      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
+      # 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 |data|
+          data.first.size
+        end.max.first
+        "".tap do |output|
+          data.each do |line|
+            output << "%-#{column_width}s #{separator} %s\n" % line
+          end
+        end
+      end
+    end
+  end
+end

data/lib/thunder/options/optparse.rb

@@ -0,0 +1,32 @@
+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 nil 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} OPT"
+          end
+          opt << option_spec[:type] unless option_spec[:type] == Boolean
+          opt << option_spec[:description]
+          parser.on(*opt) do |value|
+            options[name] = value
+          end
+        end
+      end
+      command_spec[:options_processor].parse!(args)
+
+      return options
+    end
+  end
+end

data/lib/thunder/version.rb

@@ -0,0 +1,4 @@
+module Thunder
+  # Version string for gemspec
+  VERSION = "0.4.0"
+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,55 @@
+--- !ruby/object:Gem::Specification
+name: thunder
+version: !ruby/object:Gem::Version
+  version: 0.4.0
+  prerelease: 
+platform: ruby
+authors:
+- Steven Karas
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-08-04 00:00:00.000000000 Z
+dependencies: []
+description: Thor does everything and the kitchen sink. Thunder only does command
+  line interfaces.
+email: steven.karas@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/thunder/help/default.rb
+- lib/thunder/options/optparse.rb
+- lib/thunder/version.rb
+- lib/thunder.rb
+- spec/spec_thunder.rb
+- CHANGELOG
+- DESIGN.md
+- Rakefile
+- README.md
+homepage: http://stevenkaras.github.com
+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: