#region Region.cs file

//

// StaMa state machine controller library

//

// Copyright (c) 2005, Roland Schneider. All rights reserved.

//

#endregion



using System;

using System.Collections.Generic;

using System.Diagnostics;





namespace StaMa

{

    /// <summary>

    /// Represents a container for states and defines the initial <see cref="State"/> for the contained states.

    /// </summary>

    /// <remarks>

    /// Instances of this class will be created through the <see cref="StateMachineTemplate.Region"/> method.

    /// </remarks>

    [DebuggerDisplay("DistinguishedName={DistinguishedName}")]

    public class Region

    {

        private State m_parentState;

        private StateCollection m_states;

        private State m_initialState;

        private string m_initialStateName;

        private uint m_historyIndex;

        private uint m_stateConfigurationIndex;





        /// <summary>

        /// Initializes a new <see cref="Region"/> instance. 

        /// </summary>

        /// <param name="parentState">

        /// The <see cref="State"/> instance that contains this <see cref="Region"/>. Shall be <c>null</c> for the root <see cref="Region"/> instance.

        /// </param>

        /// <param name="initialStateName">

        /// The name of the initial <see cref="State"/> of the <see cref="Region"/>.

        /// </param>

        /// <param name="historyIndex">

        /// If the <see cref="Region"/> shall have a history, the index of the slot where

        /// this <see cref="Region"/> stores its history in the <see cref="StateMachine"/> instance.

        /// If the region has no history, <see cref="uint.MaxValue">uint.MaxValue</see>.

        /// </param>

        /// <param name="stateMachineTemplate">

        /// The embedding <see cref="StateMachineTemplate"/> instance.

        /// Internally used for creating the <see cref="States"/> collection.

        /// </param>

        /// <remarks>

        /// Instances of this class will be created through the <see cref="StateMachineTemplate.Region"/> method.

        /// </remarks>

        internal protected Region(State parentState, string initialStateName, uint historyIndex, StateMachineTemplate stateMachineTemplate)

        {

            m_parentState = parentState;

            m_states = stateMachineTemplate.InternalCreateStateCollection();

            m_initialState = null;

            m_initialStateName = initialStateName;

            m_historyIndex = historyIndex;

            m_stateConfigurationIndex = uint.MaxValue;

        }





        internal void EndRegion()

        {

            foreach (State state in m_states)

            {

                if (state.Name == m_initialStateName)

                {

                    m_initialState = state;

                    break;

                }

            }

            if (m_initialState == null)

            {

                throw new InvalidOperationException("The initialStateName of the \"Region()\" statement doesn't correspond with an embedded State.");

            }

        }





        /// <summary>

        /// Overrides <see cref="System.Object.ToString"/> and returns the execution order of the <see cref="Region"/>.

        /// </summary>

        public override string ToString()

        {

            return this.ExecutionOrder.ToString();

        }





        internal string DistinguishedName

        {

            get

            {

                if (m_parentState != null)

                {

                    return m_parentState.DistinguishedName + '~' + this.ExecutionOrder.ToString();

                }

                else

                {

                    return '~' + this.ExecutionOrder.ToString();

                }

            }

        }





        /// <summary>

        /// Gets the <see cref="State"/> that aggregates this <see cref="Region"/>.

        /// </summary>

        public State Parent

        {

            get

            {

                return m_parentState;

            }

        }





        /// <summary>

        /// Gets the list of <see cref="State"/>s of this <see cref="Region"/>.

        /// </summary>

        /// <value>

        /// A <see cref="StateCollection"/> instance. At least one item (namely the

        /// <see cref="InitialState"/>) will be present in this collection.

        /// </value>

        public StateCollection States

        {

            get

            {

                return m_states;

            }

        }





        /// <summary>

        /// The sequential index of this <see cref="Region"/> within

        /// the <see cref="State.Regions"/> collection of the parent <see cref="State"/>.

        /// </summary>

        /// <value>

        /// A <see cref="uint"/> greater or equal 1.

        /// </value>

        public uint ExecutionOrder

        {

            get

            {

                if (m_parentState == null)

                {

                    return 1;

                }

                else

                {

#warning Make Regions inherit from LinkedList and follow Prev until we reach First.

                    uint index = 1;

                    foreach (Region region in this.Parent.Regions)

                    {

                        if (region == this)

                        {

                            return index;

                        }

                        index++;

                    }

                    // Logical error

                    throw new Exception("Internal error: Region instance not contained in regions list of parent state.");

                }

            }

        }





        /// <summary>

        /// The <see cref="State"/> that will be made active when the <see cref="Region"/> is entered

        /// the first time.

        /// </summary>

        public State InitialState

        {

            get

            {

                return m_initialState;

            }

        }





        /// <summary>

        /// The slot within a <see cref="StateConfiguration"/> that will be used by

        /// the active state of this <see cref="Region"/>.

        /// </summary>

        public uint StateConfigurationIndex

        {

            get

            {

                return m_stateConfigurationIndex;

            }

        }





        /// <summary>

        /// Indicates whether the recently active <see cref="State"/> will be made

        /// active on rentry of the <see cref="Region"/>.

        /// </summary>

        /// <value>

        /// <c>true</c> if the recently active <see cref="State"/> will be made

        /// active on rentry; <c>false</c> if the <see cref="InitialState"/> will be made active.

        /// </value>

        public bool HasHistory

        {

            get

            {

                return (m_historyIndex != uint.MaxValue);

            }

        }





        /// <summary>

        /// Gets the index of the slot where this <see cref="Region"/> stores its

        /// history in the <see cref="StateMachine"/> instance.

        /// </summary>

        /// <value>

        /// A <see cref="uint"/> if the <see cref="Region"/> has a history; otherwise, <see cref="uint.MaxValue">uint.MaxValue</see>.

        /// </value>

        public uint HistoryIndex

        {

            get

            {

                return m_historyIndex;

            }

        }





        internal bool PassThrough(IStateMachineTemplateVisitor visitor)

        {

            bool continuePassThrough = visitor.Region(this);

            if (!continuePassThrough)

            {

                return false;

            }



            // Iterate through states.

            foreach (State state in this.States)

            {

                continuePassThrough = state.PassThrough(visitor);

                if (!continuePassThrough)

                {

                    return false;

                }

            }



            continuePassThrough = visitor.EndRegion(this);

            if (!continuePassThrough)

            {

                return false;

            }

            

            return true;

        }





        internal void AddState(State state)

        {

            m_states.Add(state);

        }





        internal void FixupAndCalcStateConfigMetrics(ref uint stateConfigurationIndex, out uint stateConfigMax, out uint stateBasConfigMax)

        {

            // Set the slot for the active state reference.

            // For every region we have to reserve one slot in

            // the active state array.

            m_stateConfigurationIndex = stateConfigurationIndex;

            stateConfigurationIndex = stateConfigurationIndex + 1; // Increase value (children and siblings will start on a new index)



            uint stateConfigLocalMax = 0;

            stateBasConfigMax = 0; // Return the maximum of concurrent transitions for all substates



            foreach (State state in this.States)

            {

                uint stateConfigSize = 0; // Size of pointers needed for this state and its offspring in a state config array

                uint stateBasConfigSize = 0; // Size of pointers needed for this state in a base state configuration array



                state.FixupAndCalcStateConfigMetrics(stateConfigurationIndex, out stateConfigSize, out stateBasConfigSize);



                if (stateConfigSize > stateConfigLocalMax) stateConfigLocalMax = stateConfigSize; // Find the maximum needed over all states in this region

                if (stateBasConfigSize > stateBasConfigMax) stateBasConfigMax = stateBasConfigSize;

            }



            stateConfigMax = stateConfigLocalMax + 1; // Return the maximum of the offspring plus one for ourselves

            stateConfigurationIndex += stateConfigLocalMax; // Shift the index to reserve space for this region's offspring

        }





        internal void FinalFixup(StateMachineTemplate stateMachineTemplate)

        {

            // Recurse to sub items

            foreach (State state in this.States)

            {

                foreach (Transition transition in state.Transitions)

                {

                    transition.FinalFixup(stateMachineTemplate);

                }



                foreach (Region subRegion in state.Regions)

                {

                    subRegion.FinalFixup(stateMachineTemplate);

                }

            }

        }

    }





    /// <summary>

    /// Represents a list of <see cref="State"/> instances.

    /// </summary>

    public class StateCollection

    {

        private List<State> m_states;





        /// <summary>

        /// Initializes a new <see cref="StateCollection"/> instance.

        /// </summary>

        internal protected StateCollection()

        {

            m_states = new List<State>();

        }





        /// <summary>

        /// Returns an enumerator that iterates through the <see cref="StateCollection"/>. 

        /// </summary>

        /// <returns>

        /// A <see cref="System.Collections.IEnumerator"/> for the <see cref="StateCollection"/>.

        /// </returns>

        public System.Collections.IEnumerator GetEnumerator()

        {

            return ((System.Collections.IEnumerable)m_states).GetEnumerator();

        }





        /// <summary>

        /// Gets the <see cref="State"/> with a specific name within the <see cref="Region"/>.

        /// </summary>

        /// <param name="stateName">

        /// The name of the <see cref="State"/>.

        /// </param>

        /// <returns>

        /// The <see cref="State"/> with the specified name, or <c>null</c> if there is no such <see cref="State"/>.

        /// </returns>

        public State this[string stateName]

        {

            get

            {

                foreach (State state in m_states)

                {

                    if (stateName == state.Name)

                    {

                        return state;

                    }

                }

                return null;

            }

        }





        /// <summary>

        /// Gets the <see cref="State"/> at the specified index.

        /// </summary>

        /// <param name="index">

        /// The zero-based index of the <see cref="State"/> to get.

        /// </param>

        /// <returns>

        /// The <see cref="State"/> at the index.

        /// </returns>

        public State this[int index]

        {

            get

            {

                return m_states[index];

            }

        }





        /// <summary>

        /// Gets the number of elements contained in the <see cref="StateCollection"/>. 

        /// </summary>

        public int Count

        {

            get

            {

                return m_states.Count;

            }

        }

        



        internal void Add(State state)

        {

            m_states.Add(state);

        }

    }

}