textworld.logic

class textworld.logic.Action(name, preconditions, postconditions)[source]

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)[source]
Return type

Action

format_command(mapping={})[source]
inverse(name=None)[source]

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)[source]

Parse an action expression.

Parameters

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

Return type

Action

serialize()[source]
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)[source]

Bases: object

A shorthand predicate alias.

expand(predicate)[source]

Expand a use of this alias into its replacement.

Return type

Collection[Predicate]

class textworld.logic.GameLogic[source]

Bases: object

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

classmethod deserialize(data)[source]
Return type

GameLogic

classmethod load(paths)[source]
normalize_rule(rule)[source]
Return type

Rule

classmethod parse(cls, document)[source]
Return type

GameLogic

serialize()[source]
Return type

str

class textworld.logic.Inform7Command(rule, command, event)[source]

Bases: object

Information about an Inform 7 command.

class textworld.logic.Inform7Logic[source]

Bases: object

The Inform 7 bindings of a GameLogic.

class textworld.logic.Inform7Predicate(predicate, source)[source]

Bases: object

Information about an Inform 7 predicate.

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

Bases: object

Information about an Inform 7 kind.

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

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)[source]
Return type

Placeholder

classmethod parse(expr)[source]

Parse a placeholder expression.

Parameters

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

Return type

Placeholder

serialize()[source]
Return type

Mapping

name
type
class textworld.logic.Predicate(name, parameters)[source]

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)[source]
Return type

Predicate

instantiate(mapping)[source]

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)[source]

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.

classmethod parse(expr)[source]

Parse a predicate expression.

Parameters

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

Return type

Predicate

serialize()[source]
Return type

Mapping

substitute(mapping)[source]

Copy this predicate, substituting certain placeholders for others.

Parameters

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

Return type

Predicate

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=[])[source]

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)[source]
Return type

Proposition

classmethod parse(expr)[source]

Parse a proposition expression.

Parameters

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

Return type

Proposition

serialize()[source]
Return type

Mapping

arguments
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)[source]

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)[source]
Return type

Rule

instantiate(mapping)[source]

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)[source]

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)[source]

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)[source]

Parse a rule expression.

Parameters

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

Return type

Rule

serialize()[source]
Return type

Mapping

substitute(mapping, name=None)[source]

Copy this rule, substituting certain placeholders for others.

Parameters

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

Return type

Rule

property all_predicates: Iterable[Predicate]

All the pre- and post-conditions.

Return type

Iterable[Predicate]

class textworld.logic.Signature(name, types)[source]

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)[source]

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)[source]

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)[source]

Add a fact to the state.

add_facts(props)[source]

Add some facts to the state.

all_applicable_actions(rules, mapping=None)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

Returns whether the propositions are all true in this state.

Return type

bool

copy()[source]

Create a copy of this state.

Return type

State

classmethod deserialize(data)[source]

Deserialize a State object from data.

Return type

State

facts_with_signature(sig)[source]

Returns all the known facts with the given signature.

Return type

Set[Proposition]

has_variable(var)[source]

Returns whether this state is aware of the given variable.

Return type

bool

is_applicable(action)[source]

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

Return type

bool

is_fact(prop)[source]

Returns whether a proposition is true in this state.

Return type

bool

is_sequence_applicable(actions)[source]

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

Return type

bool

remove_fact(prop)[source]

Remove a fact from the state.

remove_facts(props)[source]

Remove some facts from the state.

serialize()[source]

Serialize this state.

Return type

Sequence

variable_named(name)[source]

Returns the variable with the given name, if known.

Return type

Variable

variables_of_type(type)[source]

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)[source]

Bases: object

A variable type.

has_subtype_named(name)[source]
Return type

bool

has_supertype_named(name)[source]
Return type

bool

is_subtype_of(other)[source]
Return type

bool

is_supertype_of(other)[source]
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[source]

Bases: object

A hierarchy of types.

add(type)[source]
closure(type, expand)[source]

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)[source]
Return type

Type

multi_ancestors(types)[source]

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)[source]

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)[source]

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)[source]

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

Return type

List[Collection[Type]]

multi_supertypes(types)[source]

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)[source]

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)[source]
Return type

Variable

is_a(type)[source]
Return type

bool

classmethod parse(expr)[source]

Parse a variable expression.

Parameters

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

Return type

Variable

serialize()[source]
Return type

Mapping

name
type
class textworld.logic.model.ActionNode(ctx=None, ast=None, parseinfo=None, **kwargs)[source]

Bases: ModelBase

name = None
postconditions = None
preconditions = None
class textworld.logic.model.ActionPreconditionNode(ctx=None, ast=None, parseinfo=None, **kwargs)[source]

Bases: ModelBase

condition = None
preserve = None
class textworld.logic.model.AliasNode(ctx=None, ast=None, parseinfo=None, **kwargs)[source]

Bases: ModelBase

lhs = None
rhs = None
class textworld.logic.model.ConstraintsNode(ctx=None, ast=None, parseinfo=None, **kwargs)[source]

Bases: ModelBase

constraints = None
class textworld.logic.model.DocumentNode(ctx=None, ast=None, parseinfo=None, **kwargs)[source]

Bases: ModelBase

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

Bases: ModelBuilderSemantics

class textworld.logic.model.Inform7CodeNode(ctx=None, ast=None, parseinfo=None, **kwargs)[source]

Bases: ModelBase

code = None
class textworld.logic.model.Inform7CommandNode(ctx=None, ast=None, parseinfo=None, **kwargs)[source]

Bases: ModelBase

command = None
event = None
rule = None
class textworld.logic.model.Inform7CommandsNode(ctx=None, ast=None, parseinfo=None, **kwargs)[source]

Bases: ModelBase

commands = None
class textworld.logic.model.Inform7Node(ctx=None, ast=None, parseinfo=None, **kwargs)[source]

Bases: ModelBase

parts = None
class textworld.logic.model.Inform7PredicateNode(ctx=None, ast=None, parseinfo=None, **kwargs)[source]

Bases: ModelBase

predicate = None
source = None
class textworld.logic.model.Inform7PredicatesNode(ctx=None, ast=None, parseinfo=None, **kwargs)[source]

Bases: ModelBase

predicates = None
class textworld.logic.model.Inform7TypeNode(ctx=None, ast=None, parseinfo=None, **kwargs)[source]

Bases: ModelBase

definition = None
kind = None
class textworld.logic.model.ModelBase(ctx=None, ast=None, parseinfo=None, **kwargs)[source]

Bases: Node

class textworld.logic.model.PlaceholderNode(ctx=None, ast=None, parseinfo=None, **kwargs)[source]

Bases: ModelBase

name = None
type = None
class textworld.logic.model.PredicateNode(ctx=None, ast=None, parseinfo=None, **kwargs)[source]

Bases: ModelBase

name = None
parameters = None
class textworld.logic.model.PredicatesNode(ctx=None, ast=None, parseinfo=None, **kwargs)[source]

Bases: ModelBase

predicates = None
class textworld.logic.model.PropositionNode(ctx=None, ast=None, parseinfo=None, **kwargs)[source]

Bases: ModelBase

arguments = None
name = None
class textworld.logic.model.ReverseRuleNode(ctx=None, ast=None, parseinfo=None, **kwargs)[source]

Bases: ModelBase

lhs = None
rhs = None
class textworld.logic.model.ReverseRulesNode(ctx=None, ast=None, parseinfo=None, **kwargs)[source]

Bases: ModelBase

reverse_rules = None
class textworld.logic.model.RuleNode(ctx=None, ast=None, parseinfo=None, **kwargs)[source]

Bases: ModelBase

name = None
postconditions = None
preconditions = None
class textworld.logic.model.RulePreconditionNode(ctx=None, ast=None, parseinfo=None, **kwargs)[source]

Bases: ModelBase

condition = None
preserve = None
class textworld.logic.model.RulesNode(ctx=None, ast=None, parseinfo=None, **kwargs)[source]

Bases: ModelBase

rules = None
class textworld.logic.model.SignatureNode(ctx=None, ast=None, parseinfo=None, **kwargs)[source]

Bases: ModelBase

name = None
types = None
class textworld.logic.model.TypeNode(ctx=None, ast=None, parseinfo=None, **kwargs)[source]

Bases: ModelBase

name = None
parts = None
supertypes = None
class textworld.logic.model.VariableNode(ctx=None, ast=None, parseinfo=None, **kwargs)[source]

Bases: ModelBase

name = None
type = None
class textworld.logic.parser.GameLogicBuffer(text, whitespace=None, nameguard=None, comments_re=None, eol_comments_re='#.*$', ignorecase=None, namechars='', **kwargs)[source]

Bases: Buffer

class textworld.logic.parser.GameLogicParser(whitespace=None, nameguard=None, comments_re=None, eol_comments_re='#.*$', ignorecase=None, left_recursion=True, parseinfo=True, keywords=None, namechars='', buffer_class=<class 'textworld.logic.parser.GameLogicBuffer'>, **kwargs)[source]

Bases: Parser

class textworld.logic.parser.GameLogicSemantics[source]

Bases: object

action(ast)[source]
actionPrecondition(ast)[source]
alias(ast)[source]
constraints(ast)[source]
document(ast)[source]
inform7(ast)[source]
inform7Code(ast)[source]
inform7Command(ast)[source]
inform7Commands(ast)[source]
inform7Part(ast)[source]
inform7Predicate(ast)[source]
inform7Predicates(ast)[source]
inform7Type(ast)[source]
name(ast)[source]
onlyAction(ast)[source]
onlyPlaceholder(ast)[source]
onlyPredicate(ast)[source]
onlyProposition(ast)[source]
onlyRule(ast)[source]
onlySignature(ast)[source]
onlyVariable(ast)[source]
phName(ast)[source]
placeholder(ast)[source]
predName(ast)[source]
predicate(ast)[source]
predicateDecls(ast)[source]
predicates(ast)[source]
proposition(ast)[source]
reverseRule(ast)[source]
reverseRuleDecls(ast)[source]
reverseRules(ast)[source]
rule(ast)[source]
ruleDecls(ast)[source]
ruleName(ast)[source]
rulePrecondition(ast)[source]
rules(ast)[source]
signature(ast)[source]
signatureOrAlias(ast)[source]
start(ast)[source]
str(ast)[source]
strBlock(ast)[source]
type(ast)[source]
typePart(ast)[source]
variable(ast)[source]
textworld.logic.parser.main(filename, start=None, **kwargs)[source]