textworld.logic

class textworld.logic.Action(name, preconditions, postconditions)

Bases: object

An action in the environment.

Create an Action.

Parameters:

• name (str) – The name of this action.

• preconditions (Iterable[Proposition]) – The preconditions that must hold before this action is applied.

• postconditions (Iterable[Proposition]) – The conditions that replace the preconditions once applied.

classmethod deserialize(data)

Return type:

Action

format_command(mapping={})

inverse(name=None)

Invert the direction of this action.

Parameters:

name (optional) – The new name for the inverse action.

Return type:

An action that does the exact opposite of this one.

classmethod parse(expr)

Parse an action expression.

Parameters:

expr (str) – The string to parse, in the form name :: [$]proposition [& [$]proposition]* -> proposition [& proposition]*.

Return type:

Action

serialize()

Return type:

Mapping

property added: Collection[Proposition]

All the new propositions being introduced by this action.

Return type:

Collection[Proposition]

property all_propositions: Collection[Proposition]

All the pre- and post-conditions.

Return type:

Collection[Proposition]

property removed: Collection[Proposition]

All the old propositions being removed by this action.

Return type:

Collection[Proposition]

property variables

class textworld.logic.Alias(pattern, replacement)

Bases: object

A shorthand predicate alias.

expand(predicate)

Expand a use of this alias into its replacement.

Return type:

Collection[Predicate]

class textworld.logic.GameLogic

Bases: object

The logic for a game (types, rules, etc.).

classmethod deserialize(data)

Return type:

GameLogic

classmethod load(paths)

normalize_rule(rule)

Return type:

Rule

classmethod parse(cls, document)

Return type:

GameLogic

serialize()

Return type:

str

class textworld.logic.Inform7Command(rule, command, event)

Bases: object

Information about an Inform 7 command.

class textworld.logic.Inform7Logic

Bases: object

The Inform 7 bindings of a GameLogic.

class textworld.logic.Inform7Predicate(predicate, source)

Bases: object

Information about an Inform 7 predicate.

class textworld.logic.Inform7Type(name, kind, definition=None)

Bases: object

Information about an Inform 7 kind.

class textworld.logic.Placeholder(name, type=None)

Bases: object

A symbolic placeholder for a variable in a Predicate.

Create a Placeholder.

Parameters:

• name (str) – The name of this placeholder.

• type (optional) – The type of variable represented. Defaults to the name with any trailing apostrophes stripped.

classmethod deserialize(data)

Return type:

Placeholder

classmethod parse(expr)

Parse a placeholder expression.

Parameters:

expr (str) – The string to parse, in the form name or name: type.

Return type:

Placeholder

serialize()

Return type:

Mapping

name

type

class textworld.logic.Predicate(name, parameters)

Bases: object

A boolean-valued function over variables.

Create a Predicate.

Parameters:

• name (str) – The name of this predicate.

• parameters (Iterable[Placeholder]) – The symbolic arguments to this predicate.

classmethod deserialize(data)

Return type:

Predicate

instantiate(mapping)

Instantiate this predicate with the given mapping.

Parameters:

mapping (Mapping[Placeholder, Variable]) – A mapping from Placeholders to Variables.

Return type:

The instantiated Proposition with each Placeholder mapped to the corresponding Variable.

match(proposition)

Match this predicate against a concrete proposition.

Parameters:

proposition (Proposition) – The proposition to match against.

Return type:

Optional[Mapping[Placeholder, Variable]]

Returns:

• The mapping from placeholders to variables such that self.instantiate(mapping) == proposition, or None if no

• such mapping exists.

negate()

Return type:

Predicate

classmethod parse(expr)

Parse a predicate expression.

Parameters:

expr (str) – The string to parse, in the form name(placeholder [, placeholder]*).

Return type:

Predicate

serialize()

Return type:

Mapping

substitute(mapping)

Copy this predicate, substituting certain placeholders for others.

Parameters:

mapping (Mapping[Placeholder, Placeholder]) – A mapping from old to new placeholders.

Return type:

Predicate

property is_negation: bool

Return type:

bool

property names: Collection[str]

The names of the placeholders in this predicate.

Return type:

Collection[str]

property types: Collection[str]

The types of the placeholders in this predicate.

Return type:

Collection[str]

class textworld.logic.Proposition(name, arguments=[])

Bases: NewBase

An instantiated Predicate, with concrete variables for each placeholder.

Create a Proposition.

Parameters:

• name (str) – The name of the proposition.

• arguments (Iterable[Variable]) – The variables this proposition is applied to.

classmethod deserialize(data)

Return type:

Proposition

negate()

Return type:

Proposition

classmethod parse(expr)

Parse a proposition expression.

Parameters:

expr (str) – The string to parse, in the form name(variable [, variable]*).

Return type:

Proposition

serialize()

Return type:

Mapping

arguments

property is_negation: bool

Return type:

bool

name

property names: Collection[str]

The names of the variables in this proposition.

Return type:

Collection[str]

signature

property types: Collection[str]

The types of the variables in this proposition.

Return type:

Collection[str]

class textworld.logic.Rule(name, preconditions, postconditions)

Bases: object

A template for an action.

Create a Rule.

Parameters:

• name (str) – The name of this rule.

• preconditions (Iterable[Predicate]) – The preconditions that must hold before this rule is applied.

• postconditions (Iterable[Predicate]) – The conditions that replace the preconditions once applied.

classmethod deserialize(data)

Return type:

Rule

instantiate(mapping)

Instantiate this rule with the given mapping.

Parameters:

mapping (Mapping[Placeholder, Variable]) – A mapping from Placeholders to Variables.

Return type:

The instantiated Action with each Placeholder mapped to the corresponding Variable.

inverse(name=None)

Invert the direction of this rule.

Parameters:

name (optional) – The new name for the inverse rule.

Return type:

A rule that does the exact opposite of this one.

match(action)

Match this rule against a concrete action.

Parameters:

action (Action) – The action to match against.

Return type:

Optional[Mapping[Placeholder, Variable]]

Returns:

• The mapping from placeholders to variables such that self.instantiate(mapping) == action, or None if no such

• mapping exists.

classmethod parse(expr)

Parse a rule expression.

Parameters:

expr (str) – The string to parse, in the form name :: [$]predicate [& [$]predicate]* -> predicate [& predicate]*.

Return type:

Rule

classmethod parse_conjunctive_query(expr)

Parse a conjunctive query expression framed as a rule.

A conjunctive query is similar to a Rule’s precondition, but it doesn’t allow carry-over predicate (i.e., starting with a $).

Parameters:

expr (str) – The string to parse, in the form name :: predicate [& predicate]*.

Return type:

Rule

serialize()

Return type:

Mapping

substitute(mapping, name=None)

Copy this rule, substituting certain placeholders for others.

Parameters:

mapping (Mapping[Placeholder, Placeholder]) – A mapping from old to new placeholders.

Return type:

Rule

property added: Collection[Predicate]

All the new predicates being introduced by this rule.

Return type:

Collection[Predicate]

property all_predicates: Iterable[Predicate]

All the pre- and post-conditions.

Return type:

Iterable[Predicate]

property removed: Collection[Predicate]

All the old predicates being removed by this rule.

Return type:

Collection[Predicate]

class textworld.logic.Signature(name, types)

Bases: NewBase

The type signature of a Predicate or Proposition.

Create a Signature.

Parameters:

• name (str) – The name of the proposition/predicate this signature is for.

• types (Iterable[str]) – The types of the parameters to the proposition/predicate.

classmethod parse(expr)

Parse a signature expression.

Parameters:

expr (str) – The string to parse, in the form name(type [, type]*).

Return type:

Signature

name

types

class textworld.logic.State(logic, facts=None)

Bases: object

The current state of a world.

Create a State.

Parameters:

• logic (GameLogic) – The logic for this state’s game.

• facts (optional) – The facts that will be true in this state.

add_fact(prop)

Add a fact to the state.

add_facts(props)

Add some facts to the state.

all_applicable_actions(rules, mapping=None)

Get all the rule instantiations that would be valid actions in this state.

Parameters:

• rules (Iterable[Rule]) – The possible rules to instantiate.

• mapping (optional) – An initial mapping to start from, constraining the possible instantiations.

Return type:

The actions that can be instantiated from the given rules in this state.

all_assignments(rule, mapping=None, partial=False, allow_partial=None)

Find all possible placeholder assignments that would allow a rule to be instantiated in this state.

Parameters:

• rule (Rule) – The rule to instantiate.

• mapping (optional) – An initial mapping to start from, constraining the possible instantiations.

• partial (optional) – Whether incomplete mappings, that would require new variables or propositions, are allowed.

• allow_partial (optional) – A callback function that returns whether a partial match may involve the given placeholder.

Return type:

Iterable[Mapping[Placeholder, Optional[Variable]]]

Returns:

• The possible mappings for instantiating the rule. Partial mappings requiring new variables will have None in

• place of existing Variables.

all_instantiations(rule, mapping=None)

Find all possible actions that can be instantiated from a rule in this state.

Parameters:

• rule (Rule) – The rule to instantiate.

• mapping (optional) – An initial mapping to start from, constraining the possible instantiations.

Return type:

The actions that can be instantiated from the rule in this state.

apply(action)

Apply an action to the state.

Parameters:

action (Action) – The action to apply.

Return type:

Whether the action could be applied (i.e. whether the preconditions were met).

apply_on_copy(action)

Apply an action to a copy of this state.

Parameters:

action (Action) – The action to apply.

Return type:

Optional[State]

Returns:

• The copied state after the action has been applied or None if action

• wasn’t applicable.

are_facts(props)

Returns whether the propositions are all true in this state.

Return type:

bool

copy()

Create a copy of this state.

Return type:

State

classmethod deserialize(data)

Deserialize a State object from data.

Return type:

State

facts_with_signature(sig)

Returns all the known facts with the given signature.

Return type:

Set[Proposition]

has_variable(var)

Returns whether this state is aware of the given variable.

Return type:

bool

is_applicable(action)

Check if an action is applicable in this state (i.e. its preconditions are met).

Return type:

bool

is_fact(prop)

Returns whether a proposition is true in this state.

Return type:

bool

is_sequence_applicable(actions)

Check if a sequence of actions are all applicable in this state.

Return type:

bool

remove_fact(prop)

Remove a fact from the state.

remove_facts(props)

Remove some facts from the state.

serialize()

Serialize this state.

Return type:

Sequence

variable_named(name)

Returns the variable with the given name, if known.

Return type:

Variable

variables_of_type(type)

Returns all the known variables of the given type.

Return type:

Set[Variable]

property facts: Iterable[Proposition]

All the facts in the current state.

Return type:

Iterable[Proposition]

property variables: Iterable[Variable]

All the variables tracked by the current state.

Return type:

Iterable[Variable]

class textworld.logic.Type(name, parents)

Bases: object

A variable type.

has_subtype_named(name)

Return type:

bool

has_supertype_named(name)

Return type:

bool

is_subtype_of(other)

Return type:

bool

is_supertype_of(other)

Return type:

bool

property ancestors: Iterable[Type]

The ancestors of this type (not including itself).

Return type:

Iterable[Type]

property child_types: Iterable[Type]

The direct children of this type.

Return type:

Iterable[Type]

property children: Iterable[str]

The names of the direct children of this type.

Return type:

Iterable[str]

property descendants: Iterable[Type]

The descendants of this type (not including itself).

Return type:

Iterable[Type]

property parent_types: Iterable[Type]

The parents of this type as Type objects.

Return type:

Iterable[Type]

property subtypes: Iterable[Type]

This type and its descendants.

Return type:

Iterable[Type]

property supertypes: Iterable[Type]

This type and its ancestors.

Return type:

Iterable[Type]

class textworld.logic.TypeHierarchy

Bases: object

A hierarchy of types.

add(type)

closure(type, expand)

Compute the transitive closure in a type lattice according to some type relationship (generally direct sub-/super-types).

Such a lattice may look something like this:

  A
 / \
B   C
 \ /
  D

so the closure of D would be something like [B, C, A].

Return type:

Iterable[Type]

get(name)

Return type:

Type

multi_ancestors(types)

Compute the ancestral closure of a sequence of types. If these are the types of some variables, the result will be all the function parameter types that could also accept those variables.

Return type:

Iterable[Collection[Type]]

multi_closure(types, expand)

Compute the transitive closure of a sequence of types in a type lattice induced by some per-type relationship (generally direct sub-/super-types).

For a single type, such a lattice may look something like this:

  A
 / \
B   C
 \ /
  D

so the closure of D would be something like [B, C, A]. For multiple types at once, the lattice is more complicated:

            __ (A,A) __
           /   |   |   \
      (A,B) (A,C) (B,A) (C,A)
  *******************************
(A,D) (B,B) (B,C) (C,B) (C,C) (D,A)
  *******************************
      (B,D) (C,D) (D,B) (D,C)
           \   |   |   /
            \_ (D,D) _/

Return type:

Iterable[Collection[Type]]

multi_descendants(types)

Compute the descendant closure of a sequence of types. If these are the types of some function parameters, the result will be all the variable types that could also be passed to this function.

Return type:

Iterable[Collection[Type]]

multi_subtypes(types)

Computes the descendant closure of a sequence of types, including the initial types.

Return type:

List[Collection[Type]]

multi_supertypes(types)

Computes the ancestral closure of a sequence of types, including the initial types.

Return type:

Iterable[Collection[Type]]

class textworld.logic.Variable(name, type=None)

Bases: object

A variable representing an object in a world.

Create a Variable.

Parameters:

• name (str) – The (unique) name of the variable.

• type (optional) – The type of the variable. Defaults to the same as the name.

classmethod deserialize(data)

Return type:

Variable

is_a(type)

Return type:

bool

classmethod parse(expr)

Parse a variable expression.

Parameters:

expr (str) – The string to parse, in the form name or name: type.

Return type:

Variable

serialize()

Return type:

Mapping

name

type

class textworld.logic.model.ActionNode(_parent=None, _children=None, ast=None, ctx=None, parseinfo=None, name=None, postconditions=None, preconditions=None)

Bases: ModelBase

name: Any = None

postconditions: Any = None

preconditions: Any = None

class textworld.logic.model.ActionPreconditionNode(_parent=None, _children=None, ast=None, ctx=None, parseinfo=None, condition=None, preserve=None)

Bases: ModelBase

condition: Any = None

preserve: Any = None

class textworld.logic.model.AliasNode(_parent=None, _children=None, ast=None, ctx=None, parseinfo=None, lhs=None, rhs=None)

Bases: ModelBase

lhs: Any = None

rhs: Any = None

class textworld.logic.model.ConstraintsNode(_parent=None, _children=None, ast=None, ctx=None, parseinfo=None, constraints=None)

Bases: ModelBase

constraints: Any = None

class textworld.logic.model.DocumentNode(_parent=None, _children=None, ast=None, ctx=None, parseinfo=None, types=None)

Bases: ModelBase

types: Any = None

class textworld.logic.model.GameLogicModelBuilderSemantics(context=None, types=None)

Bases: ModelBuilderSemantics

class textworld.logic.model.Inform7CodeNode(_parent=None, _children=None, ast=None, ctx=None, parseinfo=None, code=None)

Bases: ModelBase

code: Any = None

class textworld.logic.model.Inform7CommandNode(_parent=None, _children=None, ast=None, ctx=None, parseinfo=None, command=None, event=None, rule=None)

Bases: ModelBase

command: Any = None

event: Any = None

rule: Any = None

class textworld.logic.model.Inform7CommandsNode(_parent=None, _children=None, ast=None, ctx=None, parseinfo=None, commands=None)

Bases: ModelBase

commands: Any = None

class textworld.logic.model.Inform7Node(_parent=None, _children=None, ast=None, ctx=None, parseinfo=None, parts=None)

Bases: ModelBase

parts: Any = None

class textworld.logic.model.Inform7PredicateNode(_parent=None, _children=None, ast=None, ctx=None, parseinfo=None, predicate=None, source=None)

Bases: ModelBase

predicate: Any = None

source: Any = None

class textworld.logic.model.Inform7PredicatesNode(_parent=None, _children=None, ast=None, ctx=None, parseinfo=None, predicates=None)

Bases: ModelBase

predicates: Any = None

class textworld.logic.model.Inform7TypeNode(_parent=None, _children=None, ast=None, ctx=None, parseinfo=None, definition=None, kind=None)

Bases: ModelBase

definition: Any = None

kind: Any = None

class textworld.logic.model.ModelBase(_parent=None, _children=None, ast=None, ctx=None, parseinfo=None)

Bases: Node

class textworld.logic.model.PlaceholderNode(_parent=None, _children=None, ast=None, ctx=None, parseinfo=None, name=None, type=None)

Bases: ModelBase

name: Any = None

type: Any = None

class textworld.logic.model.PredicateNode(_parent=None, _children=None, ast=None, ctx=None, parseinfo=None, name=None, parameters=None)

Bases: ModelBase

name: Any = None

parameters: Any = None

class textworld.logic.model.PredicatesNode(_parent=None, _children=None, ast=None, ctx=None, parseinfo=None, predicates=None)

Bases: ModelBase

predicates: Any = None

class textworld.logic.model.PropositionNode(_parent=None, _children=None, ast=None, ctx=None, parseinfo=None, arguments=None, name=None)

Bases: ModelBase

arguments: Any = None

name: Any = None

class textworld.logic.model.ReverseRuleNode(_parent=None, _children=None, ast=None, ctx=None, parseinfo=None, lhs=None, rhs=None)

Bases: ModelBase

lhs: Any = None

rhs: Any = None

class textworld.logic.model.ReverseRulesNode(_parent=None, _children=None, ast=None, ctx=None, parseinfo=None, reverse_rules=None)

Bases: ModelBase

reverse_rules: Any = None

class textworld.logic.model.RuleNode(_parent=None, _children=None, ast=None, ctx=None, parseinfo=None, name=None, postconditions=None, preconditions=None)

Bases: ModelBase

name: Any = None

postconditions: Any = None

preconditions: Any = None

class textworld.logic.model.RulePreconditionNode(_parent=None, _children=None, ast=None, ctx=None, parseinfo=None, condition=None, preserve=None)

Bases: ModelBase

condition: Any = None

preserve: Any = None

class textworld.logic.model.RulesNode(_parent=None, _children=None, ast=None, ctx=None, parseinfo=None, rules=None)

Bases: ModelBase

rules: Any = None

class textworld.logic.model.SignatureNode(_parent=None, _children=None, ast=None, ctx=None, parseinfo=None, name=None, types=None)

Bases: ModelBase

name: Any = None

types: Any = None

class textworld.logic.model.TypeNode(_parent=None, _children=None, ast=None, ctx=None, parseinfo=None, name=None, parts=None, supertypes=None)

Bases: ModelBase

name: Any = None

parts: Any = None

supertypes: Any = None

class textworld.logic.model.VariableNode(_parent=None, _children=None, ast=None, ctx=None, parseinfo=None, name=None, type=None)

Bases: ModelBase

name: Any = None

type: Any = None

class textworld.logic.parser.GameLogicBuffer(text, /, config=None, **settings)

Bases: Buffer

class textworld.logic.parser.GameLogicParser(config=None, **settings)

Bases: Parser

class textworld.logic.parser.GameLogicSemantics

Bases: object

action(ast)

actionPrecondition(ast)

alias(ast)

conjunctiveQuery(ast)

constraints(ast)

document(ast)

inform7(ast)

inform7Code(ast)

inform7Command(ast)

inform7Commands(ast)

inform7Part(ast)

inform7Predicate(ast)

inform7Predicates(ast)

inform7Type(ast)

name(ast)

onlyAction(ast)

onlyPlaceholder(ast)

onlyPredicate(ast)

onlyProposition(ast)

onlyRule(ast)

onlySignature(ast)

onlyVariable(ast)

phName(ast)

placeholder(ast)

predName(ast)

predicate(ast)

predicateDecls(ast)

predicates(ast)

proposition(ast)

reverseRule(ast)

reverseRuleDecls(ast)

reverseRules(ast)

rule(ast)

ruleDecls(ast)

ruleName(ast)

rulePrecondition(ast)

rules(ast)

signature(ast)

signatureOrAlias(ast)

start(ast)

str(ast)

strBlock(ast)

type(ast)

typePart(ast)

variable(ast)

textworld.logic.parser.main(filename, **kwargs)