# = LICENCE
#
# == Authors
# See doc/AUTHORS.
#
#
# == Copyright
# Copyright (c) 2007, 2008 Eero Saynatkari, all rights reserved.
#
#
# == Licence
# Redistribution and use in source and binary forms, with or without
# modification, are permitted provided that the following conditions
# are met:
#
# - Redistributions of source code must retain the above copyright
# notice, this list of conditions, the following disclaimer and
# attribution to the original authors.
#
# - Redistributions in binary form must reproduce the above copyright
# notice, this list of conditions, the following disclaimer and
# attribution to the original authors in the documentation and/or
# other materials provided with the distribution.
#
# - The names of the authors may not be used to endorse or promote
# products derived from this software without specific prior
# written permission.
#
#
# == Disclaimer
# 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.
# Authors are not responsible for any damages, direct or indirect.
# A simple, independent option parser originally from the rs project.
class Options
# Create an instance. If a block is given, the new instance
# is yielded.
def initialize(header = '', &block)
@allowed, @header, @optdesc = {}, header, ''
block.call(self) if block
end # initialize
# Adds an option to the parser. The option must be defined as
# a string of the format "-s --long Description". The first
# element is a dash followed by a character (the "short option"),
# the second is two dashes followed by two or more characters
# (the "long option"). The rest of the string becomes the third
# element which is used as the description of the option's
# purpose. The elements are separated by any number of whitespace
# characters.
#
# By default an option takes no arguments but a second argument
# may be given to designate a different argument count. The
# two last versions are greedy and will consume all arguments
# until the next option switch or the end of input.
#
# :none no arguments
# :one exactly one argument
# :many one or more
# :any zero or more
def option(definition, args = :none)
result = definition.scan /-(\w)\s+--(\w\S+?)\s+?(\S.*)/
raise ArgumentError, "Option format is '-s --long Description here'" if result.empty?
short, long, desc = result.first
# Store the data along with a cross-reference
@allowed[short] = {:desc => desc, :args => args, :other => long}
@allowed[long] = {:desc => desc, :args => args, :other => short}
# Add to usage now to maintain order
argdesc = case args
when :one then 'ARG'
when :any then '[ARG, ...]'
when :many then 'ARG1, ARG2[, ...]'
else
''
end
@optdesc << " Options:\n\n" if @optdesc.empty?
@optdesc << " #{"-#{short} --#{long} #{argdesc}".ljust(30)} #{desc}\n"
end # option
# Optional error handling block
def on_error(&block)
@error_block = block
end
# Text to show above options in usage message
def header(message)
@header = message
end # header
# Generate a usage message
def usage()
@header + @optdesc
end # usage
alias :help :usage
# The accepted forms for options are:
#
# Short opts: -h, -ht, -h ARG, -ht ARG (same as -h -t ARG).
# Long opts: --help, --help ARG, (No joining.)
#
# The returned Hash is indexed by the names of the found
# options. These indices point to an Array of arguments
# to that option if any, or just true if not. The Hash
# also contains a special index, :args, containing all
# of the non-option arguments.
#
# Upon encountering an error, the parser will raise an
# ArgumentError with an explanation. This behaviour may
# be overridden by supplying a block through #on_error.
# The block will be given the Options instance and the
# Exception object.
def parse(arguments = [])
expecting = nil # An option may be expecting an argument
@opts = {} # Options parsed
@nonopts = [] # Non-option arguments
arguments = arguments.split unless arguments.kind_of?(Array)
arguments.each do |opt|
# Option type
if opt =~ /\A(-{1,2})(\S+)/
# No more arguments for the previous option
expecting = nil
# Single args may need to be split --note: only the last one can take an arg!
opts = if $1.length == 1
$2.split(//)
else
[$2]
end
# Parse individual flags if any
opts.each do |o|
data = @allowed.fetch(o) {|x| raise ArgumentError.new("Invalid option #{x}")}
# Option takes arguments?
case data[:args]
when :one, :many
# Prepare for incoming data
@opts[o] ||= []; expecting = [o, data[:args]]
when :any
# Cheat
@opts[o] = true; expecting = [o, :many]
else
@opts[o] = true
end
end # opts.each
# Nonoption arguments
else
# Previous option accepts arguments
if expecting
@opts[expecting.first] = [] if @opts[expecting.first] == true
# Store the argument with the option
@opts[expecting.first] << opt
# No more arguments unless so specified
expecting = nil unless expecting.last == :many
# Freestanding argument
else
@nonopts << opt
end # if expecting
end # case opt
end # arguments...each
# Sanity checks and crossrefs
@opts.keys.each do |key|
o = @opts[key]
@opts[@allowed[key][:other]] = o
case @allowed[key][:args]
when :one
if o.nil? or o == true or o.size != 1
raise ArgumentError, "#{key} must have one argument"
else
@opts[key] = o.first
@opts[@allowed[key][:other]] = o.first
end
when :many
if o.nil? or o == true or o.size < 2
raise ArgumentError, "Too few arguments for #{key}"
end
end
end
@opts[:args] = @nonopts
@opts
rescue ArgumentError => ex
raise ex unless @error_block
@error_block.call self, ex
end # parse
end # class Options
Pastie << self Blog
