Utility Functions

Utilities.

get_constant_string(name: str, value: str, prefix: str = '') -> str

Return a constant string of the format "{prefix}{name}={value}".

get_constants_from_arguments(argument_vector: list[str]) -> dict[str, str]

Return dict containing the constants specified on the command line arguments.

get_signatures_from_model_string(model_string: str) -> set[tuple[str, int]]

Return the signatures of all atoms of a model string.

match_ast_symbolic_atom_signature(ast_symbol: AST, signature: tuple[str, int]) -> bool

Match the signature of an AST SymbolicAtom to a tuple containing a string and int value.

logging

Setup project wide loggers.

This is a thin wrapper around Python's logging module. It supports colored logging.

SingleLevelFilter(passlevel: int, reject: bool)

Bases: Filter

Filter levels.

filter(record: logging.LogRecord) -> bool

Test if a LogRecord will be filtered.

configure_logging(stream: TextIO, level: int, use_color: bool) -> None

Configure application logging.

get_logger(name: str) -> logging.Logger

Get a logger with the given name.

match

Symbol pattern matching for logic programming.

This module provides functions for matching symbols against structured patterns. It includes a parser for transforming textual patterns into matchers, which can then be used to identify variable assignments in symbolic terms. The matchers support exact symbol matching, variable binding, and function structure recognition.

FunctionMatcher(name: str, arguments: Sequence[Matcher], positive: bool) dataclass

Bases: Matcher

Matcher for functions and tuples.

Matches a function symbol with a specific name, a sequence of argument matchers, and a polarity (positive or negative).

Also handles tuples which must be positive with empty name.

Attributes: name: The name of the function to match. arguments: Matchers for each argument of the function. positive: True if matching a positive function; False for negated function.

match(symbol: Symbol, assignment: dict[str, Symbol]) -> bool

Check if the given symbol is a function or tuple with the expected name, arguments, and polarity.

For tuples only the arguments are checked.

PARAMETER	DESCRIPTION
symbol	The function symbol to match. TYPE: Symbol
assignment	Dictionary holding current variable assignments. TYPE: dict[str, Symbol]

RETURNS	DESCRIPTION
`True` if the function symbol matches; False otherwise.

Match(assignment: dict[str, Symbol]) dataclass

A simple container for a successful match result.

Attributes: assignment: A mapping from variable names to their matched Symbol.

Matcher

Abstract base class for matchers.

A matcher encapsulates the logic required to match a Symbol against a pattern. Subclasses must implement the match method.

__call__(symbol: Symbol) -> Match | None

Make Matcher callable. Attempts to match the given symbol.

If the match is successful, returns a Match object containing the assignment. Otherwise, returns None.

Args: symbol: The symbol to match.

Returns: The match result.

match(symbol: Symbol, assignment: dict[str, Symbol]) -> bool abstractmethod

Attempt to match the given symbol and update the assignment if successful.

Args: symbol: The symbol to be matched. assignment: A dictionary to record variable assignments.

Returns: True if the match succeeds; False otherwise.

ValueMatcher(value: str | int | Symbol) dataclass

Bases: Matcher

Matcher for concrete values.

Attributes: value: The value to match.

match(symbol: Symbol, assignment: dict[str, Symbol]) -> bool

Check if the provided symbol matches the stored value.

Args: symbol: The symbol to match. assignment: Current variable assignment (unused here).

Returns: True if the symbols are equal.

VariableMatcher(name: str) dataclass

Bases: Matcher

Matcher for variables. It binds a symbol to a variable name in the assignment.

Attributes: name: The variable name.

match(symbol: Symbol, assignment: dict[str, Symbol]) -> bool

Attempt to match a variable.

If the variable is already bound in the assignment, then the symbol must be equal to the bound symbol. Otherwise, bind the variable.

Anonymous variables with name "_" are handled specially, they do not interact with the assignment and always match.

PARAMETER	DESCRIPTION
symbol	The symbol to bind or compare. TYPE: Symbol
assignment	The variable assignment mapping. TYPE: dict[str, Symbol]

RETURNS	DESCRIPTION
True if the variable matches or is successfully bound.

compile_matcher(expression: str) -> Matcher cached

Compile an expression string into a Matcher object.

PARAMETER	DESCRIPTION
expression	The matcher expression to compile. TYPE: str

RETURNS	DESCRIPTION
The compiled matcher.

main() -> None

Test for exposition.

match(expression: str, symbol: clingo.Symbol) -> Match | None

Compile an expression and match it against a symbol.

PARAMETER	DESCRIPTION
expression	The matcher expression. TYPE: str
symbol	The symbol to match against. TYPE: Symbol

RETURNS	DESCRIPTION
A Match object with the variable assignment if the symbol matches, or None if it does not.

unquote(quoted: str) -> str

Unquote the given string as clingo would.

PARAMETER	DESCRIPTION
quoted	The quoted string. TYPE: str

RETURNS	DESCRIPTION
The unquoted string.

parser

The command line parser for the project.

get_parser() -> ArgumentParser

Return the parser for command line options.

symbols

Utility functions for handling clingo symbols.

ast_symbolic_atom_to_symbol(symbolic_atom: AST) -> clingo.Symbol

Convert SymbolicAtoms of the clingo AST to clingo Symbols.

types

Custom types for clingexplaid.