ESP-BOOL-PARSER

Common errors

• NameError: name 'esp_bool_parser' is not defined

  cause The `esp_bool_parser` module was used without being imported first.
  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.

• AttributeError: 'str' object has no attribute '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()`.
  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(...)`.

• esp_bool_parser.InvalidTokenError: (or similar parsing error message with line/column details)

  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.
  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.

Warnings

• gotcha 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.
  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.
• breaking 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.
  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.
• gotcha 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`.
  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 (`==`, `!=`).

Install

• pip install esp-bool-parser Install with pip

Imports

• parse_bool_expr

  from esp_bool_parser import parse_bool_expr

• register_addition_attribute

  from esp_bool_parser import register_addition_attribute

Quickstart

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.

import esp_bool_parser

# Example 1: Parsing a simple boolean expression
stmt_string = 'IDF_TARGET == "esp32" and CONFIG_FOO'
stmt = esp_bool_parser.parse_bool_expr(stmt_string)

# You would typically have a ChipAttr-like object or context to evaluate this.
# For demonstration, let's mock a simple evaluation.
# In a real ESP-IDF context, 'target' and 'config_name' would come from build system.
# For example, checking against 'esp32' target and a configuration where CONFIG_FOO is True

# A simple mock evaluation function (not part of the library, for example purposes)
def evaluate_mock(parsed_expression, target, config_values):
    # This is a highly simplified representation.
    # The actual library's .get_value() interacts with an internal ChipAttr instance.
    # For this example, we assume parsed_expression has an internal representation
    # that can be evaluated with provided context.
    try:
        # The actual get_value method is more complex and handles SOC_CAPS, ENV_VARs, etc.
        # This line is illustrative, assuming it resolves based on target and config_values
        # In a real scenario, ChipAttr would handle the context.
        result = parsed_expression.get_value(target, config_values.get('config_name', ''))
        return result
    except Exception as e:
        print(f"Error during evaluation: {e}")
        return None

# Example usage of evaluation (simplified)
mock_config = {'config_name': 'default', 'CONFIG_FOO': True}
# Note: Direct call to stmt.get_value requires proper ChipAttr context setup internally.
# The example from docs is `result = stmt.get_value("esp32", "config_name")`
# which implies `"config_name"` is a string identifier for a configuration context.
# For a true runnable quickstart, it's difficult to fully simulate `ChipAttr`'s internal state
# without more knowledge or a simpler public API for evaluation. 
# The primary use is *parsing* the expression. Evaluation depends on the runtime context.
# Let's show the parsing and the registration of an attribute.

print(f"Successfully parsed expression: '{stmt_string}'")

# Example 2: Registering an additional attribute
import typing as t

def my_custom_action(target: str, config_name: str, **kwargs: t.Any) -> str:
    print(f"Custom attribute 'MY_ATTR' called for target: {target}, config: {config_name}")
    return f"Processed_{target}_{config_name}"

esp_bool_parser.register_addition_attribute("MY_ATTR", my_custom_action)

# Now, expressions can use MY_ATTR (e.g., 'MY_ATTR == "Processed_esp32_config"')