Learning Objectives

Note: inspired by and often copied verbatim from Lesson: Pico State the original second lesson.

After completing this lesson, you will be able to do the following:

• Explain what entity variables are.
• Use rules to mutate entity variables.
• Use functions to simplify usage of entity variables.
• Use entity variables to create persistent picos.
• Understand how rules can use explicit events to chain rules

Prerequisites

You should have completed the following lessons:

• node pico-engine quickstart

• Lesson 1. events and queries

Picos Represent State

Picos (Persistent Compute Objects) contain state that can be changed in response to events. Picos persist their state using entity variables.

Add Persistence to hello_world

Let's change the hello_world ruleset to know your name by default.

To do this we will need:

1. An entity variable to store your name in. 
2. A new rule that stores your name in that entity variable.

Before starting, visit the "Rulesets" tab for your Pico, and notice that your Pico has no entity variables for the "hello_world" ruleset.

Create a rule and name it store_name. Have it select on event domain hello and event type name.

We'll have the rule expect an event attribute named "name". We will declare a variable for the name (also named "name") and log it in the prelude. 

The rule store_name will send a directive named store_name with option name assigned giving the passed parameter name we are going to set.  The directive will allow us to know that the rule is working without having to look at the logs.

Entity variables can only be set in the postlude. We use the always form of the postlude so that this postlude is always evaluated. Just mentioning the name of the entity variable (yet another "name") will cause it to be created when the rule fires.

  rule store_name {
    select when hello name
    pre{
      passed_name = event:attr("name").klog("our passed in Name: ")
    }
    send_directive("store_name") with
      name = passed_name
    always{
      ent:name := passed_name
    }
  }

{ "domain": "hello", "type": "name", "attrs": [ "name" ] }

  rule hello_world {
    select when echo hello
    pre{
      name = event:attr("name").defaultsTo(ent:name,"use stored name")
    }
    send_directive("say") with
      something = "Hello " + name
  }