using Stateless.Reflection;

using System;

using System.Collections.Generic;

using System.Linq;

namespace Stateless

{

/// <summary>

/// Enum for the different modes used when Fire-ing a trigger

/// </summary>

public enum FiringMode

{

/// <summary> Use immediate mode when the queing of trigger events are not needed. Care must be taken when using this mode, as there is no run-to-completion guaranteed.</summary>

Immediate,

/// <summary> Use the queued Fire-ing mode when run-to-completion is required. This is the recommended mode.</summary>

Queued

}

/// <summary>

/// Models behaviour as transitions between a finite set of states.

/// </summary>

/// <typeparam name="TState">The type used to represent the states.</typeparam>

/// <typeparam name="TTrigger">The type used to represent the triggers that cause state transitions.</typeparam>

public partial class StateMachine<TState, TTrigger>

{

private readonly IDictionary<TState, StateRepresentation> _stateConfiguration = new Dictionary<TState, StateRepresentation>();

private readonly IDictionary<TTrigger, TriggerWithParameters> _triggerConfiguration = new Dictionary<TTrigger, TriggerWithParameters>();

private readonly Func<TState> _stateAccessor;

private readonly Action<TState> _stateMutator;

private UnhandledTriggerAction _unhandledTriggerAction;

private OnTransitionedEvent _onTransitionedEvent;

private readonly FiringMode _firingMode;

private class QueuedTrigger

{

public TTrigger Trigger { get; set; }

public object[] Args { get; set; }

}

private readonly Queue<QueuedTrigger> _eventQueue = new Queue<QueuedTrigger>();

private bool _firing;

/// <summary>

/// Construct a state machine with external state storage.

/// </summary>

/// <param name="stateAccessor">A function that will be called to read the current state value.</param>

/// <param name="stateMutator">An action that will be called to write new state values.</param>

public StateMachine(Func<TState> stateAccessor, Action<TState> stateMutator) :this(stateAccessor, stateMutator, FiringMode.Queued)

{

}

/// <summary>

/// Construct a state machine.

/// </summary>

/// <param name="initialState">The initial state.</param>

public StateMachine(TState initialState) : this(initialState, FiringMode.Queued)

{

}

/// <summary>

/// Construct a state machine with external state storage.

/// </summary>

/// <param name="stateAccessor">A function that will be called to read the current state value.</param>

/// <param name="stateMutator">An action that will be called to write new state values.</param>

/// <param name="firingMode">Optional specification of fireing mode.</param>

public StateMachine(Func<TState> stateAccessor, Action<TState> stateMutator, FiringMode firingMode) : this()

{

_stateAccessor = stateAccessor ?? throw new ArgumentNullException(nameof(stateAccessor));

_stateMutator = stateMutator ?? throw new ArgumentNullException(nameof(stateMutator));

_firingMode = firingMode;

}

/// <summary>

/// Construct a state machine.

/// </summary>

/// <param name="initialState">The initial state.</param>

/// <param name="firingMode">Optional specification of fireing mode.</param>

public StateMachine(TState initialState, FiringMode firingMode) : this()

{

var reference = new StateReference { State = initialState };

_stateAccessor = () => reference.State;

_stateMutator = s => reference.State = s;

_firingMode = firingMode;

}

/// <summary>

/// Default constuctor

/// </summary>

StateMachine()

{

_unhandledTriggerAction = new UnhandledTriggerAction.Sync(DefaultUnhandledTriggerAction);

_onTransitionedEvent = new OnTransitionedEvent();

}

/// <summary>

/// The current state.

/// </summary>

public TState State

{

get

{

return _stateAccessor();

}

private set

{

_stateMutator(value);

}

}

/// <summary>

/// The currently-permissible trigger values.

/// </summary>

public IEnumerable<TTrigger> PermittedTriggers

{

get

{

return GetPermittedTriggers();

}

}

/// <summary>

/// The currently-permissible trigger values.

/// </summary>

public IEnumerable<TTrigger> GetPermittedTriggers(params object[] args)

{

return CurrentRepresentation.GetPermittedTriggers(args);

}

StateRepresentation CurrentRepresentation

{

get

{

return GetRepresentation(State);

}

}

/// <summary>

/// Provides an info object which exposes the states, transitions, and actions of this machine.

/// </summary>

public StateMachineInfo GetInfo()

{

var representations = _stateConfiguration.ToDictionary(kvp => kvp.Key, kvp => kvp.Value);

var behaviours = _stateConfiguration.SelectMany(kvp => kvp.Value.TriggerBehaviours.SelectMany(b => b.Value.OfType<TransitioningTriggerBehaviour>().Select(tb => tb.Destination))).ToList();

behaviours.AddRange(_stateConfiguration.SelectMany(kvp => kvp.Value.TriggerBehaviours.SelectMany(b => b.Value.OfType<ReentryTriggerBehaviour>().Select(tb => tb.Destination))).ToList());

var reachable = behaviours

.Distinct()

.Except(representations.Keys)

.Select(underlying => new StateRepresentation(underlying))

.ToArray();

foreach (var representation in reachable)

representations.Add(representation.UnderlyingState, representation);

var info = representations.ToDictionary(kvp => kvp.Key, kvp => StateInfo.CreateStateInfo(kvp.Value));

foreach (var state in info)

StateInfo.AddRelationships(state.Value, representations[state.Key], k => info[k]);

return new StateMachineInfo(info.Values, typeof(TState), typeof(TTrigger));

}

StateRepresentation GetRepresentation(TState state)

{

if (!_stateConfiguration.TryGetValue(state, out StateRepresentation result))

{

result = new StateRepresentation(state);

_stateConfiguration.Add(state, result);

}

return result;

}

/// <summary>

/// Begin configuration of the entry/exit actions and allowed transitions

/// when the state machine is in a particular state.

/// </summary>

/// <param name="state">The state to configure.</param>

/// <returns>A configuration object through which the state can be configured.</returns>

public StateConfiguration Configure(TState state)

{

return new StateConfiguration(this, GetRepresentation(state), GetRepresentation);

}

/// <summary>

/// Transition from the current state via the specified trigger.

/// The target state is determined by the configuration of the current state.

/// Actions associated with leaving the current state and entering the new one

/// will be invoked.

/// </summary>

/// <param name="trigger">The trigger to fire.</param>

/// <exception cref="System.InvalidOperationException">The current state does

/// not allow the trigger to be fired.</exception>

public void Fire(TTrigger trigger)

{

InternalFire(trigger, new object[0]);

}

/// <summary>

/// Transition from the current state via the specified trigger.

/// The target state is determined by the configuration of the current state.

/// Actions associated with leaving the current state and entering the new one

/// will be invoked.

/// </summary>

/// <typeparam name="TArg0">Type of the first trigger argument.</typeparam>

/// <param name="trigger">The trigger to fire.</param>

/// <param name="arg0">The first argument.</param>

/// <exception cref="System.InvalidOperationException">The current state does

/// not allow the trigger to be fired.</exception>

public void Fire<TArg0>(TriggerWithParameters<TArg0> trigger, TArg0 arg0)

{

if (trigger == null) throw new ArgumentNullException(nameof(trigger));

InternalFire(trigger.Trigger, arg0);

}

/// <summary>

/// Transition from the current state via the specified trigger.

/// The target state is determined by the configuration of the current state.

/// Actions associated with leaving the current state and entering the new one

/// will be invoked.

/// </summary>

/// <typeparam name="TArg0">Type of the first trigger argument.</typeparam>

/// <typeparam name="TArg1">Type of the second trigger argument.</typeparam>

/// <param name="arg0">The first argument.</param>

/// <param name="arg1">The second argument.</param>

/// <param name="trigger">The trigger to fire.</param>

/// <exception cref="System.InvalidOperationException">The current state does

/// not allow the trigger to be fired.</exception>

public void Fire<TArg0, TArg1>(TriggerWithParameters<TArg0, TArg1> trigger, TArg0 arg0, TArg1 arg1)

{

if (trigger == null) throw new ArgumentNullException(nameof(trigger));

InternalFire(trigger.Trigger, arg0, arg1);

}

/// <summary>

/// Transition from the current state via the specified trigger.

/// The target state is determined by the configuration of the current state.

/// Actions associated with leaving the current state and entering the new one

/// will be invoked.

/// </summary>

/// <typeparam name="TArg0">Type of the first trigger argument.</typeparam>

/// <typeparam name="TArg1">Type of the second trigger argument.</typeparam>

/// <typeparam name="TArg2">Type of the third trigger argument.</typeparam>

/// <param name="arg0">The first argument.</param>

/// <param name="arg1">The second argument.</param>

/// <param name="arg2">The third argument.</param>

/// <param name="trigger">The trigger to fire.</param>

/// <exception cref="System.InvalidOperationException">The current state does

/// not allow the trigger to be fired.</exception>

public void Fire<TArg0, TArg1, TArg2>(TriggerWithParameters<TArg0, TArg1, TArg2> trigger, TArg0 arg0, TArg1 arg1, TArg2 arg2)

{

if (trigger == null) throw new ArgumentNullException(nameof(trigger));

InternalFire(trigger.Trigger, arg0, arg1, arg2);

}

/// <summary>

/// Activates current state. Actions associated with activating the currrent state

/// will be invoked. The activation is idempotent and subsequent activation of the same current state

/// will not lead to re-execution of activation callbacks.

/// </summary>

public void Activate()

{

var representativeState = GetRepresentation(State);

representativeState.Activate();

}

/// <summary>

/// Deactivates current state. Actions associated with deactivating the currrent state

/// will be invoked. The deactivation is idempotent and subsequent deactivation of the same current state

/// will not lead to re-execution of deactivation callbacks.

/// </summary>

public void Deactivate()

{

var representativeState = GetRepresentation(State);

representativeState.Deactivate();

}

/// <summary>

/// Determine how to Fire the trigger

/// </summary>

/// <param name="trigger">The trigger. </param>

/// <param name="args">A variable-length parameters list containing arguments. </param>

void InternalFire(TTrigger trigger, params object[] args)

{

switch (_firingMode)

{

case FiringMode.Immediate:

InternalFireOne(trigger, args);

break;

case FiringMode.Queued:

InternalFireQueued(trigger, args);

break;

default:

// If something is completely messed up we let the user know ;-)

throw new InvalidOperationException("The firing mode has not been configured!");

}

}

/// <summary>

/// Queue events and then fire in order.

/// If only one event is queued, this behaves identically to the non-queued version.

/// </summary>

/// <param name="trigger"> The trigger. </param>

/// <param name="args"> A variable-length parameters list containing arguments. </param>

private void InternalFireQueued(TTrigger trigger, params object[] args)

{

// If a trigger is already being handled then the trigger will be queued (FIFO) and processed later.

if (_firing)

{

_eventQueue.Enqueue(new QueuedTrigger { Trigger = trigger, Args = args });

return;

}

try

{

_firing = true;

InternalFireOne(trigger, args);

// Check if any other triggers have been queued, and fire those as well.

while (_eventQueue.Count != 0)

{

var queuedEvent = _eventQueue.Dequeue();

InternalFireOne(queuedEvent.Trigger, queuedEvent.Args);

}

}

finally

{

_firing = false;

}

}

/// <summary>

/// This method handles the execution of a trigger handler. It finds a

/// handle, then updates the current state information.

/// </summary>

/// <param name="trigger"></param>

/// <param name="args"></param>

void InternalFireOne(TTrigger trigger, params object[] args)

{

// If this is a trigger with parameters, we must validate the parameter(s)

if (_triggerConfiguration.TryGetValue(trigger, out TriggerWithParameters configuration))

configuration.ValidateParameters(args);

var source = State;

var representativeState = GetRepresentation(source);

// Try to find a trigger handler, either in the current state or a super state.

if (!representativeState.TryFindHandler(trigger, args, out TriggerBehaviourResult result))

{

_unhandledTriggerAction.Execute(representativeState.UnderlyingState, trigger, result?.UnmetGuardConditions);

return;

}

switch (result.Handler)

{

// Check if this trigger should be ignored

case IgnoredTriggerBehaviour _:

return;

// Handle special case, re-entry in superstate

// Check if it is an internal transition, or a transition from one state to another.

case ReentryTriggerBehaviour handler:

{

// Handle transition, and set new state

var transition = new Transition(source, handler.Destination, trigger);

HandleReentryTrigger(args, representativeState, transition);

break;

}

case DynamicTriggerBehaviour _ when (result.Handler.ResultsInTransitionFrom(source, args, out var destination)):

case TransitioningTriggerBehaviour _ when (result.Handler.ResultsInTransitionFrom(source, args, out destination)):

{

// Handle transition, and set new state

var transition = new Transition(source, destination, trigger);

HandleTransitioningTrigger(args, representativeState, transition);

break;

}

case InternalTriggerBehaviour _:

{

// Internal transitions does not update the current state, but must execute the associated action.

var transition = new Transition(source, source, trigger);

CurrentRepresentation.InternalAction(transition, args);

break;

}

default:

throw new InvalidOperationException("State machine configuration incorrect, no handler for trigger.");

}

}

private void HandleReentryTrigger(object[] args, StateRepresentation representativeState, Transition transition)

{

StateRepresentation representation;

transition = representativeState.Exit(transition);

var newRepresentation = GetRepresentation(transition.Destination);

if (!transition.Source.Equals(transition.Destination))

{

// Then Exit the final superstate

transition = new Transition(transition.Destination, transition.Destination, transition.Trigger);

newRepresentation.Exit(transition);

_onTransitionedEvent.Invoke(transition);

representation = EnterState(newRepresentation, transition, args);

}

else

{

_onTransitionedEvent.Invoke(transition);

representation = EnterState(newRepresentation, transition, args);

}

State = representation.UnderlyingState;

}

private void HandleTransitioningTrigger( object[] args, StateRepresentation representativeState, Transition transition)

{

transition = representativeState.Exit(transition);

State = transition.Destination;

var newRepresentation = GetRepresentation(transition.Destination);

//Alert all listeners of state transition

_onTransitionedEvent.Invoke(transition);

var representation = EnterState(newRepresentation, transition, args);

State = representation.UnderlyingState;

}

private StateRepresentation EnterState(StateRepresentation representation, Transition transition, object [] args)

{

// Enter the new state

representation.Enter(transition, args);

// Recursively enter substates that have an initial transition

if (representation.HasInitialTransition)

{

// Verify that the target state is a substate

// Check if state has substate(s), and if an initial transition(s) has been set up.

if (!representation.GetSubstates().Any(s => s.UnderlyingState.Equals(representation.InitialTransitionTarget)))

{

throw new InvalidOperationException($"The target ({representation.InitialTransitionTarget}) for the initial transition is not a substate.");

}

var initialTransition = new Transition(transition.Source, representation.InitialTransitionTarget, transition.Trigger);

representation = GetRepresentation(representation.InitialTransitionTarget);

representation = EnterState(representation, initialTransition, args);

}

return representation;

}

/// <summary>

/// Override the default behaviour of throwing an exception when an unhandled trigger

/// is fired.

/// </summary>

/// <param name="unhandledTriggerAction">An action to call when an unhandled trigger is fired.</param>

public void OnUnhandledTrigger(Action<TState, TTrigger> unhandledTriggerAction)

{

if (unhandledTriggerAction == null) throw new ArgumentNullException(nameof(unhandledTriggerAction));

_unhandledTriggerAction = new UnhandledTriggerAction.Sync((s, t, c) => unhandledTriggerAction(s, t));

}

/// <summary>

/// Override the default behaviour of throwing an exception when an unhandled trigger

/// is fired.

/// </summary>

/// <param name="unhandledTriggerAction">An action to call when an unhandled trigger is fired.</param>

public void OnUnhandledTrigger(Action<TState, TTrigger, ICollection<string>> unhandledTriggerAction)

{

if (unhandledTriggerAction == null) throw new ArgumentNullException(nameof(unhandledTriggerAction));

_unhandledTriggerAction = new UnhandledTriggerAction.Sync(unhandledTriggerAction);

}

/// <summary>

/// Determine if the state machine is in the supplied state.

/// </summary>

/// <param name="state">The state to test for.</param>

/// <returns>True if the current state is equal to, or a substate of,

/// the supplied state.</returns>

public bool IsInState(TState state)

{

return CurrentRepresentation.IsIncludedIn(state);

}

/// <summary>

/// Returns true if <paramref name="trigger"/> can be fired

/// in the current state.

/// </summary>

/// <param name="trigger">Trigger to test.</param>

/// <returns>True if the trigger can be fired, false otherwise.</returns>

public bool CanFire(TTrigger trigger)

{

return CurrentRepresentation.CanHandle(trigger);

}

/// <summary>

/// A human-readable representation of the state machine.

/// </summary>

/// <returns>A description of the current state and permitted triggers.</returns>

public override string ToString()

{

return string.Format(

"StateMachine {{ State = {0}, PermittedTriggers = {{ {1} }}}}",

State,

string.Join(", ", GetPermittedTriggers().Select(t => t.ToString()).ToArray()));

}

/// <summary>

/// Specify the arguments that must be supplied when a specific trigger is fired.

/// </summary>

/// <typeparam name="TArg0">Type of the first trigger argument.</typeparam>

/// <param name="trigger">The underlying trigger value.</param>

/// <returns>An object that can be passed to the Fire() method in order to

/// fire the parameterised trigger.</returns>

public TriggerWithParameters<TArg0> SetTriggerParameters<TArg0>(TTrigger trigger)

{

var configuration = new TriggerWithParameters<TArg0>(trigger);

SaveTriggerConfiguration(configuration);

return configuration;

}

/// <summary>

/// Specify the arguments that must be supplied when a specific trigger is fired.

/// </summary>

/// <typeparam name="TArg0">Type of the first trigger argument.</typeparam>

/// <typeparam name="TArg1">Type of the second trigger argument.</typeparam>

/// <param name="trigger">The underlying trigger value.</param>

/// <returns>An object that can be passed to the Fire() method in order to

/// fire the parameterised trigger.</returns>

public TriggerWithParameters<TArg0, TArg1> SetTriggerParameters<TArg0, TArg1>(TTrigger trigger)

{

var configuration = new TriggerWithParameters<TArg0, TArg1>(trigger);

SaveTriggerConfiguration(configuration);

return configuration;

}

/// <summary>

/// Specify the arguments that must be supplied when a specific trigger is fired.

/// </summary>

/// <typeparam name="TArg0">Type of the first trigger argument.</typeparam>

/// <typeparam name="TArg1">Type of the second trigger argument.</typeparam>

/// <typeparam name="TArg2">Type of the third trigger argument.</typeparam>

/// <param name="trigger">The underlying trigger value.</param>

/// <returns>An object that can be passed to the Fire() method in order to

/// fire the parameterised trigger.</returns>

public TriggerWithParameters<TArg0, TArg1, TArg2> SetTriggerParameters<TArg0, TArg1, TArg2>(TTrigger trigger)

{

var configuration = new TriggerWithParameters<TArg0, TArg1, TArg2>(trigger);

SaveTriggerConfiguration(configuration);

return configuration;

}

void SaveTriggerConfiguration(TriggerWithParameters trigger)

{

if (_triggerConfiguration.ContainsKey(trigger.Trigger))

throw new InvalidOperationException(

string.Format(StateMachineResources.CannotReconfigureParameters, trigger));

_triggerConfiguration.Add(trigger.Trigger, trigger);

}

void DefaultUnhandledTriggerAction(TState state, TTrigger trigger, ICollection<string> unmetGuardConditions)

{

if (unmetGuardConditions?.Any() ?? false)

throw new InvalidOperationException(

string.Format(

StateMachineResources.NoTransitionsUnmetGuardConditions,

trigger, state, string.Join(", ", unmetGuardConditions)));

throw new InvalidOperationException(

string.Format(

StateMachineResources.NoTransitionsPermitted,

trigger, state));

}

/// <summary>

/// Registers a callback that will be invoked every time the statemachine

/// transitions from one state into another.

/// </summary>

/// <param name="onTransitionAction">The action to execute, accepting the details

/// of the transition.</param>

public void OnTransitioned(Action<Transition> onTransitionAction)

{

if (onTransitionAction == null) throw new ArgumentNullException(nameof(onTransitionAction));

_onTransitionedEvent.Register(onTransitionAction);

}

}

}