{"id":8978,"library":"esp-bool-parser","title":"ESP-BOOL-PARSER","description":"esp-bool-parser is a lightweight Python package (version 0.2.3) by Espressif, designed for parsing boolean expressions primarily within the context of ESP-IDF applications. It supports diverse operand types, including SOC capabilities, environment variables, strings, booleans, and integers, and helps process statements based on `soc_caps` files. It is actively maintained by Espressif.","status":"active","version":"0.2.3","language":"en","source_language":"en","source_url":"https://github.com/espressif/esp-bool-parser","tags":["esp-idf","boolean-parsing","embedded","espressif","parsing"],"install":[{"cmd":"pip install esp-bool-parser","lang":"bash","label":"Install with pip"}],"dependencies":[],"imports":[{"symbol":"parse_bool_expr","correct":"from esp_bool_parser import parse_bool_expr"},{"symbol":"register_addition_attribute","correct":"from esp_bool_parser import register_addition_attribute"}],"quickstart":{"code":"import esp_bool_parser\n\n# Example 1: Parsing a simple boolean expression\nstmt_string = 'IDF_TARGET == \"esp32\" and CONFIG_FOO'\nstmt = esp_bool_parser.parse_bool_expr(stmt_string)\n\n# You would typically have a ChipAttr-like object or context to evaluate this.\n# For demonstration, let's mock a simple evaluation.\n# In a real ESP-IDF context, 'target' and 'config_name' would come from build system.\n# For example, checking against 'esp32' target and a configuration where CONFIG_FOO is True\n\n# A simple mock evaluation function (not part of the library, for example purposes)\ndef evaluate_mock(parsed_expression, target, config_values):\n    # This is a highly simplified representation.\n    # The actual library's .get_value() interacts with an internal ChipAttr instance.\n    # For this example, we assume parsed_expression has an internal representation\n    # that can be evaluated with provided context.\n    try:\n        # The actual get_value method is more complex and handles SOC_CAPS, ENV_VARs, etc.\n        # This line is illustrative, assuming it resolves based on target and config_values\n        # In a real scenario, ChipAttr would handle the context.\n        result = parsed_expression.get_value(target, config_values.get('config_name', ''))\n        return result\n    except Exception as e:\n        print(f\"Error during evaluation: {e}\")\n        return None\n\n# Example usage of evaluation (simplified)\nmock_config = {'config_name': 'default', 'CONFIG_FOO': True}\n# Note: Direct call to stmt.get_value requires proper ChipAttr context setup internally.\n# The example from docs is `result = stmt.get_value(\"esp32\", \"config_name\")`\n# which implies `\"config_name\"` is a string identifier for a configuration context.\n# For a true runnable quickstart, it's difficult to fully simulate `ChipAttr`'s internal state\n# without more knowledge or a simpler public API for evaluation. \n# The primary use is *parsing* the expression. Evaluation depends on the runtime context.\n# Let's show the parsing and the registration of an attribute.\n\nprint(f\"Successfully parsed expression: '{stmt_string}'\")\n\n# Example 2: Registering an additional attribute\nimport typing as t\n\ndef my_custom_action(target: str, config_name: str, **kwargs: t.Any) -> str:\n    print(f\"Custom attribute 'MY_ATTR' called for target: {target}, config: {config_name}\")\n    return f\"Processed_{target}_{config_name}\"\n\nesp_bool_parser.register_addition_attribute(\"MY_ATTR\", my_custom_action)\n\n# Now, expressions can use MY_ATTR (e.g., 'MY_ATTR == \"Processed_esp32_config\"')","lang":"python","description":"This quickstart demonstrates how to parse a boolean expression string using `parse_bool_expr` and how to register a custom attribute handler with `register_addition_attribute`. Note that the evaluation of the parsed expression (`stmt.get_value()`) heavily relies on an internal `ChipAttr` context, which is typically set up within an ESP-IDF build environment. The provided `evaluate_mock` function is a placeholder for illustrating the concept of evaluation and is not part of the library itself."},"warnings":[{"fix":"Ensure you understand the context `esp-bool-parser` operates in. If using outside ESP-IDF, be prepared to provide or mock the necessary `target` and `config_name` parameters, and understand how `get_value` resolves different operand types.","message":"The primary purpose of esp-bool-parser is to handle boolean expressions specific to ESP-IDF's SOC capabilities, configuration flags (like `CONFIG_FOO`), and environment variables. While it parses general boolean logic, its `get_value` evaluation method relies on an underlying `ChipAttr` context that is typically available or mocked within an ESP-IDF build system. Using it for entirely generic boolean parsing outside this ecosystem might require custom context setup.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"When using `register_addition_attribute`, verify that the custom action function adheres to the expected signature (`target`, `config_name`, `**kwargs`) and that you intend to replace any existing functionality of the attribute name being registered.","message":"The `register_addition_attribute` function allows overriding existing `ChipAttr` attributes. While powerful for customization, carelessly overriding a built-in attribute can lead to unexpected behavior or break core functionality if the new handler does not match the expected interface or logic.","severity":"breaking","affected_versions":">=0.1.0"},{"fix":"Always validate your input boolean expression strings against the library's documented syntax. Pay attention to string quoting (`\"string\"`), logical operators (`and`, `or`), and comparison operators (`==`, `!=`).","message":"Boolean expression parsing is sensitive to syntax. Deviations from the expected grammar (e.g., incorrect operators, unquoted strings, mismatched parentheses, or unrecognized tokens) passed to `parse_bool_expr` will result in a `ParsingError` or an `InvalidTokenError`.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Add `import esp_bool_parser` at the beginning of your Python script or ensure `from esp_bool_parser import ...` is used for specific functions.","cause":"The `esp_bool_parser` module was used without being imported first.","error":"NameError: name 'esp_bool_parser' is not defined"},{"fix":"Ensure you assign the result of `esp_bool_parser.parse_bool_expr(stmt_string)` to a variable and then call `.get_value()` on that parsed object, e.g., `parsed_stmt = esp_bool_parser.parse_bool_expr(stmt_string); result = parsed_stmt.get_value(...)`.","cause":"This error occurs when you try to call methods like `.get_value()` directly on the input string rather than the parsed expression object returned by `esp_bool_parser.parse_bool_expr()`.","error":"AttributeError: 'str' object has no attribute 'get_value'"},{"fix":"Carefully review the boolean expression string. Common issues include missing quotes around string literals, incorrect logical operators (e.g., using `&&` instead of `and`), or malformed variable names (e.g., `IDF_TARGET` vs. `IDF_TARGET_XYZ`). Consult the official documentation for the precise grammar.","cause":"The input string passed to `parse_bool_expr` contains an invalid token or does not follow the expected grammar for a boolean expression. This could be due to typos, incorrect operator usage, or improperly formatted operands.","error":"esp_bool_parser.InvalidTokenError: (or similar parsing error message with line/column details)"}]}