From 0fce49f4121fbff3a3923a2ec84ae715cd83f54c Mon Sep 17 00:00:00 2001 From: Pavel Guzenfeld Date: Tue, 2 Jun 2026 15:44:19 +0300 Subject: [PATCH 1/3] :bug: doc: fix 404 nav links, drop dead Run buttons, open Compiler Explorer in a new tab - index.md: the Changelog/Tutorial/Examples buttons and the 'Try it online' link pointed at /index.html, which 404 under use_directory_urls:false; point them at the flat CHANGELOG.html/tutorial.html/examples.html (and fix the 'hsttp://' typo). - Remove the broken ![CPP(BTN)](Run_*) buttons from index/tutorial/user_guide; each was already paired with a working 'Run on Compiler Explorer' link, so only the dead button is dropped. - utility.js: open godbolt.org (Compiler Explorer) links in a new browser tab. --- doc/index.md | 8 ++------ doc/themes/boost-modern/js/utility.js | 4 ++++ doc/tutorial.md | 17 ----------------- doc/user_guide.md | 18 ------------------ 4 files changed, 6 insertions(+), 41 deletions(-) diff --git a/doc/index.md b/doc/index.md index 149d4453..c585fba8 100644 --- a/doc/index.md +++ b/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)) | GitHub | +| Your scalable C++14 one header only State Machine Library with no dependencies ([__Try it online!__](examples.html#hello-world)) | GitHub |
-  Download        Changelog        Tutorial        Examples +  Download        Changelog        Tutorial        Examples
###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)   diff --git a/doc/themes/boost-modern/js/utility.js b/doc/themes/boost-modern/js/utility.js index 0c8215c6..f9bc1fce 100644 --- a/doc/themes/boost-modern/js/utility.js +++ b/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'); +}); diff --git a/doc/tutorial.md b/doc/tutorial.md index 365cc67c..489a0c70 100644 --- a/doc/tutorial.md +++ b/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([](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)   @@ -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)   @@ -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)   @@ -314,9 +306,7 @@ auto sm = injector.create>(); 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)   @@ -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)   @@ -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)   @@ -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)   @@ -532,9 +517,7 @@ sml::sm> 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)   diff --git a/doc/user_guide.md b/doc/user_guide.md index ac754752..1b0eb87b 100644 --- a/doc/user_guide.md +++ b/doc/user_guide.md @@ -41,7 +41,6 @@ Requirements for transition. static_assert(transitional::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)   @@ -81,7 +80,6 @@ Requirements for the state machine. static_assert(configurable::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)   @@ -119,7 +117,6 @@ Requirements for action and guards. static_assert(callable::value); static_assert(callable::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)   @@ -166,9 +163,7 @@ Requirements for the dispatch table. static_assert(dispatchable::value); static_assert(dispatchable::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)   @@ -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)   @@ -288,9 +280,7 @@ Represents a state machine event. auto my_int_event = event; -![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)   @@ -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)   @@ -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)   @@ -465,7 +451,6 @@ Additional State Machine configurations. sml::sm, sml::thread_safe> sm; // thread safe and logger policy sml::sm> 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)   @@ -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)   @@ -606,9 +590,7 @@ Creates a dispatch table to handle runtime events. auto dispatch_event = sml::utility::make_dispatch_table(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)   From 678c75a6950ec9dd0d3cf0b651e8763724992dc1 Mon Sep 17 00:00:00 2001 From: Pavel Guzenfeld Date: Tue, 2 Jun 2026 15:44:19 +0300 Subject: [PATCH 2/3] :books: doc: add eval/visitor/dispatch_policy examples; expand FAQ from open issues - examples.md: add Eval, Visitor and Dispatch Policy (present in example/ but undocumented), each with a verified Compiler Explorer link. - faq.md: add answers grounded in the user-guide API table and v1.2.0 CHANGELOG for recurring questions (current-state inspection, multi-state checks, event handling/return value, async dispatch via flush_queue, clear_defer, Boost status, Moore vs Mealy). --- doc/examples.md | 12 +++++++++++ doc/faq.md | 53 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 65 insertions(+) diff --git a/doc/examples.md b/doc/examples.md index e0848538..6c62df11 100644 --- a/doc/examples.md +++ b/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) diff --git a/doc/faq.md b/doc/faq.md index c49ef59b..91b2ef64 100644 --- a/doc/faq.md +++ b/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`). 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). From 2bde481edd8a4e15cdd295b32907e9734d2c113e Mon Sep 17 00:00:00 2001 From: Pavel Guzenfeld Date: Tue, 2 Jun 2026 16:17:55 +0300 Subject: [PATCH 3/3] :wrench: doc: use double quotes in utility.js (Codacy ESLint quotes) --- doc/themes/boost-modern/js/utility.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/themes/boost-modern/js/utility.js b/doc/themes/boost-modern/js/utility.js index f9bc1fce..b35e9cc4 100644 --- a/doc/themes/boost-modern/js/utility.js +++ b/doc/themes/boost-modern/js/utility.js @@ -14,5 +14,5 @@ $(document).ready(function () { }); // Open "Run on Compiler Explorer" links in a new browser tab. $(document).ready(function () { - $('a[href*="godbolt.org"]').attr('target', '_blank').attr('rel', 'noopener'); + $("a[href*='godbolt.org']").attr("target", "_blank").attr("rel", "noopener"); });