cli 1.0.0 → 1.1.0

data/README.md

@@ -8,9 +8,87 @@ Command Line Interface gem allows you to quickly specify command argument parser
 
 ## Examples
 
+### HTTPClient example
+
+The following example shows basic usage of the CLI gem.
+It will use HTTPClient to connect to server that address and port can be specified with `--server` and `--port` switches.
+It expects at least one argument specifying the URL (that needs to start with `/`) and optional set of POST arguments.
+
+```ruby
+re 'rubygems'
+require 'cli'
+require 'httpclient'
+
+options = CLI.new do
+    option :server, :description => 'server address', :default => 'www.google.com'
+    option :port,	:description => 'server port', :cast => Integer, :default => 80
+    argument :url,	:description => 'URL to GET or POST to if arguments are given'
+    arguments :post_arguments, :required => false
+end.parse! do |options|
+    fail "invalid URL '#{options.url}', URL has to start with '/'" unless options.url =~ /^\//
+end
+
+c = HTTPClient.new
+
+begin
+    if options.post_arguments.empty?
+        puts c.get_async("http://#{options.server}:#{options.port}#{options.url}").pop.content.read
+    else
+        puts c.post_async("http://#{options.server}:#{options.port}#{options.url}", options.post_arguments.join("\n")).pop.content.read
+    end 
+rescue SocketError, Errno::ECONNREFUSED => e
+    puts "Falied to connect: #{e}"
+end
+```
+
+Example usage with default server:
+
+    examples/httpclient /index.html
+
+The output will contain Google website.
+
+Using different server:
+
+    examples/httpclient --server ibm.com /index.html
+
+When run without arguments:
+
+    examples/httpclient
+
+The following message will be printed and the program will exit (status 42):
+
+    Error: mandatory argument 'url' not given
+    Usage: httpclient [switches|options] [--] url [post-arguments*]
+    Switches:
+       --help (-h) - display this help message
+    Options:
+       --server [www.google.com] - server address
+       --port [80] - server port
+    Arguments:
+       url - URL to GET or POST to if arguments are given
+       post-arguments* (optional)
+
+When used with command that does not start with `/`:
+
+    examples/httpclient test
+
+It will print the following message and exit:
+
+    Error: invalid URL 'test', URL has to start with '/'
+    Usage: httpclient [switches|options] [--] url [post-arguments*]
+    Switches:
+       --help (-h) - display this help message
+    Options:
+       --server [www.google.com] - server address
+       --port [80] - server port
+    Arguments:
+       url - URL to GET or POST to if arguments are given
+       post-arguments* (optional)
+
 ### Sinatra server example
 
 ```ruby
+require 'rubygems'
 require 'cli'
 require 'ip'
 
@@ -84,6 +162,7 @@ Example version output:
 ### Statistic data processor example
 
 ```ruby
+require 'rubygems'
 require 'cli'
 require 'pathname'
 require 'yaml'
@@ -106,7 +185,7 @@ p options
 
 Example help message:
 
-    Usage: processor [switches|options] [--] jekyll-dir < log-data
+    Usage: processor [switches|options] [--] [jekyll-dir] < log-data
     Generate blog posts in given Jekyll directory from input statistics
     Input:
        log-data - statistic data in YAML format
@@ -116,7 +195,7 @@ Example help message:
        --location (-l) - location name (ex. Dublin, Singapore, Califorina)
        --csv-dir (-c) [csv] - directory name where CSV file will be storred (relative to jekyll-dir)
     Arguments:
-       jekyll-dir - directory where site source is located
+       jekyll-dir [/var/lib/vhs/jekyll] - directory where site source is located
 
 With this example usage (assuming /var/lib/vhs/jekyll/csv dir exist):
 
@@ -133,7 +212,7 @@ The `options` variable will contain:
 Output if jekyll-dir does not exist:
 
     Error: jekyll-dir is not a directory
-    Usage: processor [switches|options] [--] jekyll-dir < log-data
+    Usage: processor [switches|options] [--] [jekyll-dir] < log-data
     Generate blog posts in given Jekyll directory from input statistics
     Input:
        log-data - statistic data in YAML format
@@ -155,6 +234,7 @@ Default and mandatory arguments will have priority on matching values (see specs
 The `options` specifier matched value will always be an array of casted elements or empty if option not specified.
 
 ```ruby
+require 'rubygems'
 require 'cli'
 require 'pathname'
 
@@ -182,7 +262,7 @@ end
 
 Example help message:
 
-    Usage: ls [switches|options] [--] directories*
+    Usage: ls [switches|options] [--] [directories*]
     Lists content of directories
     Switches:
        --long (-l) - use long listing

data/VERSION

@@ -1 +1 @@
-1.0.0
+1.1.0

data/cli.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = "cli"
-  s.version = "1.0.0"
+  s.version = "1.1.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Jakub Pastuszek"]
-  s.date = "2011-12-31"
+  s.date = "2012-01-02"
   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 = [
@@ -26,6 +26,7 @@ Gem::Specification.new do |s|
     "Rakefile",
     "VERSION",
     "cli.gemspec",
+    "examples/httpclient",
     "examples/ls",
     "examples/processor",
     "examples/sinatra",

data/examples/httpclient

@@ -0,0 +1,26 @@
+#!/usr/bin/ruby
+require 'rubygems'
+require 'cli'
+require 'httpclient'
+
+options = CLI.new do
+    option :server, :description => 'server address', :default => 'www.google.com'
+    option :port, :description => 'server port', :cast => Integer, :default => 80
+    argument :url, :description => 'URL to GET or POST to if arguments are given'
+    arguments :post_arguments, :required => false
+end.parse! do |options|
+    fail "invalid URL '#{options.url}', URL has to start with '/'" unless options.url =~ /^\//
+end
+
+c = HTTPClient.new
+
+begin
+    if options.post_arguments.empty?
+        puts c.get_async("http://#{options.server}:#{options.port}#{options.url}").pop.content.read
+    else
+        puts c.post_async("http://#{options.server}:#{options.port}#{options.url}", options.post_arguments.join("\n")).pop.content.read
+    end 
+rescue SocketError, Errno::ECONNREFUSED => e
+    puts "Falied to connect: #{e}"
+end
+

data/examples/ls

@@ -1,4 +1,5 @@
-#!/usr/bin/ruby -rrubygems
+#!/usr/bin/ruby
+require 'rubygems'
 require 'cli'
 require 'pathname'
 

data/examples/processor

@@ -1,4 +1,5 @@
-#!/usr/bin/ruby -rrubygems
+#!/usr/bin/ruby
+require 'rubygems'
 require 'cli'
 require 'pathname'
 require 'yaml'

data/examples/sinatra

@@ -1,20 +1,21 @@
-#!/usr/bin/ruby -rrubygems
+#!/usr/bin/ruby
+require 'rubygems'
 require 'cli'
 require 'ip'
 
 options = CLI.new do
 	description 'Example CLI usage for Sinatra server application'
 	version "1.0.0"
-	switch :no_bind,					:description => "Do not bind to TCP socket - useful with -s fastcgi option"
-	switch :no_logging,				:description => "Disable logging"
-	switch :debug,						:description => "Enable debugging"
+	switch :no_bind,			:description => "Do not bind to TCP socket - useful with -s fastcgi option"
+	switch :no_logging,			:description => "Disable logging"
+	switch :debug,				:description => "Enable debugging"
 	switch :no_optimization,	:description => "Disable size hinting and related optimization (loading, prescaling)"
-	option :bind,							:short => :b, :default => '127.0.0.1', :cast => IP, :description => "HTTP server bind address - use 0.0.0.0 to bind to all interfaces"
-	option :port,							:short => :p, :default => 3100, :cast => Integer, :description => "HTTP server TCP port"
-	option :server,						:short => :s, :default => 'mongrel', :description => "Rack server handler like thin, mongrel, webrick, fastcgi etc."
-	option :limit_memory,			:default => 128*1024**2, :cast => Integer, :description => "Image cache heap memory size limit in bytes"
-	option :limit_map,				:default => 256*1024**2, :cast => Integer, :description => "Image cache memory mapped file size limit in bytes - used when heap memory limit is used up"
-	option :limit_disk,				:default => 0, :cast => Integer, :description => "Image cache temporary file size limit in bytes - used when memory mapped file limit is used up"
+	option :bind,				:short => :b, :default => '127.0.0.1', :cast => IP, :description => "HTTP server bind address - use 0.0.0.0 to bind to all interfaces"
+	option :port,				:short => :p, :default => 3100, :cast => Integer, :description => "HTTP server TCP port"
+	option :server,				:short => :s, :default => 'mongrel', :description => "Rack server handler like thin, mongrel, webrick, fastcgi etc."
+	option :limit_memory,		:default => 128*1024**2, :cast => Integer, :description => "Image cache heap memory size limit in bytes"
+	option :limit_map,			:default => 256*1024**2, :cast => Integer, :description => "Image cache memory mapped file size limit in bytes - used when heap memory limit is used up"
+	option :limit_disk,			:default => 0, :cast => Integer, :description => "Image cache temporary file size limit in bytes - used when memory mapped file limit is used up"
 end.parse!
 
 p options

data/lib/cli.rb

@@ -234,15 +234,7 @@ class CLI
 		# process arguments
 		arguments = @arguments.dup
 		while argument = arguments.shift
-			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
+			value = if arguments.mandatory.length < argv.length
 				arg = argv.shift
 
 				if argument.multiple?
@@ -254,6 +246,14 @@ class CLI
 				else
 					arg
 				end
+			else
+				if argument.has_default?
+					argument.default
+				elsif not argument.mandatory?
+					argument.multiple? ? [] : nil
+				else
+					raise ParsingError::MandatoryArgumentNotSpecifiedError.new(argument) if argv.empty?
+				end
 			end
 
 			values.value(argument, argument.cast(value))
@@ -298,11 +298,21 @@ class CLI
 		out = StringIO.new
 		out.puts msg if msg
 		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?
+		out.print ' [switches|options]' if not @switches.empty? and not @options.optional.empty?
+		out.print ' [switches]' if not @switches.empty? and @options.optional.empty?
+		out.print ' [options]' if @switches.empty? and not @options.optional.empty?
+		@options.mandatory.each do |o|
+			out.print " #{o.switch} <value>"
+		end
 		out.print ' [--]' if not @arguments.empty? and (not @switches.empty? or not @options.empty?)
-		out.print ' ' + @arguments.map{|a| a.multiple? ? a.to_s + '*': a.to_s}.join(' ') unless @arguments.empty?
+		out.print ' ' unless @arguments.empty?
+		out.print(@arguments.map do |a|
+			v = ''
+			v += '[' unless a.mandatory?
+			v += a.multiple? ? a.to_s + '*': a.to_s
+			v += ']' unless a.mandatory?
+			v
+		end.join(' '))
 		out.print " < #{@stdin}" if @stdin
 
 		out.puts
@@ -333,23 +343,24 @@ class CLI
 					out.print "   #{o.switch}*"
 				end
 				out.print " (#{o.switch_short})" if o.has_short?
+				out.print ' (mandatory)' if o.mandatory?
 				out.print " [%s]" % o.default if o.has_default?
 				out.print " - #{o.description}" if o.description?
 				out.puts
 			end
 		end
 
-		described_arguments = @arguments.select{|a| a.description?}
-		unless described_arguments.empty?
+		unless @arguments.empty?
 			out.puts "Arguments:"
-			described_arguments.each do |a|
+			@arguments.each do |a|
 				unless a.multiple?
 					out.print "   #{a}"
 				else
 					out.print "   #{a}*"
 				end
+				out.print ' (optional)' if not a.mandatory? and not a.has_default?
 				out.print " [%s]" % (a.default.is_a?(Array) ? a.default.join(' ') : a.default) if a.has_default?
-				out.print " - #{a.description}"
+				out.print " - #{a.description}" if a.description?
 				out.puts
 			end
 		end

data/lib/cli/options.rb

@@ -9,6 +9,10 @@ class CLI::Options < CLI::Switches
 		select{|o| o.mandatory?}
 	end
 
+	def optional
+		select{|o| not o.mandatory?}
+	end
+
 	def multiple
 		select{|a| a.multiple?}
 	end

data/spec/argument_spec.rb

@@ -150,62 +150,21 @@ 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
-					argument :log, :cast => Pathname, :default => '/tmp'
-					argument :test
-				end.parse(['hello'])
-				ps.log.should be_a Pathname
-				ps.log.to_s.should == '/tmp'
-				ps.test.should be_a String
-				ps.test.should == 'hello'
-
-				ps = CLI.new do
-					argument :log, :cast => Pathname
-					argument :test, :default => 'hello'
-				end.parse(['/tmp'])
-				ps.log.should be_a Pathname
-				ps.log.to_s.should == '/tmp'
-				ps.test.should be_a String
-				ps.test.should == 'hello'
-
-				ps = CLI.new do
-					argument :log, :cast => Pathname
-					argument :magick, :default => 'word'
-					argument :test
-					argument :code, :cast => Integer, :default => '123'
-				end.parse(['/tmp', 'hello'])
-				ps.log.to_s.should == '/tmp'
-				ps.magick.should == 'word'
-				ps.test.should == 'hello'
-				ps.code.should == 123
-
+			it "should fill defaults form the beginning if more than required arguments are given" do
 				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
+					argument :test1, :default => 'x'
+					argument :test2
+					argument :test3, :default => 'c'
+					argument :test4, :default => 'd'
+					argument :test5, :default => 'e'
+				end.parse(['a', 'b'])
+				ps.test1.should == 'a'
+				ps.test2.should == 'b'
+				ps.test3.should == 'c'
+				ps.test4.should == 'd'
+				ps.test5.should == 'e'
 
-			it "should fill defaults form the beginning if more than required arguments are given" do
 				ps = CLI.new do
 					argument :log, :cast => Pathname
 					argument :magick, :default => 'word'
@@ -272,7 +231,56 @@ describe CLI do
 				ps.code.should == 123
 			end
 
-			it "should use empty array of values for multiple arguments argument when not enought arguments given" do
+			it "should fill at least one value of required multiple arguments argument" do
+				ps = CLI.new do
+					argument :test1, :default => 'x'
+					argument :test2, :default => 'b'
+					arguments :test3
+					argument :test4, :default => 'd'
+					argument :test5, :default => 'e'
+				end.parse(['a', 'c'])
+				ps.test1.should == 'a'
+				ps.test2.should == 'b'
+				ps.test3.should == ['c']
+				ps.test4.should == 'd'
+				ps.test5.should == 'e'
+			end
+		end
+
+		describe "not required"  do
+			it "argument that is not required may be nil if there is not enought command arguments" do
+				ps = CLI.new do
+					argument :test1, :required => false
+					argument :test2, :required => false
+					argument :test3, :required => false
+					argument :test4, :required => false
+					argument :test5, :required => false
+				end.parse(['a', 'b'])
+				ps.test1.should == 'a'
+				ps.test2.should == 'b'
+				ps.test3.should be_nil
+				ps.test4.should be_nil
+				ps.test5.should be_nil
+
+				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
+
+			it "should use empty array for multiple arguments argument when not enought arguments given and it is not required" do
+				ps = CLI.new do
+					argument :test1, :required => false
+					argument :test2, :required => false
+					arguments :test3, :required => false
+				end.parse(['a', 'b'])
+				ps.test1.should == 'a'
+				ps.test2.should == 'b'
+				ps.test3.should == []
+
 				ps = CLI.new do
 					argument :log, :cast => Pathname
 					argument :magick, :default => 'word'

data/spec/usage_spec.rb

@@ -184,39 +184,79 @@ describe CLI do
 			ss.usage.should include("4")
 		end
 
-		it "should suggest that arguments can be used in usage line" do
-			ss = CLI.new do
-				argument :location
+		describe "usage line" do
+			it "should suggest that arguments can be used in usage line" do
+				ss = CLI.new do
+					argument :location
+				end
+
+				# switches will always be there due to implicit --help switch
+				ss.usage.first.should == "Usage: rspec [switches] [--] location\n"
 			end
 
-			# switches will always be there due to implicit --help switch
-			ss.usage.first.should == "Usage: rspec [switches] [--] location\n"
-		end
+			it "should suggest that switches can be used in usage line" do
+				ss = CLI.new do
+					switch :location, :short => :l
+				end
 
-		it "should suggest that switches can be used in usage line" do
-			ss = CLI.new do
-				switch :location, :short => :l
+				ss.usage.first.should == "Usage: rspec [switches]\n"
 			end
 
-			ss.usage.first.should == "Usage: rspec [switches]\n"
-		end
+			it "should suggest that options can be used in usage line" do
+				ss = CLI.new do
+					option :location, :short => :l
+				end
 
-		it "should suggest that options can be used in usage line" do
-			ss = CLI.new do
-				option :location, :short => :l
+				# switches will always be there due to implicit --help switch
+				ss.usage.first.should == "Usage: rspec [switches|options]\n"
 			end
 
-			# switches will always be there due to implicit --help switch
-			ss.usage.first.should == "Usage: rspec [switches|options]\n"
-		end
+			it "should suggest that switches or options can be used in usage line" do
+				ss = CLI.new do
+					switch :location, :short => :l
+					option :size, :short => :s
+				end
 
-		it "should suggest that switches or options can be used in usage line" do
-			ss = CLI.new do
-				switch :location, :short => :l
-				option :size, :short => :s
+				ss.usage.first.should == "Usage: rspec [switches|options]\n"
 			end
 
-			ss.usage.first.should == "Usage: rspec [switches|options]\n"
+			it "should suggest that option is mandatory" do
+				ss = CLI.new do
+					option :size, :required => true
+					option :group, :short => :g, :required => true
+				end
+
+				# switches will always be there due to implicit --help switch
+				ss.usage.first.should == "Usage: rspec [switches] --size <value> --group <value>\n"
+
+				ss = CLI.new do
+					option :location, :short => :l
+					option :size, :required => true
+					option :group, :short => :g, :required => true
+				end
+
+				# switches will always be there due to implicit --help switch
+				ss.usage.first.should == "Usage: rspec [switches|options] --size <value> --group <value>\n"
+
+				ss = CLI.new do
+					switch :location, :short => :l
+					option :size, :short => :s, :required => true
+				end
+
+				ss.usage.first.should == "Usage: rspec [switches] --size <value>\n"
+			end
+
+			it "should suggest that argument is optional" do
+				ss = CLI.new do
+					argument :location
+					argument :size, :required => false
+					argument :colour, :default => 'red'
+					argument :group
+				end
+
+				# switches will always be there due to implicit --help switch
+				ss.usage.first.should == "Usage: rspec [switches] [--] location [size] [colour] group\n"
+			end
 		end
 
 		it "should allow describing whole script" do
@@ -251,7 +291,7 @@ describe CLI do
 			u.should include("log data to process")
 		end
 
-		it "should provide formated usage with optional message" do
+		it "should provide formated usage" do
 			u = CLI.new do
 				description 'Log file processor'
 				version '1.0'
@@ -261,7 +301,7 @@ describe CLI do
 				switch :run
 				option :location, :short => :r, :description => "place where server is located"
 				option :group, :default => 'red'
-				options :power_up, :short => :p
+				options :power_up, :short => :p, :required => true
 				option :speed, :short => :s, :cast => Integer
 				option :the_number_of_the_beast, :short => :b, :cast => Integer, :default => 666, :description => "The number of the beast"
 				option :size
@@ -269,14 +309,15 @@ describe CLI do
 				argument :log, :cast => Pathname, :description => "log file to process"
 				argument :magick, :default => 'word'
 				argument :string
-				argument :number, :cast => Integer
+				argument :limit, :cast => Integer, :required => false, :description => "limit in seconds"
+				argument :unlock_code, :cast => Integer, :required => false
 				argument :code, :cast => Integer, :default => '123', :description => "secret code"
 				argument :illegal_prime, :cast => Integer, :description => "prime number that represents information that it is forbidden to possess or distribute"
 				arguments :files, :cast => Pathname, :default => ['test', '1', '2'], :description => "files to process"
 			end.usage
 
 			u.should == <<EOS
-Usage: rspec [switches|options] [--] log magick string number code illegal-prime files* < log-data
+Usage: rspec [switches|options] --power-up <value> [--] log [magick] string [limit] [unlock-code] [code] illegal-prime [files*] < log-data
 Log file processor
 Input:
    log-data - YAML formatted log data
@@ -289,12 +330,16 @@ Switches:
 Options:
    --location (-r) - place where server is located
    --group [red]
-   --power-up* (-p)
+   --power-up* (-p) (mandatory)
    --speed (-s)
    --the-number-of-the-beast (-b) [666] - The number of the beast
    --size
 Arguments:
    log - log file to process
+   magick [word]
+   string
+   limit (optional) - limit in seconds
+   unlock-code (optional)
    code [123] - secret code
    illegal-prime - prime number that represents information that it is forbidden to possess or distribute
    files* [test 1 2] - files to process

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: cli
 version: !ruby/object:Gem::Version 
-  hash: 23
+  hash: 19
   prerelease: 
   segments: 
   - 1
+  - 1
   - 0
-  - 0
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors: 
 - Jakub Pastuszek
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-12-31 00:00:00 Z
+date: 2012-01-02 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   type: :development
@@ -142,6 +142,7 @@ files:
 - Rakefile
 - VERSION
 - cli.gemspec
+- examples/httpclient
 - examples/ls
 - examples/processor
 - examples/sinatra