Samovar

This is a literate test suite for Samovar, in Falderal format. It describes Samovar, and includes examples inline, which consist of valid Samovar descriptions and what you might expect from running them.

Falderal can actually run these examples and check that they actually produce these results, so these examples serve as tests.

However, Samovar only specifies the declarative meaning of a Samovar description, not the operational aspect. An implementation of Samovar is allowed to do pretty much whatever it likes. However, there are certain behaviours that many Samovar implementations (and in particular, the reference implementation) would be reasonably expected to support, and it is this behaviour which these examples will illustrate.

-> Functionality "Run Samovar Simulation" is implemented by shell command
-> "python2 bin/samovar %(test-body-file) --min-events 4 --deterministic"
-> but only if shell command "command -v python2" succeeds

-> Functionality "Run Samovar Simulation" is implemented by shell command
-> "python3 bin/samovar %(test-body-file) --min-events 4 --deterministic"
-> but only if shell command "command -v python3" succeeds

-> Tests for functionality "Run Samovar Simulation"

Basic Syntax

A minimally valid Samovar description looks like this. (The ===> is not part of the Samovar description. It indicates what output we would expect from this. In this case, nothing.)

scenario A {}

===>

You can include comments with //.

// This is my minimal Samovar description.
scenario A {}

===>

The name of a scenario must begin with a letter or underscore, and can consist of letters, numbers, hyphens, underscores, and apostrophes.

The same rules apply to most other "words" appearing in a Samovar description.

scenario Pin_afore-isn't-1000 {
    this-is-a-constructor(this-is-an-atom).
}

===>

Basic Semantics

The basic unit of a Samovar world is a scenario. Inside a scenario, facts are defined with propositions, and possible events are defined with event rules. Each event rule looks like

[A] X [B]

which can be read

If A holds, then X is a possible action to take, and if you do take it, you must make B hold afterwards.

By "hold" we mean "matches the current set of facts."

As an example,

[actor(α),item(β),~holding(α,β)] α picks up the β. [holding(α,β)]

Which can be read as

If α is an actor and β is an item and α is not holding β, then one possible action is to write out 'α picks up the β' and assert that α is now holding β.

The Greek letters represent variables, which are bound to concrete terms during the pattern-matching process. (Variables can also be written with Latin letters, and given names longer than one character, by introducing them with a question mark, like this: ?var.)

Now, we can add a complementary rule:

[actor(α),item(β),holding(α,β)] α puts down the β. [~holding(α,β)]

And we can package this all into a scenario:

scenario IgnatzWithBrick {

  [actor(α),item(β),~holding(α,β)]  α picks up the β.   [holding(α,β)]
  [actor(α),item(β),holding(α,β)]   α puts down the β.  [~holding(α,β)]

  actor(Ignatz).
  item(brick).

  goal [].
}
===> Ignatz picks up the brick.
===> Ignatz puts down the brick.
===> Ignatz picks up the brick.
===> Ignatz puts down the brick.

Scenarios

The basic unit of a Samovar world is a scenario. A scenario may contain any number of propositions and event rules, and an optional goal, in any order.

scenario IgnatzWithBrick {

  [actor(α),item(β),~holding(α,β)]  α picks up the β.   [holding(α,β)]
  [actor(α),item(β),holding(α,β)]   α puts down the β.  [~holding(α,β)]

  actor(Ignatz).
  item(brick).

  goal [].
}
===> Ignatz picks up the brick.
===> Ignatz puts down the brick.
===> Ignatz picks up the brick.
===> Ignatz puts down the brick.

A source file may contain more than one scenario. By default, our implementation of Samovar runs a simulation on each of the scenarios that has a goal defined, even if that goal is empty.

scenario MollyWithBrick {

  [actor(α),item(β),~holding(α,β)]  α picks up the β.   [holding(α,β)]
  [actor(α),item(β),holding(α,β)]   α puts down the β.  [~holding(α,β)]

  actor(Molly).
  item(brick).

}

scenario IgnatzWithBrick {

  [actor(α),item(β),~holding(α,β)]  α picks up the β.   [holding(α,β)]
  [actor(α),item(β),holding(α,β)]   α puts down the β.  [~holding(α,β)]

  actor(Ignatz).
  item(brick).

  goal [].
}
===> Ignatz picks up the brick.
===> Ignatz puts down the brick.
===> Ignatz picks up the brick.
===> Ignatz puts down the brick.

Scenarios can import the event rules and propositions from other scenarios. This makes a scenario a good place to collect a setting, or a group of characters who will appear together in scenes. These "library" scenarios should have no goal, as we don't want to generate simulations for them.

scenario ItemRules {
  [actor(α),item(β),~holding(α,β)]  α picks up the β.   [holding(α,β)]
  [actor(α),item(β),holding(α,β)]   α puts down the β.  [~holding(α,β)]
}
scenario Actors {
  actor(Ignatz).
}
scenario Brickyard {
  item(brick).
}
scenario Main {
  import ItemRules.
  import Actors.
  import Brickyard.
  goal [].
}
===> Ignatz picks up the brick.
===> Ignatz puts down the brick.
===> Ignatz picks up the brick.
===> Ignatz puts down the brick.

There is nothing stopping an implementation from allowing a Samovar description to be spread over multiple source files, but there is no facility to reference one source file from another in Samovar, so how they are located and collected is up to the implementation.

Goals

A scenario is run until it meets the goal. How it meets the goal is up to the implementation. Our implementation generates events randomly, until it comes up with a series of events wherein the goal is met, generating more events each time.

A goal of [], as above, is trivially met.

Generation of events does not stop immediately once the goal is met. A number of events are generated, and then the check is made.

scenario UntilHoldBrick {
  [actor(α),item(β),~holding(α,β)]  α picks up the β.   [holding(α,β)]
  [actor(α),item(β),holding(α,β)]   α puts down the β.  [~holding(α,β)]
  actor(Ignatz).
  item(brick).
  item(oilcan).
  goal [holding(Ignatz,brick)].
}
===> Ignatz picks up the brick.
===> Ignatz picks up the oilcan.
===> Ignatz puts down the oilcan.
===> Ignatz picks up the oilcan.
===> Ignatz puts down the oilcan.
===> Ignatz picks up the oilcan.
===> Ignatz puts down the oilcan.
===> Ignatz picks up the oilcan.

Event rules

We've already seen that an event may be selected if its pattern matches the current set of facts. Let's take a closer look at how patterns are matched.

If a variable appears more than once in a pattern, it must match the same term in each occurrence.

scenario IgnatzAndMolly {
  [actor(?A),sitting(?A)] ?A was sitting. []
  actor(Ignatz).
  sitting(Molly).

  goal [].
}
===>

No two variables can match with the same term. This may seem somewhat unusual, if you're familiar with Prolog or other languages with pattern-matching, but it prevents a "reflexive" matches (for example, "Alice looks at Alice") that don't actually come up very often when telling a story.

scenario IgnatzAndMolly {
  [actor(?A),actor(?B)] ?A looks at ?B. [~actor(?A),~actor(?B)]
  actor(Ignatz).
  actor(Molly).

  goal [].
}
===> Ignatz looks at Molly.

scenario IgnatzWithoutMolly {
  [actor(?A),actor(?B)] ?A looks at ?B. [~actor(?A),~actor(?B)]
  actor(Ignatz).

  goal [].
}
===>

A variable may appear in the pattern that is not used in the text or the consequences.

scenario IgnatzAndMolly {
  [actor(?A)] Someone. []
  actor(Ignatz).
  actor(Molly).

  goal [].
}
===> Someone.
===> Someone.
===> Someone.
===> Someone.

But a variable may not appear in the text if it did not appear in the pattern.

scenario IgnatzAndMolly {
  [actor(?A)] ?B sneezes. []
  actor(Ignatz).
  actor(Molly).

  goal [].
}
???> SamovarSyntaxError

Likewise, a variable may not appear in the consequences if it did not appear in the pattern.

scenario IgnatzAndMolly {
  [actor(?A)] Someone sneezes. [~actor(?B)]
  actor(Ignatz).
  actor(Molly).

  goal [].
}
???> SamovarSyntaxError

A special "wildcard" variable, ?_, matches any term, and does not unify.

scenario UntilHoldBrick {
  [actor(?_),item(?_)]  There was an actor and an item.  [~actor(Ignatz)]
  actor(Ignatz).
  item(brick).
  goal [].
}
===> There was an actor and an item.

?_ cannot appear in the text or the consequences of a rule, even if it appears in the pattern.

scenario UntilHoldBrick {
  [actor(?_),item(?_)]  There was ?_ and ?_.  [~actor(Ignatz)]
  actor(Ignatz).
  item(brick).
  goal [].
}
???> SamovarSyntaxError

scenario UntilHoldBrick {
  [actor(?_),item(?_)]  There was an actor and an item.  [~actor(?_)]
  actor(Ignatz).
  item(brick).
  goal [].
}
???> SamovarSyntaxError

The text inside the event rule is typically expanded with the values that the pattern variables matched.

scenario UntilHoldBrick {
  [actor(α),item(β),~holding(α,β)]  α picks up the β.   [holding(α,β)]
  actor(Ignatz).
  item(brick).
  goal [holding(Ignatz,brick)].
}
===> Ignatz picks up the brick.

The text may contain punctuation.

scenario UntilHoldBrick {
  [actor(α),item(β),~holding(α,β)]  "What a lovely β this is!" says α, picking it up.  [holding(α,β)]
  actor(Ignatz).
  item(brick).
  goal [holding(Ignatz,brick)].
}
===> "What a lovely brick this is!" says Ignatz, picking it up.

scenario UntilHoldBrick {
  [actor(?A),item(?I),~holding(?A,?I)]  "What a lovely ?I this is!" says ?A, picking it up.  [holding(?A,?I)]
  actor(Ignatz).
  item(brick).
  goal [holding(Ignatz,brick)].
}
===> "What a lovely brick this is!" says Ignatz, picking it up.

Punctuation should be preserved sensibly.

scenario UntilHoldBrick {
  [actor(α),item(β),~holding(α,β)]  "β, don't you know?" says α, picking it up.  [holding(α,β)]
  actor(Ignatz).
  item(brick).
  goal [holding(Ignatz,brick)].
}
===> "brick, don't you know?" says Ignatz, picking it up.

scenario UntilHoldBrick {
  [actor(?A),item(?I),~holding(?A,?I)]  "?I, don't you know?" says ?A, picking it up.  [holding(?A,?I)]
  actor(Ignatz).
  item(brick).
  goal [holding(Ignatz,brick)].
}
===> "brick, don't you know?" says Ignatz, picking it up.

An event rule may come with some variables pre-bound.

scenario UntilHoldBrick {
  [actor(?A),item(?I),~holding(?A,?I) where ?I=brick] ?A picked up the ?I. [holding(?A,?I)]
  actor(Ignatz).
  item(brick).
  item(banana).
  goal [holding(Ignatz,brick)].
}
===> Ignatz picked up the brick.

A variable pre-bound in a where may appear in the text and consequences.

scenario IgnatzAndMolly {
  [actor(?A) where ?B=Molly] ?B sneezes. [sneezed(?B)]
  actor(Ignatz).
  actor(Molly).

  goal [].
}
===> Molly sneezes.
===> Molly sneezes.
===> Molly sneezes.
===> Molly sneezes.

There may be multiple bindings in a where clause. These may be seperated by commas.

scenario UntilHoldBrick {
  [actor(?A),item(?I),~holding(?A,?I) where ?A=Ignatz,?I=brick] ?A picked up the ?I. [holding(?A,?I)]
  actor(Ignatz).
  item(brick).
  item(banana).
  goal [holding(Ignatz,brick)].
}
===> Ignatz picked up the brick.

You can't put a where clause in the consequences.

scenario UntilHoldBrick {
  [actor(?A),item(?I),~holding(?A,?I)] ?A picked up the ?I. [holding(?A,?I) where ?A=Ignatz]
  actor(Ignatz).
  item(brick).
  item(banana).
  goal [holding(Ignatz,brick)].
}
???> SamovarSyntaxError

chairs

Somewhat uninteresting due to the deterministic randomness engine required to get the tests to be reproducible under both Python 2 and Python 3.

scenario Chairs {

  [actor(ρ)∧¬sitting(ρ)]
    ρ walks around the room.
  []

  [actor(ρ)∧¬sitting(ρ)∧nearby(κ)∧empty(κ)]
    ρ sits down in the κ.
  [sitting(ρ)∧in(ρ,κ)∧¬empty(κ)]

  [actor(ρ)∧sitting(ρ)∧in(ρ,κ)]
    ρ leans back in the κ.
  []

  [actor(ρ)∧sitting(ρ)∧in(ρ,κ)]
    ρ gets up and stretches.
  [¬sitting(ρ)∧¬in(ρ,κ)∧empty(κ)]

  actor(Hastings).
  actor(Petersen).
  actor(Wembley).
  nearby(chair). empty(chair).
  nearby(recliner).
  empty(recliner).
  nearby(sofa).
  empty(sofa).

  goal [].
}
===> Hastings walks around the room.
===> Petersen walks around the room.
===> Hastings walks around the room.
===> Petersen walks around the room.

no need for functions

Samovar 0.1 had functions, but they were removed because they were not necessary. If you want to look up a property of some thing, you can just pattern-match for it. The example was

their(Alice) → her
their(Bob) → his

but we can just say

scenario ScratchesHead {

  [actor(ρ),possessive(ρ,ξ)]
    ρ scratches ξ head.
  []

  actor(Alice).
  possessive(Alice, her).
  actor(Bob).
  possessive(Bob, his).

  goal [].
}
===> Alice scratches her head.
===> Bob scratches his head.
===> Alice scratches her head.
===> Bob scratches his head.

This loses the nice property of the function name being a readable placeholder in the sentence, but you can now use named variables instead:

scenario ScratchesHead {

  [actor(?Actor),possessive(?Actor,?their)]
    ?Actor scratches ?their head.
  []

  actor(Alice).
  possessive(Alice, her).
  actor(Bob).
  possessive(Bob, his).

  goal [].
}
===> Alice scratches her head.
===> Bob scratches his head.
===> Alice scratches her head.
===> Bob scratches his head.