simplecli 0.1.6

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2009 ryan "remi" Taylor
+
+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/README.rdoc

@@ -0,0 +1,169 @@
+= SimpleCLI
+
+== DEPRECATED
+
+I used to use this for all of my CLI's.  Then I found Thor.
+
+I still think it would be fun to complete a new SimpleCLI DSL 
+that I was working on ... but Thor is becoming pretty standard 
+so I would much rather use something that's widely known and used.
+
+I personally recommend using Thor and, when you want to run 
+your script, call ClassThatInheritsFromThor.start
+
+Thor:: http://github.com/wycats/thor
+
+== Old Documentation ...
+
+SimpleCLI is Undergoing Renovations
+
+After over a year of use, this library needs some love!
+
+I'm going to ...
+
+- get a spec suite working again (I had specs for SimpleCLI once ... they're gone now)
+- create a DSL (or 2) for making it easier for people to make SimpleCLI apps if 
+  they don't want to just include the SimpleCLI module in one of their classes
+- make (atleast some of) the DSL work in pre-defined classes (kindof like what we do now)
+- create a screencast showing how easy it is to use SimpleCLI (and how to test-drive 
+  SimpleCLI applications)
+- document #command_missing and #default_comment usage with good examples
+- create abunchof examples and throw them in the examples directory
+- add #before and #after blocks for handling global options or something to do before 
+  exiting type stuff
+- make sure errors return the right response code
+
+== About
+
+Super Simple RubyGems-like CLI
+
+SimpleCLI gives you a stupidly simple way to implement command-line 
+interfaces like that of RubyGems with a basic interface like:
+
+    gem command [options]
+
+SimpleCLI gives you a way of defining your commands (or actions) so 
+they'll automatically show up when you run `yourapp commands`
+
+SimpleCLI also makes it really easy to add documentation to each of
+your commands (or actions)
+
+== Real Examples
+
+I use SimpleCLI in most of my apps for quick and dirty command-line interfaces.
+
+Here are a few real examples:
+
+* {Syntax On}[http://github.com/remi/syntax-on/tree/master/lib/syntax-on/bin.rb]
+* {Domain Finder}[http://github.com/remi/domain-finder/tree/master/lib/domain-finder/bin.rb]
+* ADF[http://github.com/remi/adf/tree/master/lib/adf/bin.rb]
+
+== Example
+
+Here's a super simple SimpleCLI example:
+
+    #! /usr/bin/env ruby
+
+    require File.dirname(__FILE__) + '/../lib/simplecli'
+
+    class Hello
+      include SimpleCLI
+
+      def usage
+        puts <<doco
+
+      Hello CLI
+
+        Usage:
+          #{ script_name } command [options]
+        
+        Futher help:
+          #{ script_name } commands         # list all available commands
+          #{ script_name } help <COMMAND>   # show help for COMMAND
+          #{ script_name } help             # show this help message
+
+    doco
+      end
+
+      def sayhello_help
+        <<doco
+    Usage: #{ script_name } sayhello [SAY]
+
+      Arguments:
+        SAY:         Something to say (default 'Hello World!')
+
+      Summary:
+        Says hello!
+    doco
+      end
+      def sayhello *args
+        puts args.empty? ? "Hello World!" : args.join(' ')
+      end
+
+    end
+
+    # POSTAMBLE
+    if __FILE__ == $0
+      Hello.new( ARGV, :default => 'sayhello' ).run
+    end
+
+Example usage:
+
+<em><tt>$ ./hello-cli</tt></em>
+
+    Hello CLI
+
+      Usage:
+        hello-cli command [options]
+      
+      Futher help:
+        hello-cli commands         # list all available commands
+        hello-cli help <COMMAND>   # show help for COMMAND
+        hello-cli help             # show this help message
+
+<em><tt>$ ./hello-cli commands</tt></em>
+
+    hello-cli commands are:
+
+        DEFAULT COMMAND   sayhello
+
+        commands          List all 'hello-cli' commands
+        help              Provide help documentation for a command
+        sayhello          Says hello!
+
+    For help on a particular command, use 'hello-cli help COMMAND'.
+
+<em><tt>$ ./hello-cli help</tt></em>
+
+    Usage: hello-cli help COMMAND
+
+      Summary:
+        Provide help documentation for a command
+
+<em><tt>$ ./hello-cli help sayhello</tt></em>
+
+    Usage: hello-cli sayhello [SAY]
+
+      Arguments:
+        SAY:         Something to say (default 'Hello World!')
+
+      Summary:
+        Says hello!
+
+<em><tt>$ ./hello-cli sayhello</tt></em>
+
+    Hello World!
+
+<em><tt>$ ./hello-cli sayhello Hi There</tt></em>
+
+  Hi There
+
+<em><tt>$ ./hello-cli Hi There</tt></em>    `# this works because sayhello is configured as the default command`
+
+    Hi There
+
+TODO
+----
+
+ * implement a `before` block for handling global options
+ * there was once a spec suite ... where'd it go?  find or recreate it!

data/Rakefile

@@ -0,0 +1,57 @@
+require 'rake'
+require 'rubygems'
+require 'rake/rdoctask'
+require 'spec/rake/spectask'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |s|
+    s.name        = "simplecli"
+    s.summary     = "For making simple RubyGem-like command-line interfaces"
+    s.email       = "remi@remitaylor.com"
+    s.homepage    = "http://github.com/remi/simplecli"
+    s.description = "SimpleCLI gives you a stupidly simple way to implement command-line interfaces like that of RubyGems"
+    s.authors     = %w( remi )
+    s.files       = FileList["[A-Z]*", "{lib,spec,examples}/**/*"] 
+    # s.add_dependency 'person-project' 
+    # s.executables = "neato" 
+  end
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://gems.github.com"
+end
+
+Spec::Rake::SpecTask.new do |t|
+  t.spec_files = FileList['spec/**/*_spec.rb']
+end
+
+desc "Run all examples with RCov"
+Spec::Rake::SpecTask.new('rcov') do |t|
+  t.spec_files = FileList['spec/**/*_spec.rb']
+  t.rcov = true
+end
+
+Rake::RDocTask.new do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'simplecli'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+desc 'Confirm that gemspec is $SAFE'
+task :safe do
+  require 'yaml'
+  require 'rubygems/specification'
+  data = File.read('simplecli.gemspec')
+  spec = nil
+  if data !~ %r{!ruby/object:Gem::Specification}
+    Thread.new { spec = eval("$SAFE = 3\n#{data}") }.join
+  else
+    spec = YAML.load(data)
+  end
+  spec.validate
+  puts spec
+  puts "OK"
+end
+
+task :default => :spec

data/VERSION.yml

@@ -0,0 +1,4 @@
+--- 
+:major: 0
+:minor: 1
+:patch: 6

data/examples/hello-cli

@@ -0,0 +1,44 @@
+#! /usr/bin/env ruby
+
+require File.dirname(__FILE__) + '/../lib/simplecli'
+
+class Hello
+  include SimpleCLI
+
+  def usage
+    puts <<doco
+
+  Hello CLI
+
+    Usage:
+      #{ script_name } command [options]
+      
+    Futher help:
+      #{ script_name } commands         # list all available commands
+      #{ script_name } help <COMMAND>   # show help for COMMAND
+      #{ script_name } help             # show this help message
+
+doco
+  end
+
+  def sayhello_help
+    <<doco
+Usage: #{ script_name } sayhello [SAY]
+
+  Arguments:
+    SAY:         Something to say (default 'Hello World!')
+
+  Summary:
+    Says hello!
+doco
+  end
+  def sayhello *args
+    puts args.empty? ? "Hello World!" : args.join(' ')
+  end
+
+end
+
+# POSTAMBLE
+if __FILE__ == $0
+  Hello.new( ARGV, :default => 'sayhello' ).run
+end

data/lib/simplecli.rb

@@ -0,0 +1,221 @@
+#
+# Stupidly simple way to get a CLI that handles:
+#     myapp somecommand --blah=5 args --more stuff -y
+#
+# All it does is, if the "command" (or "action") passed 
+# has a method with the same name, the rest of the args 
+# are passed to the method.
+#
+# If you provide a command_help method that returns help 
+# info as a String, that'll be used when you call:
+#     myapp help somecommand
+#
+# If you provide a 'Summary:\n blah blah blah' bit in 
+# your help_somecommand, it'll be used as the command's 
+# summary and your command will show up when you:
+#     myapp commands
+#
+# To use, include in your class
+#
+# NOTE: if you use the 'default' command functionality, 
+# we don'e even bother to check to see if we respond_to? 
+# what you provide as a default command, incase it 
+# uses method missing or something.  So it's *YOUR* 
+# responsibility to provide this method
+#
+# Conventionally, your 'default' method should simple pass
+# along the arguments to another defined and documented command!
+#
+module SimpleCLI
+  attr_accessor :options
+  attr_reader   :args, :command, :command_args
+
+  def initialize args = [], options = {}
+    @args     = args
+    @options  = options
+    parse!
+  end
+
+  # figure out what command to run, arguments to pass it, etc
+  #
+  # call #run afterwards, to run.  or call parse! to parse and run
+  #
+  # typically, you shouldn't call this yourself.  call parse when you 
+  # want to RE-parse the arguments passed in, because initialize auto-parses
+  #
+  # typical:
+  #     Bin.new( ARGV ).run
+  #     Bin.new( ARGV, :default => 'some_default_method ).run
+  #
+  # use this is you want to ...
+  #     bin = Bin.new ARGV
+  #     bin.options[:default] = 'some_default_method'
+  #     bin.instance_eval { 'do some custom stuff that might change the command to run, etc' }
+  #     bin.parse!
+  #     bin.run
+  #
+  def parse!
+    args = @args.clone
+
+    @default_command  = @options[:default].to_s if @options.keys.include? :default
+    @commands         = all_commands
+
+    # if a command is discovered, eg. $ myscript foo 1 2 3 # where foo is a command
+    if not args.empty? and @commands.map {|c| c.downcase }.include? args.first.downcase
+      @command = args.shift.downcase
+
+    # if a command is not discovered, and no arguments were sent at all, eg. $ myscript
+    elsif args.empty?
+      @command = @default_command || 'usage'
+
+    # there were args passed, but we don't know what to call ... try command_missing first
+    elsif command_from_command_missing = command_missing(args)
+      @command = command_from_command_missing # if it returns something that's not nil, set it to command
+
+    # there were some arguments, pass if to the default command if there is one, else 'command not found'
+    elsif @default_command
+      @command = @default_command
+
+    # nothing worked out ... show command not found & usage
+    else
+      puts "command not found: #{ args.first.downcase }"
+      @command = 'usage'
+
+    end
+    
+    @command_args = args
+  end
+
+  # before dropping to default command ( if defined via :default option ), 
+  # the arguments get passed along to command_missing (you get the original args array)
+  #
+  # your command_missing can return a command string (name of the command) or just a proc to call!
+  #
+  # actually, if what you respond with responds to #call, we use that, else we call #to_s to 
+  # get the name of the command to run
+  #
+  # ***NOTE*** if command_missing makes changes to the args passed to it, these are persisted 
+  #            and passed to the command.  args.dup if you need to mess with args!
+  #
+  # if you return something #call-able, the command arguments will be passed to your block
+  #
+  # you can call super to drop back to the default command_missing in SimpleCLI 
+  # or just return nil to say "nope, can't find a command for this"
+  #
+  def command_missing args
+    nil
+  end
+  
+  # run command determined by parse
+  def run
+    begin
+      if @command.respond_to? :call
+        @command.call @command_args
+      else
+        self.send @command.to_s, *@command_args
+      end
+    rescue ArgumentError => ex
+      puts "'#{@command}' called with wrong number of arguments\n\n"
+      puts help_for( @command )
+    end
+  end
+
+  # returns names of all defined 'command' methods
+  #
+  # only returns methods with methodname_help sister methods, 
+  # inotherwords: only returns DOCUMENTED methods 
+  # ... this should get you to document that command!
+  def all_commands
+    self.methods.sort.grep( /_help/ ).collect{ |help_method| help_method.gsub( /(.*)_help/ , '\1' ) }
+  end
+
+  # returns help String for command
+  def help_for command
+    help_method = "#{ command }_help".to_sym
+    self.send( help_method ) if self.respond_to? help_method
+  end
+
+  # returns summary String for command (extracted from help_for command)
+  #
+  # Looks for
+  #     Summary:
+  #        some summary text here, on a new line after 'Summary:'
+  #
+  def summary_for command
+    doco = help_for command
+    if doco
+      match = /Summary:\n*(.*)/.match doco
+      if match and match.length > 1
+        match[1].strip
+      end
+    end
+  end
+
+  # default usage message, called if we can't figure out what command to run
+  #
+  # override in your app by re-defining - it should puts the message (or do whatever) itself!
+  # this method doesn't return a string, like blah_help methods (which are called by #help).
+  # usage is called, all by itself ... so it needs to print itself!
+  #
+  def usage *args
+    puts "default usage message.  please define a 'usage' method returning a new message."
+  end
+
+  # shortcut to pretty file name of script, which can be used in your help doco
+  def script_name
+    File.basename $0
+  end
+
+  # HELP
+  def help_help
+    <<doco
+Usage: #{ script_name } help COMMAND
+
+  Summary:
+    Provide help documentation for a command
+doco
+  end
+  def help *args
+    command = args.shift
+    if command.nil?
+      puts help_for( :help )
+    elsif (doco = help_for command)
+      puts doco
+    else
+      puts "No documentation found for command: #{command}"
+    end
+  end
+
+  # COMMANDS
+  def commands_help
+    <<doco
+Usage: #{ script_name } commands
+
+  Summary:
+    List all '#{ script_name }' commands
+doco
+  end
+  def commands *no_args
+    before_spaces = 4
+    after_spaces  = 18
+    text = all_commands.inject(''){ |all,cmd| all << "\n#{' ' * before_spaces}#{cmd}#{' ' * (after_spaces - cmd.length)}#{summary_for(cmd)}" }
+    puts <<doco 
+#{ script_name } commands are:
+
+    DEFAULT COMMAND   #{ @default_command || 'not set' }
+#{ text }
+
+For help on a particular command, use '#{ script_name } help COMMAND'.
+doco
+
+#If you've made a command and it's not showing up here, you
+#need to make help method named 'COMMAND_help' that returns 
+#your commands help documentation.
+#
+#[NOT YET IMPLEMENTED:]
+#Commands may be abbreviated, so long as they are unumbiguous.
+#e.g. 'snip h commands' is short for 'snip help commands'.
+#doco
+  end
+
+end

metadata

@@ -0,0 +1,61 @@
+--- !ruby/object:Gem::Specification 
+name: simplecli
+version: !ruby/object:Gem::Version 
+  version: 0.1.6
+platform: ruby
+authors: 
+- remi
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-03-14 00:00:00 -07:00
+default_executable: 
+dependencies: []
+
+description: SimpleCLI gives you a stupidly simple way to implement command-line interfaces like that of RubyGems
+email: remi@remitaylor.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- Rakefile
+- VERSION.yml
+- README.rdoc
+- LICENSE
+- lib/simplecli.rb
+- examples/hello-cli
+has_rdoc: true
+homepage: http://github.com/remi/simplecli
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --inline-source
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 2
+summary: For making simple RubyGem-like command-line interfaces
+test_files: []
+