Events

Every event that this state model can receive is declared up front, in one block, before any states are defined.

Here is the events section from the Door lifecycle:

events
    Door opened
    Passenger open
    Passenger close
    Open delay canceled
    Time to close
    Hold released
    Door closed
    Lock
    Unlock
    Door blocked
    Keep trying
    Cannot close door
--

And the grammar:

// Events
events = events_header event_spec* block_end
events_header = "events" EOL*
event_spec = INDENT event_name EOL*
event_name = name

An unindented events keyword opens the section. Each event follows on its own indented line, and an unindented -- closes it. That closing -- is the block_end token and you'll see it again at the end of Initial transitions and at the end of every state block.

An event name is just a name — see Names and delimiters — so Time to close and Cannot close door are each a single event, not three or four words of something. My convention is to name events for what has happened, in the past tense where it reads naturally (Door opened, Door closed) or as a directive when one object is telling another to do something (Lock, Unlock, Keep trying).

Why declare them at all?

Because the declaration is the model's contract. Any event a state machine can receive is listed here, once, whether it's sent from another state model, from an external domain, or by the state machine to itself. That gives a downstream module a complete picture of what this state machine responds to without having to scan every transition, and it gives you a place to notice that you've accidentally invented two names for the same event.

The event names appearing in each state's Transitions must be drawn from this list.

Ignored and can't-happen events

An event that is declared here but that doesn't appear in a given state's transitions is simply not accepted in that state. See Transitions for how to say "this event can arrive here and should be ignored" as opposed to leaving it out entirely.