NAME
main.rb
SYNOPSIS
a class factory and dsl for generating command line programs real quick
URI
http://codeforpeople.com/lib/ruby/
http://rubyforge.org/projects/codeforpeople/
http://github.com/ahoward/main
INSTALL
gem install main
DESCRIPTION
main.rb features the following:
- unification of option, argument, keyword, and environment parameter
parsing
- auto generation of usage and help messages
- support for mode/sub-commands
- io redirection support
- logging hooks using ruby's built-in logging mechanism
- intelligent error handling and exit codes
- use as dsl or library for building Main objects
- parsing user defined ARGV and ENV
- zero requirements for understanding the obtuse apis of *any* command
line option parsers
- leather pants
in short main.rb aims to drastically lower the barrier to writing uniform
command line applications.
for instance, this program
require 'main'
Main {
argument 'foo'
option 'bar'
def run
p params['foo']
p params['bar']
exit_success!
end
}
sets up a program which requires one argument, 'bar', and which may accept one
command line switch, '--foo' in addition to the single option/mode
which is always
accepted and handled appropriately: 'help', '--help', '-h'. for the most
part main.rb stays out of your command line namespace but insists that your
application has at least a help mode/option.
main.rb supports sub-commands in a very simple way
require 'main'
Main {
mode 'install' do
def run() puts 'installing...' end
end
mode 'uninstall' do
def run() puts 'uninstalling...' end
end
}
which allows a program, called 'a.rb', to be invoked as
ruby a.rb install
and
ruby a.rb uninstall
for simple programs main.rb is a real time saver but it's for more complex
applications where main.rb's unification of parameter parsing, class
configuration dsl, and auto-generation of usage messages can really streamline
command line application development. for example the following 'a.rb'
program:
require 'main'
Main {
argument('foo'){
cast :int
}
keyword('bar'){
arity 2
cast :float
defaults 0.0, 1.0
}
option('foobar'){
argument :optional
description 'the foobar option is very handy'
}
environment('BARFOO'){
cast :list_of_bool
synopsis 'export barfoo=value'
}
def run
p params['foo'].value
p params['bar'].values
p params['foobar'].value
p params['BARFOO'].value
end
}
when run with a command line of
BARFOO=true,false,false ruby a.rb 42 bar=40 bar=2 --foobar=a
will produce
42
[40.0, 2.0]
"a"
[true, false, false]
while a command line of
ruby a.rb --help
will produce
NAME
a.rb
SYNOPSIS
a.rb foo [bar=bar] [options]+
PARAMETERS
* foo [ 1 -> int(foo) ]
* bar=bar [ 2 ~> float(bar=0.0,1.0) ]
* --foobar=[foobar] [ 1 ~> foobar ]
the foobar option is very handy
* --help, -h
* export barfoo=value
and this shows how all of argument, keyword, option, and environment parsing
can be declartively dealt with in a unified fashion - the dsl for all
parameter types is the same - and how auto synopsis and usage generation saves
keystrokes. the parameter synopsis is compact and can be read as
* foo [ 1 -> int(foo) ]
'one argument will get processed via int(argument_name)'
1 : one argument
-> : will get processed (the argument is required)
int(foo) : the cast is int, the arg name is foo
* bar=bar [ 2 ~> float(bar=0.0,1.0) ]
'two keyword arguments might be processed via float(bar=0.0,1.0)'
2 : two arguments
~> : might be processed (the argument is optional)
float(bar=0.0,1.0) : the cast will be float, the default values are
0.0 and 1.0
* --foobar=[foobar] [ 1 ~> foobar ]
'one option with optional argument may be given directly'
* --help, -h
no synopsis, simple switch takes no args and is not required
* export barfoo=value
a user defined synopsis
SAMPLES
<========< samples/a.rb >========>
~ > cat samples/a.rb
require 'main'
ARGV.replace %w( 42 ) if ARGV.empty?
Main {
argument('foo'){
required # this is the default
cast :int # value cast to Fixnum
validate{|foo| foo == 42} # raises error in failure case
description 'the foo param' # shown in --help
}
def run
p params['foo'].given?
p params['foo'].value
end
}
~ > ruby samples/a.rb
true
42
<========< samples/b.rb >========>
~ > cat samples/b.rb
require 'main'
ARGV.replace %w( 40 1 1 ) if ARGV.empty?
Main {
argument('foo'){
arity 3 # foo will given three times
cast :int # value cast to Fixnum
validate{|foo| [40,1].include? foo} # raises error in failure case
description 'the foo param' # shown in --help
}
def run
p params['foo'].given?
p params['foo'].values
end
}
~ > ruby samples/b.rb
true
[40, 1, 1]
<========< samples/c.rb >========>
~ > cat samples/c.rb
require 'main'
ARGV.replace %w( foo=40 foo=2 bar=false ) if ARGV.empty?
Main {
keyword('foo'){
required # by default keywords are not required
arity 2
cast :float
}
keyword('bar'){
cast :bool
}
def run
p params['foo'].given?
p params['foo'].values
p params['bar'].given?
p params['bar'].value
end
}
~ > ruby samples/c.rb
true
[40.0, 2.0]
true
false
<========< samples/d.rb >========>
~ > cat samples/d.rb
require 'main'
ARGV.replace %w( --foo=40 -f2 ) if ARGV.empty?
Main {
option('foo', 'f'){
required # by default options are not required, we could use 'foo=foo'
# above as a shortcut
argument_required
arity 2
cast :float
}
option('bar=[bar]', 'b'){ # note shortcut syntax for optional args
# argument_optional # we could also use this method
cast :bool
default false
}
def run
p params['foo'].given?
p params['foo'].values
p params['bar'].given?
p params['bar'].value
end
}
~ > ruby samples/d.rb
true
[40.0, 2.0]
nil
false
<========< samples/e.rb >========>
~ > cat samples/e.rb
require 'main'
ARGV.replace %w( x y argument )
Main {
argument 'argument'
option 'option'
def run() puts 'run' end
mode 'a' do
option 'a-option'
def run() puts 'a-run' end
end
mode 'x' do
option 'x-option'
def run() puts 'x-run' end
mode 'y' do
option 'y-option'
def run() puts 'y-run' end
end
end
}
~ > ruby samples/e.rb
y-run
<========< samples/f.rb >========>
~ > cat samples/f.rb
require 'main'
ARGV.replace %W( compress /data )
Main {
argument('directory'){ description 'the directory to operate on' }
option('force'){ description 'use a bigger hammer' }
def run
puts 'this is how we run when no mode is specified'
end
mode 'compress' do
option('bzip'){ description 'use bzip compression' }
def run
puts 'this is how we run in compress mode'
end
end
mode 'uncompress' do
option('delete-after'){ description 'delete orginal file after
uncompressing' }
def run
puts 'this is how we run in un-compress mode'
end
end
}
~ > ruby samples/f.rb
this is how we run in compress mode
<========< samples/g.rb >========>
~ > cat samples/g.rb
require 'main'
ARGV.replace %w( 42 ) if ARGV.empty?
Main {
argument( 'foo' )
option( 'bar' )
run { puts "This is what to_options produces:
#{params.to_options.inspect}" }
}
~ > ruby samples/g.rb
This is what to_options produces: {"help"=>nil, "foo"=>"42", "bar"=>nil}
<========< samples/h.rb >========>
~ > cat samples/h.rb
require 'main'
# block-defaults are instance_eval'd in the main instance and be
combined with
# mixins
···
#
# ./h.rb #=> forty-two
# ./h.rb a #=> 42
# ./h.rb b #=> 42.0
#
Main {
fattr :default_for_foobar => 'forty-two'
option(:foobar) do
default{ default_for_foobar }
end
mixin :foo do
fattr :default_for_foobar => 42
end
mixin :bar do
fattr :default_for_foobar => 42.0
end
run{ p params[:foobar].value }
mode :a do
mixin :foo
end
mode :b do
mixin :bar
end
}
~ > ruby samples/h.rb
"forty-two"
DOCS
test/main.rb
vim -p lib/main.rb lib/main/*rb
API section below
HISTORY
4.0.0
- avoid duping ios. new methods Main.push_ios! and Main.pop_ios! are
utilized for testing. this was done to make it simple to wrap
daemon/servolux programs around main, althought not strictly required.
not the version bump - there is not reason to expect existing main
programs to break, but it *is* and interface change which requires a major
version bump.
API
Main {
###########################################################################
# CLASS LEVEL API #
###########################################################################
#
# the name of the program, auto-set and used in usage
#
program 'foo.rb'
#
# a short description of program functionality, auto-set and used in usage
#
synopsis "foo.rb arg [options]+"
#
# long description of program functionality, used in usage iff set
#
description <<-hdoc
this text will automatically be indented to the right level.
it should describe how the program works in detail
hdoc
#
# used in usage iff set
#
author 'ara.t.howard@gmail.com'
#
# used in usage
#
version '0.0.42'
#
# stdin/out/err can be anthing which responds to read/write or a string
# which will be opened as in the appropriate mode
#
stdin '/dev/null'
stdout '/dev/null'
stderr open('/dev/null', 'w')
#
# the logger should be a Logger object, something 'write'-able, or a string
# which will be used to open the logger. the logger_level specifies the
# initalize verbosity setting, the default is Logger::INFO
#
logger(( program + '.log' ))
logger_level Logger::DEBUG
#
# you can configure exit codes. the defaults are shown
#
exit_success # 0
exit_failure # 1
exit_warn # 42
#
# the usage object is rather complex. by default it's an object which can
# be built up in sections using the
#
# usage["BUGS"] = "something about bugs'
#
# syntax to append sections onto the already pre-built usage message which
# contains program, synopsis, parameter descriptions and the like
#
# however, you always replace the usage object wholesale with one of your
# chosing like so
#
usage <<-txt
my own usage message
txt
###########################################################################
# MODE API #
###########################################################################
#
# modes are class factories that inherit from their parent class. they can
# be nested *arbitrarily* deep. usage messages are tailored for each mode.
# modes are, for the most part, independant classes but parameters are
# always a superset of the parent class - a mode accepts all of it's parents
# paramters *plus* and additional ones
#
option 'inherited-option'
argument 'inherited-argument'
mode 'install' do
option 'force' do
description 'clobber existing installation'
end
def run
inherited_method()
puts 'installing...'
end
mode 'docs' do
description 'installs the docs'
def run
puts 'installing docs...'
end
end
end
mode 'un-install' do
option 'force' do
description 'remove even if dependancies exist'
end
def run
inherited_method()
puts 'un-installing...'
end
end
def run
puts 'no mode yo?'
end
def inherited_method
puts 'superclass_method...'
end
###########################################################################
# PARAMETER API #
###########################################################################
#
# all the parameter types of argument|keyword|option|environment share this
# api. you must specify the type when the parameter method is used.
# alternatively used one of the shortcut methods
# argument|keyword|option|environment. in otherwords
#
# parameter('foo'){ type :option }
#
# is synonymous with
#
# option('foo'){ }
#
option 'foo' {
#
# required - whether this paramter must by supplied on the command line.
# note that you can create 'required' options with this keyword
#
required # or required true
#
# argument_required - applies only to options.
#
argument_required # argument :required
#
# argument_optional - applies only to options.
#
argument_optional # argument :optional
#
# cast - should be either a lambda taking one argument, or a symbol
# designation one of the built in casts defined in Main::Cast. supported
# types are :boolean|:integer|:float|:numeric|:string|:uri. built-in
# casts can be abbreviated
#
cast :int
#
# validate - should be a lambda taking one argument and returning
# true|false
#
validate{|int| int == 42}
#
# synopsis - should be a concise characterization of the paramter. a
# default synopsis is built automatically from the parameter. this
# information is displayed in the usage message
#
synopsis '--foo'
#
# description - a longer description of the paramter. it appears in the
# usage also.
#
description 'a long description of foo'
#
# arity - indicates how many times the parameter should appear on the
# command line. the default is one. negative arities are supported and
# follow the same rules as ruby methods/procs.
#
arity 2
#
# default - you can provide a default value in case none is given. the
# alias 'defaults' reads a bit nicer when you are giving a list of
# defaults for paramters of > 1 arity
#
defaults 40, 2
#
# you can add custom per-parameter error handlers using the following
#
error :before do
puts 'this fires *before* normal error handling using #instance_eval...'
end
error do
puts 'this fires *instead of* normal error handling using
#instance_eval...'
end
error :after do
puts 'this fires *after* normal error handling using #instance_eval...'
end
}
###########################################################################
# INSTANCE LEVEL API #
###########################################################################
#
# you must define a run method. it is the only method you must define.
#
def run
#
# all parameters are available in the 'params' hash and via the alias
# 'param'. it can be indexed via string or symbol. the values are all
# Main::Parameter objects
#
foo = params['foo']
#
# the given? method indicates whether or not the parameter was given on
# the commandline/environment, etc. in particular this will not be true
# when a default value was specified but no parameter was given
#
foo.given?
#
# the list of all values can be retrieved via 'values'. note that this
# is always an array.
#
p foo.values
#
# the __first__ value can be retrieved via 'value'. note that this
# never an array.
#
p foo.value
#
# the methods debug|info|warn|error|fatal are delegated to the logger
# object
#
info{ "this goes to the log" }
#
# you can set the exit_status at anytime. this status is used when
# exiting the program. exceptions cause this to be ext_failure if, and
# only if, the current value was exit_success. in otherwords an
# un-caught exception always results in a failing exit_status
#
exit_status exit_failure
#
# a few shortcuts both set the exit_status and exit the program.
#
exit_success!
exit_failure!
exit_warn!
end
}
--
-a
--
be kind whenever possible... it is always possible - h.h. the 14th dalai lama