cmdline 0.0.0

data/LICENSE

@@ -0,0 +1,58 @@
+This package is copyrighted free software by Tim Becker <tim@kuriositaet.de>.
+You can redistribute it and/or modify it under either the terms of the GPL
+(see COPYING.txt file), or the conditions below:
+
+  1. You may make and give away verbatim copies of the source form of the
+     software without restriction, provided that you duplicate all of the
+     original copyright notices and associated disclaimers.
+
+  2. You may modify your copy of the software in any way, provided that
+     you do at least ONE of the following:
+
+       a) place your modifications in the Public Domain or otherwise
+          make them Freely Available, such as by posting said
+	  modifications to Usenet or an equivalent medium, or by allowing
+	  the author to include your modifications in the software.
+
+       b) use the modified software only within your corporation or
+          organization.
+
+       c) rename any non-standard executables so the names do not conflict
+	  with standard executables, which must also be provided.
+
+       d) make other distribution arrangements with the author.
+
+  3. You may distribute the software in object code or executable
+     form, provided that you do at least ONE of the following:
+
+       a) distribute the executables and library files of the software,
+	  together with instructions (in the manual page or equivalent)
+	  on where to get the original distribution.
+
+       b) accompany the distribution with the machine-readable source of
+	  the software.
+
+       c) give non-standard executables non-standard names, with
+          instructions on where to get the original software distribution.
+
+       d) make other distribution arrangements with the author.
+
+  4. You may modify and include the part of the software into any other
+     software (possibly commercial).  But some files in the distribution
+     are not written by the author, so that they are not under this terms.
+
+     They are gc.c(partly), utils.c(partly), regex.[ch], st.[ch] and some
+     files under the ./missing directory.  See each file for the copying
+     condition.
+
+  5. The scripts and library files supplied as input to or produced as 
+     output from the software do not automatically fall under the
+     copyright of the software, but belong to whomever generated them, 
+     and may be sold commercially, and may be aggregated with this
+     software.
+
+  6. THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
+     IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
+     WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+     PURPOSE.
+

data/README

@@ -0,0 +1,242 @@
+
+= cmdline -- Yet Another Command Line Tool 
+
++cmdline+ is a small library to facilitate handling of command line
+arguments. +cmdline+ automatically checks that all required arguments
+and flags are set, performs validity checks on the arguments
+and automatically generates a usage message from the command line
+specification. Arguments are available via named accessors.
+
+	cmdline=CommandLine.new [
+		["-f", "-flag", :starts_with_a_digit, "value", true, nil, "must start with a number", /^\d.*/]
+	]
+	cmdline.parse ARGV
+	puts cmdline.starts_with_a_digit
+
+In the example above, +cmdline+ ensure the +ARGV+ array contains a -f
+(or -flag) flag which must have an argument that starts with a digit. If
+an approriate argument is found, it will be accessible via the
+automaticaly created +starts_with_a_digit+ accessor. If not, a usage
+message will be generate, printed and the application will exit.
+
+
+== Installing
+
+You can install the +cmdline+ package by executing:
+
+	gem install cmdline -r
+
+alternatively, you can download +.tar.gz+ or +.zip+ archives from 
+Rubyforge[http://rubyforge.org/frs/?group_id=3612] and install using the
++setup.rb+ script.
+
+== Types of Arguments
+
+* long and short flags : 
+	script.rb -s -long_flag
+* flags taking arguments: 
+	script.rb -o outfilename
+* subcommands (a la +gem+ or +svn+):
+	script.rb generate -h
+if you want to use subcommands, they have to appear as the very first
+argument, i.e. this is not possible
+	script.rb -v subcommand -h # NOT POSSIBLE
+* plain arguments:
+	script.rb -v file_name
+
+
+
+== Usage
+
+You'll need to require +cmdline+ like this:
+
+	require 'cmdline'
+
+(if you installed the package using gems, you'll either need to use:
+
+	require_gem 'cmdline'
+
+or start ruby with the -rubygems command line flag.)
+
+In order to use +cmdline+, you'll need to provide an array containing
+a definition for each argument and pass the +ARGV+ to the method
++parse+. (Actually, you can pass in any array, or none, in which case,
+ARGV will be used by default) An example (from examples/exmaple.rb):
+
+	require 'cmdline'	
+	cmdline=CommandLine.new [
+		["-m", "-message", :message, "message", true, nil, "message for 'usage'"]
+	]
+	cmdline.parse ARGV
+	puts cmdline.message
+
+Running the script yields:
+
+	$ruby example.rb
+	usage: example.rb options
+	  -m/-message <message>* message for 'usage'
+	  -h/--help              print this message
+	* required flags
+
+	missing mandatory flag -m 
+
+The definition for the --help flag was added by default. Running the
+script with the required argument yields:
+
+	$ruby example.rb -message 'This is the message to print.'
+	This is the message to print.
+
+=== Flag Definition
+
+Each argument that is should be accepted is defined using an array. In the
+above example, a single argument is defined:
+
+	["-m", "-message", :message, "message", true, nil, "message for 'usage'"]
+
+The meaning of the fields in the definition array (at least for flags)
+are as follows:
+
+1. the 'short' flag name
+2. the long flag name
+3. the name of the accessor through which the flag value will be available 
+4. this value defines whether the flag takes arguments (i.e. script.rb -o outfile). Value should be +false+ if the flag takes no argument (i.e.  script.rb -verbose) or a string which is used in the generated +usage+ message.
+5. whether this is a required argument
+6. default value in case the flag is not set on the command line
+7. a detailed message for the generated usage string
+8. an optional eighth argument that may be either a +proc+ or a regular expression to check the the validity of the passed argument or and Array containing all allowed arguments. 
+
+
+=== Subcommand Definition
+
+Subcommands are defined in a simliar manner. An example of how one would parse
++gem+ subcommands (from examples/subcommand_example.rb):
+
+	doc= <<END_DOC
+	    build            Build a gem from a gemspec
+	    cert             Adjust RubyGems certificate settings
+	    check            Check installed gems
+	    cleanup          Clean up old versions of installed gems in the local
+			     repository
+	    contents         Display the contents of the installed gems
+	    ...
+	END_DOC
+
+	command_arr=["build", "cert", "check", "cleanup", "contents"] # ...
+	cmdline=CommandLine.new [
+		[:command, nil, :command, "command", false, "build", doc, command_arr]
+	]
+
+	puts cmdline.command
+
+In this example, the subcommand isn't  required, so we'll use the
+automatically generated -h flag to display the usage message:
+
+	$ruby subcommand_example.rb -h
+	usage: subcommand_example.rb [command] [options]
+	    build            Build a gem from a gemspec
+	    cert             Adjust RubyGems certificate settings
+	    check            Check installed gems
+	    cleanup          Clean up old versions of installed gems in the local
+			     repository
+	    contents         Display the contents of the installed gems
+	    ...
+	  -h/--help print this message
+
+
+=== Final Arguments
+
+In order to access, verify and add usage information for plain
+arguments after flags (e.g. copy.rb -name tim -v file1 file2 file3) you
+can add a final definition (from examples/plain_args_example.rb):
+
+	args_doc = "files to process"		
+	file_readable=lambda{|f| File.readable? f}
+	cmdline=CommandLine.new [
+		[:args, nil, :args, "args", false, nil, args_doc, file_readable]
+	]
+	cmdline.parse ARGV
+	puts cmdline.args
+
+In the example above the file arguments are required. So running the
+example without args yields:
+
+	$ruby plain_args_example.rb
+	usage: plain_args_example.rb [options] args
+	  -h/--help print this message
+
+	args: files to process
+
+	missing mandatory args
+
+Finally, a proc is passed to check that any filename arguments refer to
+readable files.
+
+=== Putting it all together
+
+(from examples/long_example.rb):
+
+	commands_check= ["add", "blame", "cat", "checkout"]
+	file_readable=lambda{|f| File.readable? f}
+	cmdline=CommandLine.new [
+		[:command, nil, :command, "command", false, "add", commands_doc, commands_check],
+		["-o", nil, :outfile, "file", false, STDOUT, "filename to write output to, default STDOUT"],
+		["-i", "--infile", :infile, "file",  false, STDIN, "filename to read from, default STDIN", file_readable],
+		["-v", "--verbose", :verbose, false,  false, nil, "verbose"],
+		["-n", "--numeric", :number, "num",  true, nil, "numeric value", /^\d+$/],
+		[:args, nil, :args, "args", false, nil, args_doc, file_readable]
+	]
+	
+
+This definition requires:
+
+* an optional subcommand which defaults to "add"
+* an optional -o flag which defaults to STDOUT
+* an optional -i/--infile flag which checks that filename args refer to readable files	
+* an optional -v flag that doesn't take an argument
+* a mandatory -n/--numeric flag which checks the argument is numeric
+* optional args, which, if passed must be names of readable files
+
+The generated usage message will look like this:
+
+	$ruby long_example.rb 
+	usage: long_example.rb [command] options [args]
+
+	Available commands:
+	  add
+	  blame
+	  cat
+	  checkout
+
+	  -o <file>           filename to write output to, default STDOUT
+	  -i/--infile <file>  filename to read from, default STDIN
+	  -v/--verbose        verbose
+	  -n/--numeric <num>* numeric value
+	  -h/--help           print this message
+	* required flags
+
+	args: files to process
+
+	missing mandatory flag -n
+
+
+== Contact
+
+In case you discover bugs, offer suggestions for improvements or would
+like to help out with the project, you can contact me via email
+(tim@kuriositaet.de).	
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+=

data/Rakefile

@@ -0,0 +1,124 @@
+require "rake/rdoctask"
+require "rake/gempackagetask"
+require "rake/testtask"
+require "rake/clean"
+require "rubygems"
+
+# Some definitions that you'll need to edit in case you reuse this
+# Rakefile for your own project.
+
+SHORTNAME	='cmdline'	# this should be the rubyforge project name
+DESC		='Yet Another Command Line Tool'
+PKG_VERSION 	='0.0.0'
+LONG_DESC	= <<END_DESC
+	Library used to handle command line arguments.	
+END_DESC
+RUBYFORGE_USER	='a2800276'
+
+# Specifies the default task to execute. This is often the "test" task
+# and we'll change things around as soon as we have some tests.
+
+task  :default => [:rdoc]
+
+# The directory to generate +rdoc+ in.
+RDOC_DIR="doc/html"
+
+# This global variable contains files that will be erased by the `clean` task.
+# The `clean` task itself is automatically generated by requiring `rake/clean`.
+
+CLEAN << RDOC_DIR << "pkg"
+
+
+# This is the task that generates the +rdoc+ documentation from the
+# source files. Instantiating Rake::RDocTask automatically generates a
+# task called `rdoc`.
+
+Rake::RDocTask.new do |rd|
+	# Options for documenation generation are specified inside of
+	# this block. For example the following line specifies that the
+	# content of the README file should be the main page of the
+	# documenation.
+	rd.main = "README" 
+	
+	# The following line specifies all the files to extract
+	# documenation from.
+	rd.rdoc_files.include(	"README", "AUTHORS", "LICENSE", 
+				"CHANGELOG", "bin/**/*", "lib/**/*.rb", 
+				"examples/**/*rb","test/**/*.rb", "doc/*.rdoc")
+	# This one specifies the output directory ...
+	rd.rdoc_dir 	= "doc/html"
+
+	# Or the HTML title of the generated documentation set.
+	rd.title 	= "#{SHORTNAME}: #{DESC}"
+
+	# These are options specifiying how source code inlined in the
+	# documentation should be formatted.
+	
+	rd.options 	= ["--line-numbers", "--inline-source"]
+
+	# Check:
+	# `rdoc --help` for more rdoc options
+	# the {rdoc documenation home}[http://www.ruby-doc.org/stdlib/libdoc/rdoc/rdoc/index.html]
+	# or the documentation for the +Rake::RDocTask+ task[http://rake.rubyforge.org/classes/Rake/RDocTask.html]
+end
+
+# The GemPackageTask facilitates getting all your files collected
+# together into gem archives. You can also use it to generate tarball
+# and zip archives.
+
+# First you'll need to assemble a gemspec
+
+PKG_FILES 	= FileList['lib/**/*.rb', 'bin/**/*', 'examples/**/*', '[A-Z]*', 'test/**/*'].to_a
+
+spec = Gem::Specification.new do |s|
+	s.platform = Gem::Platform::RUBY
+	s.summary = "#{SHORTNAME}: #{DESC}"
+	s.name = SHORTNAME
+	s.version = PKG_VERSION
+	s.files = PKG_FILES
+	s.requirements << "none"
+	s.require_path = 'lib'
+	s.description = LONG_DESC
+end
+
+# Adding a new GemPackageTask adds a task named `package`, which generates
+# packages as gems, tarball and zip archives.
+Rake::GemPackageTask.new(spec) do |pkg|
+	pkg.need_zip = true
+	pkg.need_tar_gz = true
+end
+
+
+# This task is used to demonstrate how to upload files to Rubyforge.
+# Calling `upload_page` creates a current version of the +rdoc+
+# documentation and uploads it to the Rubyforge homepage of the project,
+# assuming it's hosted there and naming conventions haven't changed.
+#
+# This task uses `sh` to call the `scp` binary, which is plattform
+# dependant and may not be installed on your computer if you're using
+# Windows. I'm currently not aware of any pure ruby way to do scp
+# transfers.
+
+RubyForgeProject=SHORTNAME
+
+desc "Upload the web pages to the web."
+task :upload_pages => ["rdoc"] do
+  if RubyForgeProject then
+    path = "/var/www/gforge-projects/#{RubyForgeProject}"
+    sh "scp -r doc/html/* #{RUBYFORGE_USER}@rubyforge.org:#{path}"
+    sh "scp doc/images/*.png #{RUBYFORGE_USER}@rubyforge.org:#{path}/images"
+  end
+end
+
+# This task will run the unit tests provided in files called
+# `test/test*.rb`. The task itself can be run with a call to `rake test`
+
+Rake::TestTask.new do |t| 
+	t.libs << "test" 
+	t.libs << "lib" 
+	t.test_files = FileList['test/*.rb'] 
+	t.verbose = true 
+end
+
+
+

data/examples/example.rb

@@ -0,0 +1,9 @@
+require 'cmdline'
+
+	cmdline=CommandLine.new [
+		["-m", "-message", :message, "message", true, nil, "message for 'usage'"]
+	]
+
+	cmdline.parse ARGV
+	puts cmdline.message	
+

data/examples/long_example.rb

@@ -0,0 +1,34 @@
+require 'cmdline'
+
+if $0 == __FILE__
+
+commands_doc= <<ENDDOC
+
+Available commands:
+  add
+  blame
+  cat
+  checkout
+
+ENDDOC
+
+args_doc = "files to process"
+commands_check= ["add", "blame", "cat", "checkout"]
+
+file_readable=lambda{|f| File.readable? f}
+		
+
+cmdline=CommandLine.new [
+	[:command, nil, :command, "command", false, "add", commands_doc, commands_check],
+	["-o", nil, :outfile, "file", false, STDOUT, "filename to write output to, default STDOUT"],
+	["-i", "--infile", :infile, "file",  false, STDIN, "filename to read from, default STDIN", file_readable],
+	["-v", "--verbose", :verbose, false,  false, nil, "verbose"],
+	["-n", "--numeric", :number, "num",  true, nil, "numeric value", /^\d+$/],
+	[:args, nil, :args, "args", false, nil, args_doc, file_readable]
+]
+
+cmdline.parse ARGV
+puts cmdline.outfile
+puts cmdline.command
+puts cmdline.args
+end

data/examples/plain_args_example.rb

@@ -0,0 +1,10 @@
+require 'cmdline'
+
+args_doc = "files to process"		
+file_readable=lambda{|f| File.readable? f}
+cmdline=CommandLine.new [
+	[:args, nil, :args, "args", true, nil, args_doc, file_readable]
+]
+cmdline.parse ARGV
+puts cmdline.args
+

data/examples/regexp_example.rb

@@ -0,0 +1,9 @@
+require 'cmdline'
+
+	cmdline=CommandLine.new [
+		["-f", "-flag", :starts_with_a_digit, "value", true, nil, "must start with a number", /^\d.*/]
+	]
+
+	cmdline.parse ARGV
+	puts cmdline.starts_with_a_digit	
+

data/examples/subcommand_example.rb

@@ -0,0 +1,20 @@
+require 'cmdline'
+
+doc= <<END_DOC
+    build            Build a gem from a gemspec
+    cert             Adjust RubyGems certificate settings
+    check            Check installed gems
+    cleanup          Clean up old versions of installed gems in the local
+                     repository
+    contents         Display the contents of the installed gems
+    ...
+END_DOC
+
+
+command_arr=["build", "cert", "check", "cleanup", "contents"] # ...
+cmdline=CommandLine.new [
+	[:command, nil, :command, "command", false, "add", doc, command_arr]
+]
+cmdline.parse ARGV
+puts cmdline.command
+