pablo 1.0.3

data/History.txt

@@ -0,0 +1,4 @@
+=== 1.0.3 / 2009-05-05
+
+* First release of version 1
+

data/LICENSE.txt

@@ -0,0 +1,22 @@
+/*---- DON'T PANIC License 1.1 -----------
+
+  Don't panic, this piece of software is
+  free, i.e. you can do with it whatever
+  you like, including, but not limited to:
+  
+    * using it
+    * copying it
+    * (re)distributing it
+    * burning/burying/shredding it
+    * eating it
+    * using it to obtain world domination
+    * and ignoring it
+  
+  Under the sole condition that you
+  
+    * CONSIDER buying the author a strong
+      brownian motion producer, say a nice
+      hot cup of tea, should you ever meet
+      him in person.
+
+----------------------------------------*/

data/Manifest.txt

@@ -0,0 +1,26 @@
+History.txt
+LICENSE.txt
+Manifest.txt
+README.txt
+lib/pablo.rb
+lib/pablo/always.rb
+lib/pablo/arguments.rb
+lib/pablo/color.rb
+lib/pablo/command.rb
+lib/pablo/errors.rb
+lib/pablo/expansion.rb
+lib/pablo/help.rb
+lib/pablo/helpers.rb
+lib/pablo/option.rb
+lib/pablo/parser.rb
+lib/pablo/token.rb
+lib/pablo/version.rb
+test/fixtures/license.txt
+test/fixtures/load_yaml.yml
+test/fixtures/output.yml
+test/help_fixtures.rb
+test/test_arguments.rb
+test/test_expansion.rb
+test/test_output.rb
+test/test_pablo.rb
+test/test_parsers.rb

data/README.txt

@@ -0,0 +1,61 @@
+= pablo
+
+Support for pablo is given at http://pablo.rubyforge.org/.
+If you have questions, problems, want to report bugs or request features, this is the
+place for you.
+Have fun with it!
+
+== DESCRIPTION
+
+This is pablo, a Ruby commandline parser that follows the command/option paradigm.
+pablo stands for "PArsing BLOcks" (I know, it's a really stupid name).
+
+== FEATURES/PROBLEMS:
+
+* Commandline parsing following the well-known command/option paradigm (like `gem` does).
+* Easy declaration and description of commands/options via YAML syntax
+* Auto-generated `help`, `version` and `license` commands
+* Optional expansion of commands and options and detection of ambiguities
+
+== SYNOPSIS:
+
+  pablo ARGV, :program => 'test', :desc => 'a test program',
+      :version => '1.0', :license => 'GPL or something' do
+
+    desc('prints foo')
+    option :foo do
+        puts 'foo'
+    end
+
+    help_command
+    version_command
+    license_command
+    ambiguity_command
+
+    command :bar do |args, pablo|
+        option :goo || missing_argument('goo')
+
+        if pablo.options[:goo]
+            puts 'goo'
+        else
+            puts 'bar'
+        end
+    end
+  end
+
+== REQUIREMENTS:
+
+* none so far
+
+== INSTALL:
+
+* On Linux:
+  sudo gem install -t pablo
+* On Windows:
+  gem install -t pablo
+
+== LICENSE:
+
+DON'T PANIC License v1.1
+See LICENSE.txt for full license text
+

data/lib/pablo.rb

@@ -0,0 +1,298 @@
+###### DON'T PANIC License 1.1 ###########
+#
+# Don't panic, this piece of software is
+# free, i.e. you can do with it whatever
+# you like, including, but not limited to:
+# 
+#   * using it
+#   * copying it
+#   * (re)distributing it
+#   * burning/burying/shredding it
+#   * eating it
+#   * using it to obtain world domination
+#   * and ignoring it
+# 
+# Under the sole condition that you
+# 
+#   * CONSIDER buying the author a strong
+#     brownian motion producer, say a nice
+#     hot cup of tea, should you ever meet
+#     him in person.
+#
+##########################################
+
+# other libs
+require 'yaml'
+
+# global helpers
+require 'pablo/helpers'
+
+# standard equipment
+require 'pablo/arguments'
+require 'pablo/parser'
+require 'pablo/command'
+require 'pablo/option'
+require 'pablo/token'
+require 'pablo/always'
+
+# additional gadgets
+require 'pablo/color'
+require 'pablo/errors'
+require 'pablo/expansion'
+require 'pablo/help'
+
+#
+# Shortcut. Creates a Pablo instance, instance_evals the
+# given block on it an calls Pablo#parse.
+# Also, if +args+ is empty, +ARGV+ will be used.
+def pablo args, opts = Hash.new, &block
+    raise 'pablo needs a block to do something senisble' unless block_given?
+    args = [ARGV] if args.empty?
+    p = Pablo.new opts
+    p.instance_eval(&block)
+    p.parse args
+end
+
+#
+# Does the heavy lifting.
+class Pablo
+
+    include Pablo::Helpers
+
+    attr_accessor :args
+    attr_accessor :options, :commands, :tokens
+    attr_accessor :registered, :expand
+
+    #
+    # * +opts+: options for Pablo
+    #   * :command_consumes_all => true|false
+    #     Forces toplevel commands (not) to consume all arguments after
+    #     being applied.
+    #     I'm still looking for a better name for that option, so it may
+    #     be subject to change.
+    #   * :expand => true|false|Array
+    #     Turns on the automatic abbreviation expansion mechanism for
+    #     * all parsers (true)
+    #     * no parsers (false)
+    #     * a specific parser (Array containing :commands and/or :options)
+    #   * :program => String
+    #     The name of the Program to be displayed by +help+ and +version+.
+    #   * :version => String
+    #     The version of the Program to be displayed by +version+ and +help+.
+    #   * :usage => String
+    #     The usage information of the Program to be displayed by +help+, e.g.
+    #       [<command>] [<options>]
+    def initialize opts = Hash.new
+        @opts = {
+            :command_consumes_all => true,
+            :expand => false
+        }.merge(opts)
+
+        check_options()
+
+        @finalize = @colorize = @cur = nil
+        @toplevel, @args, @pending = true, nil, Hash.new
+        @expand, @ambiguity, @registered = Array.new, nil, Array.new
+        @options, @commands, @tokens = Hash.new, Hash.new, Hash.new
+    end
+
+    #
+    # Starts the parsing process on the given +args+,
+    # according to the registered parsers.
+    def parse args
+        @toplevel, @args = false, Pablo::Arguments.new(args)
+
+        catch :abort do
+            begin
+                @registered.each { |parser|
+                    @cur = parser
+                    parser.parse(@args)
+                }
+                true
+            rescue MissingArgumentError, WrongArgumentError => e
+                $stderr.puts e.message
+                false
+            end
+        end
+    end
+
+    #
+    # Define a command.
+    # +args+ must be:
+    # * at least one name for the command
+    # * a hash of options:
+    #   * :default
+    #     The default value to be set if the command is not recognized.
+    #   * :consume_all => true|false
+    #     Whether (or not) the command should consume_all remaining
+    #     arguments after it has been recognized
+    #   * :consume => Fixnum|String|Regexp|Array
+    #     * Fixnum: consume the next n arguments
+    #     * String: consume if the next argument equals that String. Else
+    #       the option will not match.
+    #     * Regexp: consume if the next argument matches that Regexp. Else
+    #       the option will not match.
+    #     * Array: consume next +arr.length+ arguments if they equal those
+    #       given in the Array.
+    #   * :expand => Proc
+    #     A Proc that will be passed a single argument String and a single
+    #     name of the token as parameters and has to return a Boolean indicating
+    #     whether or not the String is an abbreviation of that name.
+    def command *args, &block
+        exec(Pablo::Command, *args, &block)
+    end
+    alias_method :cmd, :command
+
+    #
+    # Define an option.
+    # +args+ must be:
+    # * at least one name for the command
+    # * a hash of options:
+    #   * :default
+    #     The default value to be set if the option is not recognized.
+    #   * :negative => true|false|String
+    #     If +true+, the option will have a counterpart named +--no<name>+.
+    #     If a String, the option will have a counterpart named
+    #     +--<string><name>+.
+    #   * :consume => Fixnum|String|Regexp|Array
+    #     * Fixnum: consume the next n arguments
+    #     * String: consume if the next argument equals that String. Else
+    #       the option will not match.
+    #     * Regexp: consume if the next argument matches that Regexp. Else
+    #       the option will not match.
+    #     * Array: consume next +arr.length+ arguments if they equal those
+    #       given in the Array.
+    #   * :expand => Proc
+    #     A Proc that will be passed a single argument String and a single
+    #     name of the token as parameters and has to return a Boolean indicating
+    #     whether or not the String is an abbreviation of that name.
+    def option *args, &block
+        exec(Pablo::Option, *args, &block)
+    end
+    alias_method :opt, :option
+
+    #
+    # Define a token.
+    # +args+ must be:
+    # * at least one name for the command
+    # * a hash of options:
+    #   * :default
+    #     The default value to be set if the token is not recognized.
+    #   * :consume => Fixnum|String|Regexp|Array
+    #     * Fixnum: consume the next n arguments
+    #     * String: consume if the next argument equals that String. Else
+    #       the option will not match.
+    #     * Regexp: consume if the next argument matches that Regexp. Else
+    #       the option will not match.
+    #     * Array: consume next +arr.length+ arguments if they equal those
+    #       given in the Array.
+    def token *args, &block
+        exec(Pablo::Token, *args, &block)
+    end
+    alias_method :tok, :token
+
+    #
+    # Define arbitrary code to always run at that stage of parsing.
+    def always &block
+        exec(Pablo::Always, &block)
+    end
+
+    #
+    # Set the short description of the next parser.
+    def desc d
+        @pending[:desc] = d
+    end
+
+    #
+    # Set the long description of the next parser.
+    def longdesc l
+        @pending[:longdesc] = l
+    end
+
+    #
+    # Set the usage information of the next parser.
+    def usage u
+        @pending[:usage] = u
+    end
+
+    #
+    # Loads whole parsers and global options from a YAML source.
+    # +yml+ can either be a String of YAML or the path of a YAML file.
+    def load_yaml yml
+        yml = open(yml).read() if File.exist?(yml)
+        opts = YAML::load(yml)
+
+        parsers = opts.delete(:parsers)
+        @opts.merge!(opts)
+
+        parsers.each do |p|
+            type = [:command, :token, :option, :help_command,
+                :ambiguity_command, :license_command, :version_command].find { |s| !p[s].nil? }
+
+            unless type.nil?
+                args = p.delete(type)
+
+                if args.is_a? Array then args << p
+                else args = [p]
+                end
+
+                type == :ambiguity_command ?
+                    self.send(type) : self.send(type, *args)
+            end
+        end
+    end
+
+    #
+    # Whether or not we dwell at toplevel currently.
+    # Only valid within a Command, Option, Token etc,
+    # but NOT within this class.
+    def toplevel?
+        @toplevel
+    end
+
+    #
+    # Sets the run object for this pablo instance.
+    def run= object
+        @opts[:run] = object
+    end
+
+    #
+    # Returns the object which keeps all the instance methods corresponding
+    # to the defined parsers - or +nil+ if none was given
+    def run_object
+        @opts[:run]
+    end
+
+    #
+    # Whether or not commands should consume all arguments after they
+    # parsed something.
+    def consume_all?
+        @opts[:command_consumes_all]
+    end
+
+    private
+
+    def check_options
+        raise ":expand expects any of true, false, :commands, :options" unless
+            [true, false, :commands, :options].include? @opts[:expand]
+        %w{program version usage}.each { |sym|
+            raise ":#{sym} expects a String" unless
+                @opts[sym.to_sym].nil? or @opts[sym.to_sym].respond_to? :to_str
+        }
+    end
+
+    #
+    # Generalization of command, option etc. methods.
+    def exec klass, *args, &block
+        opts = args[-1].respond_to?(:to_hash) ?
+            args.delete_at(-1).to_hash : Hash.new
+        opts = @pending.merge(opts)
+        @pending.clear
+        args << opts
+
+        e = klass.new(self, *args, &block)
+        e.parse(@args) unless @toplevel
+    end
+
+end
+

data/lib/pablo/always.rb

@@ -0,0 +1,44 @@
+###### DON'T PANIC License 1.1 ###########
+#
+# Don't panic, this piece of software is
+# free, i.e. you can do with it whatever
+# you like, including, but not limited to:
+# 
+#   * using it
+#   * copying it
+#   * (re)distributing it
+#   * burning/burying/shredding it
+#   * eating it
+#   * using it to obtain world domination
+#   * and ignoring it
+# 
+# Under the sole condition that you
+# 
+#   * CONSIDER buying the author a strong
+#     brownian motion producer, say a nice
+#     hot cup of tea, should you ever meet
+#     him in person.
+#
+##########################################
+
+class Pablo
+
+    class Always
+
+        def initialize pablo, *args, &block
+            @pablo, @block = pablo, block
+            @pablo.registered << self
+        end
+
+        def parse args
+            @block.call(args, @pablo)
+        end
+
+        def names_to_user; ''; end
+        def names_to_rex; nil; end
+        def klass_to_sym; :always; end
+
+    end
+
+end
+