module CLASP

Main module for CLASP.Ruby library

Examples¶ ↑

Simple command-line, no specifications¶ ↑

argv = %w{ --show-all=true infile -c outfile }

args = CLASP::Arguments.new(argv)

puts args.flags.size             # => 1
puts args.flags[0]               # => -c
puts args.flags[0].name          # => -c
puts args.flags[0].inspect       # => #<CLASP::Arguments::FlagArgument:0x007f87e18d4530 @arg="-c", @given_index=2, @given_name="-c", @argument_specification=nil, @given_hyphens=1, @given_label="c", @name="-c", @extras={}>

puts args.options.size           # => 1
puts args.options[0]             # => --show-all=true
puts args.options[0].name        # => --show-all
puts args.options[0].value       # => true
puts args.options[0].inspect     # => #<CLASP::Arguments::OptionArgument:0x007f87e18d4940 @arg="--show-all=true", @given_index=0, @given_name="--show-all", @argument_specification=nil, @given_hyphens=2, @given_label="show-all", @value="true", @name="--show-all", @extras={}>

puts args.values.size            # => 2
puts args.values[0]              # => infile
puts args.values[0].given_index  # => 1
puts args.values[1]              # => outfile
puts args.values[1].given_index  # => 3

Use of the special double-slash flag to treat all subsequent arguments as values¶ ↑

argv = %w{ --show-all=true -- infile outfile -c }

args = CLASP::Arguments.new(argv)

puts args.flags.size             # => 0

puts args.options.size           # => 1
puts args.options[0]             # => --show-all
puts args.options[0].inspect     # => #<CLASP::Arguments::OptionArgument:0x007fd23aa3aca0 @arg="--show-all=true", @given_index=0, @given_name="--show-all", @argument_specification=nil, @given_hyphens=2, @given_label="show-all", @value="true", @name="--show-all", @extras={}>

puts args.values.size            # => 3
puts args.values[0]              # => infile
puts args.values[1]              # => outfile
puts args.values[2]              # => "-c"

Use of flag short forms¶ ↑

specifications = [

  CLASP.Flag('--verbose', alias: '-v'),
  CLASP.Flag('--trace-output', aliases: [ '-t', '--trace' ]),
]

argv = %w{ -trace -v }

args = CLASP::Arguments.new(argv, specifications)

puts args.flags.size        # => 2
puts args.flags[0].name     # => --trace-output
puts args.flags[1].name     # => --verbose
puts args.options.size      # => 0
puts args.values.size       # => 0

Use of flag single short forms combined¶ ↑

specifications = [

  CLASP.Flag('--expand', alias: '-x'),
  CLASP.Flag('--verbose', alias: '-v'),
  CLASP.Flag('--trace-output', aliases: [ '-t', '--trace' ]),
]

argv = %w{ -tvx }

args = CLASP::Arguments.new(argv, specifications)

puts args.flags.size        # => 3
puts args.options.size      # => 0
puts args.values.size       # => 0

Use of option short form¶ ↑

specifications = [

  CLASP.Option('--show-all', alias: '-a'),
]

argv = %w{ -c -a true infile outfile }

args = CLASP::Arguments.new(argv, specifications)

puts args.flags.size         # => 1
puts args.flags[0]           # => -c
puts args.flags[0].inspect   # => #<CLASP::Arguments::FlagArgument:0x007f8593b0ddd8 @arg="-c", @given_index=0, @given_name="-c", @argument_specification=nil, @given_hyphens=1, @given_label="c", @name="-c", @extras={}>

puts args.options.size       # => 1
puts args.options[0]         # => --show-all
puts args.options[0].inspect # => "#<CLASP::Arguments::OptionArgument:0x007f8593b0db80 @arg="-a", @given_index=1, @given_name="-a", @argument_specification=#<CLASP::OptionArgument:0x007f8593b2ea10 @name="--show-all", @aliases=["-a"], @help=nil, @values_range=[], @default_value=nil, @extras={}>, @given_hyphens=1, @given_label="a", @value="true", @name="--show-all", @extras={}>"

puts args.values.size        # => 2
puts args.values[0]          # => infile
puts args.values[1]          # => outfile

Classes of interest¶ ↑

Functions of interest¶ ↑

Constants

Alias: A class that represents an explicit alias for a flag or an option
Flag: A class that represents the specification for a command-line flag
FlagAlias: A class that represents the specification for a command-line flag
Option: A class that represents the specification for a command-line option
OptionAlias: A class that represents the specification for a command-line option
VERSION: Current version of the CLASP.Ruby library

Public Class Methods

Alias(name, *args) click to toggle source

# File lib/clasp/specifications.rb, line 513
def CLASP.Alias(name, *args)

        options        =      args.pop if args[-1].is_a?(::Hash)
        options        ||=    {}

        if options[:alias]

                aliases       =     [ options[:alias] ]
        elsif options[:aliases]

                aliases       =     options[:aliases]
        else

                aliases       =     args
        end

        CLASP::AliasSpecification.new name, aliases
end

Flag(name, options = {}, &blk) click to toggle source

Generator method that obtains a CLASP::FlagSpecification according to the given parameters

Signature¶ ↑

Parameters:
- name (::String) The flag name, e.g. '–verbose'
- options (::Hash) An options hash, containing any of the following options:
Options:
- :alias (::String) An alias, e.g. '-v'
- :aliases (::Array) An array of aliases, e.g. [ '-v', '-verb' ]. Ignored if :alias is specified
- :extras An application-defined object, usually a hash of custom attributes
- :help (::String) A help string
Block An optional block that is called when a matching flag argument is found

# File lib/clasp/specifications.rb, line 397
def CLASP.Flag(name, options = {}, &blk)

        aliases        =      nil
        help   = nil
        extras =       nil

        options.each do |k, v|

                case  k
                when  Symbol
                        case k
                        when :alias

                                aliases     =   [ v ] if v
                        when :aliases

                                aliases     =   v unless aliases
                        when :help

                                help        =      v
                        when :extras

                                extras      =    v
                        else

                                raise ArgumentError, "invalid option for flag: '#{k}' => '#{v}'"
                        end
                else

                        raise ArgumentError, "invalid option type for flag: '#{k}' (#{k.class}) => '#{v}'"
                end
        end

        CLASP::FlagSpecification.new(name, aliases, help, extras, &blk)
end

Option(name, options = {}, &blk) click to toggle source

Generator method that obtains a CLASP::OptionSpecification according to the given parameters

Signature¶ ↑

Parameters:
- name (::String) The flag name, e.g. '–verbose'
- options (::Hash) An options hash, containing any of the following options:
Options:
- :alias (::String) An alias, e.g. '-v'
- :aliases (::Array) An array of aliases, e.g. [ '-v', '-verb' ]. Ignored if :alias is specified
- :default_value The default value for the option
- :default [DEPRECATED] Alternative to :default_value
- :extras An application-defined object, usually a hash of custom attributes
- :help (::String) A help string
- required (boolean) Whether the option is required. May be nil
- required_message (::String) Message to be used when reporting that a required option is missing. May be nil in which case a message of the form “<option-name> not specified; use –help for usage”. If begins with the nul character (“0”), then is used in the place of the <option-name> and placed into the rest of the standard form message
- extras An application-defined additional parameter. If nil, it is assigned an empty Hash.
- constraint (Hash) Constraint to be applied to the parsed values of options matching this specification. NOTE: only integer constraints are supported in the current version
- :values_range (::Array) An array defining the accepted values for the option
- :values [DEPRECATED] Alternative to :values_range
Block An optional block that is called when a matching option argument is found

# File lib/clasp/specifications.rb, line 457
def CLASP.Option(name, options = {}, &blk)

        aliases                        =    nil
        help                   =       nil
        values_range   = nil
        default_value  =        nil
        required               =    false
        require_message        =      nil
        constraint             =  nil
        extras                 =     nil

        options.each do |k, v|

                case  k
                when  Symbol
                        case k
                        when :alias

                                aliases     =   [ v ] if v
                        when :aliases

                                aliases     =   v unless aliases
                        when :help

                                help        =      v
                        when :values_range, :values

                                values_range        =      v
                        when :default_value, :default

                                default_value       =     v
                        when :required

                                required    =  v
                        when :required_message

                                require_message     =   v
                        when :extras

                                extras      =    v
                        when :constraint

                                constraint  =        v
                        else

                                raise ArgumentError, "invalid option for option: '#{k}' => '#{v}'"
                        end
                else

                        raise ArgumentError, "invalid option type for option: '#{k}' (#{k.class}) => '#{v}'"
                end
        end

        CLASP::OptionSpecification.new(name, aliases, help, values_range, default_value, required, require_message, constraint, extras, &blk)
end

parse(argv = ARGV, specifications = nil, options = {}) click to toggle source

TBC (but is a shorthand for calling +Arguments.new()+

# File lib/clasp/clasp.rb, line 56
def self.parse(argv = ARGV, specifications = nil, options = {})

        return Arguments.new(argv, specifications, options)
end

show_usage(specifications, options={}) click to toggle source

Displays usage for the program according to the given specifications and options

Signature¶ ↑

Parameters:
- specifications (Array) The arguments array. May not be nil. Defaults to ARGV.
- options An options hash, containing any of the following options.
Options:
- :exit a program exit code; exit() not called if not specified (or nil).
- :program_name program name; inferred from $0 if not specified.
- :stream output stream; $stdout if not specified.
- :suppress_blank_lines_between_options does exactly what it says on the tin.
- :values appends this string to USAGE line if specified.
- :flags_and_options inserts a custom string instead of the default string '[ ... flags and options ... ]'.
- :info_lines inserts 0+ information lines prior to the usage.
- :default_indicator (String) a string placed after the matching value in the listing of an option's range of values. Defaults to “(default)”. If nil default is used. If empty string no indication given

# File lib/clasp/cli.rb, line 133
def self.show_usage specifications, options={}

        options        ||=    {}

        raise ArgumentError, "specifications may not be nil" if specifications.nil?
        raise TypeError, "specifications must be an array or must respond to each, reject and select" unless ::Array === specifications || (specifications.respond_to?(:each) && specifications.respond_to?(:reject) && specifications.respond_to?(:select))

        constants              =   CLI_helpers_::Constants
        specifications.each { |s| raise ::TypeError, "each element in specifications array must be one of the types #{constants::VALID_ALIAS_TYPES_STRING}" unless constants::VALID_ALIAS_TYPES.any? { |c| c === s } }

        alias_dups = {}
        specifications.each { |s| s.aliases.each { |aa| warn "WARNING: alias '#{aa}' is already used for specification '#{s}'" if alias_dups.has_key? aa; alias_dups[aa] = s; } }

        suppress_blanks        =      options[:suppress_blank_lines_between_options] || ENV['SUPPRESS_BLANK_LINES_BETWEEN_OPTIONS']

        stream                 =     options[:stream] || $stdout
        program_name   = options[:program_name] || File.basename($0)

        info_lines             =  options[:info_lines]
        case info_lines
        when ::Array

                ;
        when ::NilClass

                info_lines    =  []
        else

                info_lines = [ info_lines ] unless [ :each, :empty? ].all? { |m| info_lines.respond_to? m }
        end
        info_lines             =  info_lines.map do |line|

                case line
                when :version

                        CLI_helpers_.generate_version_string_ options
                else

                        line
                end
        end

        values                 =     options[:values] || ''
        values                 =     " #{values}" if !values.empty? && ' ' != values[0]

        flags_and_options      =    options[:flags_and_options] || ' [ ... flags and options ... ]'
        flags_and_options      =    " #{flags_and_options}" if !flags_and_options.empty? && ' ' != flags_and_options[0]

        default_indicator      =    options[:default_indicator] || '(default)'
        default_indicator      =    nil if default_indicator.empty?

        # sift the specifications to sort out which are value-option
        # specifications (VOAs)

        voas                   =       {}

        specifications.select { |s| s.name =~ /^-+[a-zA-Z0-3_-]+[=:].+/ }.each do |s|

                s.name =~ /^(-+[a-zA-Z0-3_-]+)[=:](.+)$/

                voas[$1]      =    [] unless voas.has_key? $1
                voas[$1]      <<   [ s, $2 ]
        end

        fas                            =       {}

        specifications.select { |s| AliasSpecification === s }.each do |s|

                fas[s.name]   = [] unless fas.has_key? $1
                fas[s.name]   <<        s
        end

        specifications =       specifications.reject { |s| s.name =~ /^-+[a-zA-Z0-3_-]+[=:].+/ }

        info_lines.each { |info_line| stream.puts info_line } unless info_lines.empty?

        stream.puts "USAGE: #{program_name}#{flags_and_options}#{values}"
        stream.puts

        unless specifications.empty?

                stream.puts "flags/options:"
                stream.puts
                specifications.each do |s|

                        case s
                        when AliasSpecification

                                next
                        when FlagSpecification

                                if fas.has_key? s.name

                                        fas[s.name].each do |fa|

                                                fa.aliases.each { |al| stream.puts "\t#{al}" }
                                        end
                                end
                                s.aliases.each { |al| stream.puts "\t#{al}" }
                                stream.puts "\t#{s.name}"
                                stream.puts "\t\t#{s.help}"
                        when OptionSpecification

                                if voas.has_key? s.name

                                        voas[s.name].each do |ar|

                                                ar[0].aliases.each { |al| stream.puts "\t#{al} #{ar[0].name}" }
                                        end
                                end
                                s.aliases.each { |al| stream.puts "\t#{al} <value>" }
                                stream.puts "\t#{s.name}=<value>"
                                stream.puts "\t\t#{s.help}"
                                unless s.values_range.empty?

                                        d = s.default_value

                                        stream.puts "\t\twhere <value> one of:"
                                        s.values_range.each do |v|

                                                if default_indicator && v == d

                                                        stream.puts "\t\t\t#{v}\t#{default_indicator}"
                                                else

                                                        stream.puts "\t\t\t#{v}"
                                                end
                                        end
                                end
                        end
                        stream.puts unless suppress_blanks
                end
        end

        exit_code              =   options[:exit_code] || options[:exit]

        exit exit_code if exit_code
end

show_version(specifications, options = {}) click to toggle source

Displays version for the program according to the given specifications and options

Signature¶ ↑

Parameters:
- specifications (Array) The arguments array. May not be nil. Defaults to ARGV.
- options An options hash, containing any of the following options.
Options:
- :exit a program exit code; exit() not called if not specified (or nil).
- :program_name program name; inferred from $0 if not specified.
- :stream output stream; $stdout if not specified.
- :version an array (of N elements, each of which will be separated by a period '.'), or a string. Must be specified if not :version_major.
- :version_major a number or string. Only considered and must be specified if :version is not.
- :version_minor a number or string. Only considered if :version is not.
- :version_revision a number or string. Only considered if :version is not.
- :version_build a number or string. Only considered if :version is not.
- :version_prefix optional string to prefix the version number(s).

# File lib/clasp/cli.rb, line 290
def self.show_version specifications, options = {}

        options        ||=    {}

        raise ArgumentError, "specifications may not be nil" if specifications.nil?
        raise TypeError, "specifications must be an array or must respond to each, reject and select" unless ::Array === specifications || (specifications.respond_to?(:each) && specifications.respond_to?(:reject) && specifications.respond_to?(:select))

        constants              =   CLI_helpers_::Constants
        specifications.each { |s| raise ::TypeError, "each element in specifications array must be one of the types #{constants::VALID_ALIAS_TYPES_STRING}" unless constants::VALID_ALIAS_TYPES.any? { |c| c === s } }

        stream                 =     options[:stream] || $stdout

        version_string =       CLI_helpers_.generate_version_string_ options

        stream.puts version_string

        exit_code              =   options[:exit_code] || options[:exit]

        exit exit_code if exit_code
end