Defining Custom Terms and Formulae

Terms return values for expressions. Formulae participate in guards and queries. Both can expose module state directly, without maintaining an ordinary belief for every value. The light-device example in Chapter 5 implements both forms.

Creating a Custom Term

A public @TERM method returns the value used by the ASTRA expression:

@TERM
public String state() {
    return state;
}

Here state is the module’s string-valued device state. In a plan, use string Current = device.state();. Java primitive return types map to corresponding ASTRA types; ListTerm maps to list and Funct to funct. Java object results retain their class type.

A term reader should be quick and should not change the world as a side effect of evaluating an expression. It may be evaluated when a guard is checked as well as in a plan body. Use an action for an operation that changes external state.

Creating a Custom Formula

A public @FORMULA method returns astra.formula.Formula. For a simple ground test, return Predicate.TRUE or Predicate.FALSE:

@FORMULA
public Formula is(String expected) {
    return state.equals(expected) ? Predicate.TRUE : Predicate.FALSE;
}

Use it as if (device.is("on")) { ... }, in a context, or in wait(device.is("on"), 2000);. It is a formula test, not a boolean-returning term. Annotating a boolean getter with @TERM does not make it a custom formula.

This is method requires an input value. It tests whether the current state equals that value; it does not enumerate or bind an unknown state variable. To obtain the current state, use the term getter. Richer formula providers can expose queryable facts, but require an appropriate reasoning integration rather than simply returning a true/false test.

Choosing Between Terms, Formulae and Beliefs

Need	Interface
Read state into a local variable or expression	`string Current = device.state();`
Select a plan or branch according to a known target	`device.is(Target)`
React to state changes through belief events	A sensor publishes `light(State)`
React to a Java notification without retaining it as knowledge	A custom event

A module formula describes what its implementation can establish at evaluation time. An observed belief describes the state last published to the agent. These may differ briefly while an update is being sensed. Choose the interface matching the evidence your goal requires.

Using the Module

The complete LightDevice class imports Formula and Predicate, declares its device state and exposes both methods. Download the sample project or use the complete code in Observing and Acting.

Direct queries do not generate belief events. If a control policy must react to changes, use a sensor or a custom event, then decide whether the reaction should retain a belief.