(p:define-protocol state-machine-internal ()
  (:function %define-state-machine (name variables transitions options))
  "Validates and expands the DEFINE-STATE-MACHINE macro."
  (:function %define-state (state-machine-name state-name body))
  "Validates and expands the DEFINE-STATE macro.")

(p:define-protocol state-machine (:dependencies (state-machine-internal))
  (:class state-machine () ())
  "Protocol state machine class. All state machine classes participating in
the state machine protocol should inherit from this class."
  (:class state-definition () ())
  "Protocol state definition class. All state definition classes participating
in the state machine protocol should inherit from this class."

(:function find-state-machine
    ((name symbol) &optional errorp)
    (or null state-machine))
  "Returns the state machine object named by NAME in the global environment. If
there is no such state machine, NIL is returned if ERRORP is false; otherwise,
an error of type STATE-MACHINE-NOT-FOUND is signaled."
  (:function (setf find-state-machine)
    ((new-value (or null state-machine)) (name symbol) &optional errorp)
    (values (or null state-machine) &optional))
  "Associates the state machine object with NAME in the global environment.
The ERRORP argument is evaluated for side effects, but its value is ignored."

  (:function state-machine-name
    ((state-machine state-machine))
    (values symbol &optional))
  "Returns the name of the state machine."
  (:function (setf state-machine-name)
    ((new-value symbol) (state-machine state-machine))
    (values symbol &optional))
  "Sets the name of the state machine."

  (:function state-machine-variables
    ((state-machine state-machine))
    (values list &optional))
  "Returns the list of variables of the state machine."
  (:function (setf state-machine-variables)
    ((new-value list) (state-machine state-machine))
    (values list &optional))
  "Sets the list of variables of the state machine."

  (:function state-machine-default-starting-state
    ((state-machine state-machine))
    (values symbol boolean &optional))
  "Returns the default starting state of the state machine as the primary value
and T as the secondary value, if the default starting state is set. Otherwise,
returns NIL as both primary and secondary value."
  (:function (setf state-machine-default-starting-state)
    ((new-value symbol) (state-machine state-machine))
    (values symbol &optional))
  "Sets the default starting state of the state machine."

  (:function state-machine-states
    ((state-machine state-machine))
    (values list &optional))
  "Returns the list of all states of the state machine.
\
Consequences are undefined if the returned list is modified."

  (:function find-state-definition
    ((state-machine state-machine) (name symbol) &optional errorp)
    (values (or null state-definition) &optional))
  "Returns the state definition that is named by NAME in STATE-MACHINE. If there
is no such state, NIL is returned if ERRORP is false; otherwise, an error of
type STATE-NOT-FOUND is signaled."

  (:function state-definition-name
    ((state-definition state-definition))
    (values symbol &optional))
  "Returns the name of the state definition."
  (:function (setf state-definition-name)
    ((new-value symbol) (state-definition state-definition))
    (values symbol &optional))
  "Sets the name of the state definition."

  (:function state-definition-body
    ((state-definition state-definition))
    (values t &optional))
  "Returns the body of the state definition."
  (:function (setf state-definition-body)
    (new-value (state-definition state-definition))
    (values t &optional))
  "Sets the body of the state definition."

  (:function state-definition-state-machine
    ((state-definition state-definition))
    (values (or null state-machine) &optional))
  "Returns the state machine object that the state definition is associated
with, or NIL, if the state definition is not associated with any state machine."
  (:function (setf state-definition-state-machine)
    ((new-value (or null state-machine)) (state-definition state-definition))
    (values (or null state-machine) &optional))
  "Sets the state machine that the state definition is associated with."

  (:function add-state-definition
    ((state-machine state-machine) (state-definition state-definition))
    (values state-machine &optional))
  "Adds the provided state definition to the state machine.
\
If a state definition with the same name already exists, a continuable error of
type STATE-DEFINITION-ALREADY-EXISTS is signaled."
  (:function remove-state-definition
    ((state-machine state-machine) (state-definition state-definition))
    (values state-machine &optional))
  "Removes the provided state definition from the state machine."

  (:function state-transitions
    ((state-machine state-machine) (state symbol))
    (values list &optional))
  "Returns a list of all state names that STATE is allowed to transition to in
STATE-MACHINE. This list may contain the name of STATE if it is allowed to
transition to itself.
\
Consequences are undefined if the returned list is modified."

  (:function transition-valid-p
    ((state-machine state-machine) (state-from symbol) (state-to symbol))
    (values boolean &optional))
  "Returns true if STATE-MACHINE contains a valid transition from state
STATE-FROM to state STATE-TO; otherwise, returns false."

  (:function add-transition
    ((state-machine state-machine) (state-from symbol) (state-to symbol)
     &optional errorp)
    (values state-machine &optional))
  "Adds a transition from STATE-FROM to STATE-TO in STATE-MACHINE.
\
If no such transition existed, T is returned; if such a transition already
exists, NIL is returned if ERRORP is NIL; otherwise, a continuable error of type
TRANSITION-ALREADY-EXISTS is signaled."
  (:function remove-transition
    ((state-machine state-machine) (state-from symbol) (state-to symbol)
     &optional errorp)
    (values state-machine &optional))
  "Removes a transition from STATE-FROM to STATE-TO in STATE-MACHINE.
\
If such a transition existed, T is returned; if such a transition did not exist,
NIL is returned if ERRORP is NIL; otherwise, a continuable error of type
TRANSITION-DOES-NOT-EXIST is signaled."

  (:function compile-state-machine
    ((state-machine state-machine) (bindings list))
    (values t &optional))
  "Compiles STATE-MACHINE into a Lisp form using the provided variable
bindings and returns the compiled Lisp form."
  (:function compile-state
    ((state-machine state-machine) (state-definition state-definition) bindings)
    (values t &optional))
  "Compiles state STATE of the provided state machine into a Lisp form using the
provided variable bindings and returns the compiled Lisp form."

  (:function ensure-state-machine-using-class
    (state-machine name &key variables transitions options &allow-other-keys)
    (values state-machine &optional))
  "Defines or modifies the definition of a named state machine. Usually called
by ENSURE-STATE-MACHINE, but can be also called directly."

  (:function ensure-state-machine
    (name &rest args &key &allow-other-keys)
    (values state-machine &optional))
  "Defines or modifies the definition of a named state machine by calling
ENSURE-STATE-MACHINE-USING-CLASS."

  (:macro expand-state-machine
    (name bindings &key &allow-other-keys)
    "Expands into the compiled form of a globally named state machine by calling
COMPILE-STATE-MACHINE.")

  (:macro expand-state-definition
    (state-machine-name state-name bindings &key &allow-other-keys)
    "Expands into the compiled form of a given state of a globally named state
machine by calling COMPILE-STATE.")

  (:macro define-state-machine
    (name (&rest variables) (&rest transitions) &body options))
  "Defines a globally named state machine."
  (:macro define-state
    (state-machine-name state-name () &body body))
  "Defines a state of a globally named state machine.")

(p:execute-protocol state-machine-internal)

(p:execute-protocol state-machine)