Experimental (#18)

+ documented most methods and classes
^ hid logger code under HFSM_IF_LOG_INTERFACE
^ hid utility code under HFSM_ENABLE_UTILITY_THEORY
* fixed linking issues with feature configuration macros
~ renamed 'HFSM_*' macros to 'HFSM2_*'

Author: andrew-gresyk

examples/advanced_event_handling/main.cpp

@@ -22,7 +22,7 @@
 //	    changed to Target
 
 // optional: enable FSM structure report in debugger
-#define HFSM_ENABLE_STRUCTURE_REPORT
+#define HFSM2_ENABLE_STRUCTURE_REPORT
 #include <hfsm2/machine.hpp>
 
 #include <iostream>
@@ -38,6 +38,29 @@ using TransitionEvent = char;
 
 //------------------------------------------------------------------------------
 
+#if 0
+
+// states need to be forward declared to be used in FSM struct declaration
+class Reactive;
+class NonHandler;
+class ConcreteHandler;
+class TemplateHandler;
+class EnableIfHandler;
+class Target;
+
+using FSM = M::PeerRoot<
+				M::Orthogonal<Reactive,
+					NonHandler,
+					ConcreteHandler,
+					TemplateHandler,
+					EnableIfHandler
+				>,
+				Target
+			>;
+
+#else
+
+// alternatively, some macro magic can be invoked to simplify FSM structure declaration
 #define S(s) struct s
 
 using FSM = M::PeerRoot<
@@ -52,6 +75,8 @@ using FSM = M::PeerRoot<
 
 #undef S
 
+#endif
+
 //------------------------------------------------------------------------------
 
 static_assert(FSM::regionId<Reactive>()		  ==  1, "");

examples/basic_audio_player/main.cpp

@@ -4,8 +4,8 @@
 // An HFSM2 port of https://gist.github.com/martinmoene/797b1923f9c6c1ae355bb2d6870be25e
 // by Martin Moene (see https://twitter.com/MartinMoene/status/1118453128834232320)
 
-#define HFSM_ENABLE_LOG_INTERFACE
-#define HFSM_ENABLE_STRUCTURE_REPORT
+#define HFSM2_ENABLE_LOG_INTERFACE
+#define HFSM2_ENABLE_STRUCTURE_REPORT
 #include <hfsm2/machine.hpp>
 
 #include <assert.h>
@@ -25,15 +25,34 @@ struct Stop   {};
 using Context = std::string;
 using M = hfsm2::MachineT<hfsm2::Config::ContextT<Context>>;
 
-// fsm structure
+#if 0
+
+// states need to be forward declared to be used in FSM struct declaration
+struct Idle;
+struct Playing;
+struct Paused;
+
+using FSM = M::PeerRoot<
+				Idle,
+				Playing,
+				Paused
+			>;
+
+#else
+
+// alternatively, some macro magic can be invoked to simplify FSM structure declaration
 #define S(s) struct s
+
 using FSM = M::PeerRoot<
 				S(Idle),
 				S(Playing),
 				S(Paused)
 			>;
+
 #undef S
 
+#endif
+
 //------------------------------------------------------------------------------
 
 // double-check state ids for Logger::stateName()

examples/basic_traffic_light/main.cpp

@@ -33,7 +33,7 @@
 // Off
 
 // optional: enable FSM structure report in debugger
-#define HFSM_ENABLE_STRUCTURE_REPORT
+#define HFSM2_ENABLE_STRUCTURE_REPORT
 #include <hfsm2/machine.hpp>
 
 #include <iostream>
@@ -48,6 +48,31 @@ struct Context {
 // convenience typedef
 using M = hfsm2::MachineT<hfsm2::Config::ContextT<Context>>;
 
+#if 0
+
+// states need to be forward declared to be used in FSM struct declaration
+struct On;
+struct Red;
+struct YellowDownwards;
+struct YellowUpwards;
+struct Green;
+struct Off;
+
+using FSM = M::PeerRoot<
+				// sub-machine ..
+				M::Composite<On,
+					// .. with 4 sub-states
+					Red,
+					YellowDownwards,
+					YellowUpwards,
+					Green
+				>,
+				Off
+			>;
+
+#else
+
+// alternatively, some macro magic can be invoked to simplify FSM structure declaration
 #define S(s) struct s
 
 // state machine structure
@@ -65,6 +90,8 @@ using FSM = M::PeerRoot<
 
 #undef S
 
+#endif
+
 //------------------------------------------------------------------------------
 
 static_assert(FSM::regionId<On>()			  ==  1, "");

examples/calculator/main.cpp

@@ -6,7 +6,6 @@
 
 #include <iostream>
 #include <conio.h>
-#include <cmath>
 
 
 #define DEBUG 1

examples/debug_logger_interface/main.cpp

@@ -39,7 +39,7 @@
 //	---------- done! ---------
 
 // enable logger functionality
-#define HFSM_ENABLE_LOG_INTERFACE
+#define HFSM2_ENABLE_LOG_INTERFACE
 #include <hfsm2/machine.hpp>
 
 #include <iostream>
@@ -49,6 +49,21 @@
 // convenience typedef
 using M = hfsm2::Machine;
 
+#if 0
+
+// states need to be forward declared to be used in FSM struct declaration
+struct Top;
+struct From;
+struct To;
+
+using FSM = M::Root<Top,
+				From,
+				To
+			>;
+
+#else
+
+// alternatively, some macro magic can be invoked to simplify FSM structure declaration
 #define S(s) struct s
 
 using FSM = M::Root<S(Top),
@@ -58,6 +73,8 @@ using FSM = M::Root<S(Top),
 
 #undef S
 
+#endif
+
 //------------------------------------------------------------------------------
 
 static_assert(FSM::regionId<Top>()	==  0, "");

examples/snippets/docs_serialization.cpp

@@ -1,10 +1,9 @@
 // HFSM2 (hierarchical state machine for games and interactive applications)
 // Created by Andrew Gresyk
 
-#define HFSM_ENABLE_SERIALIZATION
+#define HFSM2_ENABLE_SERIALIZATION
 
-//#include <hfsm2/machine.hpp>
-#include <hfsm2/machine_dev.hpp>
+#include <hfsm2/machine.hpp>
 
 #include <catch2/catch.hpp>
 #undef assert

examples/snippets/wiki_transitions-within-hierarchy.cpp

@@ -1,6 +1,7 @@
 // HFSM2 (hierarchical state machine for games and interactive applications)
 // Created by Andrew Gresyk
 
+#define HFSM2_ENABLE_UTILITY_THEORY
 #include <hfsm2/machine.hpp>
 
 #include <catch2/catch.hpp>

examples/snippets/wiki_utility-theory.cpp

@@ -1,8 +1,9 @@
 // HFSM2 (hierarchical state machine for games and interactive applications)
 // Created by Andrew Gresyk
 
-#define HFSM_ENABLE_LOG_INTERFACE
-#define HFSM_ENABLE_VERBOSE_DEBUG_LOG
+#define HFSM2_ENABLE_LOG_INTERFACE
+#define HFSM2_ENABLE_UTILITY_THEORY
+#define HFSM2_ENABLE_VERBOSE_DEBUG_LOG
 #include <hfsm2/machine.hpp>
 
 #include <catch2/catch.hpp>
@@ -38,7 +39,7 @@ using Events = std::vector<Event>;
 //------------------------------------------------------------------------------
 
 struct Logger
-    : hfsm2::LoggerInterface    // requires HFSM_ENABLE_LOG_INTERFACE defined
+    : hfsm2::LoggerInterface    // requires HFSM2_ENABLE_LOG_INTERFACE defined
 {
     void recordMethod(Context& /*context*/,
                       const StateID state,
@@ -122,7 +123,7 @@ using FSM = M::PeerRoot<
             >;
 
 //------------------------------------------------------------------------------
-// with HFSM_ENABLE_VERBOSE_DEBUG_LOG inherited state methods will also be logged
+// with HFSM2_ENABLE_VERBOSE_DEBUG_LOG inherited state methods will also be logged
 
 struct Origin       : FSM::State {};
 

include/hfsm2/detail/debug/logger_interface.hpp

@@ -1,16 +1,22 @@
-#pragma once
-
 namespace hfsm2 {
 
-#if defined HFSM_ENABLE_LOG_INTERFACE || defined HFSM_ENABLE_VERBOSE_DEBUG_LOG
+#ifdef HFSM2_ENABLE_LOG_INTERFACE
 
 ////////////////////////////////////////////////////////////////////////////////
 
-template <typename TContext = EmptyContext,
-		  typename TUtilty = float>
+template <typename TContext = EmptyContext
+
+#ifdef HFSM2_ENABLE_UTILITY_THEORY
+		, typename TUtilty = float
+#endif
+
+		  >
 struct LoggerInterfaceT {
 	using Context		 = TContext;
+
+#ifdef HFSM2_ENABLE_UTILITY_THEORY
 	using Utilty		 = TUtilty;
+#endif
 
 	using Method		 = ::hfsm2::Method;
 	using StateID		 = ::hfsm2::StateID;
@@ -44,6 +50,8 @@ struct LoggerInterfaceT {
 										const StateID /*origin*/)
 	{}
 
+#ifdef HFSM2_ENABLE_UTILITY_THEORY
+
 	virtual void recordUtilityResolution(Context& /*context*/,
 										 const StateID /*head*/,
 										 const StateID /*prong*/,
@@ -55,6 +63,8 @@ struct LoggerInterfaceT {
 										const StateID /*prong*/,
 										const Utilty /*utilty*/)
 	{}
+
+#endif
 };
 
 ////////////////////////////////////////////////////////////////////////////////

include/hfsm2/detail/debug/shared.hpp

@@ -1,14 +1,15 @@
-#pragma once
-
 ////////////////////////////////////////////////////////////////////////////////
 
 namespace hfsm2 {
 
 enum class Method : uint8_t {
 	NONE,
 
+#ifdef HFSM2_ENABLE_UTILITY_THEORY
 	RANK,
 	UTILITY,
+#endif
+
 	ENTRY_GUARD,
 	CONSTRUCT,
 	ENTER,
@@ -28,8 +29,12 @@ enum class TransitionType : uint8_t {
 	CHANGE,
 	RESTART,
 	RESUME,
+
+#ifdef HFSM2_ENABLE_UTILITY_THEORY
 	UTILIZE,
 	RANDOMIZE,
+#endif
+
 	SCHEDULE,
 
 	COUNT
@@ -74,8 +79,12 @@ static inline
 const char*
 methodName(const Method method) {
 	switch (method) {
+
+#ifdef HFSM2_ENABLE_UTILITY_THEORY
 	case Method::RANK:			 return "rank";
 	case Method::UTILITY:		 return "utility";
+#endif
+
 	case Method::ENTRY_GUARD:	 return "entryGuard";
 	case Method::ENTER:			 return "enter";
 	case Method::CONSTRUCT:		 return "construct";
@@ -89,7 +98,7 @@ methodName(const Method method) {
 	case Method::PLAN_FAILED:	 return "planFailed";
 
 	default:
-		HFSM_BREAK();
+		HFSM2_BREAK();
 		return nullptr;
 	}
 }
@@ -103,12 +112,16 @@ transitionName(const TransitionType transitionType) {
 	case TransitionType::CHANGE:	return "changeTo";
 	case TransitionType::RESTART:	return "restart";
 	case TransitionType::RESUME:	return "resume";
+
+#ifdef HFSM2_ENABLE_UTILITY_THEORY
 	case TransitionType::UTILIZE:	return "utilize";
 	case TransitionType::RANDOMIZE:	return "randomize";
+#endif
+
 	case TransitionType::SCHEDULE:	return "schedule";
 
 	default:
-		HFSM_BREAK();
+		HFSM2_BREAK();
 		return nullptr;
 	}
 }