SetProgramOptions Class Reference
The SetProgramOptions module is an extension of configparserenhanced.ConfigParserEnhanced
which implements handlers for environment variable and environment modules rules in
a .ini file.
Supported .ini File Operations
Operation |
Usage |
Description |
---|---|---|
opt-set |
|
Sets a program option. |
opt-remove |
|
Removes options in the option list that match |
API Documentation
SetProgramOptions
SetProgramOptions
is a subclass of ConfigParserEnhanced
that adds program-option handling capabilities.
Operation: opt-set
The opt-set
operation can have the following format:
1opt-set Param1 [Param2] ... [ParamN] : <value>
Options are processed using gen_option_list()
to produce a
list
or strings
representing a command or set of command line
options that can be processed by the caller.
These options are added to the options
property.
Operation: opt-remove
The opt-remove
operation can have the following format:
1opt-remove Param1 [SUBSTR]
This command is used to remove options that have already been processed
and added to the options
property.
Option entries are removed according to the rules:
If
SUBSTR
is not provided, entries are removed if any of its Param options are exactly matched.If the
SUBSTR
parameter is included, the matching criteria is relaxed so that an option is removed from the list if any of its parameters containsParam1
(i.e.,Param1
is a sub string of any paramter in the option).
- Authors:
William C. McLendon III <wcmclen@sandia.gov>
Public API
- class setprogramoptions.SetProgramOptions(filename=None)[source]
Bases:
ConfigParserEnhanced
- __init__(filename=None)[source]
Constructor
- Parameters:
filename (str,Path,list) – The
.ini
file or files to be loaded. If astr
orPath
is provided then we load only the one file. Alist
of strings orPath
s can also be provided, which will be loaded byConfigParser
’s read() method.
- gen_option_list(section, generator='bash') list [source]
Generate a list of options for a section.
Generates a list of strings that captures the requested operation based on the entries in the .ini file that is stored in
options
during parsing.The
bash
generator will generate a set of ‘bash’ like entries that could be concactenated to generate a bash command.For example, the .ini section:
1[SECTION_A] 2opt-set cmake 3opt-set -G : Ninja 4opt-set /path/to/source/dir
will generate this output:
>>> option_list = parser.gen_option_list("SECTION_A", "bash") >>> option_list [ 'cmake', '-G=Ninja', '/path/to/source/dir' ]
Which can be joined easily to create a bash instruction, such as:
>>> " ".join(option_list) cmake -G=Ninja
or we could generate a multi-line bash command with continuation lines like this:
>>> " \\\n ".join(option_list) cmake \ -G=Ninja \ /path/to/source/dir
This can then be executed in a bash shell or saved to a script file that could be executed separately.
- Parameters:
section (str) – The section name that contains the options we wish to process.
generator (str) – What kind of generator are we to use to build up our options list? Currently we allow
bash
but subclasses can define their own functions using the format_gen_option_entry_<generator>(option_entry:dict)
- Returns:
A
list
containing the processed options text.- Return type:
list
- property options: dict
The
options
property contains the set of parsed options that has been processed so far stored as a dictionary. For example, the following .ini snippet:1[SECTION_A] 2opt-set cmake 3opt-set -G : Ninja
might generate the folllowing result in
options
:>>> parser.options {'SECTION_A': [ {'type': ['opt_set'], 'params': ['cmake'], 'value': None }, {'type': ['opt_set'], 'params': ['-G'], 'value': 'Ninja' } ] }
would encode the reults of a
.ini
file section “SECTION_A” which encoded the command:cmake -G Ninja
.This data is used by the
gen_option_list
method to generate snippets according to the requested generator, such as “bash” or “cmake_fragment”.- Raises:
TypeError – A TypeError can be raised if a non-dictionary is assigned to this property.
- property SetProgramOptions.options: dict
The
options
property contains the set of parsed options that has been processed so far stored as a dictionary. For example, the following .ini snippet:1[SECTION_A] 2opt-set cmake 3opt-set -G : Ninja
might generate the folllowing result in
options
:>>> parser.options {'SECTION_A': [ {'type': ['opt_set'], 'params': ['cmake'], 'value': None }, {'type': ['opt_set'], 'params': ['-G'], 'value': 'Ninja' } ] }
would encode the reults of a
.ini
file section “SECTION_A” which encoded the command:cmake -G Ninja
.This data is used by the
gen_option_list
method to generate snippets according to the requested generator, such as “bash” or “cmake_fragment”.- Raises:
TypeError – A TypeError can be raised if a non-dictionary is assigned to this property.
Private API
Properties
Key used by
handler_parameters
forshared_data
This key is used inside the
handler_parameters.shared_data[_data_shared_key]
as the place we’re storing the action list and other data associated with theConfigParserEnhanced
parsing of a given root section.This information is generally copied out during the
handler_finalize()
into some class property for accessing beyond the search itself.Currently this just uses the current class name.
- Returns:
Default dictionary key internal parser use.
This property returns a string that is used as the default key in
handler_parameters.data_shared
to bin the data being generated during a search.This can be used in the
handler_finalize()
method to extract the shared data captured by the parser before it is discarded at the end of a search.- Return type:
str
Handlers
- SetProgramOptions._handler_opt_set(section_name, handler_parameters)
- SetProgramOptions._handler_opt_remove(section_name, handler_parameters)
- SetProgramOptions.handler_initialize(section_name, handler_parameters)
- SetProgramOptions.handler_finalize(section_name, handler_parameters)
- SetProgramOptions._initialize_handler_parameters(section_name, handler_parameters) int [source]
Initialize
handler_parameters
Initializes any default settings needed for
handler_parameters
. Takes the same parameters as handlers.- Parameters:
section_name (str) – The section name string.
handler_parameters (
HandlerParameters
) – A HandlerParameters object containing the state data we need for this handler.
- Called By:
handler_initialize()
Handler Helpers
- SetProgramOptions._option_handler_helper_add(section_name: str, handler_parameters) int [source]
Add an option to the shared data options list
Inserts an option into the
handler_parameters.data_shared["{_data_shared_key}"]
list, where{_data_shared_key}
is generated from the property_data_shared_key
. Currently,_data_shared_key
returns the class name of the class object.Operations with the format such as this:
1[SECTION NAME] 2operation Param1 Param2 ... ParamN : Value
which result in a
dict
entry:1{ 2 'type' : [ operation ], 3 'params': [ param1, param2, ... , paramN ], 4 'value' : Value 5}
this entry is then appended to the
handler_parameters.data_shared[{_data_shared_key}]
list, where_data_shared_key
is generated from the property_data_shared_key
.Currently
_data_shared_key
returns the current class name, but this can be changed if needed.- Parameters:
section_name (str) – The name of the section being processed.
handler_parameters (
HandlerParameters
) – The parameters passed to the handler.
- Returns:
0 : SUCCESS
[1-10]: Reserved for future use (WARNING)
> 10 : An unknown failure occurred (CRITICAL)
- Return type:
int
- SetProgramOptions._option_handler_helper_remove(section_name: str, handler_parameters) int [source]
Removes option(s) from the shared data options list.
Removes an option or options from the
handler_parameters.data_shared["{_data_shared_key}"]
list, where{_data_shared_key}
is generated from the property_data_shared_key
. Currently,_data_shared_key
returns the class name of the class object.In this case the format is based on the following .ini snippet:
1[SECTION NAME] 2<operation> KEYWORD [SUBSTR]
where we remove entries from the shared data options list according to one of the following methods:
Removes entries if one of the parameters matches the provided
KEYWORD
.If the optional
SUBSTR
parameter is provided, then we remove entries if any paramter contains theKEYWORD
as either an exact match or a substring.
- Parameters:
section_name (str) – The name of the section being processed.
handler_parameters (
HandlerParameters
) – The parameters passed to the handler.
- Returns:
0 : SUCCESS
[1-10]: Reserved for future use (WARNING)
> 10 : An unknown failure occurred (CRITICAL)
- Return type:
int
Program Option Handlers
- SetProgramOptions._program_option_handler_opt_set_bash(params: list, value: str) str [source]
Bash generator for
opt-set
operations.This method handles the generation of an entry for an
opt-set
operation when the generator is set to bebash
.Called by:
_gen_option_entry()
.- Returns:
A
string
containing a generated program option with the parameters concactenated together using the format<param1><param2>...<paramN>=<value>
will be returned.- Return type:
str
- SetProgramOptions._generic_program_option_handler_bash(params: list, value: str) str [source]
Generic processer for generic bash options.
This is the simplest kind of option handler for bash-like commands where we just concatenate all the
params
together and set them equal to thevalue
.For example:
>>> params = ['-D','SOMEFLAG',':BOOL'] >>> value = "ON" >>> _generic_program_option_handler_bash(params,value) "-DSOMEFLAG:BOOL=ON"
Called by:
_program_option_handler_opt_set_bash()
- Parameters:
params (list) – A
list
of strings containing the parameters that would be to the LHS or the=
when constructing an option entry.value (str) – A
str
that is placed to the RHS of the option assignment expression.
- Returns:
A
str
object representing an option.- Return type:
str
- SetProgramOptions._gen_option_entry(option_entry: dict, generator='bash') str | None [source]
Takes an
option_entry
and looks for a specialized handler for that option type.This looks for a method named
_program_option_handler_<typename>_<generator>
wheretypename
comes from theoption_entry['type']
field. For example, ifoption_entry['type']
isopt_set
andgenerator
isbash
then we look for a method called_program_option_handler_opt_set_bash()
, which is executed and returns the line-item entry for the givenoption_entry
.- Parameters:
option_entry (dict) – A dictionary storing a single option entry.
- Returns:
A
string
containing the single entry for this option orNone
None
is returned IF thetype
field inoption_entry
does not resolve to a proper method and the exception control level is not set sufficiently high to trigger an exception.- Return type:
Union[str,None]
- Raises:
ValueError – If we aren’t able to locate the options formatter.