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