ActiveConfigProgramOptions
==========================
The `ActiveConfigProgramOptions` package extends [`ActiveConfigParser`][5] to enable the
processing of **.ini** files that specify **command line program options**.
As a subclass of ActiveConfigParser, ActiveConfigProgramOptions supports all
the _operations_ that [`ActiveConfigParser`][5] supports and adds some of its
own. The following table notes the new **operations** that ActiveConfigProgramOptions adds:
| Operation | Format | Defined By |
| ------------ | --------------------------------------------- | ---------------------------- |
| `use` | `use <section>` | [`ActiveConfigParser`][5] |
| `opt-set` | `opt-set Param1 [Param2..ParamN] [: <VALUE>]` | `ActiveConfigProgramOptions` |
| `opt-remove` | `opt-remove Param [SUBSTR]` | `ActiveConfigProgramOptions` |
Generally speaking, when we parse a section from a .ini file, the following
steps are taken:
1. Parse the section, resolving any `use` operations to fully parse the DAG
generated by the section and its dependents.
2. This generates a *list of actions* that are specified in the configuration
file. Any `remove` operations encountered will execute their removal search
during parsing to ensure they only remove matches that are _previously_ defined.
3. Once parsed, a _generator_ can be invoked to process the actions-list and generate
the requested back-end format. Currently, ActiveConfigProgramOptions only generates output
for *bash* scripts but this can easily be extended to support other formats such
as Windows batch or Powershell files, or other kinds of shell commands.
Subclasses can also be extended to include their own generator types as well.
Supported Operations
--------------------
### `use`
The `use` operation is inherited from [`ActiveConfigParser`][5]. Please see its documentation
on this command and its use.
### `opt-set`
Sets a generic _command line_ style option.
The format of this is `opt-set Param1 [Param2] [Param3] ... [ParamN] : [VALUE]`
In a _bash_ context, this operation attempts to generate an option for some command
that will be executed.
`ActiveConfigProgramOptions` will concactenate the _Params_ together and then append `=VALUE`
if a VALUE field is present.
For example, `opt-set Foo Bar : Baz` will become `FooBar=Baz`.
### `opt-remove`
_Removes_ existing entries that have been processed up to the point the `opt-remove` is
encountered that match a pattern.
The format of this is `opt-remove Param [SUBSTR]`
When a _remove_ is encountered, `ActiveConfigProgramOptions` will search through all processed
options and will delete any that contain any _Param-i_ that matches `Param`.
By default the parameters much be an _exact match_ of `Param`, but if the optional
`SUBSTR` parameter is provided then `ActiveConfigProgramOptions` will treat `Param` as a
substring and will remove all existing options if _any parameter contains Param_.
ActiveConfigProgramOptions Config Files
---------------------------------------
A **.ini** file that can be processed by `ActiveConfigProgramOptions` can be formatted like this:
```ini
[COMMAND_LS]
opt-set ls
```
This is perhaps the most simple thing we could do.
Using `gen_option_list('COMMAND_LS', generator="bash")`
this operation would generate the command `ls` when processed.
A more complex section which creates a CMake command call might look like this:
```ini
[COMMAND_CMAKE]
opt-set cmake
opt-set -G : Ninja
opt-set -D CMAKE_CXX_FLAGS : "-O3"
```
and this would generate the command `cmake -G=Ninja -DCMAKE_CXX_FLAGS="-O3"` when
processed for _bash_ output.
### Variable Expansion within VALUE fields
Variables can be added to the VALUE fields in handled instructions, but they have their
own format that must be used:
```
${VARNAME|VARTYPE}
```
- `VARNAME` is the variable name that you might expect for a bash style environment variable
that might be defined like this: `export VARNAME=VALUE`.
- `VARTYPE` is the **type** of the variable that is being declared. For `ActiveConfigProgramOptions`
the only recognized type is `ENV` which defines _environment variables_. Subclasses such
as `ActiveConfigProgramOptionsCMake` define their own types.
We do not provide a **default** type for this because we wish it to be _explicit_ that this
is a pseudo-type and do not want it to be confused with some specific variable type since that
meaning can change depending on the kind of generator being used. For example, `${VARNAME}`
is an _environment variable_ within a bash context but in a CMake fragment file it would be
an _internal CMake variable_ and `$ENV{VARNAME}` would be an _environment variable_.
By not providing a default we force type consideration to be made explicitly during the creation
of the .ini file.
Linked Projects
---------------
- [ActiveConfigParser][5] - prerequisite - [Docs][7], [Source][2], [PyPi][10]
- [ExceptionControl][] - prerequisite - [Docs][11], [Source][12], [PyPi][13]
- [StronglyTypedProperty][] - prerequisite - [Docs][], [Source][], [PyPi][]
ActiveConfigProgramOptions Examples
-----------------------------------
### Example 1
#### [ActiveConfigProgramOptions-example-01.ini][8]
```ini
[BASH_VERSION]
opt-set bash
opt-set --version
[LS_COMMAND]
opt-set ls
[LS_LIST_TIME_REVERSED]
opt-set "-l -t -r"
[LS_CUSTOM_TIME_STYLE]
opt-set --time-style : "+%Y-%m-%d %H:%M:%S"
[MY_LS_COMMAND]
use LS_COMMAND
use LS_LIST_TIME_REVERSED
use LS_CUSTOM_TIME_STYLE
```
#### [ActiveConfigProgramOptions-example-01.py][9]
```python
#!/usr/bin/env python3
import activeconfigprogramoptions
filename = "ActiveConfigProgramOptions-example-01.ini"
section = "MY_LS_COMMAND"
# Create ActiveConfigProgramOptions instance
popts = activeconfigprogramoptions.ActiveConfigProgramOptions(filename)
# Parse section
popts.parse_section(section)
# Generate the list of bash options for the command
bash_options = popts.gen_option_list(section, generator="bash")
# Print out the commands
print(" ".join(bash_options))
```
generates the output:
```bash
ls -l -t -r --time-style="+%Y-%m-%d %H:%M:%S"
```
### Example 2
We can utilize the `use` operation to create a more complex configuration file
that provides some sort of common sections and then point-of-use sections that
would generate customized configurations for a particular use:
```ini
[CMAKE_COMMAND]
opt-set cmake
opt-set -G : Ninja
[CMAKE_OPTIONS_COMMON]
opt-set -D CMAKE_CXX_FLAGS : "-fopenmp"
[CMAKE_OPTIONS_APPLICATION]
opt-set -D MYAPP_FLAG1 : "foo"
opt-set -D MYAPP_FLAG2 : "bar"
[APPLICATION_PATH_TO_SOURCE]
opt-set /path/to/source/.
[APPLICATION_CMAKE_PROFILE_01]
use CMAKE_COMMAND
use CMAKE_OPTIONS_COMMON
use CMAKE_OPTIONS_APPLICATION
use APPLICATION_PATH_TO_SOURCE
[APPLICATION_CMAKE_PROFILE_02]
use APPLICATION_PROFILE_01
opt-remove MYAPP_FLAG2
```
This example follows a pattern that larger projects might wish to use
when there are many configurations that may be getting tested.
Here, we set up some common option groups and then create aggregation sections
that will include the other sections to compose a full command line.
Using this .ini file, if we generate _bash_ output for section
`APPLICATION_CMAKE_PROFILE_01` the resulting command generated would be:
`cmake -G=Ninja -DCMAKE_CXX_FLAGS="-fopenmp" -DMYAPP_FLAG1="foo" -DMYAPP_FLAG2="bar" /path/to/source/.`
Alternatively, we can generate _bash_ output for section
`APPLICATION_CMAKE_PROFILE_02` which first clones `APPLICATION_CMAKE_PROFILE_01`
and then _removes_ all entries containing the parameter `MYAPP_FLAG2` using the
`opt-remove` operation.
This will result in a generated comand
`cmake -G=Ninja -DCMAKE_CXX_FLAGS="-fopenmp" -DMYAPP_FLAG1="foo" /path/to/source/.`.
This example shows how the `opt-remove` operation will fully
remove occurrences that contain that substring from the list
of actions.
This example shows some of the capabilities that `ActiveConfigProgramOptions`
provides for managing many build configurations within a single .ini
file.
ActiveConfigProgramOptionsCMake
===============================
`ActiveConfigProgramOptionsCMake` is a subclass of `ActiveConfigProgramOptions` that adds additional
operations and generators to handle processing [CMake][6] options:
- Adds `opt-set-cmake-var`.
- Adds `cmake_fragment` generator.
- Adds `CMAKE` type to variables.
New operations defined in `ActiveConfigProgramOptionsCMake`:
| Operation | Format | Defined By |
| ------------------- | ---------------------------------------------------------------- | --------------------------------- |
| `opt-set-cmake-var` | `opt-set-cmake-var VARNAME [TYPE] [FORCE] [PARENT_SCOPE]: VALUE` | `ActiveConfigProgramOptionsCMake` |
Supported Operations
--------------------
### `opt-set-cmake-var`
This adds a CMake variable program option. These have a special syntax in
_bash_ that looks like `-DVARNAME:TYPE=VALUE` where the `:TYPE` is an
optional parameter. If the *type* is left out then CMake assumes the
value is a _STRING_.
We may not wish to generate bash only output though. For CMake files, we
might wish to generate a _cmake fragment_ file which is basically a snippet
of CMake that can be loaded during a CMake call using the `-S`
option: `cmake -S cmake_fragment.cmake`.
The syntax within a CMake fragment file is the same as in a CMake script
itself.
If the back-end generator is creating a CMake fragment file,
the _set_ command generated will use [CMake set syntax].
This looks something like `set(<variable> <value>)` but can also
contain additional options. These extra options can
be provided in the `opt-set-cmake-var` operation in the .ini file:
- `FORCE` -
- By default, a `set()` operation does not overwrite entries in a CMake file.
This can be added to _force_ the value to be saved.
- This is only applicable to generating _cmake fragment_ files.
- `PARENT_SCOPE` - If provided, this option instructs CMake to set the variable
in the scope that is above the current scope.
- This is only applicable to generating _cmake fragment_ files.
- `TYPE` - Specifies the _TYPE_ the variable can be.
- This is a _positional_ argument and must always come after _VARNAME_.
- Valid options for this are `STRING` (default), `BOOL`, `PATH`, `INTERNAL`, `FILEPATH`.
- Adding a _TYPE_ option implies that the _CACHE_ and _docstring_
parameters will be added to a `set()` command in a CMake fragment
file according to the syntax: `set(<variable> <value> CACHE <type> <docstring> [FORCE])`
as illustrated on the [CMake `set()` documentation][1].
- This is applicable to both _cmake fragment_ and _bash_ generation.
ActiveConfigProgramOptionsCMake Config Files
--------------------------------------------
Here is an example of what a .ini file may look like using the
CMake operations provided by this class:
```ini
[SECTION_A]
opt-set cmake
opt-set-cmake-var MYVARIABLENAME : VALUE
opt-set-cmake-var MYVARIABLENAME2 PARENT_SCOPE : VALUE
```
### Handling CMake Variables
A _CMake variable_ in this context would be an _internal variable_ that is
known to CMake. Because this is not a variable that would be known outside
of the context of `.cmake` files, this kind of variable is only applicable
when generating CMake fragment files.
It is necessary to provide a CMake variant for variable expansions because
the CMake syntax for variables is different than that used by Bash, and
CMake fragments have a specialized syntax for *environment* variables as well.
In CMake fragment files:
- environment variables are written as `$ENV{VARNAME}`
- internal CMake variables are written as: `${VARNAME}`
We saw variables in `ActiveConfigProgramOptions` follow the syntax: `${VARNAME|ENV}`
where `ENV` specifies the kind of variable we're declaring.
We extend this in `ActiveConfigProgramOptionsCMake` by adding a `${VARNAME|CMAKE}`
variation which indicates that the variable is expected to be an _internal_
cmake variable and is more suited towards being used within a CMake fragment
file since it has no meaning at the command line.
You can still use a _CMake_ variable expansion entry when generating _bash_
output but there is a catch. The variable *must* be resolvable to something
that is **not** a CMake variable through its transitive closure.
This is achieved by caching the _last known value_ of a variable as we process
a .ini file and provided that the value ultimately resolves to either a string
or an environment variable we can still use it.
If it cannot be resolved to something that isn't a CMake variable then an
exception should be generated.
For example, if we have a .ini file that sets up `CMAKE_CXX_FLAGS` to
include `-O0` in a common section like this:
```ini
[COMMON]
opt-set-cmake-var CMAKE_CXX_FLAGS STRING FORCE: "-O0"
```
and then we have a later section that adds an OpenMP flag to it like this:
```.ini
[ADD_OPENMP]
use COMMON
opt-set-cmake-var CMAKE_CXX_FLAGS STRING FORCE: "${CMAKE_CXX_FLAGS|CMAKE} -fopenmp"
```
This is valid since `${CMAKE_CXX_FLAGS|CMAKE}` will get replaced with `-O0` so the
resulting `CMAKE_CXX_FLAGS` variable would be set to `-O0 -fopenmp` after processing.
If we generate _bash_ output for the `ADD_OPENMP` section we'll get
a `-D` option that looks like `-DCMAKE_CXX_FLAGS:STRING="-O0 -fopenmp"`.
But what if we have a .ini file with a CMake variable that can't be resolved to
something that is not a CMake flag, such as:
```ini
[COMMON]
opt-set-cmake-var FOO : ${SOME_CMAKE_VAR|CMAKE}
```
If we tried to process this and write out the resulting script
using the _bash_ generator an exception should be raised citing
that we don't know what to do with that unresolved CMake variable.
This would be the equivalent to a bash option `-DFOO=<SOME_CMAKE_VAR>`
and bash can't handle that because it has no idea what it should put
in that cmake var field.
Note: if the same CMake option is provided in multiple lines they will
all be included in the generated output. In that case, the behaviour will
match what will occur if one called cmake directly with the same option
multiple times.
In that case, the _last one wins_ since all `-D` options are treated as
though they both have `FORCE` and `CACHE` flags set.
ActiveConfigProgramOptionsCMake Examples
----------------------------------------
### Example
This example shows a configuration file that can be used to generate
build files using Ninja or Makefile. In the .ini file we set up some
common sections that contain the arguments and then the point-of-use
sections ( `MYPROJ_CONFIGURATION_NINJA` and `MYPROJ_CONFIGURATION_MAKEFILES` )
can compose their command lines by importing the argument definition sections
via `use`.
#### [ActiveConfigProgramOptions-example-02.ini][17]
```ini
#
# ActiveConfigProgramOptions-example-02.ini
#
[CMAKE_COMMAND]
opt-set cmake
[CMAKE_GENERATOR_NINJA]
opt-set -G : Ninja
[CMAKE_GENERATOR_MAKEFILES]
opt-set -G : "Unix Makefiles"
[MYPROJ_OPTIONS]
opt-set-cmake-var MYPROJ_CXX_FLAGS STRING : "-O0 -fopenmp"
opt-set-cmake-var MYPROJ_ENABLE_OPTION_A BOOL FORCE : ON
opt-set-cmake-var MYPROJ_ENABLE_OPTION_B BOOL : ON
[MYPROJ_SOURCE_DIR]
opt-set /path/to/source/dir
[MYPROJ_CONFIGURATION_NINJA]
use CMAKE_COMMAND
use CMAKE_GENERATOR_NINJA
use MYPROJ_OPTIONS
use MYPROJ_SOURCE_DIR
[MYPROJ_CONFIGURATION_MAKEFILES]
use CMAKE_COMMAND
use CMAKE_GENERATOR_MAKEFILES
use MYPROJ_OPTIONS
use MYPROJ_SOURCE_DIR
```
#### [ActiveConfigProgramOptions-example-02.py][18]
This python code shows generating a bash script and a CMake fragment
of the configuration specified in the .ini file.
```python
#!/usr/bin/env python3
# -*- mode: python; py-indent-offset: 4; py-continuation-offset: 4 -*-
from pathlib import Path
import activeconfigprogramoptions
print(80*"-")
print(f"- {Path(__file__).name}")
print(80*"-")
filename = "ActiveConfigProgramOptions-example-02.ini"
popts = activeconfigprogramoptions.ActiveConfigProgramOptionsCMake(filename)
section = "MYPROJ_CONFIGURATION_NINJA"
popts.parse_section(section)
# Generate BASH output
print("")
print("Bash output")
print("-----------")
bash_options = popts.gen_option_list(section, generator="bash")
print(" \\\n ".join(bash_options))
# Generate a CMake Fragment
print("")
print("CMake fragment output")
print("---------------------")
cmake_options = popts.gen_option_list(section, generator="cmake_fragment")
print("\n".join(cmake_options))
print("\nDone")
```
#### Output
Using the *Ninja* specialization from the above code, we generate the following
output:
```bash
$ python3 ActiveConfigProgramOptions-example-02.py
--------------------------------------------------------------------------------
- ActiveConfigProgramOptions-example-02.py
--------------------------------------------------------------------------------
**Bash output**
cmake \
-G=Ninja \
-DMYPROJ_CXX_FLAGS:STRING="-O0 -fopenmp" \
-DMYPROJ_ENABLE_OPTION_A:BOOL=ON \
-DMYPROJ_ENABLE_OPTION_B:BOOL=ON \
/path/to/source/dir
CMake fragment output
---------------------
set(MYPROJ_CXX_FLAGS "-O0 -fopenmp" CACHE STRING "from .ini configuration")
set(MYPROJ_ENABLE_OPTION_A ON CACHE BOOL "from .ini configuration" FORCE)
set(MYPROJ_ENABLE_OPTION_B ON CACHE BOOL "from .ini configuration")
Done
```
[1]: https://cmake.org/cmake/help/latest/command/set.html
[2]: https://gitlab.com/semantik-software/code/python/ActiveConfigParser
[3]: https://gitlab.com/semantik-software/code/python/ActiveConfigParser/-/blob/main/CHANGELOG.md
[4]: https://semantik-software.gitlab.io/code/python/ActiveConfigProgramOptions/
[5]: https://pypi.org/project/activeconfigparser/
[6]: https://www.cmake.org/
[7]: https://semantik-software.gitlab.io/code/python/ActiveConfigParser/
[8]: https://gitlab.com/semantik-software/code/python/ActiveConfigProgramOptions/-/blob/main/examples/ActiveConfigProgramOptions-example-01.ini
[9]: https://gitlab.com/semantik-software/code/python/ActiveConfigProgramOptions/-/blob/main/examples/ActiveConfigProgramOptions-example-01.py
[10]: https://pypi.org/project/activeconfigparser/
[11]: https://semantik-software.gitlab.io/code/python/ExceptionControl/
[12]: https://gitlab.com/semantik-software/code/python/ExceptionControl
[13]: https://pypi.org/project/exceptioncontrol/
[14]: https://semantik-software.gitlab.io/code/python/StronglyTypedProperty/
[15]: https://gitlab.com/semantik-software/code/python/StronglyTypedProperty
[16]: https://pypi.org/project/stronglytypedproperty/
[17]: https://gitlab.com/semantik-software/code/python/ActiveConfigProgramOptions/-/blob/main/examples/ActiveConfigProgramOptions-example-02.ini
[18]: https://gitlab.com/semantik-software/code/python/ActiveConfigProgramOptions/-/blob/main/examples/ActiveConfigProgramOptions-example-02.py
Raw data
{
"_id": null,
"home_page": "https://gitlab.com/semantik-software/code/python/ActiveConfigProgramOptions",
"name": "activeconfigprogramoptions",
"maintainer": "William McLendon",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "Semantik-Code@outlook.com",
"keywords": "Utility,Bash,Configuration,ActiveConfigParser,ConfigParser",
"author": "William McLendon",
"author_email": "Semantik-Code@outlook.com",
"download_url": "https://files.pythonhosted.org/packages/a8/8a/8806162f90495280f18218e4635a271a4dd754b58b8a44cba28e23b9936e/activeconfigprogramoptions-0.6.0.0.tar.gz",
"platform": null,
"description": "ActiveConfigProgramOptions\n==========================\nThe `ActiveConfigProgramOptions` package extends [`ActiveConfigParser`][5] to enable the\nprocessing of **.ini** files that specify **command line program options**.\n\nAs a subclass of ActiveConfigParser, ActiveConfigProgramOptions supports all\nthe _operations_ that [`ActiveConfigParser`][5] supports and adds some of its\nown. The following table notes the new **operations** that ActiveConfigProgramOptions adds:\n\n| Operation | Format | Defined By |\n| ------------ | --------------------------------------------- | ---------------------------- |\n| `use` | `use <section>` | [`ActiveConfigParser`][5] |\n| `opt-set` | `opt-set Param1 [Param2..ParamN] [: <VALUE>]` | `ActiveConfigProgramOptions` |\n| `opt-remove` | `opt-remove Param [SUBSTR]` | `ActiveConfigProgramOptions` |\n\nGenerally speaking, when we parse a section from a .ini file, the following\nsteps are taken:\n\n1. Parse the section, resolving any `use` operations to fully parse the DAG\n generated by the section and its dependents.\n2. This generates a *list of actions* that are specified in the configuration\n file. Any `remove` operations encountered will execute their removal search\n during parsing to ensure they only remove matches that are _previously_ defined.\n3. Once parsed, a _generator_ can be invoked to process the actions-list and generate\n the requested back-end format. Currently, ActiveConfigProgramOptions only generates output\n for *bash* scripts but this can easily be extended to support other formats such\n as Windows batch or Powershell files, or other kinds of shell commands.\n Subclasses can also be extended to include their own generator types as well.\n\n\nSupported Operations\n--------------------\n\n### `use`\nThe `use` operation is inherited from [`ActiveConfigParser`][5]. Please see its documentation\non this command and its use.\n\n### `opt-set`\nSets a generic _command line_ style option.\n\nThe format of this is `opt-set Param1 [Param2] [Param3] ... [ParamN] : [VALUE]`\n\nIn a _bash_ context, this operation attempts to generate an option for some command\nthat will be executed.\n`ActiveConfigProgramOptions` will concactenate the _Params_ together and then append `=VALUE`\nif a VALUE field is present.\nFor example, `opt-set Foo Bar : Baz` will become `FooBar=Baz`.\n\n\n### `opt-remove`\n_Removes_ existing entries that have been processed up to the point the `opt-remove` is\nencountered that match a pattern.\n\nThe format of this is `opt-remove Param [SUBSTR]`\n\nWhen a _remove_ is encountered, `ActiveConfigProgramOptions` will search through all processed\noptions and will delete any that contain any _Param-i_ that matches `Param`.\nBy default the parameters much be an _exact match_ of `Param`, but if the optional\n`SUBSTR` parameter is provided then `ActiveConfigProgramOptions` will treat `Param` as a\nsubstring and will remove all existing options if _any parameter contains Param_.\n\n\nActiveConfigProgramOptions Config Files\n---------------------------------------\nA **.ini** file that can be processed by `ActiveConfigProgramOptions` can be formatted like this:\n```ini\n[COMMAND_LS]\nopt-set ls\n```\nThis is perhaps the most simple thing we could do.\nUsing `gen_option_list('COMMAND_LS', generator=\"bash\")`\nthis operation would generate the command `ls` when processed.\n\nA more complex section which creates a CMake command call might look like this:\n```ini\n[COMMAND_CMAKE]\nopt-set cmake\nopt-set -G : Ninja\nopt-set -D CMAKE_CXX_FLAGS : \"-O3\"\n```\nand this would generate the command `cmake -G=Ninja -DCMAKE_CXX_FLAGS=\"-O3\"` when\nprocessed for _bash_ output.\n\n\n### Variable Expansion within VALUE fields\nVariables can be added to the VALUE fields in handled instructions, but they have their\nown format that must be used:\n```\n${VARNAME|VARTYPE}\n```\n- `VARNAME` is the variable name that you might expect for a bash style environment variable\n that might be defined like this: `export VARNAME=VALUE`.\n- `VARTYPE` is the **type** of the variable that is being declared. For `ActiveConfigProgramOptions`\n the only recognized type is `ENV` which defines _environment variables_. Subclasses such\n as `ActiveConfigProgramOptionsCMake` define their own types.\n\nWe do not provide a **default** type for this because we wish it to be _explicit_ that this\nis a pseudo-type and do not want it to be confused with some specific variable type since that\nmeaning can change depending on the kind of generator being used. For example, `${VARNAME}`\nis an _environment variable_ within a bash context but in a CMake fragment file it would be\nan _internal CMake variable_ and `$ENV{VARNAME}` would be an _environment variable_.\nBy not providing a default we force type consideration to be made explicitly during the creation\nof the .ini file.\n\n\nLinked Projects\n---------------\n- [ActiveConfigParser][5] - prerequisite - [Docs][7], [Source][2], [PyPi][10]\n- [ExceptionControl][] - prerequisite - [Docs][11], [Source][12], [PyPi][13]\n- [StronglyTypedProperty][] - prerequisite - [Docs][], [Source][], [PyPi][]\n\n\nActiveConfigProgramOptions Examples\n-----------------------------------\n\n### Example 1\n\n#### [ActiveConfigProgramOptions-example-01.ini][8]\n```ini\n[BASH_VERSION]\nopt-set bash\nopt-set --version\n\n[LS_COMMAND]\nopt-set ls\n\n[LS_LIST_TIME_REVERSED]\nopt-set \"-l -t -r\"\n\n[LS_CUSTOM_TIME_STYLE]\nopt-set --time-style : \"+%Y-%m-%d %H:%M:%S\"\n\n[MY_LS_COMMAND]\nuse LS_COMMAND\nuse LS_LIST_TIME_REVERSED\nuse LS_CUSTOM_TIME_STYLE\n```\n\n#### [ActiveConfigProgramOptions-example-01.py][9]\n\n```python\n#!/usr/bin/env python3\nimport activeconfigprogramoptions\n\nfilename = \"ActiveConfigProgramOptions-example-01.ini\"\nsection = \"MY_LS_COMMAND\"\n\n# Create ActiveConfigProgramOptions instance\npopts = activeconfigprogramoptions.ActiveConfigProgramOptions(filename)\n\n# Parse section\npopts.parse_section(section)\n\n# Generate the list of bash options for the command\nbash_options = popts.gen_option_list(section, generator=\"bash\")\n\n# Print out the commands\nprint(\" \".join(bash_options))\n```\n\ngenerates the output:\n\n```bash\nls -l -t -r --time-style=\"+%Y-%m-%d %H:%M:%S\"\n```\n\n### Example 2\n\nWe can utilize the `use` operation to create a more complex configuration file\nthat provides some sort of common sections and then point-of-use sections that\nwould generate customized configurations for a particular use:\n\n```ini\n[CMAKE_COMMAND]\nopt-set cmake\nopt-set -G : Ninja\n\n[CMAKE_OPTIONS_COMMON]\nopt-set -D CMAKE_CXX_FLAGS : \"-fopenmp\"\n\n[CMAKE_OPTIONS_APPLICATION]\nopt-set -D MYAPP_FLAG1 : \"foo\"\nopt-set -D MYAPP_FLAG2 : \"bar\"\n\n[APPLICATION_PATH_TO_SOURCE]\nopt-set /path/to/source/.\n\n[APPLICATION_CMAKE_PROFILE_01]\nuse CMAKE_COMMAND\nuse CMAKE_OPTIONS_COMMON\nuse CMAKE_OPTIONS_APPLICATION\nuse APPLICATION_PATH_TO_SOURCE\n\n[APPLICATION_CMAKE_PROFILE_02]\nuse APPLICATION_PROFILE_01\nopt-remove MYAPP_FLAG2\n```\n\nThis example follows a pattern that larger projects might wish to use\nwhen there are many configurations that may be getting tested.\nHere, we set up some common option groups and then create aggregation sections\nthat will include the other sections to compose a full command line.\n\nUsing this .ini file, if we generate _bash_ output for section\n`APPLICATION_CMAKE_PROFILE_01` the resulting command generated would be:\n`cmake -G=Ninja -DCMAKE_CXX_FLAGS=\"-fopenmp\" -DMYAPP_FLAG1=\"foo\" -DMYAPP_FLAG2=\"bar\" /path/to/source/.`\n\nAlternatively, we can generate _bash_ output for section\n`APPLICATION_CMAKE_PROFILE_02` which first clones `APPLICATION_CMAKE_PROFILE_01`\nand then _removes_ all entries containing the parameter `MYAPP_FLAG2` using the\n`opt-remove` operation.\nThis will result in a generated comand\n`cmake -G=Ninja -DCMAKE_CXX_FLAGS=\"-fopenmp\" -DMYAPP_FLAG1=\"foo\" /path/to/source/.`.\n\nThis example shows how the `opt-remove` operation will fully\nremove occurrences that contain that substring from the list\nof actions.\n\nThis example shows some of the capabilities that `ActiveConfigProgramOptions`\nprovides for managing many build configurations within a single .ini\nfile.\n\n\n\nActiveConfigProgramOptionsCMake\n===============================\n`ActiveConfigProgramOptionsCMake` is a subclass of `ActiveConfigProgramOptions` that adds additional\noperations and generators to handle processing [CMake][6] options:\n- Adds `opt-set-cmake-var`.\n- Adds `cmake_fragment` generator.\n- Adds `CMAKE` type to variables.\n\nNew operations defined in `ActiveConfigProgramOptionsCMake`:\n\n| Operation | Format | Defined By |\n| ------------------- | ---------------------------------------------------------------- | --------------------------------- |\n| `opt-set-cmake-var` | `opt-set-cmake-var VARNAME [TYPE] [FORCE] [PARENT_SCOPE]: VALUE` | `ActiveConfigProgramOptionsCMake` |\n\n\nSupported Operations\n--------------------\n### `opt-set-cmake-var`\nThis adds a CMake variable program option. These have a special syntax in\n_bash_ that looks like `-DVARNAME:TYPE=VALUE` where the `:TYPE` is an\noptional parameter. If the *type* is left out then CMake assumes the\nvalue is a _STRING_.\n\nWe may not wish to generate bash only output though. For CMake files, we\nmight wish to generate a _cmake fragment_ file which is basically a snippet\nof CMake that can be loaded during a CMake call using the `-S`\noption: `cmake -S cmake_fragment.cmake`.\nThe syntax within a CMake fragment file is the same as in a CMake script\nitself.\n\nIf the back-end generator is creating a CMake fragment file,\nthe _set_ command generated will use [CMake set syntax].\nThis looks something like `set(<variable> <value>)` but can also\ncontain additional options. These extra options can\nbe provided in the `opt-set-cmake-var` operation in the .ini file:\n\n- `FORCE` -\n - By default, a `set()` operation does not overwrite entries in a CMake file.\n This can be added to _force_ the value to be saved.\n - This is only applicable to generating _cmake fragment_ files.\n- `PARENT_SCOPE` - If provided, this option instructs CMake to set the variable\n in the scope that is above the current scope.\n - This is only applicable to generating _cmake fragment_ files.\n- `TYPE` - Specifies the _TYPE_ the variable can be.\n - This is a _positional_ argument and must always come after _VARNAME_.\n - Valid options for this are `STRING` (default), `BOOL`, `PATH`, `INTERNAL`, `FILEPATH`.\n - Adding a _TYPE_ option implies that the _CACHE_ and _docstring_\n parameters will be added to a `set()` command in a CMake fragment\n file according to the syntax: `set(<variable> <value> CACHE <type> <docstring> [FORCE])`\n as illustrated on the [CMake `set()` documentation][1].\n - This is applicable to both _cmake fragment_ and _bash_ generation.\n\n\nActiveConfigProgramOptionsCMake Config Files\n--------------------------------------------\nHere is an example of what a .ini file may look like using the\nCMake operations provided by this class:\n\n```ini\n[SECTION_A]\nopt-set cmake\nopt-set-cmake-var MYVARIABLENAME : VALUE\nopt-set-cmake-var MYVARIABLENAME2 PARENT_SCOPE : VALUE\n```\n\n### Handling CMake Variables\nA _CMake variable_ in this context would be an _internal variable_ that is\nknown to CMake. Because this is not a variable that would be known outside\nof the context of `.cmake` files, this kind of variable is only applicable\nwhen generating CMake fragment files.\n\nIt is necessary to provide a CMake variant for variable expansions because\nthe CMake syntax for variables is different than that used by Bash, and\nCMake fragments have a specialized syntax for *environment* variables as well.\nIn CMake fragment files:\n- environment variables are written as `$ENV{VARNAME}`\n- internal CMake variables are written as: `${VARNAME}`\n\nWe saw variables in `ActiveConfigProgramOptions` follow the syntax: `${VARNAME|ENV}`\nwhere `ENV` specifies the kind of variable we're declaring.\nWe extend this in `ActiveConfigProgramOptionsCMake` by adding a `${VARNAME|CMAKE}`\nvariation which indicates that the variable is expected to be an _internal_\ncmake variable and is more suited towards being used within a CMake fragment\nfile since it has no meaning at the command line.\n\nYou can still use a _CMake_ variable expansion entry when generating _bash_\noutput but there is a catch. The variable *must* be resolvable to something\nthat is **not** a CMake variable through its transitive closure.\nThis is achieved by caching the _last known value_ of a variable as we process\na .ini file and provided that the value ultimately resolves to either a string\nor an environment variable we can still use it.\nIf it cannot be resolved to something that isn't a CMake variable then an\nexception should be generated.\n\nFor example, if we have a .ini file that sets up `CMAKE_CXX_FLAGS` to\ninclude `-O0` in a common section like this:\n\n```ini\n[COMMON]\nopt-set-cmake-var CMAKE_CXX_FLAGS STRING FORCE: \"-O0\"\n```\nand then we have a later section that adds an OpenMP flag to it like this:\n```.ini\n[ADD_OPENMP]\nuse COMMON\nopt-set-cmake-var CMAKE_CXX_FLAGS STRING FORCE: \"${CMAKE_CXX_FLAGS|CMAKE} -fopenmp\"\n```\nThis is valid since `${CMAKE_CXX_FLAGS|CMAKE}` will get replaced with `-O0` so the\nresulting `CMAKE_CXX_FLAGS` variable would be set to `-O0 -fopenmp` after processing.\nIf we generate _bash_ output for the `ADD_OPENMP` section we'll get\na `-D` option that looks like `-DCMAKE_CXX_FLAGS:STRING=\"-O0 -fopenmp\"`.\n\nBut what if we have a .ini file with a CMake variable that can't be resolved to\nsomething that is not a CMake flag, such as:\n```ini\n[COMMON]\nopt-set-cmake-var FOO : ${SOME_CMAKE_VAR|CMAKE}\n```\nIf we tried to process this and write out the resulting script\nusing the _bash_ generator an exception should be raised citing\nthat we don't know what to do with that unresolved CMake variable.\nThis would be the equivalent to a bash option `-DFOO=<SOME_CMAKE_VAR>`\nand bash can't handle that because it has no idea what it should put\nin that cmake var field.\n\nNote: if the same CMake option is provided in multiple lines they will\nall be included in the generated output. In that case, the behaviour will\nmatch what will occur if one called cmake directly with the same option\nmultiple times.\nIn that case, the _last one wins_ since all `-D` options are treated as\nthough they both have `FORCE` and `CACHE` flags set.\n\n\n\nActiveConfigProgramOptionsCMake Examples\n----------------------------------------\n\n### Example\n\nThis example shows a configuration file that can be used to generate\nbuild files using Ninja or Makefile. In the .ini file we set up some\ncommon sections that contain the arguments and then the point-of-use\nsections ( `MYPROJ_CONFIGURATION_NINJA` and `MYPROJ_CONFIGURATION_MAKEFILES` )\ncan compose their command lines by importing the argument definition sections\nvia `use`.\n\n#### [ActiveConfigProgramOptions-example-02.ini][17]\n```ini\n#\n# ActiveConfigProgramOptions-example-02.ini\n#\n[CMAKE_COMMAND]\nopt-set cmake\n\n[CMAKE_GENERATOR_NINJA]\nopt-set -G : Ninja\n\n[CMAKE_GENERATOR_MAKEFILES]\nopt-set -G : \"Unix Makefiles\"\n\n[MYPROJ_OPTIONS]\nopt-set-cmake-var MYPROJ_CXX_FLAGS STRING : \"-O0 -fopenmp\"\nopt-set-cmake-var MYPROJ_ENABLE_OPTION_A BOOL FORCE : ON\nopt-set-cmake-var MYPROJ_ENABLE_OPTION_B BOOL : ON\n\n[MYPROJ_SOURCE_DIR]\nopt-set /path/to/source/dir\n\n[MYPROJ_CONFIGURATION_NINJA]\nuse CMAKE_COMMAND\nuse CMAKE_GENERATOR_NINJA\nuse MYPROJ_OPTIONS\nuse MYPROJ_SOURCE_DIR\n\n[MYPROJ_CONFIGURATION_MAKEFILES]\nuse CMAKE_COMMAND\nuse CMAKE_GENERATOR_MAKEFILES\nuse MYPROJ_OPTIONS\nuse MYPROJ_SOURCE_DIR\n```\n\n#### [ActiveConfigProgramOptions-example-02.py][18]\nThis python code shows generating a bash script and a CMake fragment\nof the configuration specified in the .ini file.\n\n```python\n#!/usr/bin/env python3\n# -*- mode: python; py-indent-offset: 4; py-continuation-offset: 4 -*-\nfrom pathlib import Path\nimport activeconfigprogramoptions\n\nprint(80*\"-\")\nprint(f\"- {Path(__file__).name}\")\nprint(80*\"-\")\n\nfilename = \"ActiveConfigProgramOptions-example-02.ini\"\npopts = activeconfigprogramoptions.ActiveConfigProgramOptionsCMake(filename)\n\nsection = \"MYPROJ_CONFIGURATION_NINJA\"\npopts.parse_section(section)\n\n# Generate BASH output\nprint(\"\")\nprint(\"Bash output\")\nprint(\"-----------\")\nbash_options = popts.gen_option_list(section, generator=\"bash\")\nprint(\" \\\\\\n \".join(bash_options))\n\n# Generate a CMake Fragment\nprint(\"\")\nprint(\"CMake fragment output\")\nprint(\"---------------------\")\ncmake_options = popts.gen_option_list(section, generator=\"cmake_fragment\")\nprint(\"\\n\".join(cmake_options))\n\nprint(\"\\nDone\")\n```\n\n#### Output\nUsing the *Ninja* specialization from the above code, we generate the following\noutput:\n```bash\n$ python3 ActiveConfigProgramOptions-example-02.py\n--------------------------------------------------------------------------------\n- ActiveConfigProgramOptions-example-02.py\n--------------------------------------------------------------------------------\n\n**Bash output**\ncmake \\\n -G=Ninja \\\n -DMYPROJ_CXX_FLAGS:STRING=\"-O0 -fopenmp\" \\\n -DMYPROJ_ENABLE_OPTION_A:BOOL=ON \\\n -DMYPROJ_ENABLE_OPTION_B:BOOL=ON \\\n /path/to/source/dir\n\nCMake fragment output\n---------------------\nset(MYPROJ_CXX_FLAGS \"-O0 -fopenmp\" CACHE STRING \"from .ini configuration\")\nset(MYPROJ_ENABLE_OPTION_A ON CACHE BOOL \"from .ini configuration\" FORCE)\nset(MYPROJ_ENABLE_OPTION_B ON CACHE BOOL \"from .ini configuration\")\n\nDone\n```\n\n[1]: https://cmake.org/cmake/help/latest/command/set.html\n[2]: https://gitlab.com/semantik-software/code/python/ActiveConfigParser\n[3]: https://gitlab.com/semantik-software/code/python/ActiveConfigParser/-/blob/main/CHANGELOG.md\n[4]: https://semantik-software.gitlab.io/code/python/ActiveConfigProgramOptions/\n[5]: https://pypi.org/project/activeconfigparser/\n[6]: https://www.cmake.org/\n[7]: https://semantik-software.gitlab.io/code/python/ActiveConfigParser/\n[8]: https://gitlab.com/semantik-software/code/python/ActiveConfigProgramOptions/-/blob/main/examples/ActiveConfigProgramOptions-example-01.ini\n[9]: https://gitlab.com/semantik-software/code/python/ActiveConfigProgramOptions/-/blob/main/examples/ActiveConfigProgramOptions-example-01.py\n[10]: https://pypi.org/project/activeconfigparser/\n[11]: https://semantik-software.gitlab.io/code/python/ExceptionControl/\n[12]: https://gitlab.com/semantik-software/code/python/ExceptionControl\n[13]: https://pypi.org/project/exceptioncontrol/\n[14]: https://semantik-software.gitlab.io/code/python/StronglyTypedProperty/\n[15]: https://gitlab.com/semantik-software/code/python/StronglyTypedProperty\n[16]: https://pypi.org/project/stronglytypedproperty/\n[17]: https://gitlab.com/semantik-software/code/python/ActiveConfigProgramOptions/-/blob/main/examples/ActiveConfigProgramOptions-example-02.ini\n[18]: https://gitlab.com/semantik-software/code/python/ActiveConfigProgramOptions/-/blob/main/examples/ActiveConfigProgramOptions-example-02.py\n\n\n\n",
"bugtrack_url": null,
"license": "LICENSE",
"summary": "Program options configuration file reader using ActiveConfigParser.",
"version": "0.6.0.0",
"project_urls": {
"Documentation": "https://semantik-software.gitlab.io/code/python/ActiveConfigProgramOptions",
"Homepage": "https://gitlab.com/semantik-software/code/python/ActiveConfigProgramOptions",
"Repository": "https://gitlab.com/semantik-software/code/python/ActiveConfigProgramOptions"
},
"split_keywords": [
"utility",
"bash",
"configuration",
"activeconfigparser",
"configparser"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "97abe89fe9aba23f4c6ca113c781bfbe446044c45c53c7e64b72f0b3584f7557",
"md5": "b621e1309ad2065bfe1a1b093db3cc02",
"sha256": "01ca1e51efb1d9ca8bedf2feda5784ba46c64e404f21c8f9fb254ae4ad77abdd"
},
"downloads": -1,
"filename": "activeconfigprogramoptions-0.6.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b621e1309ad2065bfe1a1b093db3cc02",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 47315,
"upload_time": "2023-07-07T02:12:04",
"upload_time_iso_8601": "2023-07-07T02:12:04.376825Z",
"url": "https://files.pythonhosted.org/packages/97/ab/e89fe9aba23f4c6ca113c781bfbe446044c45c53c7e64b72f0b3584f7557/activeconfigprogramoptions-0.6.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a88a8806162f90495280f18218e4635a271a4dd754b58b8a44cba28e23b9936e",
"md5": "a158bc584a0ef7dc3e317e10583f63ae",
"sha256": "132f31b8cc58602f87871a2eb0d16f84664f2c5a4a65e1e3f4a12c609b528fcf"
},
"downloads": -1,
"filename": "activeconfigprogramoptions-0.6.0.0.tar.gz",
"has_sig": false,
"md5_digest": "a158bc584a0ef7dc3e317e10583f63ae",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 40059,
"upload_time": "2023-07-07T02:12:06",
"upload_time_iso_8601": "2023-07-07T02:12:06.943089Z",
"url": "https://files.pythonhosted.org/packages/a8/8a/8806162f90495280f18218e4635a271a4dd754b58b8a44cba28e23b9936e/activeconfigprogramoptions-0.6.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-07 02:12:06",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "semantik-software",
"gitlab_project": "code",
"lcname": "activeconfigprogramoptions"
}
JSON