cli 0.4.0 → 1.0.0

data/README.md

@@ -1,25 +1,12 @@
 # CLI
 
-Command Line Interface gem allows you to quickly specify command argument parser that will automatically handle usage rendering, casting, default values and other stuff for you.
-
-CLI supports following specifiers:
-
-* switch - (`--verbose` or `-v`) binary operators, by default set to nil, when specified set to true
-* option - (`--name John` or `-n John`) switches that take value; default value can be specified, otherwise defaults to nil
-* options - (`-n John -n Frank`) like option but can be used multiple times on command line; default value or array of values can be given, otherwise defaults to empty array
-* argument - (`John`) capture single command; default value can be specified; raises error if not given
-* arguments - (`John Frank`) capture multiple command arguments; defaults to empty array
-* stdin - if standard input is to be handled it can be mentioned in usage output; also stdin data casting is supported
-
-Each element can have description that will be visible in the usage output.
-
-See examples and specs for more info.
+Command Line Interface gem allows you to quickly specify command argument parser that will automatically generate usage, handle stdin, switches, options and arguments with default values and value casting.
 
 ## Installing
 
     gem install cli
 
-## Usage
+## Examples
 
 ### Sinatra server example
 
@@ -273,6 +260,91 @@ Prints:
     501:20 pkg/cli-0.0.2.gem
     ...
     
+## Usage
+
+`CLI.new` takes a block where you specify parser behavior. The returned object is a parser that has `#parse` and `#parse!` methods.
+
+### `#parse` method
+
+It will take argument array (defaults to ARGV), standard input IO (defaults to STDIO) and standard error IO (defaults to STDERR).
+
+The method will parse argument array and cast standard input IO according to parser specification and return OpenStruct kind of object with resulting values.
+
+The returned object will have `help` attribute set if `--help` or `-h` switch was found in argument array or `version` attribute if `--version` argument was found. 
+In other case all the attributes will be set to appropriate values depending on argument array and parser specification.
+In case of parsing error `CLI::ParsingError` kind of exception will be raised.
+
+### `#parse!` method
+
+This is higher level version of `#parse` method that will exit the program and print out usage if there was parsing error. Also it will display usage on `--help` or `-h` switch and version string on `--version` switch found in argument array.
+
+In other case it will return OpenStruct object from `#parse` method.
+
+Additionally this method can be called with a block that will get the OpenStruct like object before returning it. This block should contain additional value verifications and if it raises RuntimeError (via `fail` method for instance) the error message will be displayed followed by usage and the program will exit.
+
+### Parser behavior specifiers
+
+#### description 'string'
+The *string* will be displayed in usage output as your program short description.
+
+#### version 'string'
+The *string* representing program version that will be displayed when `--version` switch is used
+
+#### switch :name [, options hash]
+
+When switch is specified in the command argument list the object returned by `#parse` or `#parse!` will contain argument of same name set to `true`. Otherwise the argument value will be `nil`.
+
+*:name* should be a symbol that will map to long switch (`--name`) where underscore (`_`) will be replaced with minus (`-`). Name has to be unique.
+
+Option hash can contain following pairs:
+
+* **:short => :symbol** - where *:symbol* is a single letter symbol that will represent short switch name (`-n`). Short name has to be unique.
+* **:description => 'string'** - switch description string that will be displayed in the usage output
+
+#### option :name [, options hash]
+
+Same as *switch* but additionally it has to be followed by a value on the command argument list.
+The value after casting (if used) will be available from the `#parse` or `#parse!` returned object as argument of the same name.
+
+In addition to *switch*, option hash can have following pairs:
+
+* **:default => value** - use default value of *value* if the option was not specified on the command argument list. The *value* will firstly be casted to string (with `#to_s`) and then it will be casted if casting is specified.
+* **:cast => cast specifier** - cast the provided value (or default) with given *cast specifier*. 
+The specifier can be a class constant (like `Integer` or `Float`); the value will be provided to `#new` method of the class and resulting object used as option value. When provided constant does not respond to `#new` (i.e. it is a module) the `#load` method will be tried. If provided specifier is a Proc (or `lambda {}`) the Proc will be called with the value and resulting value will be used. Otherwise `CLI::ParsingError::CastError` will be raised.
+* **:required => true** - if used and no *default* value is specified the `#parse` method will fail with `CLI::ParsingError::MissingOptionValueError` if the option was not specified in the command argument list. If `#parse!` method was used the program will exit with appropriate message.
+
+#### options :name [, options hash]
+
+Same as *option* but can be specified multiple times in the command argument list.
+The resulting `#parse` or `#parse!` returned object will contain an argument with the same name that will always be an array.
+The array may be empty if the option was not used and *required* option was not set, otherwise it will contain casted values in order of specification in the command argument list.
+
+#### argument :name [,options hash]
+
+After the parser encounters command line argument that is not a *switch* or *option* or it is literally `--` string it will start matching arguments.
+
+Each argument will be matched to argument specifications in order and their value after optional casting will be available as `#parse` or `#parse!` returned object argument with the same name.
+
+Options hash can contain the same pairs as *option* expect of **:short => :symbol**. 
+
+If defaults are used the parser will keep using default values until it has enough command line arguments available to fill all mandatory arguments.
+Arguments are required by default, use **:required => false** option pair to use `nil` value if argument is not specified on the command line argument list.
+
+#### arguments :name [,options hash]
+
+Same as *argument* but will match one or more arguments and provide them in array of casted values.
+If argument is not required and not specified in command argument list then its value will be an empty array.
+
+When used with *argument* specifiers that use default values the parser will try to assign at least one value to this specifier, but not more values so that all mandatory (that have no default and are required) arguments will be assigned.
+
+#### stdin :name, [options hash]
+
+Used once to specify that stdin should be handled.
+When used the `#parse` or `#parse!` returned object will have `stdin` argument that by default will contain stdin IO object.
+
+As with *switch* specifier the **:description => 'string'** can be used.
+Also **:cast => cast specifier** option pair can be used but the value will be an IO object and not string.
+
 ## Contributing to CLI
  
 * Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet

data/Rakefile

@@ -17,8 +17,8 @@ Jeweler::Tasks.new do |gem|
   gem.name = "cli"
   gem.homepage = "http://github.com/jpastuszek/cli"
   gem.license = "MIT"
-  gem.summary = %Q{Helps writing Command-line interface program}
-  gem.description = %Q{Provides DSL for command-line options, switches and arguments parser and stdin handling with generated usage printer}
+  gem.summary = %Q{Command line argument parser with stdin handling and usage generator}
+  gem.description = %Q{Command Line Interface gem allows you to quickly specify command argument parser that will automatically generate usage, handle stdin, switches, options and arguments with default values and value casting}
   gem.email = "jpastuszek@gmail.com"
   gem.authors = ["Jakub Pastuszek"]
   # dependencies defined in Gemfile

data/VERSION

@@ -1 +1 @@
-0.4.0
+1.0.0

data/cli.gemspec

@@ -5,12 +5,12 @@
 
 Gem::Specification.new do |s|
   s.name = "cli"
-  s.version = "0.4.0"
+  s.version = "1.0.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Jakub Pastuszek"]
-  s.date = "2011-12-30"
-  s.description = "Provides DSL for command-line options, switches and arguments parser and stdin handling with generated usage printer"
+  s.date = "2011-12-31"
+  s.description = "Command Line Interface gem allows you to quickly specify command argument parser that will automatically generate usage, handle stdin, switches, options and arguments with default values and value casting"
   s.email = "jpastuszek@gmail.com"
   s.extra_rdoc_files = [
     "LICENSE.txt",
@@ -51,7 +51,7 @@ Gem::Specification.new do |s|
   s.licenses = ["MIT"]
   s.require_paths = ["lib"]
   s.rubygems_version = "1.8.10"
-  s.summary = "Helps writing Command-line interface program"
+  s.summary = "Command line argument parser with stdin handling and usage generator"
 
   if s.respond_to? :specification_version then
     s.specification_version = 3

data/lib/cli.rb

@@ -181,7 +181,7 @@ class CLI
 			end
 
 			if @version and arg == '--version' 
-				values.version = "#{name} version \"#{@version}\"\n"
+				values.version = "#{CLI.name} version \"#{@version}\"\n"
 				return values
 			end
 		end
@@ -234,10 +234,15 @@ class CLI
 		# process arguments
 		arguments = @arguments.dup
 		while argument = arguments.shift
-			value = if arguments.mandatory.length >= argv.length and argument.has_default?
-				argument.default
+			value = if arguments.mandatory.length >= argv.length
+				if argument.has_default?
+					argument.default
+				elsif not argument.mandatory?
+					argument.multiple? ? [] : nil
+				else
+					raise ParsingError::MandatoryArgumentNotSpecifiedError.new(argument) if argv.empty?
+				end
 			else
-				raise ParsingError::MandatoryArgumentNotSpecifiedError.new(argument) if argv.empty?
 				arg = argv.shift
 
 				if argument.multiple?
@@ -285,14 +290,14 @@ class CLI
 		end
 	end
 
-	def name
+	def self.name
 		File.basename $0
 	end
 
 	def usage(msg = nil)
 		out = StringIO.new
 		out.puts msg if msg
-		out.print "Usage: #{name}"
+		out.print "Usage: #{CLI.name}"
 		out.print ' [switches|options]' if not @switches.empty? and not @options.empty?
 		out.print ' [switches]' if not @switches.empty? and @options.empty?
 		out.print ' [options]' if @switches.empty? and not @options.empty?

data/lib/cli/dsl.rb

@@ -62,7 +62,7 @@ class CLI
 			end
 
 			def mandatory?
-				not has_default?
+				not has_default? and @options[:required]
 			end
 		end
 
@@ -87,6 +87,11 @@ class CLI
 			include DSL::Cast
 			include DSL::Description
 
+			def initialize(name, options = {})
+				super
+				@options[:required] = true unless @options.member?(:required)
+			end
+
 			def to_s
 				name.to_s.tr('_', '-')
 			end
@@ -148,10 +153,6 @@ class CLI
 			include DSL::Value
 			include DSL::Cast
 
-			def mandatory?
-				not has_default? and @options[:required]
-			end
-
 			def multiple?
 				false
 			end

data/spec/argument_spec.rb

@@ -150,6 +150,16 @@ describe CLI do
 			}.should raise_error CLI::ParserError::MultipleArgumentsSpecifierError, "only one 'arguments' specifier can be used, got: test1, test3"
 		end
 
+		it "should not require non mandatory argument" do
+			ps = CLI.new do
+				argument :log, :cast => Pathname
+				argument :test, :required => false
+			end.parse(['/tmp'])
+			ps.log.should be_a Pathname
+			ps.log.to_s.should == '/tmp'
+			ps.test.should be_nil
+		end
+
 		describe "with defaults" do
 			it "when not enought arguments given it should fill required arguments only with defaults" do
 				ps = CLI.new do
@@ -180,6 +190,19 @@ describe CLI do
 				ps.magick.should == 'word'
 				ps.test.should == 'hello'
 				ps.code.should == 123
+
+				ps = CLI.new do
+					argument :log, :cast => Pathname
+					argument :magick, :default => 'word'
+					argument :test0, :required => false
+					argument :test
+					argument :code, :cast => Integer, :default => '123'
+				end.parse(['/tmp', 'hello'])
+				ps.log.to_s.should == '/tmp'
+				ps.magick.should == 'word'
+				ps.test0.should be_nil
+				ps.test.should == 'hello'
+				ps.code.should == 123
 			end
 
 			it "should fill defaults form the beginning if more than required arguments are given" do
@@ -248,6 +271,24 @@ describe CLI do
 				ps.test2.should == 'test2'
 				ps.code.should == 123
 			end
+
+			it "should use empty array of values for multiple arguments argument when not enought arguments given" do
+				ps = CLI.new do
+					argument :log, :cast => Pathname
+					argument :magick, :default => 'word'
+					argument :test
+					arguments :words, :required => false
+					argument :test2
+					argument :code, :cast => Integer, :default => '123'
+				end.parse(['/tmp', 'test', 'test2'])
+
+				ps.log.to_s.should == '/tmp'
+				ps.magick.should == 'word'
+				ps.test.should == 'test'
+				ps.words.should == []
+				ps.test2.should == 'test2'
+				ps.code.should == 123
+			end
 		end
 	end
 end

data/spec/cli_spec.rb

@@ -28,6 +28,10 @@ describe CLI do
 		ps.debug.should be_true
 	end
 
+	it "provides name method that provides current program name" do
+		CLI.name.should == 'rspec'
+	end
+
 	describe "parse!" do
 		it "should return value structure with all the values on successful parsing" do
 			ps = CLI.new do

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: cli
 version: !ruby/object:Gem::Version 
-  hash: 15
+  hash: 23
   prerelease: 
   segments: 
+  - 1
   - 0
-  - 4
   - 0
-  version: 0.4.0
+  version: 1.0.0
 platform: ruby
 authors: 
 - Jakub Pastuszek
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-12-30 00:00:00 Z
+date: 2011-12-31 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   type: :development
@@ -123,7 +123,7 @@ dependencies:
   prerelease: false
   name: ruby-ip
   version_requirements: *id007
-description: Provides DSL for command-line options, switches and arguments parser and stdin handling with generated usage printer
+description: Command Line Interface gem allows you to quickly specify command argument parser that will automatically generate usage, handle stdin, switches, options and arguments with default values and value casting
 email: jpastuszek@gmail.com
 executables: []
 
@@ -194,6 +194,6 @@ rubyforge_project:
 rubygems_version: 1.8.10
 signing_key: 
 specification_version: 3
-summary: Helps writing Command-line interface program
+summary: Command line argument parser with stdin handling and usage generator
 test_files: []