|Did you know ...||Search Documentation:|
|Packs (add-ons) for SWI-Prolog|
|Title:||Allows to retrieve setting from execution environment, given flexibility over setting/2, get_env, or command line configuration|
|Rating:||Not rated. Create the first rating!|
|Author:||Milan Unger http://milung.eu/|
No reviews. Create the first review!.
Prolog module for reading execution context variables. Enables to retrieve execution specific variables from command line options, environment variables, configuration file or fallback to some predefined default value.
execution_context and declare your context variables by invoking context_variable/3 predicate.
After that you can use the predicate context_variable/2 or option_or_context_variable/2 predicates to read
value of the context variable.
:- use_module(library(execution_context)). :- context_variable(my_variable, atom, [long('cli-arg-name'), short(m), env(MY_VARIABLE), default(some_value)]). hallo :- context_variable_value(my_variable, Value), writeln(Value).
The variable names are module scoped. The resolution is done in the following order:
context_variable(+Name:atom, +Type, +Options:list)is det.
Declares new contextual variable with the module specific name. Repeated declarations
for the same Name are possible, the last call is taken into account but not after the
value was queried (which would be served from the cache.
Type can be one of the atom, bool, number, string, list,
in case of list types, the list can be specified as a list of atoms or numbers separate by comma (,)
or semicolon, and optionally enclosed into parenthesis or brackets (e.g.
[ a, b,c, e],
(1;2; 3 ; 4), or
o, p ; q, r ) will work. Elements in the list are trimmed of left and right spaces.
Options can be one of:
describe(Message)- provides human readable information about the command that is printed when the CLI help is invoked (for cli options).
long(Long)- specifies the long name of the command line parameter prefixed with two dashes. If not provided then the Long name is assumed to be based on the name with characters ' ', '_', ':' replaced by the dash. Value of the variable can be either concatenated into argument with '=' character, or separated by space. For example if the
long(some_option)is given then the argument `--some-option=value`, or `--some-option value` will both assign
valueto context variable of the Name.
short(Short)- specifies short variant of the command line argument prefixed by '-'. Value must be provided after the space. For example if the option
short(s)is given then the argument `-s value` will assign 'value' to context variable of the Name
is_flag(Bool)- if Bool is true, then the system recognize the options with out value and `--no-long
options, wherelong` correspnds to the
long(Atom)option value. Variables of type
boolare implicitly considered to be flags
env(EnvName)- specifies the name of the environment variable to check for the value of the context variable. If not provided then the EnvName name is assumed to be based on the name with characters ' ', '_', ':' replaced by the undescore.
default(Value)- Specifies the default values if no other means provides a value. If the Value is of the form
context(Variable), then context variable Variable is evaluated for the default value. Infinite dependency cycles are not resolved, so be carefull here.
cli_command(Commands)- Commands is list of CLI commands (see execute_cli/1), for which the variable is intended. This information is only used to describe usage of the command. Either option
shortor `long˙, and option `describe˙ must be provided to provide any help information about the variable. The option
cli_command()is interpreted as the option for all CLI commands.
context_variable_value(+Variable, -Value)is semidet
Unifies Value with the contextual variable. The Variable must be declared using context_variable/3 call. To resolve the contextual variable following steps are executed. The first step that succed will determine the Value
config.envfiles are looked up in the file search paths defined as
paramspath resolves to current working directory or into the
configdirectory of the current working directory. The name variants are provided by the options of the predicate context_variable/2 or derived from the context variable name.
option_or_context_variable(Option, Options)is semidet
As option/2, but if that fails then it behaves as
Options are checked for the module specific or local name of the option.
current_prolog_flag(argv, Arguments), execute_cli(Arguments)
Interprets Arguments which are assumed to be unified by
current_prolog_flag(argv, Arguments) call
and calls goal registered by cli_command/2 directive. The name of the command is determined
by the first positional argument. Options are removed from the Arguments list by checking against
registered context variables - see context_variable/3 predicate.
cli_option(Type, OptionName) exception if required arguments are not provided
(see register_cli_command/3), or when the option that cannot be associated with any context variable
is found on command line arguments. The exception can be used for print_message call.
Registers new command for CLI. The Goal will be invoked when the first positional argument
unifies with Command. The Goal is invoked as
call(Goal, PositionalArguments, Options)
where PositionalArguments are all arguments that are not an command line option, and Options
maps some of the context variables to the goal options.
ArgumentSpec can contain some of the following terms:
describe(Message)- provides human readable information about the command that is printed when the CLI command
helpor `command help` is invoked.
context(ContextVariable, OptionName)- if call to
context_variable_value(ContextVariable, Value)succeeds, then Goal second argument will contain option named OptionName with the value Value. If the context_variable is not resolved then the exception is raised and user informed that the required option is missing
optional(context(ContextVariable, OptionName))- similar to above, but the context variable is not required to be resolved
positional(Nth1, OptionName)- associates Nth1 element of positional arguments with option OptionName when calling Goal. If there are not enough positional argumentsthen the exception is raised and user is informed that argument is missing
optional(positional(Nth1, OptionName))- similar to above, but the positional argument is not required to be resolved
The tests requires some command line options and environment variables, also the availability of config files. The script run-tests.ps1 prepares the environment.
To debug the module, load the
debug.pl file into prolog top.
Pack contains 12 files holding a total of 45.5K bytes.