🐛 doc: fix 404 links, dead Run buttons, add examples + FAQ

doc/examples.md

@@ -79,6 +79,10 @@
 ![CPP](https://raw.githubusercontent.com/boost-ext/sml/master/example/dispatch_table.cpp)
 [▶ Run on Compiler Explorer](https://godbolt.org/z/j5bMnobY9)
 
+###Dispatch Policy
+![CPP](https://raw.githubusercontent.com/boost-ext/sml/master/example/dispatch_policy.cpp)
+[▶ Run on Compiler Explorer](https://godbolt.org/z/Mnqz6bEoz)
+
 ###eUML Emulation
 ![CPP](https://raw.githubusercontent.com/boost-ext/sml/master/example/euml_emulation.cpp)
 [▶ Run on Compiler Explorer](https://godbolt.org/z/n93Y5Mner)
@@ -95,6 +99,14 @@
 ![CPP](https://raw.githubusercontent.com/boost-ext/sml/master/example/in_place.cpp)
 [▶ Run on Compiler Explorer](https://godbolt.org/z/r43fKbz6z)
 
+###Eval
+![CPP](https://raw.githubusercontent.com/boost-ext/sml/master/example/eval.cpp)
+[▶ Run on Compiler Explorer](https://godbolt.org/z/MM1aTd11a)
+
+###Visitor
+![CPP](https://raw.githubusercontent.com/boost-ext/sml/master/example/visitor.cpp)
+[▶ Run on Compiler Explorer](https://godbolt.org/z/frPxxYv74)
+
 ###Dependency Injection
 ![CPP](https://raw.githubusercontent.com/boost-ext/sml/master/example/dependency_injection.cpp)
 [▶ Run on Compiler Explorer](https://godbolt.org/z/1Pv6EaG7n)

doc/faq.md

@@ -29,3 +29,56 @@ class types — so SML's action-sequencing is bypassed. Wrap the actions with
 ```
 
 See `example/actions_guards.cpp` for a worked example.
+
+## Frequently asked questions
+
+### How do I get / inspect the current state(s)?
+
+Use `sm.is(...)` to test the active state, or `sm.visit_current_states(...)` to
+iterate them. `state.c_str()` gives the state name:
+
+```cpp
+assert(sm.is("idle"_s));
+sm.visit_current_states([](auto state) { std::cout << state.c_str() << '\n'; });
+```
+
+### How do I check whether the machine is in one of several states?
+
+`is(...)` accepts one state per orthogonal region, so all regions are tested in a
+single call (no need to release a held mutex between checks):
+
+```cpp
+sm.is(s1, s2);  // region 0 == s1 AND region 1 == s2
+```
+
+### How do I know whether an event was handled? Can I pass an event instance?
+
+`process_event` returns `bool` — `true` when the event was handled, `false`
+otherwise (an unhandled event triggers `unexpected_event<E>`). You can pass either a
+type or an instance:
+
+```cpp
+const bool handled = sm.process_event(my_event{42});
+```
+
+### How do I dispatch events from another thread or an async handler?
+
+Configure the machine with a `process_queue` / `defer_queue` policy and call
+`sm.flush_queue()` to drain events that were pushed after `process_event` returned
+(for example from an asynchronous callback). `flush_queue()` is a no-op when empty.
+
+### How do I discard deferred events?
+
+Use the `sml::clear_defer` action in a transition to drop events that were deferred
+earlier.
+
+### Is SML part of Boost?
+
+`[Boost].SML` is a standalone, single-header library with **no dependencies** —
+neither STL nor Boost are required. It is part of the `boost-ext` project; it is not
+(currently) an official Boost library, and you do not need Boost to use it.
+
+### Is SML a Moore or a Mealy state machine?
+
+Both. Transition actions run on transitions (Mealy), while `on_entry<...>` /
+`on_exit<...>` provide per-state actions (Moore).

doc/index.md

@@ -11,10 +11,10 @@ Introduction
 
 | **[Boost::ext].SML (State Machine Language/Lite/Library)** | |
 | - | - |
-| Your scalable C++14 one header only State Machine Library with no dependencies ([__Try it online!__](hsttp://boost-ext.github.io/sml/examples/index.html#hello-world)) | <a class="github-button" href="https://github.com/boost-ext/sml" data-style="mega" data-count-href="/boost-ext/sml/stargazers" data-count-api="/repos/boost-ext/sml#stargazers_count" data-count-aria-label="# stargazers on GitHub" aria-label="Star boost-ext/sml on GitHub">GitHub</a> |
+| Your scalable C++14 one header only State Machine Library with no dependencies ([__Try it online!__](examples.html#hello-world)) | <a class="github-button" href="https://github.com/boost-ext/sml" data-style="mega" data-count-href="/boost-ext/sml/stargazers" data-count-api="/repos/boost-ext/sml#stargazers_count" data-count-aria-label="# stargazers on GitHub" aria-label="Star boost-ext/sml on GitHub">GitHub</a> |
 
 <div class="important">
-<a href="https://github.com/boost-ext/sml/releases" class="btn btn-success" style="margin-bottom:8px;" role="button"><span class="fa fa-download"></span>&nbsp; <b>Download</b></a> &nbsp;&nbsp;&nbsp;&nbsp; <a href="CHANGELOG/index.html" class="btn btn-info" style="margin-bottom:8px;" role="button"><span class="fa fa-reorder"></span>&nbsp; <b>Changelog</b></a> &nbsp;&nbsp;&nbsp;&nbsp; <a href="tutorial/index.html" class="btn btn-warning" style="margin-bottom:8px;" role="button"><span class="fa fa-gear"></span>&nbsp; <b>Tutorial</b></a> &nbsp;&nbsp;&nbsp;&nbsp; <a href="examples/index.html" class="btn btn-danger" style="margin-bottom:8px;" role="button"><span class="fa fa-book"></span>&nbsp; <b>Examples</b></a>
+<a href="https://github.com/boost-ext/sml/releases" class="btn btn-success" style="margin-bottom:8px;" role="button"><span class="fa fa-download"></span>&nbsp; <b>Download</b></a> &nbsp;&nbsp;&nbsp;&nbsp; <a href="CHANGELOG.html" class="btn btn-info" style="margin-bottom:8px;" role="button"><span class="fa fa-reorder"></span>&nbsp; <b>Changelog</b></a> &nbsp;&nbsp;&nbsp;&nbsp; <a href="tutorial.html" class="btn btn-warning" style="margin-bottom:8px;" role="button"><span class="fa fa-gear"></span>&nbsp; <b>Tutorial</b></a> &nbsp;&nbsp;&nbsp;&nbsp; <a href="examples.html" class="btn btn-danger" style="margin-bottom:8px;" role="button"><span class="fa fa-book"></span>&nbsp; <b>Examples</b></a>
 </div>
 
 ###UML State Machine
@@ -44,13 +44,9 @@ to avoid it `[Boost].SML` may suit you!
 
 ###Real Life examples?
 
-![CPP(BTN)](Run_SDL2_Integration_Example|https://raw.githubusercontent.com/boost-ext/sml/master/example/sdl2.cpp)
 [▶ Run on Compiler Explorer](https://godbolt.org/z/8heY58eE6)
-![CPP(BTN)](Run_Plant_UML_Example|https://raw.githubusercontent.com/boost-ext/sml/master/example/plant_uml.cpp)
 [▶ Run on Compiler Explorer](https://godbolt.org/z/8eT6aWsc9)
-![CPP(BTN)](Run_Logging_Example|https://raw.githubusercontent.com/boost-ext/sml/master/example/logging.cpp)
 [▶ Run on Compiler Explorer](https://godbolt.org/z/Tec7jz36r)
-![CPP(BTN)](Run_Testing_Example|https://raw.githubusercontent.com/boost-ext/sml/master/example/testing.cpp)
 [▶ Run on Compiler Explorer](https://godbolt.org/z/oc73h5sY8)
 
 &nbsp;

doc/themes/boost-modern/js/utility.js

@@ -12,3 +12,7 @@ $(document).ready(function () {
         $(this).replaceWith(video);
     });
 });
+// Open "Run on Compiler Explorer" links in a new browser tab.
+$(document).ready(function () {
+    $("a[href*='godbolt.org']").attr("target", "_blank").attr("rel", "noopener");
+});

doc/tutorial.md

@@ -74,11 +74,8 @@ States are printable too.
 assert(string("idle") == "idle"_s.c_str());
 ```
 
-![CPP(BTN)](Run_Events_Example|https://raw.githubusercontent.com/boost-ext/sml/master/example/events.cpp)
 [▶ Run on Compiler Explorer](https://godbolt.org/z/s816cG5j8)
-![CPP(BTN)](Run_States_Example|https://raw.githubusercontent.com/boost-ext/sml/master/example/states.cpp)
 [▶ Run on Compiler Explorer](https://godbolt.org/z/c9asGjYTr)
-![CPP(BTN)](Run_Composite_Example|https://raw.githubusercontent.com/boost-ext/sml/master/example/composite.cpp)
 [▶ Run on Compiler Explorer](https://godbolt.org/z/5sYb9eGbe)
 
  
@@ -130,7 +127,6 @@ struct Counter { int n = 0; };
 auto inc = sml::make_action<Counter&>([](auto& c) { c.n++; }); // generic lambda -> Counter&
 ```
 
-![CPP(BTN)](Run_Actions_Guards_Example|https://raw.githubusercontent.com/boost-ext/sml/master/example/actions_guards.cpp)
 [▶ Run on Compiler Explorer](https://godbolt.org/z/nehrdofPx)
 
 &nbsp;
@@ -201,9 +197,7 @@ make_transition_table(
 );
 ```
 
-![CPP(BTN)](Run_Transition_Table_Example|https://raw.githubusercontent.com/boost-ext/sml/master/example/transitions.cpp)
 [▶ Run on Compiler Explorer](https://godbolt.org/z/qr8qs78Ts)
-![CPP(BTN)](Run_eUML_Emulation_Example|https://raw.githubusercontent.com/boost-ext/sml/master/example/euml_emulation.cpp)
 [▶ Run on Compiler Explorer](https://godbolt.org/z/n93Y5Mner)
 
 &nbsp;
@@ -248,9 +242,7 @@ make_transition_table(
 );
 ```
 
-![CPP(BTN)](Run_Orthogonal_Regions_Example|https://raw.githubusercontent.com/boost-ext/sml/master/example/orthogonal_regions.cpp)
 [▶ Run on Compiler Explorer](https://godbolt.org/z/vqGbsrqM3)
-![CPP(BTN)](Run_History_Example|https://raw.githubusercontent.com/boost-ext/sml/master/example/history.cpp)
 [▶ Run on Compiler Explorer](https://godbolt.org/z/Pvz6Y7vd4)
 
 &nbsp;
@@ -314,9 +306,7 @@ auto sm = injector.create<sm<example>>();
 sm.process_event(e1{});
 ```
 
-![CPP(BTN)](Run_Hello_World_Example|https://raw.githubusercontent.com/boost-ext/sml/master/example/hello_world.cpp)
 [▶ Run on Compiler Explorer](https://godbolt.org/z/dq85hW4ab)
-![CPP(BTN)](Run_Dependency_Injection_Example|https://raw.githubusercontent.com/boost-ext/sml/master/example/dependency_injection.cpp)
 [▶ Run on Compiler Explorer](https://godbolt.org/z/1Pv6EaG7n)
 
 &nbsp;
@@ -384,11 +374,8 @@ SDL_Event event{SDL_QUIT};
 dispatch_event(event, event.type); // will call sm.process(game_over{});
 ```
 
-![CPP(BTN)](Run_Hello_World_Example|https://raw.githubusercontent.com/boost-ext/sml/master/example/hello_world.cpp)
 [▶ Run on Compiler Explorer](https://godbolt.org/z/dq85hW4ab)
-![CPP(BTN)](Run_Dispatch_Table_Example|https://raw.githubusercontent.com/boost-ext/sml/master/example/dispatch_table.cpp)
 [▶ Run on Compiler Explorer](https://godbolt.org/z/j5bMnobY9)
-![CPP(BTN)](Run_SDL2_Integration_Example|https://raw.githubusercontent.com/boost-ext/sml/master/example/sdl2.cpp)
 [▶ Run on Compiler Explorer](https://godbolt.org/z/8heY58eE6)
 
 &nbsp;
@@ -456,7 +443,6 @@ make_transition_table(
 );
 ```
 
-![CPP(BTN)](Run_Error_Handling_Example|https://raw.githubusercontent.com/boost-ext/sml/master/example/error_handling.cpp)
 [▶ Run on Compiler Explorer](https://godbolt.org/z/cGd7TnM1G)
 
 &nbsp;
@@ -490,7 +476,6 @@ sm.process_event(event{});
 assert(sm.is(X));
 ```
 
-![CPP(BTN)](Run_Testing_Example|https://raw.githubusercontent.com/boost-ext/sml/master/example/testing.cpp)
 [▶ Run on Compiler Explorer](https://godbolt.org/z/oc73h5sY8)
 
 &nbsp;
@@ -532,9 +517,7 @@ sml::sm<logging, sml::logger<my_logger>> sm{logger};
 sm.process_event(my_event{}); // will call logger appropriately
 ```
 
-![CPP(BTN)](Run_Logging_Example|https://raw.githubusercontent.com/boost-ext/sml/master/example/logging.cpp)
 [▶ Run on Compiler Explorer](https://godbolt.org/z/Tec7jz36r)
-![CPP(BTN)](Run_Plant_UML_Example|https://raw.githubusercontent.com/boost-ext/sml/master/example/plant_uml.cpp)
 [▶ Run on Compiler Explorer](https://godbolt.org/z/8eT6aWsc9)
 
 &nbsp;

doc/user_guide.md

@@ -41,7 +41,6 @@ Requirements for transition.
     static_assert(transitional<decltype(transition)>::value);
     }
 
-![CPP(BTN)](Run_Transitional_Example|https://raw.githubusercontent.com/boost-ext/sml/master/test/ft/errors/not_transitional.cpp)
 [▶ See the compile error on Compiler Explorer](https://godbolt.org/z/3aWdcTanT)
 
 &nbsp;
@@ -81,7 +80,6 @@ Requirements for the state machine.
 
     static_assert(configurable<example>::value);
 
-![CPP(BTN)](Run_Configurable_Example|https://raw.githubusercontent.com/boost-ext/sml/master/test/ft/errors/not_configurable.cpp)
 [▶ See the compile error on Compiler Explorer](https://godbolt.org/z/zehzezMoe)
 
 &nbsp;
@@ -119,7 +117,6 @@ Requirements for action and guards.
     static_assert(callable<bool, decltype(guard)>::value);
     static_assert(callable<void, decltype(action)>::value);
 
-![CPP(BTN)](Run_Callable_Example|https://raw.githubusercontent.com/boost-ext/sml/master/test/ft/errors/not_callable.cpp)
 [▶ See the compile error on Compiler Explorer](https://godbolt.org/z/fb8K6q4WK)
 
 &nbsp;
@@ -166,9 +163,7 @@ Requirements for the dispatch table.
     static_assert(dispatchable<runtime_event, event1>::value);
     static_assert(dispatchable<runtime_event, event2>::value);
 
-![CPP(BTN)](Run_Dispatchable_Example|https://raw.githubusercontent.com/boost-ext/sml/master/test/ft/errors/not_dispatchable.cpp)
 [▶ See the compile error on Compiler Explorer](https://godbolt.org/z/984KoaP6x)
-![CPP(BTN)](Run_SDL2_Integration_Example|https://raw.githubusercontent.com/boost-ext/sml/master/example/sdl2.cpp)
 [▶ Run on Compiler Explorer](https://godbolt.org/z/8heY58eE6)
 
 &nbsp;
@@ -233,11 +228,8 @@ Represents a state machine state.
     auto history_state = idle(H);
     auto terminate_state = X;
 
-![CPP(BTN)](Run_States_Example|https://raw.githubusercontent.com/boost-ext/sml/master/example/states.cpp)
 [▶ Run on Compiler Explorer](https://godbolt.org/z/c9asGjYTr)
-![CPP(BTN)](Run_Composite_Example|https://raw.githubusercontent.com/boost-ext/sml/master/example/composite.cpp)
 [▶ Run on Compiler Explorer](https://godbolt.org/z/5sYb9eGbe)
-![CPP(BTN)](Run_Orthogonal_Regions_Example|https://raw.githubusercontent.com/boost-ext/sml/master/example/orthogonal_regions.cpp)
 [▶ Run on Compiler Explorer](https://godbolt.org/z/vqGbsrqM3)
 
 &nbsp;
@@ -288,9 +280,7 @@ Represents a state machine event.
 
     auto my_int_event = event<int>;
 
-![CPP(BTN)](Run_Events_Example|https://raw.githubusercontent.com/boost-ext/sml/master/example/actions_guards.cpp)
 [▶ Run on Compiler Explorer](https://godbolt.org/z/nehrdofPx)
-![CPP(BTN)](Run_Error_Handling_Example|https://raw.githubusercontent.com/boost-ext/sml/master/example/error_handling.cpp)
 [▶ Run on Compiler Explorer](https://godbolt.org/z/cGd7TnM1G)
 
 &nbsp;
@@ -337,7 +327,6 @@ Creates a transition table.
       }
     };
 
-![CPP(BTN)](Run_Transition_Table_Example|https://raw.githubusercontent.com/boost-ext/sml/master/example/transitions.cpp)
 [▶ Run on Compiler Explorer](https://godbolt.org/z/qr8qs78Ts)
 
 &nbsp;
@@ -424,11 +413,8 @@ Creates a State Machine.
 
     sm.visit_current_states([](auto state) { std::cout << state.c_str() << std::endl; });
 
-![CPP(BTN)](Run_Hello_World_Example|https://raw.githubusercontent.com/boost-ext/sml/master/example/hello_world.cpp)
 [▶ Run on Compiler Explorer](https://godbolt.org/z/dq85hW4ab)
-![CPP(BTN)](Run_Dependency_Injection_Example|https://raw.githubusercontent.com/boost-ext/sml/master/example/dependency_injection.cpp)
 [▶ Run on Compiler Explorer](https://godbolt.org/z/1Pv6EaG7n)
-![CPP(BTN)](Run_eUML_Emulation_Example|https://raw.githubusercontent.com/boost-ext/sml/master/example/euml_emulation.cpp)
 [▶ Run on Compiler Explorer](https://godbolt.org/z/n93Y5Mner)
 
 &nbsp;
@@ -465,7 +451,6 @@ Additional State Machine configurations.
     sml::sm<example, sml::logger<my_logger>, sml::thread_safe<std::recursive_mutex>> sm; // thread safe and logger policy
     sml::sm<example, sml::deps<MyDep>> sm{dep}; // explicit pool dependency for generic-lambda actions/guards
 
-![CPP(BTN)](Run_Logging_Example|https://raw.githubusercontent.com/boost-ext/sml/master/example/logging.cpp)
 [▶ Run on Compiler Explorer](https://godbolt.org/z/Tec7jz36r)
 
 &nbsp;
@@ -511,7 +496,6 @@ Creates a state machine with testing capabilities.
     sm.process_event(TEvent{});
     sm.is(X);
 
-![CPP(BTN)](Run_Testing_Example|https://raw.githubusercontent.com/boost-ext/sml/master/example/testing.cpp)
 [▶ Run on Compiler Explorer](https://godbolt.org/z/oc73h5sY8)
 
 &nbsp;
@@ -606,9 +590,7 @@ Creates a dispatch table to handle runtime events.
     auto dispatch_event = sml::utility::make_dispatch_table<runtime_event, 1 /*min*/, 5 /*max*/>(sm);
     dispatch_event(event, event.id);
 
-![CPP(BTN)](Run_Dispatch_Table_Example|https://raw.githubusercontent.com/boost-ext/sml/master/example/dispatch_table.cpp)
 [▶ Run on Compiler Explorer](https://godbolt.org/z/j5bMnobY9)
-![CPP(BTN)](Run_SDL2_Integration_Example|https://raw.githubusercontent.com/boost-ext/sml/master/example/sdl2.cpp)
 [▶ Run on Compiler Explorer](https://godbolt.org/z/8heY58eE6)
 
 &nbsp;