cli 0.0.4 → 0.1.0

data/README.md

@@ -0,0 +1,151 @@
+# 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 specifying:
+
+* switches - (`--name` or `-n`) binary operators, by default set to nil and when specified set to true
+* options - (`--name John` or `-n John`) switches that take value; default value can be given, otherwise default to nil
+* arguments - (`John`) capture command arguments that are not switches
+* 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.
+
+## Installing
+
+    gem install cli
+
+## Usage
+
+### Sinatra server example
+
+```ruby
+require 'cli'
+require 'ip'
+
+options = CLI.new do
+	description 'Example CLI usage for Sinatra server application'
+	version (cli_root + 'VERSION').read
+	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"
+end.parse!
+
+# use to set sinatra settings
+require 'sinatra/base'
+
+sinatra = Sinatra.new
+
+sinatra.set :environment, 'production'
+sinatra.set :server, options.server
+sinatra.set :lock, true
+sinatra.set :boundary, "thumnail image data"
+sinatra.set :logging, (not options.no_logging)
+sinatra.set :debug, options.debug
+sinatra.set :optimization, (not options.no_optimization)
+sinatra.set :limit_memory, options.limit_memory
+sinatra.set :limit_map, options.limit_map
+sinatra.set :limit_disk, options.limit_disk
+
+# set up your application
+
+sinatra.run!
+```
+
+To see help message use `--help` or `-h` anywhere on the command line:
+
+    examples/sinatra --help
+
+Example help message:
+
+    Usage: sinatra [switches|options]
+    Example CLI usage for Sinatra server application
+    Switches:
+       --no-bind - Do not bind to TCP socket - useful with -s fastcgi option
+       --no-logging - Disable logging
+       --debug - Enable debugging
+       --no-optimization - Disable size hinting and related optimization (loading, prescaling)
+       --help (-h) - display this help message
+       --version - display version string
+    Options:
+       --bind (-b) [127.0.0.1] - HTTP server bind address - use 0.0.0.0 to bind to all interfaces
+       --port (-p) [3100] - HTTP server TCP port
+       --server (-s) [mongrel] - Rack server handler like thin, mongrel, webrick, fastcgi etc.
+       --limit-memory [134217728] - Image cache heap memory size limit in bytes
+       --limit-map [268435456] - Image cache memory mapped file size limit in bytes - used when heap memory limit is used up
+       --limit-disk [0] - Image cache temporary file size limit in bytes - used when memory mapped file limit is used up
+
+To see version string use `--version`
+
+    examples/sinatra --version
+
+Example version output:
+
+    sinatra version "0.0.4"
+
+### Statistic data processor example
+
+```ruby
+require 'cli'
+
+options = CLI.new do
+	description 'Generate blog posts in given Jekyll directory from input statistics'
+	stdin :log_data,		:cast => YAML, :description => 'statistic data in YAML format'
+	option :location,		:short => :l, :description => 'location name (ex. Dublin, Singapore, Califorina)'
+	option :csv_dir,		:short => :c, :cast => Pathname, :default => 'csv', :description => 'directory name where CSV file will be storred (relative to jekyll-dir)'
+	argument :jekyll_dir,	:cast => Pathname, :default => '/var/lib/vhs/jekyll', :description => 'directory where site source is located'
+end.parse!
+
+# do your stuff
+```
+
+Example help message:
+
+    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
+    Switches:
+       --help (-h) - display this help message
+    Options:
+       --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
+
+With this example usage:
+
+    examples/processor --location Singapore <<EOF
+    :parser: 
+      :successes: 41
+      :failures: 0
+    EOF
+
+The `options` variable will contain:
+
+    #<CLI::Values location="Singapore", stdin={:parser=>{:failures=>0, :successes=>41}}, jekyll_dir=#<Pathname:/var/lib/vhs/jekyll>, csv_dir=#<Pathname:csv>>
+
+## 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
+* Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
+* Fork the project
+* Start a feature/bugfix branch
+* Commit and push until you are happy with your contribution
+* Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
+* Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
+
+## Copyright
+
+Copyright (c) 2011 Jakub Pastuszek. See LICENSE.txt for
+further details.
+

data/VERSION

@@ -1 +1 @@
-0.0.4
+0.1.0

data/cli.gemspec

@@ -5,16 +5,16 @@
 
 Gem::Specification.new do |s|
   s.name = "cli"
-  s.version = "0.0.4"
+  s.version = "0.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-15"
+  s.date = "2011-12-16"
   s.description = "Provides DSL for command-line options, switches and arguments parser and stdin handling with generated usage printer"
   s.email = "jpastuszek@gmail.com"
   s.extra_rdoc_files = [
     "LICENSE.txt",
-    "README.rdoc"
+    "README.md"
   ]
   s.files = [
     ".document",
@@ -22,10 +22,12 @@ Gem::Specification.new do |s|
     "Gemfile",
     "Gemfile.lock",
     "LICENSE.txt",
-    "README.rdoc",
+    "README.md",
     "Rakefile",
     "VERSION",
     "cli.gemspec",
+    "examples/processor",
+    "examples/sinatra",
     "features/cli.feature",
     "features/step_definitions/cli_steps.rb",
     "features/support/env.rb",
@@ -34,8 +36,15 @@ Gem::Specification.new do |s|
     "lib/cli/dsl.rb",
     "lib/cli/options.rb",
     "lib/cli/switches.rb",
+    "spec/argument_spec.rb",
     "spec/cli_spec.rb",
-    "spec/spec_helper.rb"
+    "spec/conflict_reporting_spec.rb",
+    "spec/option_spec.rb",
+    "spec/separator_spec.rb",
+    "spec/spec_helper.rb",
+    "spec/stdin_spec.rb",
+    "spec/switch_spec.rb",
+    "spec/usage_spec.rb"
   ]
   s.homepage = "http://github.com/jpastuszek/cli"
   s.licenses = ["MIT"]

data/examples/processor

@@ -0,0 +1,17 @@
+#!/usr/bin/ruby
+require 'pathname'
+cli_root = Pathname.new(__FILE__).dirname + '..'
+$LOAD_PATH.unshift(cli_root + 'lib')
+
+require 'cli'
+
+options = CLI.new do
+	description 'Generate blog posts in given Jekyll directory from input statistics'
+	stdin :log_data,		:cast => YAML, :description => 'statistic data in YAML format'
+	option :location,		:short => :l, :description => 'location name (ex. Dublin, Singapore, Califorina)'
+	option :csv_dir,		:short => :c, :cast => Pathname, :default => 'csv', :description => 'directory name where CSV file will be storred (relative to jekyll-dir)'
+	argument :jekyll_dir,	:cast => Pathname, :default => '/var/lib/vhs/jekyll', :description => 'directory where site source is located'
+end.parse!
+
+p options
+

data/examples/sinatra

@@ -0,0 +1,41 @@
+#!/usr/bin/ruby
+require 'pathname'
+cli_root = Pathname.new(__FILE__).dirname + '..'
+$LOAD_PATH.unshift(cli_root + 'lib')
+
+require 'cli'
+require 'ip'
+
+options = CLI.new do
+	description 'Example CLI usage for Sinatra server application'
+	version (cli_root + 'VERSION').read
+	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"
+end.parse!
+
+p options
+
+## use to set sinatra settings
+#require 'sinatra/base'
+#
+#sinatra = Sinatra.new
+#
+#sinatra.set :environment, 'production'
+#sinatra.set :server, options.server
+#sinatra.set :lock, true
+#sinatra.set :boundary, "thumnail image data"
+#sinatra.set :logging, (not options.no_logging)
+#sinatra.set :debug, options.debug
+#sinatra.set :optimization, (not options.no_optimization)
+#sinatra.set :limit_memory, options.limit_memory
+#sinatra.set :limit_map, options.limit_map
+#sinatra.set :limit_disk, options.limit_disk
+

data/lib/cli.rb

@@ -98,13 +98,21 @@ class CLI
 		@arguments = Arguments.new
 		@switches = Switches.new
 		@options = Options.new
+
 		instance_eval(&block) if block_given?
+
+		switch :help, :short => :h, :description => 'display this help message'
+		switch :version, :description => 'display version string' if @version
 	end
 
 	def description(desc)
 		@description = desc
 	end
 
+	def version(version)
+		@version = version.to_s
+	end
+
 	def stdin(name = :data, options = {})
 		@stdin = DSL::Input.new(name, options)
 	end
@@ -143,10 +151,19 @@ class CLI
 		values = Values.new
 		argv = _argv.dup
 
-		# check help
-		if argv.include? '-h' or argv.include? '--help' 
-			values.help = usage
-			return values
+		# check help and version
+		argv.each do |arg|
+			break if arg == '--'
+
+			if arg == '-h' or arg == '--help' 
+				values.help = usage
+				return values
+			end
+
+			if @version and arg == '--version' 
+				values.version = "#{name} version \"#{@version}\"\n"
+				return values
+			end
 		end
 
 		# set defaults
@@ -157,7 +174,7 @@ class CLI
 		# process switches
 		mandatory_options = @options.mandatory.dup
 
-		while Switches.is_switch?(argv.first)
+		while not argv.first == '--' and Switches.is_switch?(argv.first)
 			arg = argv.shift
 
 			if switch = @switches.find(arg)
@@ -171,18 +188,24 @@ class CLI
 			end
 		end
 
+		argv.shift if argv.first == '--'
+
 		# check mandatory options
 		raise ParsingError::MandatoryOptionsNotSpecifiedError.new(mandatory_options) unless mandatory_options.empty?
 
 		# process arguments
 		arguments = @arguments.dup
+		mandatory_arguments_left = @arguments.mandatory.length
+
 		while argument = arguments.shift
-			value = if argv.length < arguments.length + 1 and argument.optional?
-				argument.default # not enough arguments, try to skip optional if possible
+			value = if argv.length == mandatory_arguments_left and not argument.mandatory?
+				argument.default # use defaults for optional arguments
 			else
 				argv.shift or raise ParsingError::MandatoryArgumentNotSpecifiedError.new(argument)
 			end
 
+			mandatory_arguments_left -= 1 if argument.mandatory?
+
 			values.value(argument, argument.cast(value))
 		end
 
@@ -199,19 +222,28 @@ class CLI
 				stdout.write pp.help
 				exit 0
 			end
+			if pp.version
+				stdout.write pp.version
+				exit 0
+			end
 			pp
 		rescue ParsingError => pe
 			usage!(pe, stderr)
 		end
 	end
 
+	def name
+		File.basename $0
+	end
+
 	def usage(msg = nil)
 		out = StringIO.new
 		out.puts msg if msg
-		out.print "Usage: #{File.basename $0}"
+		out.print "Usage: #{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 ' [--]' if not @arguments.empty? and (not @switches.empty? or not @options.empty?)
 		out.print ' ' + @arguments.map{|a| a.to_s}.join(' ') unless @arguments.empty?
 		out.print " < #{@stdin}" if @stdin
 

data/lib/cli/arguments.rb

@@ -2,5 +2,9 @@ class CLI::Arguments < Array
 	def has?(argument_dsl)
 		self.find{|a| a.name == argument_dsl.name}
 	end
+
+	def mandatory
+		select{|a| a.mandatory?}
+	end
 end
 

data/lib/cli/dsl.rb

@@ -15,17 +15,24 @@ class CLI
 		module Cast
 			def cast(value)
 				begin
-					cast_class = @options[:cast]
-					if cast_class == nil
-						value
-					elsif cast_class == Integer
-						value.to_i
-					elsif cast_class == Float
-						value.to_f
-					elsif cast_class == YAML
-						YAML.load(value)
+					cast_to = @options[:cast] or return value
+
+					if cast_to.is_a? Module # all classes are modules
+						if cast_to == Integer
+							value.to_i
+						elsif cast_to == Float
+							value.to_f
+						elsif cast_to == YAML
+							YAML.load(value)
+						else
+							cast_to.new(value)
+						end
 					else
-						cast_class.new(value)
+						if cast_to.is_a? Proc
+							cast_to.call(value)
+						else
+							raise ArgumentError, "can't cast to instance of #{cast_to.class.name}"
+						end
 					end
 				rescue => e
 					raise ParsingError::CastError.new(@name, @options[:cast].name, e)
@@ -39,21 +46,21 @@ class CLI
 			end
 
 			def description
-				@options[:description]
+				@options[:description].to_s
 			end
 		end
 
 		module Value
 			def default
-				@options[:default]
+				@options[:default].to_s
 			end
 
 			def has_default?
 				@options.member? :default
 			end
 
-			def optional?
-				has_default?
+			def mandatory?
+				not has_default?
 			end
 		end
 
@@ -112,8 +119,8 @@ class CLI
 			include DSL::Value
 			include DSL::Cast
 
-			def optional?
-				has_default? or not @options[:required]
+			def mandatory?
+				not has_default? and @options[:required]
 			end
 		end
 	end