6. Names

This chapter describes how sigils, identifiers, and decorators combine to form names for roles and variables.

Names

EBNF

name = [ scope_sigil ] type_sigil identifier [ group_role_decorator ] .
scope_sigil          = "$" | "_" .
type_sigil           = "@" | "&" .
group_role_decorator = "*" .

A name is how an author declares, and later refers to, a role, scratch variable, or local variable that binds a particular value.

It combines the following components, in order:

1. An optional scope sigil ($ or _).
2. A type sigil (@ or &).
3. An identifier.
4. An optional group-role decorator (*).

Scope sigils

An optional scope sigil marks the storage scope of a variable:

Sigil	Name	Usage
$	Scratch sigil	Prefix on scratch variables, which persist across the fields of an action.
_	Local sigil	Prefix on local variables, which are scoped to a single block (e.g., a loop body).
	(neither)	When no scope sigil is present, the name refers to a role.

When included in a name, the scope sigil must be present on both its initial declaration and any subsequent references to it.

A scope sigil, when present, appears before the type sigil in a name.

Type sigils

The required type sigil marks whether the name binds an entity or a symbol:

Sigil	Name	Usage
@	Entity sigil	Prefix on roles/variables that bind characters, items, locations, or actions.
&	Symbol sigil	Prefix on roles/variables that bind symbols.

The type sigil must be present on both the initial declaration of a name and any subsequent references to it.

A type sigil always appears immediately before the identifier in a name.

Identifier

At the heart of a name is an identifier.

For example, in the name @friends*, the identifier is friends.

Group-role decorator

The group-role decorator * is appended to the end of a name to mark that it denotes a group role (a role with multiple slots).

It must be present in the initial declaration of a group role, and also any subsequent references to the role.

The group-role decorator MUST NOT be attached to the name of a variable.

Example names

// Role binding a single entity
@person

// Role binding a group of entities
@people*

// Role binding a single symbol
&thing

// Role binding a group of symbols
&things*

// Scratch variable binding a (single) entity
$@person

// Scratch variable binding a (single) symbol
$&reason

// Local variable binding a (single) entity
_@temp_person

// Local variable binding a (single) symbol
_&temp_thing

Declarations

When a role is defined, its full name (including sigil and any decorator) must be declared:

action hang-out:
    roles:
        @person:
            as: initiator
        @friends*:
            as: recipient
            n: 2-5

Likewise when a variable is defined:

scratch:
    $@boss = @person.boss
effects:
    loop $@boss.friends as _@p:
        _@p.affinity[$@boss] -= #BIG
    end

References

Once a role or variable has been defined, an author can refer to its bound value in an expression called a reference. Again, its full name (including sigils and any decorator) must be used:

conditions:
    @person in @other.friends

A role or variable MUST NOT be referred to prior to being declared.

Plan-phase names

Though not a name in the sense of this chapter, a plan phase is introduced by prefixing an identifier with the plan-phase sigil >:

>setup:
    ...
>confrontation:
    ...

Plan phases cannot be referenced outside these declarations.

Construct names

Construct names (for actions, tropes, plans, etc.) are always declared as bare identifiers, and thus also fall outside the purview of this chapter:

action foo:
    ...

trope bar:
    ...

plan baz:
    ...

Unlike roles and variables, constructs can only be referred to in ways that are disambiguated by context, e.g.:

action child from parent
queue action foo
queue plan bar
fit trope rivalry
search query betrayal
sift pattern rags-to-riches