ASTRA Programming Language

https://guide.astralanguage.com/en/latest/
Admin
ASTRA is an Agent-Oriented Programming Language developed by University College Dublin, combining...
Tokens:45,249
Snippets:380
Trust Score:5.5
Update:10 months ago
Show doc for...
Tokens:
Raw
### Console Input/Output Example in ASTRA

Source: https://guide.astralanguage.com/en/latest/libraries

An example ASTRA agent demonstrating console interaction. It prompts the user for input, reads a string using `console.read`, and then prints a greeting back to the console. Requires the `Console` module.

```astra
agent Example {
    module Console console;

    rule +!main(list args) {
        console.println("Please enter your name: ");
        console.read(string name);
        console.println("Hello, " + name);
    }
}
```

--------------------------------

### ASTRA 'Hello World' Agent Example

Source: https://guide.astralanguage.com/en/latest/index

A basic ASTRA agent program demonstrating a module declaration for console output and a main event rule to print 'Hello World'. This serves as a fundamental example for understanding ASTRA program structure.

```astra
agent Hello {
    module Console console;

    rule +!main(list args) {
        console.println("Hello World!");
    }
}
```

--------------------------------

### ASTRA Hello World Program

Source: https://guide.astralanguage.com/en/latest/basicastra

Declares an initial goal to display 'Hello World' to the console. This example utilizes the Console module for output.

```ASTRA
agent Hello {
    module Console C;

    initial !init();

    rule +!init() {
        C.println("Hello World");
    }
}
```

--------------------------------

### Invoke an ASTRA Action from an Agent Rule

Source: https://guide.astralanguage.com/en/latest/modules/calculator

An ASTRA agent can invoke module actions within its rules. This example shows how to call the 'doublePrint' action from the 'main' rule of 'MyAgent' to display a formatted double.

```java
package example.calculator;

agent MyAgent {
  module Calculator calc;

  rule +!main(list args) {
    calc.doublePrint(3.1415926, 2);
  }
}
```

--------------------------------

### Create an ASTRA Action to Print a Double

Source: https://guide.astralanguage.com/en/latest/modules/calculator

ASTRA actions are methods annotated with '@ACTION' that represent agent capabilities. They should return a boolean indicating success (true) or anticipated failure (false). This example creates an action to print a double to a specified number of decimal places.

```java
package example.calculator;

import java.text.DecimalFormat;
import astra.core.Module;

public class Calculator extends Module {
  @ACTION
  public boolean doublePrint(double value, int places) {
    String pattern = "#.";
    for (int i=0;i<places;i++) pattern +="0";
    DecimalFormat df = new DecimalFormat(pattern);
    System.out.println(df.format(value));
    return true;
  }
}
```

--------------------------------

### AgentSpeak(L) 'Hello World' Example

Source: https://guide.astralanguage.com/en/latest/astra-concepts

A basic 'Hello World' program in AgentSpeak(L) includes an initial goal (!init()) and a plan rule that handles the goal adoption event by printing 'hello world' to the console using a private action.

```agentspeak
01 !init().
02 
03 +!init() <-
04     println(hello world).

```

--------------------------------

### Create ASTRA Term Methods for Arithmetic

Source: https://guide.astralanguage.com/en/latest/modules/calculator

ASTRA term methods, annotated with '@TERM', dynamically generate values used in predicate formulas. This example implements 'add' and 'divide' term methods for basic arithmetic operations within the Calculator module.

```java
@TERM
public double add(double X, double Y) {
  return X+Y;
}

@TERM
public double divide(double  X, double Y) {
  return X/Y;
}
```

--------------------------------

### Maven Project Setup for ASTRA

Source: https://guide.astralanguage.com/en/latest/multiple

Configures a Maven project for ASTRA development, including specifying dependencies and the ASTRA Maven plugin for building and deploying ASTRA projects. This setup is crucial for managing ASTRA project artifacts.

```xml
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>examples</groupId>
    <artifactId>replicator</artifactId>
    <version>1.4.1</version>

    <parent>
        <groupId>com.astralanguage</groupId>
        <artifactId>astra-base</artifactId>
        <version>1.4.1</version>
    </parent>

    <build>
        <defaultGoal>clean compile astra:deploy</defaultGoal>
        <plugins>
            <plugin>
                <groupId>com.astralanguage</groupId>
                <artifactId>astra-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>
```

--------------------------------

### Create Main Agent to Start Replication in Astral

Source: https://guide.astralanguage.com/en/latest/communication

The Main agent initiates the replication process by creating the first Replicator agent and sending it an initial message. It utilizes console and system modules for interaction.

```astra
agent Main {
    module Console console;
    module System system;

    types replicate {
        formula replicate(int);
    }

    rule +!main(list args) {
        console.println("Starting Replication...");

        system.createAgent("agt_0", "Replicator");
        send(request, "agt_0", replicate(1));
    }
}
```

--------------------------------

### Use ASTRA Term Methods in Agent Rule

Source: https://guide.astralanguage.com/en/latest/modules/calculator

ASTRA term methods can be nested within agent rules to perform calculations. This example demonstrates using the 'add' and 'divide' term methods, along with the 'doublePrint' action, to calculate and display a complex arithmetic expression.

```java
agent MyAgent {
  module Calculator calc;

  rule +!main(list args) {
    calc.doublePrint(3+calc.divide(calc.add(1.2, 3.2), 2.3131), 2);
  }
}
```

--------------------------------

### Instantiate an ASTRA Module in an Agent

Source: https://guide.astralanguage.com/en/latest/modules/calculator

To use a declared ASTRA module within an agent, declare an instance of the module within the agent's definition. This makes the module's functionalities accessible to the agent.

```java
package example.calculator;

agent MyAgent {
  module Calculator calc;
}
```

--------------------------------

### ASTRA Code to Launch an EISHUB Environment

Source: https://guide.astralanguage.com/en/latest/eis

This ASTRA code defines an agent named 'Example' that uses the EIS module. The `+!main` rule, upon execution, calls the `ei.launch` function, passing a unique identifier ('my_id') and the path to the environment's JAR file (e.g., 'dependency/vacuumworld-1.2.0.jar'). This path is derived from the Maven dependencies specified in the POM file.

```astra
agent Example {
    module EIS ei;

    rule +!main(list args) {
        ei.launch("my_id", "dependency/vacuumworld-1.2.0.jar");
    }
}
```

--------------------------------

### ASTRA Plan Rule Syntax Example

Source: https://guide.astralanguage.com/en/latest/astra-concepts

Illustrates the basic structure of an ASTRA plan rule, including the 'rule' keyword, triggering event, optional context, and the plan body defined as a code block. Primitive statements are terminated by a semicolon.

```ASTRA
rule te : ctxt {
    Ac1;
    Ac2;
    {
        Ac3;
        Ac4;
    }
}

```

--------------------------------

### ASTRA Agent Using Calculator and Console Modules

Source: https://guide.astralanguage.com/en/latest/modules/calculator

This ASTRA agent code demonstrates the usage of custom formulas and modules. It utilizes the `Calculator` module to store a value and the `Console` module to print messages and the retrieved value, conditional on the `hasMemory` formula's result.

```java
package example.calculator;

agent MyAgent {
  module Calculator calc;
  module Console C;

  rule +!main(list args) {
    calc.store(3+calc.divide(calc.add(1.2, 3.2), 2.3131));
    if (calc.hasMemory()) {
      C.println("stored value: ");
      calc.doublePrint(calc.retrieve(),2);
    } else {
      C.println("There was no stored value...");
    }
  }
}
```

--------------------------------

### Initial LightSwitch Agent Program in ASTRA

Source: https://guide.astralanguage.com/en/latest/astra-concepts

Defines the basic structure of the LightSwitch agent, including types for switch and light states, initial conditions, and rules for directly manipulating the light state. It serves as a starting point for agent program design.

```ASTRA
agent LightSwitch {
    types lightExample {
        formula switch(string);
        formula light(string);
    }

    initial switch("up"), light("off");

    rule +!light(string X) : light(X) { }

    rule +!light("on") {
        -light("off");
        +light("on");
    }

    rule +!light("off") {
        -light("on");
        +light("off");
    }
}

```

--------------------------------

### Updating List Beliefs in ASTRA (Blocks World Example)

Source: https://guide.astralanguage.com/en/latest/lists

Demonstrates a common ASTRA pattern for managing mutable lists as beliefs. This example shows how an agent can dynamically add newly observed blocks to an 'available' list belief.

```ASTRA
types bw {
    formula available([]);
    formula block(string);
}

initial available([]);

rule +block(string X) : available(list L) {
    -+available(L+[X]);
}
```

--------------------------------

### ASTRA Package Declaration Example

Source: https://guide.astralanguage.com/en/latest/deploying

Example of a package declaration in an ASTRA agent program. ASTRA follows Java's package naming conventions, requiring a 'package' declaration for programs not in the default package.

```astra
package soccer;
```

--------------------------------

### ASTRA Agent with Calculator Module and Memory Sensor Rule

Source: https://guide.astralanguage.com/en/latest/modules/calculator

This ASTRA code defines an agent named 'MyAgent' that utilizes a 'Calculator' module and a 'Console' module. It declares a 'memory(double)' belief type. The agent's main execution rule stores a calculated value using the calculator module and checks for memory. A side-effect rule is defined to print a message whenever the 'memory' belief changes. This demonstrates the integration of sensors and belief updates within an ASTRA agent.

```astra
package example.calculator;

agent MyAgent {
   module Calculator calc;
   module Console C;

   types calculator {
      formula memory(double);
   }

   rule +!main(list args) {
      calc.store(3+calc.divide(calc.add(1.2, 3.2), 2.3131));
      if (calc.hasMemory()) {
         C.println("stored value: ");
         calc.doublePrint(calc.retrieve(),2);
      } else {
         C.println("There was no stored value...");
      }
   }

   rule +memory(double value) {
      C.println("Memory changed: "+value);
   }
}
```

--------------------------------

### Credentials File Format for Docker Authentication

Source: https://guide.astralanguage.com/en/latest/docker

This example shows the format of a credentials file used by ASTRA for secure access to Docker repositories. Each line contains the repository base URL, username, and passkey, delimited by colons. This file is loaded via the `credentials` module to provide necessary authentication details.

```plaintext
MY_REPOSITORY:MY_USERNAME:MY-PASS-KEY
MY_OTHER_REPOSITORY:MY_OTHER_USERNAME:MY-OTHER-PASS-KEY

```

--------------------------------

### Debug Agent Beliefs Example in ASTRA

Source: https://guide.astralanguage.com/en/latest/libraries

An ASTRA agent example utilizing the `Debug` module to display beliefs. It defines custom types and initial beliefs, then uses `debug.dumpBeliefs()` and `debug.dumpBeliefsWithPredicate()` to output the agent's knowledge base.

```astra
agent Example {
    types eg {
        formula likes(string);
        formula has(string);
    }

    initial likes("icecream"), likes("sausages"), likes("beer");
    initial has("icecream"), has("pickles");

    module Debug debug;

    rule +!main(list args) {
        debug.dumpBeliefs();
        debug.dumpBeliefsWithPredicate("has");
    }
}
```

--------------------------------

### Create Memory Event Class in Java

Source: https://guide.astralanguage.com/en/latest/modules/calculator

Defines a custom event class `MemoryEvent` that implements the `astra.event.Event` interface. It includes a field for event parameters and a constructor for initialization. The `getSource()` method returns null, and `signature()` returns a unique event identifier.

```java
package example.calculator;

import astra.event.Event;
import astra.term.Term;

public class MemoryEvent implements Event {
   public Term value;

   public MemoryEvent(Term value) {
      this.value = value;
   }

   @Override
   public Object getSource() {
      return null;
   }

   @Override
   public String signature() {
      return "$mem";
   }
}
```

--------------------------------

### Generate ASTRA Project using Maven Archetype

Source: https://guide.astralanguage.com/en/latest/modules/sensors

Creates a new ASTRA project using the official Maven archetype. This command initializes a project with the necessary structure and configurations, simplifying the setup process. Users need to replace placeholder groupId and artifactId.

```bash
mvn archetype:generate \
    -DarchetypeGroupId=com.astralanguage \
    -DarchetypeArtifactId=astra-archetype \
    -DarchetypeVersion=1.0.2 \
    -DgroupId=examples \
    -DartifactId=module-sensors \
    -Dversion=0.1.0
```

--------------------------------

### ASTRA Agent Rule for Custom Event

Source: https://guide.astralanguage.com/en/latest/modules/calculator

Defines a rule within an ASTRA agent to handle a custom event. Custom event rules are prefixed with a dollar sign ($). This example shows a rule that listens for the '$calc.event' and prints a message when it's triggered.

```astra
rule $calc.event(double value) {
   C.println("Memory changed (custom event): "+value);
}
```

--------------------------------

### Implement ASTRA Memory Sensor (Java)

Source: https://guide.astralanguage.com/en/latest/modules/calculator

This Java code implements a sensor for an ASTRA agent that monitors a 'memory' value. It checks if the current memory value differs from the last recorded value. If it differs, it removes the old 'memory' belief from the agent's beliefs and adds a new belief reflecting the current memory value. It uses the protected 'agent' field to interact with the agent's belief system. Dependencies include the ASTRA agent API.

```java
private Predicate memoryBelief;
private double lastMemory;

@SENSOR 
public void memory() {
   if (lastMemory != memory) {
      if (memoryBelief != null) {
         agent.beliefs().dropBelief(memoryBelief);
      }
      memoryBelief = new Predicate("memory", new Term[] {Primitive.newPrimitive(memory)});
      agent.beliefs().addBelief(memoryBelief);
      lastMemory = memory;
   }
}
```

--------------------------------

### Define ASTRA Action, Term, and Formula

Source: https://guide.astralanguage.com/en/latest/modules/calculator

This Java code defines a memory store, retrieve, and hasMemory formula for an ASTRA module. The `store` action sets a double value, `retrieve` returns the stored value, and `hasMemory` checks if the memory is non-zero, returning Predicate.TRUE or Predicate.FALSE.

```java
private double memory;

@ACTION
public boolean store(double value) {
  memory = value;
  return true;
}

@TERM
public double retrieve() {
  return memory;
}

@FORMULA
public Formula hasMemory() {
  return memory == 0.0 ? Predicate.FALSE:Predicate.TRUE;
}
```

--------------------------------

### Create ASTRA Project using Maven Archetype

Source: https://guide.astralanguage.com/en/latest/modules/actions

Generates a new ASTRA project structure using a Maven archetype. This command simplifies project setup by providing a pre-configured template for ASTRA development.

```bash
mvn archetype:generate \
    -DarchetypeGroupId=com.astralanguage \
    -DarchetypeArtifactId=astra-archetype \
    -DarchetypeVersion=1.0.2 \
    -DgroupId=examples \
    -DartifactId=module-actions \
    -Dversion=0.1.0
```

--------------------------------

### ASTRA Terminal Hello World Program

Source: https://guide.astralanguage.com/en/latest/basicastra

A variation of 'Hello World' that terminates the program after printing 'Hello World' using the exit() action from the System module.

```ASTRA
agent Hello {
    module Console C;
    module System S;
    initial !init();

    rule +!init() {
        C.println("Hello World");
        S.exit();
    }
}
```

--------------------------------

### Create Memory Event Unifier in Java

Source: https://guide.astralanguage.com/en/latest/modules/calculator

Implements the `astra.reasoner.EventUnifier` interface to match custom events against triggering events in ASTRA rules. The `unify` method handles the logic for unifying event parameters, ensuring correct event processing.

```java
package example.calculator;

import java.util.HashMap;
import java.util.Map;

import astra.core.Agent;
import astra.event.Event;
import astra.reasoner.EventUnifier;
import astra.reasoner.Unifier;
import astra.term.Term;

public class MemoryEventUnifier implements EventUnifier<MemoryEvent> {
   @Override
   public Map unify(MemoryEvent source, MemoryEvent target, Agent agent) {
      return Unifier.unify(
         new Term[] {source.value}, 
         new Term[] {target.value}, 
         new HashMap(),
         agent);
   }
}
```

--------------------------------

### Declaring Heterogeneous Lists in ASTRA

Source: https://guide.astralanguage.com/en/latest/lists

Presents an example of a heterogeneous list in ASTRA, which contains elements of different data types, including strings, integers, and functional terms. Note that manipulation typically requires the Prelude API.

```ASTRA
[ "rem", 46, parentOf("coral") ]
```

--------------------------------

### Extend ASTRA Docker Agent to Deploy Container

Source: https://guide.astralanguage.com/en/latest/docker

This example demonstrates how to create a custom ASTRA agent that extends the `astra.Docker` class to deploy a specific Docker image. It defines an image constant, an initial belief for the image, and a rule to trigger the container deployment using the `!container` goal.

```astra
agent MyAgent extends astra.Docker {
    constant string TIC_TAC_TOE = "registry.gitlab.com/mams-ucd/examples/semantic-environments/tic-tac-toe" ;

    initial image(TIC_TAC_TOE);
    initial binding(TIC_TAC_TOE, "8083:8083");

    rule +!main(list args) {
        !container(TIC_TAC_TOE, string id);
    }
}

```

--------------------------------

### Create ASTRA Project using Maven Archetype

Source: https://guide.astralanguage.com/en/latest/multiple

Generates a new ASTRA project using the official Maven archetype. This command simplifies project setup by creating the necessary directory structure and configuration files.

```bash
mvn archetype:generate \
    -DarchetypeGroupId=com.astralanguage \
    -DarchetypeArtifactId=astra-archetype \
    -DarchetypeVersion=1.0.0 \
    -DgroupId=examples \
    -DartifactId=replicator \
    -Dversion=0.1.0
```

--------------------------------

### Declare an ASTRA Module

Source: https://guide.astralanguage.com/en/latest/modules/calculator

To declare a custom module in ASTRA, create a Java class that extends 'astra.core.Module'. This class provides necessary annotations for actions, terms, formulae, sensors, and events, and a reference to the agent that created it.

```java
package example.calculator;

import astra.core.Module;

public class Calculator extends Module {
}
```

--------------------------------

### AgentSpeak(L) Belief Update Operators

Source: https://guide.astralanguage.com/en/latest/astra-concepts

This AgentSpeak(L) code demonstrates adding and removing beliefs to manage an agent's state. It uses the '+' operator to add a belief and the '-' operator to remove a belief, triggering subsequent rules. This example creates an infinite loop by toggling between 'light(on)' and 'light(off)' states.

```agentspeak
01 light(on).
02
03 +light(on) <-
04     println(the light is on, turn it off!);
05     -light(on);
06     +light(off).
07     
08 +light(off) <-
09     println(the light is off, turn it on!);
10     -light(off);
11     +light(on).
```

--------------------------------

### ASTRA Initial Belief Declaration

Source: https://guide.astralanguage.com/en/latest/astra-concepts

Declares the initial state of an agent's beliefs using the `initial` keyword in ASTRA. This sets up the agent's environment at the start of execution. Multiple beliefs can be declared individually or combined in a single `initial` statement.

```ASTRA
initial switch("up");
initial light("off");

```

```ASTRA
initial switch("up"), light("off");

```

--------------------------------

### Astralanguage Agent Program Using Custom Formulas

Source: https://guide.astralanguage.com/en/latest/modules/terms

An example Astralanguage agent program demonstrating the use of a custom formula `switch.on()` to manage the state of a switch. It includes rules for flashing lights and controlling the switch, utilizing the custom formula for state comparison.

```astralanguage
agent Main {
  module Switch switch;
  module Console console;

  rule +!main(list args) {
    !flash(3);
    console.println("FINISHED");
  }

  rule +!flash(int N) : N > 0 {
    !switch("on");
    !switch("off");
    !flash(N-1);
  }

  rule +!flash(int N) {}

  rule +!switch(string state) : state ~= switch.on() {
    switch.flip();
    wait(switch.on() == state);
  }

  rule +!switch(string state) {
    console.println("should not happen");
  }

  rule $switch.state(string state) {
    console.println("switch=" + state);
  }
}

```

--------------------------------

### Create ASTRA Project using Maven Archetype

Source: https://guide.astralanguage.com/en/latest/lists

Generates a new ASTRA project using the `astra-archetype`. This command requires Maven to be installed and configured. It prompts for `groupId`, `artifactId`, and `version`, which should be tailored to the specific project. The archetype version used is `1.0.0`.

```bash
mvn archetype:generate \
    -DarchetypeGroupId=com.astralanguage \
    -DarchetypeArtifactId=astra-archetype \
    -DarchetypeVersion=1.0.0 \
    -DgroupId=examples \
    -DartifactId=lists \
    -Dversion=0.1.0
```

--------------------------------

### Declare Docker Image Belief in ASTRA

Source: https://guide.astralanguage.com/en/latest/docker

This ASTRA code snippet illustrates how to declare an initial belief for a Docker image using the `image(<name>)` predicate. It shows examples for both qualified image names from private repositories and less qualified names for public repositories, as well as the use of constants for long image names.

```astra
initial image("registry.gitlab.com/mams-ucd/examples/semantic-environments/tic-tac-toe");
initial image("arm64v8/hello-world");

constant string TIC_TAC_TOE = "registry.gitlab.com/mams-ucd/examples/semantic-environments/tic-tac-toe";
initial image(TIC_TAC_TOE);

```

--------------------------------

### Register Custom Event Handler in ASTRA

Source: https://guide.astralanguage.com/en/latest/modules/calculator

Registers a custom event handler with the astra.reasoner.Unifier. This is typically done in a static initialization block to ensure it's loaded before the first custom event is posted. It associates a custom event class with its corresponding unifier implementation.

```java
static {
   Unifier.eventFactory.put(MemoryEvent.class, new MemoryEventUnifier());
}
```

--------------------------------

### Define Astral Formulas and Initial States

Source: https://guide.astralanguage.com/en/latest/astra-concepts

This snippet demonstrates how to define formulas for state transitions (switch and light) and initialize the agent's state using these formulas. It showcases the syntax for declaring formulas and setting initial conditions.

```Astral
formula switchTransition(string, string);
formula lightTransition(string, string);

initial lightTransition("off", "on"), lightTransition("on", "off");
initial switchTransition("down", "up"), switchTransition("up", "down");
initial switch("up"), light("off");
```

--------------------------------

### Java Message Class Example

Source: https://guide.astralanguage.com/en/latest/libraries

A simple Java class named `Message` with a public `text` field and a `toString` method. This class is used in the ASTRA example to demonstrate object access.

```java
public class Message {
    public String text;

    public String toString() {
        return text;
    }
}

```

--------------------------------

### ASTRA Foreach Loop for Updating Balances

Source: https://guide.astralanguage.com/en/latest/reference

Illustrates the use of a foreach loop in ASTRA to iterate over generated variable bindings. In this example, it iterates through 'balance' beliefs, updates the amount based on a 'rate', and prints the changes. The loop's iterations are determined by the initial guard evaluation and are not affected by statements within the loop body.

```ASTRA
agent Eachy {
    module Console console;
    module System system;

    types local {
        formula balance(string, double);
        formula rate(double);
    }

    initial !init();
    initial rate(1.21);
    initial balance("Rem", 1000.0);
    initial balance("Bob", 500.0);

    rule +!init() : rate(double rate) {
        console.println("before loop");
        foreach (balance(string name, double amt)) {
            -balance(name, amt);
            +balance(name, amt*rate);
            console.println(name + " change from: " + amt + " to: " + (amt*rate));
        }
        console.println("after loop");
        system.exit();
    }
}
```

--------------------------------

### ASTRA Subgoal Execution with Console Output

Source: https://guide.astralanguage.com/en/latest/astra-concepts

Demonstrates how an ASTRA agent handles goals and subgoals using the Console module. The agent adopts an initial goal, prints a message, and then adopts a subgoal to print 'hello world'. It requires the Console module.

```ASTRA
agent Subby {
    module Console C;

    initial !init();

    rule +!init() {
        !printHello();
    }

    rule +!printHello() {
        C.println("hello world");
    }
}
```

--------------------------------

### Generate Custom Event in ASTRA Action Method

Source: https://guide.astralanguage.com/en/latest/modules/calculator

Updates an action method to generate a custom event. The agent's `addEvent` method is used to post a new instance of the custom event, passing necessary parameters. This action also updates a belief (`memory`) and returns a boolean status.

```java
@ACTION
public boolean store(double value) {
   memory = value;
   agent.addEvent(new MemoryEvent(Primitive.newPrimitive(value)));
   return true;
}
```

--------------------------------

### Create Maven Project Structure

Source: https://guide.astralanguage.com/en/latest/modules/events

This snippet shows the required directory structure for an ASTRA project when creating it from scratch. It includes the main source directory and the Maven build file.

```text
|-- src
|    |-- main
|          |-- astra
|-- pom.xml

```

--------------------------------

### Run Astral Application using Maven

Source: https://guide.astralanguage.com/en/latest/communication

This command executes the Maven build for the Astral project. It compiles the code and deploys the agents, allowing the application to run.

```bash
mvn
```

```bash
mvn clean compile astra:deploy
```

--------------------------------

### AgentSpeak(L) Subgoal Declaration and Handling

Source: https://guide.astralanguage.com/en/latest/astra-concepts

This AgentSpeak(L) code defines an initial goal '!init()' that triggers a subgoal '!printHello()'. The '!printHello()' goal is then handled by a separate rule that executes the 'println' action. This demonstrates modularity and subgoal invocation.

```agentspeak
01 !init().
02 
03 +!init() <-
04     !printHello().
05
06 +!printHello() <-
07     println(hello world).

```

--------------------------------

### ASTRA Multiple Inheritance: Super Agent

Source: https://guide.astralanguage.com/en/latest/multiple-inheritence

An additional parent agent named Super. It defines a 'isSuper' belief and initializes it to true.

```ASTRA
agent Super {

   types super_ont {
       formula isSuper(boolean);
   }

   initial isSuper(true);

}

```

--------------------------------

### Astral Language Logical Operators and Examples

Source: https://guide.astralanguage.com/en/latest/reference

Demonstrates the logical operators NOT (~), AND (&), OR (|), and Brackets () in Astral Language. These are fundamental for constructing complex conditions in plan rules and queries.

```Astral Language
|----------|--------|-----------------------------------------------------------------|
| OPERATOR | SYMBOL | EXAMPLE                                                         |
|----------|--------|-----------------------------------------------------------------|
| Not      |   ~    | ~likes(string X, "icecream")                                    |
|          |        | ~result(int X, int Y, int Z)                                    |
|----------|--------|-----------------------------------------------------------------|
| And      |   &    | likes(string X, "icecream") & is(X, "happy")                    |
|----------|--------|-----------------------------------------------------------------|
| Or       |   |    | has(X, "icecream") | has(X, "beer")                             |
|----------|--------|-----------------------------------------------------------------|
| Brackets |   ()   | hungry(string X) & (likes(X, "icecream") | likes(X, "burgers")) |
|----------|--------|-----------------------------------------------------------------|

```

--------------------------------

### Launch an EIS Environment using ASTRA

Source: https://guide.astralanguage.com/en/latest/eis

This code demonstrates how to launch an EIS environment within ASTRA. It requires an instance of the EIS module and specifies a unique ID and the path to the environment's JAR file. The launch action is typically called within the agent's main rule.

```ASTRA
agent Example {
    module EIS ei;

    rule +!main(list args) {
        ei.launch("my_id", "/path/to/MyEnvironment.jar");
    }
}

```

--------------------------------

### ASTRA Single Inheritance: Parent Agent

Source: https://guide.astralanguage.com/en/latest/multiple-inheritence

Defines a parent agent with a Console module and a belief_predicate formula. It includes a default validation rule that prints the input value.

```ASTRA
agent Parent {

    module Console c;

    types parent_ont {
        formula belief_predicate(int);
    }

    rule +!validate(belief_predicate(int v)) {
        c.println("Default:"+v);
    }
}

```

--------------------------------

### ASTRA Multiple Inheritance: Modified Child Agent

Source: https://guide.astralanguage.com/en/latest/multiple-inheritence

A modified Child agent that now extends both Parent and Super agents. It includes logic to query the 'isSuper' belief and print a message.

```ASTRA
agent Child extends Parent, Super {

    rule +!main(list args) {
        //Set initial belief from arguments
        +belief_predicate(p.valueAsInt(args, 0));

        //Query belief
        query(belief_predicate(int v));

        //Goal: validate belief
        !validate(belief_predicate(v));

        //Query belief
        query(isSuper(true));
        c.println("agent is super agent");
    }

    rule +!validate(belief_predicate(int v)) : v>1 {
        c.println(v+" is greater than 1");
    }
}

```

--------------------------------

### Compiling and Running ASTRA Program

Source: https://guide.astralanguage.com/en/latest/modules/sensors

This command is used to compile and run the ASTRA program. It assumes a Maven build environment is set up for the project.

```Shell
$ mvn

```

--------------------------------

### ASTRA Single Inheritance: Main Agent to Run Child

Source: https://guide.astralanguage.com/en/latest/multiple-inheritence

The main agent used to create and run the Child agent. It initializes the Child agent and sets its main goal with an initial argument.

```ASTRA
agent Main {

    module System s;

    rule +!main(list args) {
        s.createAgent("child", "Child");
        s.setMainGoal("child", [1]);
    }

}

```

--------------------------------

### Iterate with while Loop and list_count/at_index in ASTRA

Source: https://guide.astralanguage.com/en/latest/lists

Illustrates list iteration using a while loop in ASTRA. This technique employs `list_count()` to get the list size and `at_index()` to access elements by their index. The index is manually incremented.

```ASTRA
int i=0;
while (i < list_count(L)) {
    console.println(at_index(L, i, string));
    i++;
}

```

--------------------------------

### ASTRA Rule Examples for Football Agent Decisions

Source: https://guide.astralanguage.com/en/latest/reference

Demonstrates ASTRA rules for a football agent's decision-making, including shooting and passing based on game context. These rules show the direct translation of conditions to actions.

```ASTRA
rule +!decide() :
        has("ball") & is("closed_down") & 
        close("opposition_goal") {
    shoot();
}

rule +!decide() :
        has("ball") & is("closed_down") &
        near("team_player", string P) {
    pass(P);
}
```

--------------------------------

### Declare Variables in ASTRA Rule Context

Source: https://guide.astralanguage.com/en/latest/reference

Declares variables within the context of a plan rule to extract information from the agent's beliefs. This example prioritizes a rule if a 'result' belief already exists for the given inputs.

```ASTRA
rule +!addition(int X, int Y) : result(X, Y, int R) {
    // do nothing because we already know the result!
}
```

--------------------------------

### Configure Maven pom.xml for ASTRA Project

Source: https://guide.astralanguage.com/en/latest/modules/events

This XML snippet defines the Maven build configuration for an ASTRA project. It specifies project coordinates, dependencies on the ASTRA base, and configures the astra-maven-plugin for deployment. Ensure to update groupId and artifactId.

```xml
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>examples</groupId>
    <artifactId>module-events</artifactId>
    <version>1.4.1</version>

    <parent>
        <groupId>com.astralanguage</groupId>
        <artifactId>astra-base</artifactId>
        <version>1.4.1</version>
    </parent>

    <build>
        <defaultGoal>clean compile astra:deploy</defaultGoal>
        <plugins>
            <plugin>
                <groupId>com.astralanguage</groupId>
                <artifactId>astra-maven-plugin</artifactId>
                <version>1.4.1</version>
            </plugin>
        </plugins>
    </build>
</project>

```

--------------------------------

### Main Agent Implementation in ASTRA

Source: https://guide.astralanguage.com/en/latest/communication

This ASTRA agent, 'Main', extends 'ReplicatorCommon' and utilizes 'Console' and 'System' modules. The 'main' rule initiates replication, creates a new agent named 'agt_0' of type 'Replicator', and sends a replication request. This code demonstrates basic agent lifecycle management and inter-agent communication.

```ASTRA
agent Main extends ReplicatorCommon {
    module Console console;
    module System system;

    rule +!main(list args) {
        console.println("Starting Replication...");

        system.createAgent("agt_0", "Replicator");
        send(request, "agt_0", replicate(1));
    }
}

```

--------------------------------

### Declare an Agent in ASTRA

Source: https://guide.astralanguage.com/en/latest/astra-concepts

Demonstrates the basic syntax for declaring an agent in ASTRA. Agent programs are stored in '.astra' files and use the 'agent' keyword followed by the agent's name and a block of code enclosed in braces. This structure is similar to Java class declarations.

```ASTRA
agent MyFirstAgent {

}
```

--------------------------------

### ASTRA Single Inheritance: Child Agent

Source: https://guide.astralanguage.com/en/latest/multiple-inheritence

A child agent that extends the Parent agent. It sets an initial belief, queries it, and then calls the validation goal. It also overrides the validation rule for values greater than 1.

```ASTRA
agent Child extends Parent {

    rule +!main(list args) {
        //Set initial belief from arguments
        +belief_predicate(p.valueAsInt(args, 0));

        //Query belief
        query(belief_predicate(int v));

        //Goal: validate belief
        !validate(belief_predicate(v));
    }

    rule +!validate(belief_predicate(int v)) : v>1 {
        c.println(v+" is greater than 1");
    }
}

```

--------------------------------

### ASTRA Recursive Loop (Variable Limit)

Source: https://guide.astralanguage.com/en/latest/reference

Implements a loop that iterates from a starting number up to a specified limit, using two rules. This version uses parameters for both the current iteration and the total number of iterations, making it more dynamic.

```ASTRA
agent GoodUpLoopy {
    module Console console;

    initial !print(1, 5);

    rule +!print(int X, int N) : X < N {
        console.println(X);
        !print(X-1); 
    }

    rule +!print(int X, int N) : X == N {
        console.println(X);
    }
}
```

--------------------------------

### ASTRA Rule for Turning Light On

Source: https://guide.astralanguage.com/en/latest/astra-concepts

Demonstrates ASTRA rules to achieve the goal of turning the light on. It includes a rule for when the light is already on, and a rule for when the light is off, which updates the agent's beliefs to reflect the desired state.

```ASTRA
rule +!light("on") : light("on") {}

rule +!light("on") {
    -light("off");
    +light("on");
}

```

--------------------------------

### Turn Light On/Off Actions in Java

Source: https://guide.astralanguage.com/en/latest/modules/actions

Defines two separate actions, turnOn() and turnOff(), for a light switch module. Each action is annotated with @ACTION and returns a boolean to indicate success. This approach is contrasted with a relative state change.

```java
package example;

public class Switch extends Module {
  private boolean on = false;

  @ACTION
  public boolean turnOn() {
    on = true;
    return true;
  }

  @ACTION
  public boolean turnOff() {
    on = false;
    return true;
  }
}
```

--------------------------------

### Custom SwitchEvent: Basic Implementation (Java)

Source: https://guide.astralanguage.com/en/latest/modules/events

This Java code outlines a basic custom event class, `SwitchEvent`, implementing ASTRA's `Event` interface. It includes the required `getSource()`, `accept()`, and `signature()` methods, with a focus on defining a unique event signature for ASTRA's interpreter.

```java
public class SwitchEvent implements Event {
    @Override
    public Event accept(LogicVisitor arg0) {
        return null;
    }

    @Override
    public Object getSource() {
        return null;
    }

    @Override
    public String signature() {
        return "$swe;";
    }
}
```

--------------------------------

### Astral Language Rule with AND Operator

Source: https://guide.astralanguage.com/en/latest/reference

An example of an Astral Language rule using the AND operator to define a 'shoot' action when a player has the ball, is being closed down, and is in range of the opposition goal. This illustrates conditional execution based on multiple beliefs.

```Astral Language
rule +!decide() :
        has("ball") & is("closed_down") &
        close("opposition_goal") {
    shoot();
}

```

--------------------------------

### Define a basic ASTRA agent program

Source: https://guide.astralanguage.com/en/latest/deploying

This ASTRA code defines a simple agent named 'Main' that utilizes the Console module to print 'Hello World, ASTRA' to the console upon execution. It serves as the equivalent of a main method in Java.

```astra
agent Main {
    module Console C;

    rule +!main(list args) {
        C.println("Hello World, ASTRA");
    }
}

```

--------------------------------

### Astral Language Rule with OR Operator

Source: https://guide.astralanguage.com/en/latest/reference

An example of an Astral Language rule using the OR operator to define an 'eat' action. The action is executed if the agent likes the food 'F' OR tolerates the food 'F', showcasing disjunction in rule conditions.

```Astral Language
rule +!eat(string F) : likes(F) | tolerates(F) {
    body.eat(F);
}

```

--------------------------------

### ASTRA Belief Querying with Types and Console Output

Source: https://guide.astralanguage.com/en/latest/astra-concepts

Illustrates ASTRA's belief query mechanism using the 'query' keyword and defining custom belief types with the 'types' keyword. It initializes a belief, queries for its existence, and then queries for a non-existent belief, affecting program flow. Requires the Console module.

```ASTRA
agent Query {
    module Console C;

    types eg {
        formula is(string, string);
    }

    initial !init();
    initial is("rem", "happy");

    rule +!init() {
        C.println("starting");
        query(is("rem", "happy"));
        C.println("first hurdle passed");
        query(is("rem", "sad"));
        C.println("ending");
    }
}
```

--------------------------------

### Declare Variables in ASTRA Triggering Event

Source: https://guide.astralanguage.com/en/latest/reference

Declares variables implicitly within a rule's triggering event to extract information for use in the associated plan. This example shows extracting two integers X and Y and creating a belief with their sum.

```ASTRA
rule +!addition(int X, int Y) {
    +result(X, Y, X+Y);
}
```

--------------------------------

### Run ASTRA Application with Maven

Source: https://guide.astralanguage.com/en/latest/multiple

Commands to run the ASTRA application using Maven. The default goal executes the build process, while 'mvn clean compile astra:deploy' provides a more explicit way to clean, compile, and deploy the agent application.

```bash
mvn

```

```bash
mvn clean compile astra:deploy

```

--------------------------------

### Create Maven Project Structure for ASTRA Module

Source: https://guide.astralanguage.com/en/latest/modules/sensors

Defines the directory structure for an ASTRA project, including the main source folder and the pom.xml file. This is a prerequisite for building ASTRA modules.

```text
|-- src
|    |-- main
|          |-- astra
|-- pom.xml
```

--------------------------------

### ASTRA Belief Type Definitions

Source: https://guide.astralanguage.com/en/latest/astra-concepts

Defines custom types for beliefs in ASTRA. The `types` construct allows developers to specify expected data types for belief arguments, enabling compile-time type checking and reducing errors. This example shows definitions for `switch` and `light` beliefs.

```ASTRA
types lightExample {
    formula switch(string); // the argument should be "up" or "down"
    formula light(string); // the argument should be "on" or "off"
}

```

--------------------------------

### Console Output using ASTRA

Source: https://guide.astralanguage.com/en/latest/libraries

Demonstrates how to print messages to the console using the ASTRA `Console` module. It shows the declaration of a `Console` module instance and the usage of the `println` action.

```astra
module Console con;

// ... later in the code
con.println("Hello World");
```

```astra
module Console console;

// ... later in the code
console.println("Hello World");
```

--------------------------------

### Configure ASTRA Project with Maven (pom.xml)

Source: https://guide.astralanguage.com/en/latest/modules/sensors

Sets up the Maven build configuration for an ASTRA project. It specifies project coordinates, parent ASTRA base, and the astra-maven-plugin for building and deploying ASTRA modules. Users should customize groupId and artifactId.

```xml
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <groupId>examples</groupId>
    <artifactId>module-sensors</artifactId>
    <version>1.4.1</version>

    <parent>
        <groupId>com.astralanguage</groupId>
        <artifactId>astra-base</artifactId>
        <version>1.4.1</version>
    </parent>

    <build>
        <defaultGoal>clean compile astra:deploy</defaultGoal>
        <plugins>
            <plugin>
                <groupId>com.astralanguage</groupId>
                <artifactId>astra-maven-plugin</artifactId>
                <version>1.4.1</version>
            </plugin>
        </plugins>
    </build>
</project>
```

--------------------------------

### Implement Astral Rules for State Changes

Source: https://guide.astralanguage.com/en/latest/astra-concepts

This snippet illustrates the definition of rules in Astral to manage state changes. It includes rules for handling light states, flipping switches, and transitioning between switch states based on defined transitions and current conditions.

```Astral
rule +!light(string X) : light(X) { }

rule +!light(string X) {
    !flipSwitch();
}

rule +!flipSwitch() : switch(string X) & switchTransition(X, string Y) {
    !switch(Y);
}

// if the switch is already in state X, do nothing
rule +!switch(string X) : switch(X) {}

// if the switch is not is state X, change it to state X
rule +!switch(string X): switch(string Y) & switchTransition(Y, X) {
    -switch(Y);
    +switch(X);
}

rule +switch(string X) : light(string Y) & lightTransition(Y, string Z) {
    -light(Y);
    +light(Z);
}
```

--------------------------------

### ASTRA Belief Update for State Modification

Source: https://guide.astralanguage.com/en/latest/astra-concepts

Shows how ASTRA agents modify their internal state using belief update operators ('+' for addition, '-' for deletion). This example toggles a 'light' belief between 'on' and 'off' states, printing messages accordingly. It defines a custom belief type 'light'.

```ASTRA
agent Uppy {
    module Console C;

    types uppy {
        formula light(string);
    }

    initial light("on");

    rule +light("on") {
        C.println("the light is on, turn it off!");
        -light("on");
        +light("off");
    }
    
    rule +light("off") {
        C.println("the light is off, turn it on!");
        -light("off");
        +light("on");
    }
}
```

--------------------------------

### Overriding Default Behavior with Rule Order in ASTRA

Source: https://guide.astralanguage.com/en/latest/astra-concepts

Illustrates how ASTRA uses rule order to manage behavior. Specific rules, like handling `light("on")`, can override more general rules, such as the default behavior for `!light("on")` when the context is omitted.

```ASTRA
rule +!light("on") : light("on") {}

rule +!light("on") {
    !flipSwitch();
}

```

--------------------------------

### Generate ASTRA Project using Maven Archetype

Source: https://guide.astralanguage.com/en/latest/modules/events

This command uses the Maven archetype mechanism to quickly generate a new ASTRA project. It sets the archetype coordinates and defines the project's group ID, artifact ID, and version. Customize the groupId and artifactId as needed.

```bash
mvn archetype:generate \
    -DarchetypeGroupId=com.astralanguage \
    -DarchetypeArtifactId=astra-archetype \
    -DarchetypeVersion=1.0.2 \
    -DgroupId=examples \
    -DartifactId=module-events \
    -Dversion=0.1.0

```

--------------------------------

### Configure Maven to run a specific ASTRA agent

Source: https://guide.astralanguage.com/en/latest/deploying

These Maven configurations demonstrate how to specify a non-default ASTRA agent to run. The '<astra.main>' property can be set in the pom.xml file or overridden via the command line using '-Dastra.main=<AgentName>'.

```xml
<properties>
    <astra.main>Namey</astra.main>
</properties>

```

```bash
mvn -Dastra.main=Namey

```

--------------------------------

### Link SwitchEvent and Register Unifier in ASTRA Module

Source: https://guide.astralanguage.com/en/latest/modules/events

This ASTRA module code demonstrates how to link a SwitchEvent to its corresponding module and register the SwitchEventUnifier. It includes a static initializer to register the unifier, an @ACTION method 'flip' to generate SwitchEvents, and an @EVENT method to declare how the event is created.

```java
public class Switch extends Module {
  static {
    Unifier.eventFactory.put(SwitchEvent.class, new SwitchEventUnifier());
  }

  private boolean on = false;

  @ACTION
  public boolean flip() {
    on = !on;
    agent.addEvent(new SwitchEvent(
      Primitive.newPrimitive(on ? "on":"off")
    ));
    return true;
  }


  @EVENT( symbols={}, types = {"string"}, signature = "$swe")
  public Event event(Term state) {
      return new SwitchEvent(state);
  }
}
```

--------------------------------

### Refining Light Control with !flipSwitch() Subgoal in ASTRA

Source: https://guide.astralanguage.com/en/latest/astra-concepts

This snippet demonstrates an improved approach to controlling the light by introducing a `!flipSwitch()` subgoal instead of directly manipulating the light state. This abstraction allows for more flexible switch logic.

```ASTRA
rule +!light("on") {
    !flipSwitch();
}

```

--------------------------------

### Setting Initial Agent Belief for Light Switch State in Java

Source: https://guide.astralanguage.com/en/latest/modules/actions

Overrides the setAgent() method to initialize an agent's belief about the light switch's state. It creates a Predicate representing the current 'on' or 'off' state and adds it to the agent's beliefs.

```java
package example;

public class Switch extends Module {
  private boolean on = false;

  public void setAgent(Agent agent) {
    super.setAgent(agent);

    Predicate belief = new Predicate("switch", new Term[] {
      Primitive.newPrimitive(on ? "on":"off")
    });
    agent.beliefs().addBelief(belief);
  }

  @ACTION
  public boolean flip() {
    on = !on;
    return true;
  }
}
```
Tokens:
Raw