Package SCons :: Package compat :: Module _scons_optparse :: Class OptionParser
[hide private]
[frames] | no frames]

Class OptionParser

source code

OptionContainer --+
                  |
                 OptionParser


Class attributes:
  standard_option_list : [Option]
    list of standard options that will be accepted by all instances
    of this parser class (intended to be overridden by subclasses).

Instance attributes:
  usage : string
    a usage string for your program.  Before it is displayed
    to the user, "%prog" will be expanded to the name of
    your program (self.prog or os.path.basename(sys.argv[0])).
  prog : string
    the name of the current program (to override
    os.path.basename(sys.argv[0])).
  epilog : string
    paragraph of help text to print after option help

  option_groups : [OptionGroup]
    list of option groups in this parser (option groups are
    irrelevant for parsing the command-line, but very useful
    for generating help)

  allow_interspersed_args : bool = true
    if true, positional arguments may be interspersed with options.
    Assuming -a and -b each take a single argument, the command-line
      -ablah foo bar -bboo baz
    will be interpreted the same as
      -ablah -bboo -- foo bar baz
    If this flag were false, that command line would be interpreted as
      -ablah -- foo bar -bboo baz
    -- ie. we stop processing options as soon as we see the first
    non-option argument.  (This is the tradition followed by
    Python's getopt module, Perl's Getopt::Std, and other argument-
    parsing libraries, but it is generally annoying to users.)

  process_default_values : bool = true
    if true, option default values are processed similarly to option
    values from the command line: that is, they are passed to the
    type-checking function for the option's type (as long as the
    default value is a string).  (This really only matters if you
    have defined custom types; see SF bug #955889.)  Set it to false
    to restore the behaviour of Optik 1.4.1 and earlier.

  rargs : [string]
    the argument list currently being parsed.  Only set when
    parse_args() is active, and continually trimmed down as
    we consume arguments.  Mainly there for the benefit of
    callback options.
  largs : [string]
    the list of leftover arguments that we have skipped while
    parsing options.  If allow_interspersed_args is false, this
    list is always empty.
  values : Values
    the set of option values currently being accumulated.  Only
    set when parse_args() is active.  Also mainly for callbacks.

Because of the 'rargs', 'largs', and 'values' attributes,
OptionParser is not thread-safe.  If, for some perverse reason, you
need to parse command-line arguments simultaneously in different
threads, use different OptionParser instances.



Instance Methods [hide private]
 
__init__(self, usage=False, option_list=False, option_class=<class SCons.compat._scons_optparse.Option at 0x849f4dc>, version=False, conflict_handler='error', description=False, formatter=False, add_help_option=True, prog=False, epilog=False) source code
 
destroy(self)
Declare that you are done with this OptionParser.
source code
 
_create_option_list(self) source code
 
_add_help_option(self) source code
 
_add_version_option(self) source code
 
_populate_option_list(self, option_list, add_help=True) source code
 
_init_parsing_state(self) source code
 
set_usage(self, usage) source code
 
enable_interspersed_args(self) source code
 
disable_interspersed_args(self) source code
 
set_process_default_values(self, process) source code
 
set_default(self, dest, value) source code
 
set_defaults(self, **kwargs) source code
 
_get_all_options(self) source code
 
get_default_values(self) source code
 
add_option_group(self, *args, **kwargs) source code
 
get_option_group(self, opt_str) source code
 
_get_args(self, args) source code
 
parse_args(self, args=False, values=False)
parse_args(args : [string] = sys.argv[1:], values : Values = None) -> (values : Values, args : [string]) Parse the command-line options found in 'args' (default: sys.argv[1:]).
source code
 
check_values(self, values, args)
check_values(values : Values, args : [string]) -> (values : Values, args : [string]) Check that the supplied option values and leftover arguments are valid.
source code
 
_process_args(self, largs, rargs, values)
_process_args(largs : [string], rargs : [string], values : Values) Process command-line arguments and populate 'values', consuming options and arguments from 'rargs'.
source code
 
_match_long_opt(self, opt)
_match_long_opt(opt : string) -> string Determine which long option string 'opt' matches, ie.
source code
 
_process_long_opt(self, rargs, values) source code
 
_process_short_opts(self, rargs, values) source code
 
get_prog_name(self) source code
 
expand_prog_name(self, s) source code
 
get_description(self) source code
 
exit(self, status=0, msg=False) source code
 
error(self, msg)
error(msg : string) Print a usage message incorporating 'msg' to stderr and exit.
source code
 
get_usage(self) source code
 
print_usage(self, file=False)
print_usage(file : file = stdout) Print the usage message for the current program (self.usage) to 'file' (default stdout).
source code
 
get_version(self) source code
 
print_version(self, file=False)
print_version(file : file = stdout) Print the version message for this program (self.version) to 'file' (default stdout).
source code
 
format_option_help(self, formatter=False) source code
 
format_epilog(self, formatter) source code
 
format_help(self, formatter=False) source code
 
_get_encoding(self, file) source code
 
print_help(self, file=False)
print_help(file : file = stdout) Print an extended help message, listing all options and any help text provided with them, to 'file' (default stdout).
source code

Inherited from OptionContainer: add_option, add_options, format_description, get_option, has_option, remove_option, set_conflict_handler, set_description

Class Variables [hide private]
  standard_option_list = []
Method Details [hide private]

__init__(self, usage=False, option_list=False, option_class=<class SCons.compat._scons_optparse.Option at 0x849f4dc>, version=False, conflict_handler='error', description=False, formatter=False, add_help_option=True, prog=False, epilog=False)
(Constructor)

source code 
Overrides: OptionContainer.__init__

destroy(self)

source code 

Declare that you are done with this OptionParser.  This cleans up
reference cycles so the OptionParser (and all objects referenced by
it) can be garbage-collected promptly.  After calling destroy(), the
OptionParser is unusable.

Overrides: OptionContainer.destroy

parse_args(self, args=False, values=False)

source code 

parse_args(args : [string] = sys.argv[1:],
           values : Values = None)
-> (values : Values, args : [string])

Parse the command-line options found in 'args' (default:
sys.argv[1:]).  Any errors result in a call to 'error()', which
by default prints the usage message to stderr and calls
sys.exit() with an error message.  On success returns a pair
(values, args) where 'values' is an Values instance (with all
your option values) and 'args' is the list of arguments left
over after parsing options.

check_values(self, values, args)

source code 

check_values(values : Values, args : [string])
-> (values : Values, args : [string])

Check that the supplied option values and leftover arguments are
valid.  Returns the option values and leftover arguments
(possibly adjusted, possibly completely new -- whatever you
like).  Default implementation just returns the passed-in
values; subclasses may override as desired.

_process_args(self, largs, rargs, values)

source code 
_process_args(largs : [string],
                 rargs : [string],
                 values : Values)

Process command-line arguments and populate 'values', consuming
options and arguments from 'rargs'.  If 'allow_interspersed_args' is
false, stop at the first non-option argument.  If true, accumulate any
interspersed non-option arguments in 'largs'.

_match_long_opt(self, opt)

source code 
_match_long_opt(opt : string) -> string

Determine which long option string 'opt' matches, ie. which one
it is an unambiguous abbrevation for.  Raises BadOptionError if
'opt' doesn't unambiguously match any long option string.

get_description(self)

source code 
Overrides: OptionContainer.get_description

error(self, msg)

source code 
error(msg : string)

Print a usage message incorporating 'msg' to stderr and exit.
If you override this in a subclass, it should not return -- it
should either exit or raise an exception.

print_usage(self, file=False)

source code 
print_usage(file : file = stdout)

Print the usage message for the current program (self.usage) to
'file' (default stdout).  Any occurence of the string "%prog" in
self.usage is replaced with the name of the current program
(basename of sys.argv[0]).  Does nothing if self.usage is empty
or not defined.

print_version(self, file=False)

source code 
print_version(file : file = stdout)

Print the version message for this program (self.version) to
'file' (default stdout).  As with print_usage(), any occurence
of "%prog" in self.version is replaced by the current program's
name.  Does nothing if self.version is empty or undefined.

format_option_help(self, formatter=False)

source code 
Overrides: OptionContainer.format_option_help

format_help(self, formatter=False)

source code 
Overrides: OptionContainer.format_help