Examples

This page contains the raw code + output of our examples. For detailed explanations of what is going on please see the Quick Start guide.

Example 1

See Example 01 in the QuickStart guide for a detailed explanation of this example.

Input File Listing: Example 1

 1#
 2# ActiveConfigProgramOptions-example-01.ini
 3#
 4[LS_COMMAND]
 5opt-set ls
 6
 7[LS_LIST_TIME_REVERSED]
 8opt-set "-l -t -r"
 9
10[LS_CUSTOM_TIME_STYLE]
11opt-set --time-style : "+%%Y-%%m-%%d %%H:%%M:%%S"
12
13[MY_LS_COMMAND]
14use LS_COMMAND
15use LS_LIST_TIME_REVERSED
16use LS_CUSTOM_TIME_STYLE

Code Listing: Example 1

 1#!/usr/bin/env python3
 2# -*- mode: python; py-indent-offset: 4; py-continuation-offset: 4 -*-
 3from pathlib import Path
 4import activeconfigprogramoptions
 5
 6# print a banner
 7print(80 * "-")
 8print(f"- {Path(__file__).name}")
 9print(80 * "-")
10
11filename = "ActiveConfigProgramOptions-example-01.ini"
12
13# create a ActiveConfigProgramOptions object using the .ini file
14popts = activeconfigprogramoptions.ActiveConfigProgramOptions(filename)
15
16# Parse a section that generates a LS command
17section = "MY_LS_COMMAND"
18popts.parse_section(section)
19
20# Extract a list containing the options
21bash_options = popts.gen_option_list(section, generator="bash")
22
23# Print the option list
24print(" ".join(bash_options))

Output: Example 1

Program execution output:

1--------------------------------------------------------------------------------
2- ActiveConfigProgramOptions-example-01.py
3--------------------------------------------------------------------------------
4ls -l -t -r --time-style="+%Y-%m-%d %H:%M:%S"

Example 2

Input File Listing: Example 2

 1#
 2# ActiveConfigProgramOptions-example-02.ini
 3#
 4[CMAKE_COMMAND]
 5opt-set cmake
 6
 7[CMAKE_GENERATOR_NINJA]
 8opt-set -G : Ninja
 9
10[MYPROJ_OPTIONS]
11opt-set-cmake-var  MYPROJ_CXX_FLAGS       STRING       : "-O0 -fopenmp"
12opt-set-cmake-var  MYPROJ_ENABLE_OPTION_A BOOL   FORCE : ON
13opt-set-cmake-var  MYPROJ_ENABLE_OPTION_B BOOL         : ON
14
15[MYPROJ_SOURCE_DIR]
16opt-set /path/to/source/dir
17
18[MYPROJ_CONFIGURATION_NINJA]
19use CMAKE_COMMAND
20use CMAKE_GENERATOR_NINJA
21use MYPROJ_OPTIONS
22use MYPROJ_SOURCE_DIR

Code Listing: Example 2

 1#!/usr/bin/env python3
 2# -*- mode: python; py-indent-offset: 4; py-continuation-offset: 4 -*-
 3from pathlib import Path
 4import activeconfigprogramoptions
 5
 6
 7
 8def print_separator(label):
 9    print("")
10    print(f"{label}")
11    print("-" * len(label))
12    return
13
14
15
16print(80 * "-")
17print(f"- {Path(__file__).name}")
18print(80 * "-")
19
20filename = "ActiveConfigProgramOptions-example-02.ini"
21popts = activeconfigprogramoptions.ActiveConfigProgramOptionsCMake(filename)
22
23section = "MYPROJ_CONFIGURATION_NINJA"
24popts.parse_section(section)
25
26# Generate BASH output
27print_separator("Generate Bash Output")
28bash_options = popts.gen_option_list(section, generator="bash")
29print(" \\\n   ".join(bash_options))
30
31# Generate a CMake Fragment
32print_separator("Generate CMake Fragment")
33cmake_options = popts.gen_option_list(section, generator="cmake_fragment")
34print("\n".join(cmake_options))
35
36print("\nDone")

Output: Example 2

Program execution output:

 1--------------------------------------------------------------------------------
 2- ActiveConfigProgramOptions-example-02.py
 3--------------------------------------------------------------------------------
 4
 5Generate Bash Output
 6--------------------
 7cmake \
 8   -G=Ninja \
 9   -DMYPROJ_CXX_FLAGS:STRING="-O0 -fopenmp" \
10   -DMYPROJ_ENABLE_OPTION_A:BOOL=ON \
11   -DMYPROJ_ENABLE_OPTION_B:BOOL=ON \
12   /path/to/source/dir
13
14Generate CMake Fragment
15-----------------------
16set(MYPROJ_CXX_FLAGS "-O0 -fopenmp" CACHE STRING "from .ini configuration")
17set(MYPROJ_ENABLE_OPTION_A ON CACHE BOOL "from .ini configuration" FORCE)
18set(MYPROJ_ENABLE_OPTION_B ON CACHE BOOL "from .ini configuration")
19
20Done

Example 3

Input File Listing: Example 3

 1#
 2# ActiveConfigProgramOptions-example-03.ini
 3#
 4[TEST_VAR_EXPANSION_COMMON]
 5opt-set-cmake-var CMAKE_CXX_FLAGS STRING : "${LDFLAGS|ENV} -foo"
 6# note: STRING type implies this is a CACHE var.
 7
 8
 9[TEST_VAR_EXPANSION_UPDATE_01]
10opt-set cmake
11use TEST_VAR_EXPANSION_COMMON
12
13opt-set-cmake-var CMAKE_CXX_FLAGS STRING: "${CMAKE_CXX_FLAGS|CMAKE} -bar"
14# This will be skipped by the BASH generator without a FORCE option added
15# because .cmake files treate CACHE vars as immutable and won't overwrite
16# the value unless forced, but all bash `-D` options are CACHE and FORCE
17# so without FORCE the only way we can ensure the bash and cmake_fragment
18# generators create a result that generates the same CMakeCache.txt file
19# upon generation is to remove this option from the bash generated result.

Code Listing: Example 3

 1#!/usr/bin/env python3
 2# -*- mode: python; py-indent-offset: 4; py-continuation-offset: 4 -*-
 3from pathlib import Path
 4from pprint import pprint
 5import activeconfigprogramoptions
 6
 7
 8
 9def print_separator(label):
10    print("")
11    print(f"{label}")
12    print("-" * len(label))
13    return
14
15
16
17filename = "ActiveConfigProgramOptions-example-03.ini"
18print(f"filename: {filename}")
19
20section_name = "TEST_VAR_EXPANSION_UPDATE_01"
21print(f"section_name = {section_name}")
22
23parser = activeconfigprogramoptions.ActiveConfigProgramOptionsCMake(filename=filename)
24parser.debug_level = 0
25parser.exception_control_level = 4
26parser.exception_control_compact_warnings = True
27
28data = parser.activeconfigparserdata[section_name]
29print_separator(f"parser.activeconfigparserdata[{section_name}]")
30pprint(data, width=120)
31
32print_separator("Show parser.options")
33pprint(parser.options, width=200, sort_dicts=False)
34
35print_separator("Bash Output")
36print("Note: The _second_ assignment to `CMAKE_CXX_FLAGS` is skipped by a BASH generator")
37print("      without a `FORCE` option since by definition all CMake `-D` options on a ")
38print("      BASH command line are both CACHE and FORCE. Within a CMake source fragment")
39print("      changing an existing CACHE var requires a FORCE option to be set so we should")
40print("      skip the second assignment to maintain consistency between the bash and cmake")
41print("      fragment generators with respect to the CMakeCache.txt file that would be")
42print("      generated.")
43print("      The `WARNING` message below is terse since it's in compact form -- disable")
44print("      the `exception_control_compact_warnings` flag to get the full warning message.")
45print("")
46option_list = parser.gen_option_list(section_name, generator="bash")
47print("")
48print(" \\\n    ".join(option_list))
49
50print_separator("CMake Fragment")
51option_list = parser.gen_option_list(section_name, generator="cmake_fragment")
52if len(option_list) > 0:
53    print("\n".join(option_list))
54else:
55    print("-")
56print("")

Output: Example 3

Program execution output:

 1filename: ActiveConfigProgramOptions-example-03.ini
 2section_name = TEST_VAR_EXPANSION_UPDATE_01
 3
 4parser.activeconfigparserdata[TEST_VAR_EXPANSION_UPDATE_01]
 5-----------------------------------------------------------
 6{}
 7
 8Show parser.options
 9-------------------
10{'TEST_VAR_EXPANSION_UPDATE_01': [{'type': ['opt_set'], 'value': None, 'params': ['cmake']},
11                                  {'type': ['opt_set_cmake_var'], 'value': '${LDFLAGS|ENV} -foo', 'params': ['CMAKE_CXX_FLAGS', 'STRING']},
12                                  {'type': ['opt_set_cmake_var'], 'value': '${CMAKE_CXX_FLAGS|CMAKE} -bar', 'params': ['CMAKE_CXX_FLAGS', 'STRING']}]}
13
14Bash Output
15-----------
16Note: The _second_ assignment to `CMAKE_CXX_FLAGS` is skipped by a BASH generator
17      without a `FORCE` option since by definition all CMake `-D` options on a 
18      BASH command line are both CACHE and FORCE. Within a CMake source fragment
19      changing an existing CACHE var requires a FORCE option to be set so we should
20      skip the second assignment to maintain consistency between the bash and cmake
21      fragment generators with respect to the CMakeCache.txt file that would be
22      generated.
23      The `WARNING` message below is terse since it's in compact form -- disable
24      the `exception_control_compact_warnings` flag to get the full warning message.
25
26!! EXCEPTION SKIPPED (WARNING : ValueError) @ File "/builds/semantik-software/code/python/ActiveConfigProgramOptions/venv-examples/lib/python3.14/site-packages/activeconfigprogramoptions/ActiveConfigProgramOptionsCMake.py", line 306, in _program_option_handler_opt_set_cmake_var_bash
27
28cmake \
29    -DCMAKE_CXX_FLAGS:STRING="${LDFLAGS} -foo"
30
31CMake Fragment
32--------------
33set(CMAKE_CXX_FLAGS "$ENV{LDFLAGS} -foo" CACHE STRING "from .ini configuration")
34set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -bar" CACHE STRING "from .ini configuration")
35