rule-engine

When defining complex schemas, you may need to handle recursive or mutually-recursive types:

1. Self-references: Use DataType.OBJECT.self as a shorthand sentinel to refer back to the enclosing object's schema.
2. Forward references: Use DataType.OBJECT.reference('TypeName') to create a placeholder for a type that hasn't been defined yet.
3. Mutual recursion: For types that refer to each other (e.g., Person refers to Company and Company refers to Person), place both types in the type_resolver dictionary of the rule_engine.Context. The references will then be resolved lazily at rule parse time.

# Self-reference example
Hero = rule_engine.DataType.OBJECT('Hero', attributes={
    'name': rule_engine.DataType.STRING,
    'nemesis': rule_engine.DataType.OBJECT.self,  # resolved to Hero
})

# Mutual recursion example
Person = rule_engine.DataType.OBJECT('Person', attributes={
    'name': rule_engine.DataType.STRING,
    'employer': rule_engine.DataType.OBJECT.reference('Company'),
})
Company = rule_engine.DataType.OBJECT('Company', attributes={
    'name': rule_engine.DataType.STRING,
    'ceo': rule_engine.DataType.OBJECT.reference('Person'),
})

context = rule_engine.Context(type_resolver={
    'employee': Person,
    'Person': Person,
    'Company': Company,
})
rule = rule_engine.Rule('employee.employer.ceo.name == "Palpatine"', context=context)

The NULLABLE(T) type constructor marks a data slot as permitting None (null) at runtime. It is structurally distinct from both T and NULL.

Strictness and Errors

Rule Engine uses Python-style semantics (not SQL three-valued logic). Many operators are strict and will reject a NULLABLE operand at parse time with an EvaluationError or FunctionCallError. These include:

• Arithmetic (+, -, *, /, etc.)
• Ordered comparisons (<, <=, >, >=)
• Regex operators (=~, =~~, !~, !~~)
• Bitwise operators
• Unary minus
• Containment (x in container)
• Attribute/Item access (obj.attr, container[key], container[a:b])
• Function arguments

Discharging Nullability

To use a nullable value with strict operators, you must "discharge" the nullability using one of these mechanisms:

1. Null-coalesce (left ?? right): Evaluates to left if it is not None, otherwise returns right. This converts a NULLABLE(T) into a non-nullable type (unless right is also nullable).
2. Safe Navigation: Use obj&.attr for safe attribute access or container&[key] for safe item access. These allow the expression to proceed without error, but the resulting value remains NULLABLE and must be discharged later if passed to a strict operator.

Lenient Operators

Equality and logical connectives always accept NULLABLE operands and return a plain BOOLEAN:

• ==, !=, and, or, not
• Ternary expressions (cond ? a : b) propagate nullability to the result.
• not NULLABLE(BOOLEAN) returns a plain BOOLEAN (not None is True).

# Example of discharging nullability with null-coalesce
# If 'user.name' is NULLABLE(STRING), this ensures a STRING result
rule_text = "user.name ?? 'Unknown'"

The rule_engine.DataType.OBJECT type allows you to define a schema with named, typed attributes. This enables parse-time validation: if a rule references an attribute not in the schema, an ObjectAttributeError is raised immediately.

• Use rule_engine.DataType.OBJECT.self for self-referential attributes.
• Use rule_engine.DataType.OBJECT.reference('TypeName') for cross-type references.
• Attributes in an OBJECT are accessed using dot syntax (e.g., hero.name). Item access (e.g., hero['name']) is not supported.

HeroType = rule_engine.DataType.OBJECT('Hero', attributes={
    'name': rule_engine.DataType.STRING,
    'publisher': rule_engine.DataType.STRING,
    'first_appearance': rule_engine.DataType.DATETIME,
    'nemesis': rule_engine.DataType.OBJECT.self,
})

context = rule_engine.Context(type_resolver={'Hero': HeroType})
rule = rule_engine.Rule('hero.name == "Batman"', context=context)