Pablo 0.0.1

data/README

@@ -0,0 +1,20 @@
+
+This is Pablo, a Ruby commandline parser that is entirely based on the concept of blocks.
+Pablo stands for "PArsing BLOcks" (I know, it's a really stupid name).
+
+_______________________________________________________
+
+License: Creative Commons Attribution 3.0 Germany
+For further information regarding this license, visit:
+http://creativecommons.org/licenses/by/3.0/de/
+______________________________________________________
+
+
+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!
+

data/lib/pablo.rb

@@ -0,0 +1,458 @@
+# This is Pablo, a commandline parser for Ruby based entirely on the
+# concept of blocks.
+#
+# If you want to find out more or need a tutorial, go to
+# http://pablo.rubyforge.org/
+# You'll find a nice wiki there!
+#
+# Author::      Fabian Streitel (karottenreibe)
+# Copyright::   Copyright (c) 2008 Fabian Streitel
+# License::     Creative Commons Attribution 3.0 Germany
+#               For further information regarding this license, you can go to
+#               http://creativecommons.org/licenses/by/3.0/de/
+# Homepage::    http://pablo.rubyforge.org/
+# Git repo::    http://www.github.org/pablo-commandline-parser/
+#
+
+module Pablo
+	##
+	# Parses arguments with the help of the tokens defined in the +block+.
+    #
+    # The arguments passed to the parser can be
+    # - one Hash, containing the options for the parsing process and
+    # - one Array, containing the arguments that should be parsed
+    #
+    # Either of the two can be omitted.
+    # If no arguments Array is found, +ARGV+ is parsed.
+    # If no options Hash is found, the defaults are used.
+	#
+	# See _Pablo::Parser#command_ and _Pablo::Parser#option_ for more details.
+	#
+	def self.parse *argsopts, &block
+        # parse arguments and options apart
+        args, opts = nil, {}
+        args = argsopts[1] if argsopts[1].is_a? Array
+        args = argsopts[0] if argsopts[0].is_a? Array
+        opts = argsopts[1] if argsopts[1].is_a? Hash
+        opts = argsopts[0] if argsopts[0].is_a? Hash
+
+		args = ARGV if args.nil?
+        # do under NO circumstances modify the real args
+        args = args.dup
+		
+		# create tokens
+		p = Pablo::TopLevel.new opts
+		p.instance_eval &block if block_given?
+
+        # test on a present help command
+        return if p.help? args
+
+		# prepare arguments for marking
+		args.collect! { |a| [ [], a ] }
+
+		# start marking
+		p.mark args
+
+		# start parsing
+		# we process the args until there are no remaining tokens that request parsing
+		empty = !args.any? { |pair| not pair[0].empty? }
+
+		# do the defaults if noone wants parsing
+		return p.do_defaults if empty
+
+		while not empty
+			# get the next token
+			next_token = args.index { |pair| not pair[0].empty? }
+			# parse it
+			args[next_token][0][0].parse args
+			# test on empty again
+			empty = !args.any? { |pair| not pair[0].empty? }
+		end
+	end
+	
+	##
+	# The base class for all parsing tokens, i.e. Options and Commands.
+	#
+	# Each token is expected to implement a mark and a parse method.
+	# The mark method is expected to mark all the occurrences of the command with a reference to
+	# it's +self+ object.
+	# The parse method will get all the parameters (including subcommands) for consuming.
+	#
+	class Token
+		##
+		# Initializes the structure so it's ready for processing
+		#
+		def initialize toplevel
+            @toplevel = toplevel
+            @toplevel.everyone << self if self != @toplevel
+			@aliases = []
+			@run = lambda {}
+			@requests = []
+			@tokens = []
+			@default = false
+			@sdesc = ""
+			@ldesc = ""
+		end
+
+        attr_reader :tokens
+
+		##
+		# Sets the +block+ to run on discovery of the token.
+		#
+		def run &block
+			@run = block if block_given?
+		end
+
+		##
+		# Adds the alias +a+ to the list of aliases for this token.
+		#
+		def name a
+			@aliases << a.to_s
+		end
+
+        attr_reader :aliases
+
+		##
+		# Marks all occurences of this command's aliases
+		#
+		def mark args
+			args.collect { |pair|
+				@aliases.each { |a| pair[0] << self if pair[1] == a }
+				pair
+			}
+
+			mark_children args
+		end
+
+		##
+		# A very basic implementation of parse that can be utilized by subclasses to make their
+		# code look tidier.
+		#
+		# Basically goes through the +args+ and removes the consumed arguments if there are any
+		# and calls the +@run+ block if there is any.
+		#
+		# If you supply a +block+ it will be executed instead of the +@run+ block.
+		#
+		def parse args, &block
+			# if no block has been given, we do the default
+			# watch out here: if you use a name that is already present (like args) for
+			# the block argument variable, it will actually use the already present
+			# variable! (not nice!)
+			block = lambda { |argus| @run.call argus } unless block_given?
+
+			return args if ( not @run and not block_given? ) or # no need to parse if we don't run anything...
+				@aliases.empty? # ...or don't have any names anyways.
+
+			# find ourselves
+			myself = args.index { |pair| pair[0].include? self }
+			# if we're not present, we can go
+			return args unless myself
+
+			# where the next mark is
+			stop = args[myself+1..-1].index { |pair| not pair[0].empty? }
+			stop += myself+1 if stop
+
+			# which arguments we will consume
+			myargs = args[myself+1...stop] unless stop.nil?
+			myargs = args[myself+1..-1] if stop.nil?
+
+			# and call the block
+			block.call unmark(myargs)
+
+			# consume the arguments if there are any
+			(0..args.length-1).each { |i|
+				# remove ourselves from our call
+				args[i][0].delete self if myself == i
+
+                # if others have registered for these arguments as well, let them have
+                # their fair share of the cake.
+                if args[myself] and args[myself][0].empty?
+				    # remove the whole call if there's noone else requesting it
+				    args[i] = nil if myself == i
+				    # remove our arguments
+				    args[i] = nil if myself < i and ( not stop or i < stop ) 
+                end
+			}
+			
+			args.reject! { |a| a.nil? }
+		end
+
+		##
+		# Goes through +@tokens+ and let's each of them mark the args.
+		#
+		def mark_children args
+			org_args = args.dup
+			@tokens.each { |t| args = t.mark args }
+			args
+		end
+
+		##
+		# Goes through +@tokens+ and let's each of them parse the args.
+		#
+		def parse_children args
+			@tokens.each { |t| args = t.parse args  }
+			args
+		end
+
+		##
+		# Whether or not the current token is a default token.
+		# I.e. it will be called in case no (recognized) arguments were supplied for the parent
+		# command (or the entire argument string if this is a level 1 token).
+		#
+		# _Note:_
+		# The blocks of default tokens' +@run+ blocks will be supplied with an empty array as a
+		# single argument when run as a default.
+		#
+		def default!; @default = true; end
+		attr_accessor :default
+
+		##
+		# Run the associated block explicitly.
+		# Used when running default commands.
+		#
+		def run!
+			@run.call [] if @run
+		end
+
+		##
+		# Removes all markings from the +args+ so they can be passed to the +@run+ block.
+		#
+		def unmark args
+			args.collect { |pair| pair[1] }
+		end
+
+		##
+		# Call this to provide a short descriptive text for the +--help/-h/help+ command
+		#
+		def short_desc desc
+			@sdesc = desc
+		end
+
+        attr_reader :sdesc
+
+		##
+		# Call this to provide a longer description of what the token does.
+		# This will be displayed when the user calls +--help/-h/help _command_+.
+		#
+		def long_desc desc
+			@ldesc = desc
+		end
+
+        attr_reader :ldesc
+	end
+
+	##
+	# Keeps and parses an option.
+	# Simple, easy, no children.
+	#
+	class Option < Pablo::Token
+		##
+		# Marks all occurences of this command's aliases
+		#
+		def mark args
+			args.collect { |pair|
+				@aliases.each { |a|
+					if a.length == 2 and '-' == a[0..0]
+						match = /-(.*)/.match pair[1]
+						pair[0] << self if match and match[1].include? a[1..1]
+					else
+						pair[0] << self if pair[1] == a
+					end
+				}
+				pair
+			}
+
+			mark_children args
+		end
+
+        ##
+        # Special name function for options. It prepends '--' or '-' to the name passed.
+        # Only exception, if the name already starts with '-' nothing will be changed.
+        #
+        def name a
+            if '-' == a[0..0] then super a
+            elsif 1 == a.length then super '-' + a
+            else super '--' + a
+            end
+        end
+	end
+
+	##
+	# Keeps and parses a command.
+	# More sophisticated than an option, can have children.
+	#
+	class Command < Pablo::Token
+		##
+		# Adds a subcommand to the current command. The +block+ will be executed in the context of
+		# the new command and can be used to set its aliases, what code to run on discovery etc.
+		#
+		def command &block
+			return unless block_given?
+			c = Pablo::Command.new @toplevel
+			c.instance_eval &block
+			@tokens << c
+		end
+
+		##
+		# Adds an option to the command. The +block+ will be executed in the context of the option
+		# and can be used to set its aliases, what code to run on discovery etc.
+		#
+		def option &block
+			o = Pablo::Option.new @toplevel
+			o.instance_eval &block
+			@tokens << o
+		end
+
+		##
+		# Implementation of parse for commands:
+		# 	- Let children mark
+		# 	- Parse ourselves using standard parse implementation
+		# 	- Let children parse
+		# 	- Return parsed args
+		#
+		def parse args
+			# will someone just for one second PLEASE think about the children!
+
+			# use the standard implementation to do the dirty job.
+			super args
+
+			# let the children have their fun as well!
+			parse_children args
+		end
+	end
+
+    ##
+    # Special TopLevel parser.
+    # Only instantiated by +Pablo::parse+. Contains additional commands.
+    #
+    class TopLevel < Pablo::Command
+        def initialize options
+            @everyone = []
+            @options = options
+            @help = false
+            super self # set toplevel
+        end
+
+        attr_accessor :everyone
+
+        ##
+        # Will run the default token's run block, if there is one or will try to show
+        # the help otherwise.
+        #
+		def do_defaults
+            done = false
+			@tokens.each { |t|
+                if t.default
+                    t.run!
+                    done = true
+                end
+            }
+
+            help? [] unless done
+		end
+
+        ##
+        # Tests whether a help command is present in +args+ and +help!+ has been called
+        # and if so:
+        # - executes +Pablo::help+
+        # - and returns true
+        # otherwise only returns false.
+        #
+        def help? args
+            return false unless @help
+            found = args.index { |a|
+                @help_aliases.any? { |h| h == a }
+            }
+            found = 0 if args.empty?
+            return false unless found
+            Pablo::help args[found+1..-1], @everyone, @options
+            return true
+        end
+
+        ##
+        # Instructs Pablo to display a help message generated from the +short_desc+
+        # and +long_desc+ descriptions of the tokens.
+        #
+        # +alis+ are the aliases the help command should respond to.
+        # By default these are _help_, _--help_ and _-h_.
+        #
+        def help! alis = ['help', '--help', '-h']
+            @help = true
+            @help_aliases = alis
+        end
+    end
+
+    ##TODO: Version command and version in help command
+    ##TODO: caseless aliases!
+
+    ##
+    # Displays a help message generated from the +short_desc+ and +long_desc+
+    # specifications of the tokens.
+    #
+    # Output depends on +args+.
+    #
+    # +tokens+ must be a complete list of all tokens defined in the parser.
+    #
+    # +options+ must be a hash of options that will be used to generate the
+    # output, namely +:program+, +:version+, +:usage+.
+    #
+    def self.help args, tokens, options
+        msg = ""
+        aliases = []
+        tokens.each { |t| t.aliases.each { |a| aliases << [a,t] } }
+
+        # whether help for a special command is requested or not
+        found = aliases.find { |a| a[0] == args[0] }
+        found = found[1] if found
+
+        # program name and version
+        puts "#{options[:program]} v#{options[:version].join '.'}" if
+            options[:program] and options[:version]
+
+        # usage
+        puts "Usage: #{options[:usage]}" if options[:usage]
+
+        if found  # do long_desc
+            # print long_desc
+            print "Help for "
+            print case found
+                  when Pablo::Command then 'command'
+                  when Pablo::Option then 'option'
+                  else 'Token'
+                  end
+            puts " '#{args[0]}':"
+            puts
+            puts found.ldesc
+
+            # print aliases
+            puts
+            puts "::Aliases"
+            puts found.aliases.join ", "
+
+            # print subcommands if any
+            strs = []
+            found.tokens.each { |t| strs << t.aliases[0] }
+            puts "\n::Subcommands" unless strs.empty?
+            puts strs.join "   "
+        else  # do short_descs
+            # print short_descs
+            puts '::Available commands and options'
+            puts
+
+            strs = []
+            tokens.each { |t| strs << [ t.aliases.join(' '), t.sdesc ] }
+            maxrow = strs.max_by { |x| x[0].length } || ['']
+            maxlen = maxrow[0].length.to_i + 2
+            strs.each { |s| msg += s[0].ljust(maxlen) + '|  ' + s[1] + "\n" }
+            puts msg
+
+            # print defaults if any
+            strs = []
+            tokens.each { |t| strs << t.aliases[0] if t.default }
+            puts "\n::Defaults" unless strs.empty?
+            puts strs.join ", "
+        end
+    end
+
+end
+

data/tests/help.rb

@@ -0,0 +1,135 @@
+#!/usr/bin/env ruby
+require 'test/unit'
+require 'lib/pablo'
+
+def error msg
+    # win does not support ANSI color sequences
+    puts "\e[31m" + msg + "\e[0m" unless PLATFORM =~ /win32/
+    puts msg if PLATFORM =~ /win32/
+    raise msg
+end
+
+def message msg
+    # win does not support ANSI color sequences
+    puts "\e[33m" + msg + "\e[0m" unless PLATFORM =~ /win32/
+    puts msg if PLATFORM =~ /win32/
+end
+
+class Help < Test::Unit::TestCase
+    def testHelp
+        args = ['help']
+
+        puts
+        message 'Expected output: some stupid help message'
+        message "-----------------------------------------"
+
+        Pablo::parse args, :program => 'stupid', :version => [1,0,5],
+                :usage => 'stupid --null <String>' do
+            option {
+                name 'null'
+                short_desc 'Displays a lot of zeros'
+                run { error "option 'null' incorrectly called!" }
+                long_desc 'Zero Zero Zero Zero Zero Zero\nZero!'
+            }
+
+            command {
+                name 'oneortwo'
+                name 'anotherone'
+                short_desc 'Displays one or two'
+                long_desc 'One two? One two!\noneoneone twotwotwo.'
+                run { error "command 'oneortwo' incorrectly called!" }
+                default!
+            }
+
+            help!
+        end
+
+        message '-----------------------------------------'
+        message 'End of expected output'
+    end
+
+    def testCommandHelp
+        args = ['help', 'oneortwo']
+
+        puts
+        message 'Expected output: some stupid command help'
+        message '-----------------------------------------'
+
+        Pablo::parse args, :program => 'stupid', :version => [1,0,5],
+                :usage => 'stupid --null <String>' do
+            option {
+                name 'n'
+                name 'null'
+                short_desc 'Displays a lot of zeros'
+                long_desc "Zero Zero Zero Zero Zero Zero\nZero!"
+                run { error "option 'null' incorrectly called!" }
+            }
+
+            command {
+                name 'oneortwo'
+                name 'anotherone'
+                short_desc 'Displays one or two'
+                long_desc "One two? One two!\noneoneone twotwotwo."
+                default!
+                run { error "command 'oneortwo' incorrectly called!" }
+
+                command {
+                    name 'threeAndFour'
+                }
+            }
+
+            help!
+        end
+
+        message '-----------------------------------------'
+        message 'End of expected output'
+        puts
+    end
+
+    def testHelpAliases
+        args = ['huuulpy']
+
+        puts
+        message 'Expected output: the same message again'
+        message "-----------------------------------------"
+
+        Pablo::parse args, :program => 'stupid', :version => [1,0,5],
+                :usage => 'stupid --null <String>' do
+            option {
+                name 'null'
+                short_desc 'Displays a lot of zeros'
+                run { error "option 'null' incorrectly called!" }
+                long_desc 'Zero Zero Zero Zero Zero Zero\nZero!'
+            }
+
+            command {
+                name 'oneortwo'
+                name 'anotherone'
+                short_desc 'Displays one or two'
+                long_desc 'One two? One two!\noneoneone twotwotwo.'
+                run { error "command 'oneortwo' incorrectly called!" }
+                default!
+            }
+
+            help! ['huuulpy', 'foo']
+        end
+
+        message '-----------------------------------------'
+        message 'End of expected output'
+    end
+
+    def testHelpDefault
+
+        puts
+        message 'Expected output: an empty help message'
+        message "-----------------------------------------"
+
+        Pablo::parse [] do
+            help!
+        end
+
+        message '-----------------------------------------'
+        message 'End of expected output'
+    end
+end
+

data/tests/tests.rb

@@ -0,0 +1,290 @@
+#!/usr/bin/env ruby
+require 'test/unit'
+require 'lib/pablo'
+
+class Tests < Test::Unit::TestCase
+	def self.val
+		@@val
+	end
+
+	def self.val= v
+		@@val = v
+	end
+
+	def testSingleCommand
+		args = [ "add", "5" ]
+		Tests.val = 0
+	
+		Pablo::parse args do
+			command {
+				name 'add'
+				run { |args| Tests.val += args[0].to_i }
+			}
+		end
+
+		assert_equal 5, Tests.val
+	end
+    
+    def testSingleCharOption
+		args = [ "-n", "3" ]
+		Tests.val = 0
+	
+		Pablo::parse args do
+			option {
+				name 'n'
+				run { |args| Tests.val += args[0].to_i }
+			}
+		end
+
+		assert_equal 3, Tests.val
+
+	end
+
+	def testMultiCharOption
+		args = [ "--nojo", "3" ]
+		Tests.val = 0
+	
+		Pablo::parse args do
+			option {
+				name 'nojo'
+				run { |args| Tests.val += args[0].to_i }
+			}
+		end
+
+		assert_equal 3, Tests.val
+
+	end
+
+    def testDashPrependedOption
+		args = [ "-nojo", "3" ]
+		Tests.val = 0
+	
+		Pablo::parse args do
+			option {
+				name '-nojo'
+				run { |args| Tests.val += args[0].to_i }
+			}
+		end
+
+		assert_equal 3, Tests.val
+
+	end
+
+    def testOptionMerging
+		args = [ "-no", "3" ]
+		Tests.val = 0
+	
+		Pablo::parse args do
+			option {
+				name 'n'
+				run { |args| Tests.val += args[0].to_i }
+			}
+            
+            option {
+				name 'o'
+				run { |args| Tests.val += args[0].to_i }
+			}
+		end
+
+		assert_equal 6, Tests.val
+
+	end
+
+	def testUnneccessaryData
+		args = [ "bla", "blu", "-n", "3", "dudu" ]
+		Tests.val = []
+	
+		Pablo::parse args do
+			option {
+				name 'n'
+				run { |args| 
+					Tests.val << args[0].to_i << args.count }
+			}
+		end
+
+		assert_equal 3, Tests.val[0]
+		assert_equal 2, Tests.val[1]
+
+	end
+
+	def testManyTokens
+		args = [ "add", "5", "add", "3", "-r", "2", "-m",  "add", "3", "-m" ]
+		Tests.val = [ [0,0], [0,0], [0,0], 0 ]
+	
+		Pablo::parse args do
+			command {
+				name 'add'
+				run { |args|
+					Tests.val[0][0] += 1 #call counter
+					Tests.val[0][1] += args.count #args counter
+					Tests.val[3] += args[0].to_i
+				}
+			}
+
+			option {
+				name 'r'
+				run { |args|
+					Tests.val[1][0] += 1
+					Tests.val[1][1] += args.count
+					Tests.val[3] -= args[0].to_i
+				}
+			}
+
+			option {
+				name 'm'
+				run { |args|
+					Tests.val[2][0] += 1
+					Tests.val[2][1] += args.count
+					Tests.val[3] += 10
+				}
+			}
+		end
+
+		assert_equal [3, 3], Tests.val[0]
+		assert_equal [1, 1], Tests.val[1]
+		assert_equal [2, 0], Tests.val[2]
+		assert_equal 29, Tests.val[3]
+
+	end
+
+	def testDefault
+		args = []
+		Tests.val= 0
+
+		Pablo::parse args do
+			command {
+				name 'never'
+				run { |args| Tests.val += 1 }
+			}
+
+			command {
+				name 'ever'
+				run { |args| Tests.val += 2 }
+				default!
+			}
+
+            command {
+                name 'java'
+                run { |args| Tests.val += 4 }
+                default!
+            }
+		end
+
+		assert_equal 6, Tests.val
+	end
+
+	def testDefaultCluttered
+		args = ['junky', 'bacon']
+		Tests.val= 0
+
+		Pablo::parse args do
+			command {
+				name 'never'
+				run { |args| Tests.val += 1 }
+			}
+
+			command {
+				name 'ever'
+				run { |args| Tests.val += 2 }
+				default!
+			}
+		end
+
+		assert_equal 2, Tests.val
+	end
+
+	##TODO: still failing!
+=begin
+	def testDefaultLevel2
+		args = ["bla"]
+		Tests.val= 0
+
+		Pablo::parse args do
+			command {
+				name 'never'
+				run { |args| Tests.val += 1 }
+			}
+
+			command {
+				name 'bla'
+				run { |args| Tests.val += 4 }
+
+				option {
+					name 'ever'
+					run { |args| Tests.val += 2 }
+					default!
+				}
+			}
+		end
+
+		assert_equal 6, Tests.val
+	end
+=end
+
+    ##TODO: make code-order possible.
+	def testNaturalOrder
+		args = ["--first", "second"]
+		Tests.val = []
+
+		Pablo::parse args do
+			command {
+				name 'second'
+				run { |args| Tests.val << 2 }
+			}
+
+			option {
+				name 'first'
+				run { |args| Tests.val << 1 }
+			}
+		end
+
+		assert_equal [1,2], Tests.val
+	end
+
+    def testEmptyParser
+        Pablo::parse do
+        end
+        Pablo::parse
+    end
+
+    ##TODO: implement children before parent as well
+    ##TODO: implement passing of args from children to parents as well
+	def testParentBeforeChildren
+		args = ['add', 5, '--mul', 2]
+		Tests.val = 0
+
+		Pablo::parse args do
+			command {
+				name 'add'
+				run { |args| Tests.val += args[0].to_i }
+
+				option {
+					name 'mul'
+					run { |args| Tests.val *= args[0].to_i }
+				}
+			}
+		end
+
+		assert_equal 10, Tests.val
+	end
+
+	def testMultiOptions
+		args = ['-nu']
+		Tests.val = 0
+
+		Pablo::parse args do
+			option {
+				name 'n'
+				run { |args| Tests.val += 2 }
+			}
+
+			option {
+				name 'u'
+				run { |args| Tests.val += 5 }
+			}
+		end
+
+		assert_equal 7, Tests.val
+	end
+end
+

metadata

@@ -0,0 +1,55 @@
+--- !ruby/object:Gem::Specification 
+name: Pablo
+version: !ruby/object:Gem::Version 
+  version: 0.0.1
+platform: ruby
+authors: 
+- Fabian Streitel
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2008-12-07 00:00:00 -08:00
+default_executable: 
+dependencies: []
+
+description: 
+email: karottenreibe @nospam@ gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README
+files: 
+- lib/pablo.rb
+- README
+has_rdoc: true
+homepage: http://pablo.rubyforge.org/
+post_install_message: 
+rdoc_options: []
+
+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: pablo
+rubygems_version: 1.3.1
+signing_key: 
+specification_version: 2
+summary: A commandline parser for Ruby that is entirely based on blocks.
+test_files: 
+- tests/help.rb
+- tests/tests.rb