Feat/filter control blocks #20

ElijahSwiftIBM · 2025-12-31T17:39:13Z

💡 Issue Reference

Issue: #5

💻 What does this address?

Control block filtering is a valuable enhancement. In basic cases it allows for simple validation that a control block containing the right data is collected, but in more complex cases, it allows users to grab information on just a singular relevant control block or collection of them in a large table.

📟 Implementation Details

The core control block class now has a new unordered map for filtration that is built on object creation. The filter is passed from block to block along with inclusion patterns and validated along the way. At the "end" of the line, the control block's value is validated against that of the filter. In the event of a match, the json data is returned, otherwise an empty json comes back. Large lists of control blocks like ASCB's and ASSB's were edited to filter out these null values, allowing for a true filter.

📋 Is there a test case?

I added the following tests in both the python and the shell test suites (the names in python are fare more descriptive)

test_cbxp_raises_cbxp_error_if_filter_uses_non_included_control_block
test_cbxp_raises_cbxp_error_if_filter_uses_unknown_key
test_cbxp_raises_cbxp_error_if_filter_dict_wrong_size (python only)
test_cbxp_raises_cbxp_error_if_filter_value_not_string (python only)
test_cbxp_raises_cbxp_error_if_no_filter_match
test_cbxp_can_use_basic_filter
test_cbxp_can_use_include_filter_with_generic_include
test_cbxp_can_use_include_filter_with_discrete_include

* Feature/includeparameter (#14) * Add skeleton for inclusion list parameter Extend interface/skeleton for include_list * Input POinter Attempt to add input pointer parameter for control blocks * Definitions outside of if statements * Attempt to map the intended inclusion list * Try Virtual Function to keep Control Block in Explorer * No longer have get return * Attempt to add the meat of the function -Add methods and members to control blocks to get name of control block, specific control blocks within it, and all control blocks within it -add functions in control block explorer to parse inclusion "map" into actionable data name fix * Update psa.cpp Update psa.cpp * Update cvt.cpp * Update asvt.cpp * algorithm cleanup * better cleanup * Update control_block.cpp * Update main.cpp * Finish addressing merge issues and commit hooks -Minor code updates that were lost in merge commit -Bring new code up to standard for cppcheck -Format new code with clang-format * Update _cbxp.c * Streamline Control Block Explorer Class Update control_block_explorer.hpp * Massive refactor -Shave 2 step process down to one -Change serialized json inclusion map to use a vector of strings still split by "dot" operators * Error Handling Logic * BIG UPDATE PR COMMENTS -Switch pre-processing to one hash map function -use try/catch with custom errors rather than passing return codes everywhere -style and name changes -Enforce more rigid parm structure on entry -Fix some behavioral bugs and oversights in inclusion preprocessing -General streamlining and refactoring of functions, methods, classes, etc. * Another Big Refactor -PR comments (mostly style, but streamlining of error code as well) -Reworked base and derived classes to allow for includables to be defined to the base class and include_map to be defined to the base and derived classes * Update ascb.cpp * Update control_block.hpp * . * .. * ... * PR Comments -ASCB pointer deref in ASVT -Minor name changes -Remove double wildcard error -Add control_block_name_ private member and add initialization to constructor -move include_map_ to protected and remove private using statement * Update asvt.cpp * Update asvt.cpp * PR Comments Mostly renaming things streamlining some unnecessary text, parms and strings * Update control_block.cpp * Update main.cpp * Last round of PR comments string compare with == remove vestiges of old mechanisms for control block management name changes minor tweaks * Update cvt.cpp * Update cvt.cpp * Update cvt.cpp * Final comments Update control_block_explorer.cpp * comments * Last Comments * include changes * Last round of comments * debug * Unit testing (#17) * initial commit 1 * cleaned code before include test cases * wrote test cases, need to check with team now * added space after every function * added .value * shell script done * made changes proposed by leonard 1 * PR changes requested by team * added tests to check for ascb and asvt entries whether it be a string or dict * added tests to check for ascb and asvt entries whether it be a string or dict one more place * made minor tweaks * added updates provided by leonard * grouped failure test cases together * grouped error test cases together * removed extra lines * style changes * Feat/oss housekeeping2 (#18) * Set explicit C/C++ standard and cleanup README. Signed-off-by: Leonard Carcaramo <lcarcaramo@ibm.com> * Update contribution guidelines and functional tests. Signed-off-by: Leonard Carcaramo <lcarcaramo@ibm.com> * Cleanup contribution guidelines and debug debug mode. Signed-off-by: Leonard Carcaramo <lcarcaramo@ibm.com> * Cleanup. Signed-off-by: Leonard Carcaramo <lcarcaramo@ibm.com> * Cleanup. Signed-off-by: Leonard Carcaramo <lcarcaramo@ibm.com> * Fix sdist packaging and pyproject.toml metadata. Signed-off-by: Leonard Carcaramo <lcarcaramo@ibm.com> --------- Signed-off-by: Leonard Carcaramo <lcarcaramo@ibm.com> * Fix _C.pyi and removed unused import from cbxp.py. Signed-off-by: Leonard Carcaramo <lcarcaramo@ibm.com> --------- Signed-off-by: Leonard Carcaramo <lcarcaramo@ibm.com> Co-authored-by: Elijah Swift <Elijah.Swift@ibm.com> Co-authored-by: Varun Chennamadhava <varunchennamadhava@ibm.com>

lcarcaramo · 2026-01-02T13:09:40Z

DCO signoff seems to be missing on all commits. Maybe consider squashing all of these commits into one commit that has a DCO signoff?

cbxp/main.cpp

cbxp/control_block_explorer.cpp

cbxp/control_blocks/control_block.cpp

lcarcaramo · 2026-01-02T15:16:09Z

cbxp/control_blocks/control_block.hpp

  void processAsteriskInclude();
  void processExplicitInclude(std::string& include);

 protected:


We should restrict filters to only "repeated" control blocks. Maybe we can have a boolean class attribute to keep track of this?

const bool repeated_;

Should we? What if we have a script design to regularly run and throw flags if a certain value is found in a singular control block like the PSA? I see a much STRONGER benefit to using them in repeated control blocks, but I'm not convinced that they should be DISALLOWED from others.

I think the use case for singleton control blocks is completely separate from the concept of filtering, which is meant to filter items in an array or list of items. If somebody wants to check the value of something in a singleton control block they can just do a comparison.

if psa["psapsa"] == "PSA ": // do something

The point of filtering is saving the user from having to manually construct their own logic for looping through and filtering repeated control block data rather than checking if a value in a single control block meets some condition.

I think that's a fair and well-reasoned argument, and I agree that the use cases may be different, and that there is not a strong need to prevent a user from having to construct their own logic to check values in singleton control blocks.

To me, though, it makes little sense to restrict the feature when it does also have a valid use-case. Like yes, it is TRIVIAL to implement the kinds of checks filtering does for a singleton block, but is that a reason to restrict the feature artificially, when it can perform the task at hand? Especially now that we have more robust checking beyond strings, you could check for count thresholds and other things. You could also use a compound set of filtering rules that evaluate singleton control blocks AND lists of them. I don't know that I can articulate a clean use-case for this, but I do think that they exist.

It would make sense to me to restrict it if the resulting behavior was different, unpredictable, or in some way unexpected. I don't see that as the case here.

In thinking about this more, I think that the command line version of this tool is an excellent demonstration of this use-case. If I want to add logical parsing to the command line output based on specific json values, I have to pipe this through other utilities to get where I want, whereas the filter option of a singleton can give me immediate feedback without invoking other tools.

I still don't think I would consider this filtering and you can just extract a particular value in the control block to see what it is using jq.

./dist/cbxp psa | jq '.psapsa'

cbxp/control_blocks/control_block.cpp

cbxp/main.cpp

tests/test.py

cbxp/control_blocks/ascb.cpp

Signed-off-by: Elijah Swift <Elijah.Swift@IBM.com>

tests/test.sh

cbxp/cbxp.cpp

cbxp/control_block_explorer.cpp

cbxp/control_blocks/control_block.cpp

tests/test.py

cbxp/control_blocks/assb.cpp

cbxp/control_blocks/control_block.hpp

Signed-off-by: Elijah Swift <Elijah.Swift@IBM.com>

lcarcaramo · 2026-01-16T20:24:35Z

cbxp/control_blocks/control_block.cpp

+void ControlBlock::createOptionsMap(const std::vector<std::string>& includes,
+                                    const std::vector<std::string>& filters) {
+  createIncludeMap(includes);
+  createFilterMap(filters);


Prefix these with ControlBlock::.

lcarcaramo · 2026-01-16T20:31:16Z

cbxp/control_blocks/control_block.cpp

+    return true;
+  }
+  for (const auto& [filter_key, filter_values] : current_filters_) {
+    if (control_block_json.contains(filter_key)) {


Use guard statement here instead to reduce nesting?

Rename filter_values to filter_list?

lcarcaramo · 2026-01-16T20:41:07Z

python/cbxp/cbxp.py

 def cbxp(
    control_block: str,
    includes: list[str] = None,
+    control_block_filters: list[str] = None,


Change control_block_filters to filters.

lcarcaramo · 2026-01-16T20:46:29Z

cbxp/cbxp.cpp

-                          const char* includes_string, bool debug) {
+cbxp_result_t* cbxp(const char* control_block_name, const char* includes_string,
+                    const char* filters_string, bool debug) {
  nlohmann::json control_block_json;


Sort of unrelated to this PR, but should we move the mutex from the Python extension code to here since we are now have a library libcbxp.so that can be used to call CBXP from a C/C++ caller.

I would also suggest changing control_block_name to control_block to make it consistent with the other interfaces.

lcarcaramo · 2026-01-16T20:48:43Z

cbxp/control_blocks/control_block.cpp

+      filter_value = filter.substr(del_pos + del.length());
+      filter_key   = filter.substr(0, del_pos);
+      if (filter_value == "") {
+        Logger::getInstance().debug("cannot specify null filter value");


"Filter patterns cannot be null"

lcarcaramo · 2026-01-16T20:50:25Z

cbxp/control_blocks/control_block.cpp

+        return (fnmatch(filter_value.c_str(), value_str.c_str(), 0) == 0);
+      } else {
+        Logger::getInstance().debug(
+            "Cannot use <,<=,> or >= with string filter");


<, <=, >, and >= cannot be used with string filter patterns

lcarcaramo · 2026-01-16T20:53:13Z

cbxp/control_blocks/control_block.cpp

+    }
+  } catch (...) {
+    Logger::getInstance().debug(
+        "Error with type conversions for filter evaluation");


"Type conversion failed for control block value '" + <control-block-value> + "'"

lcarcaramo · 2026-01-16T20:56:09Z

cbxp/control_blocks/control_block.cpp

+      }
+    } else {
+      Logger::getInstance().debug(
+          "Specified filter key not found in control block json");


"The filter key '" + filter_key + "' does correspond to any control block field in the '" + control_block_name_ "' control block"

lcarcaramo · 2026-01-16T21:01:47Z

cbxp/control_block_error.hpp


 namespace CBXP {
-enum Error { BadControlBlock = 1, BadInclude };
+enum Error { BadControlBlock = 1, BadInclude, BadFilter };


We may want to consider assigning explicit numbers to these since we now provide a Library interface to C/C++ callers, where the user gets back these return codes and may need to interpret them.

lcarcaramo · 2026-01-16T21:08:18Z

cbxp/control_blocks/control_block.cpp

+  }
+}
+
+bool ControlBlock::compare(const nlohmann::json& json_value,


Check the integer comparison logic. The logic seems to be buggy and is not working correctly for me.

lcarcaramo · 2026-01-16T21:19:14Z

tests/test.py

+        cbdata = cbxp("psa", control_block_filters=["psapsa=PSA"])
+        self.assertIs(type(cbdata), dict)
+
+    def test_cbxp_can_use_include_filter_with_wildcard_include(self):


Some of these contain include_filter, but probably should be changed to just filter.

lcarcaramo · 2026-01-16T21:28:18Z

Somewhat unrelated, but I think we should remove the trailing spaces from extracted string fields in control blocks. Now that we are extracting more string fields, I am now noticing this more:

"assbjbns": "BPXAS   ",

lcarcaramo and others added 2 commits November 6, 2025 07:34

Merge branch 'dev' into feat/filter-control-blocks

17990b6

ElijahSwiftIBM requested review from lcarcaramo and varunchennamadhava December 31, 2025 17:39

lcarcaramo reviewed Jan 2, 2026

View reviewed changes

cbxp/main.cpp Show resolved Hide resolved

lcarcaramo reviewed Jan 2, 2026

View reviewed changes

cbxp/main.cpp Show resolved Hide resolved

lcarcaramo reviewed Jan 2, 2026

View reviewed changes

cbxp/control_block_explorer.cpp Outdated Show resolved Hide resolved

lcarcaramo reviewed Jan 2, 2026

View reviewed changes

cbxp/control_blocks/control_block.cpp Outdated Show resolved Hide resolved

lcarcaramo reviewed Jan 2, 2026

View reviewed changes

cbxp/control_blocks/control_block.cpp Outdated Show resolved Hide resolved

lcarcaramo reviewed Jan 2, 2026

View reviewed changes

cbxp/main.cpp Outdated Show resolved Hide resolved

lcarcaramo reviewed Jan 2, 2026

View reviewed changes

tests/test.py Outdated Show resolved Hide resolved

lcarcaramo reviewed Jan 2, 2026

View reviewed changes

tests/test.py Outdated Show resolved Hide resolved

lcarcaramo reviewed Jan 2, 2026

View reviewed changes

tests/test.py Outdated Show resolved Hide resolved

lcarcaramo reviewed Jan 2, 2026

View reviewed changes

cbxp/control_blocks/ascb.cpp Outdated Show resolved Hide resolved

Squashed Commit

954478d

Signed-off-by: Elijah Swift <Elijah.Swift@IBM.com>

ElijahSwiftIBM force-pushed the feat/filter-control-blocks branch from 0d354a7 to 954478d Compare January 6, 2026 20:46

ElijahSwiftIBM added 3 commits January 7, 2026 14:22

change to ensure filter check fails empty lists

1d91795

Signed-off-by: Elijah Swift <Elijah.Swift@IBM.com>

More robust unit testing

1388e38

Signed-off-by: Elijah Swift <Elijah.Swift@IBM.com>

trailing commas in python

a6b42c9

Signed-off-by: Elijah Swift <Elijah.Swift@IBM.com>