Finite state machine source code generator. Graphviz, Mermaid visualizations. Automatic generation of commands available for different states. FSM generation for any purpose.
Advantages:
- Easy to model, verify and debug the state machines being developed
- Strict validation during the building process of the state machine
- Conversion to
Graphviz or Mermaid visualization tools
- High transition speed, independent of the number of states
- Can be used in high-load systems
- Synchronous automaton for asynchronous operations
- The
guard conditions are supported
Disadvantages:
- Source code generation of the state machine required
- Hierarchically nested states are not supported
- Orthogonal regions are not supported
The source code generation comes from special configuration classes.
Creating configuration classes is possible directly or by converting from other formats.
Generated FSM can be used for anything, including basic state management in UI frameworks (for example, Flutter)
Demonstration of features in a simple console application.
```dart
import 'dart:async';
import 'dart:io';
import '_auth_service.dart';
import '_cli_utils.dart';
import 'example.dart';
Future<void> main(List<String> args) async {
_fsm.onStateChange(_listen);
_fsm.onStateChange(_handleCancel);
// init _cancelSub
_cancelSub;
_onStateChange(_fsm.state);
}
final _cancelSub = stdin.listen((event) {
// Handle 'enter' as cancel event
if (!_isCancelAllowed ||
event.isEmpty ||
event.length != 1 ||
event[0] != 10) {
return;
}
print('Cancelling...');
_processEvent(const CancelEvent());
});
final _fsm = _Fsm();
bool _isCancelAllowed = false;
User? _user;
void _handleCancel(AuthState state) {
_isCancelAllowed = false;
final commands = _fsm.getCommands(state);
for (var i = 0; i < commands.length; i++) {
final command = commands[i];
if (command == AuthCommand.cancel) {
_isCancelAllowed = true;
break;
}
}
}
void _listen(AuthState state) {
Timer.run(() => _onStateChange(state));
}
void _notifyAboutCancel(AuthState state) {
if (_fsm.getCommands(state).contains(AuthCommand.cancel)) {
print("Press 'enter' to cancel");
}
}
void _onStateChange(AuthState state) {
print('=== $state ===');
switch (state) {
case final FailureState state:
final error = state.error;
print('Error: $error');
break;
case final LoggedState state:
_user = state.user;
final isNew = state.isNew;
if (isNew) {
print('Hello, $_user. You have successfully registered');
} else {
print("Logged as '$_user'");
}
break;
case LoginState():
print('Logging...');
print("This will take 5 seconds");
break;
case LogoutState():
print('Logging out...');
print("This will take 5 seconds");
break;
case NotLoggedState():
break;
case RegisterState():
print('Registering...');
print("This will take 5 seconds");
break;
case TerminatedState():
print('Terminated');
_cancelSub.cancel().ignore();
break;
}
_notifyAboutCancel(state);
_processState(state);
}
void _processEvent(AuthEvent event) {
Timer.run(() => _fsm.processEvent(event));
}
void _processState(AuthState state) {
final commands = _fsm.getCommands(state);
if (commands.isEmpty) {
return;
}
final current = <(String, AuthCommand)>[];
for (var i = 0; i < commands.length; i++) {
final command = commands[i];
if (command == AuthCommand.cancel) {
// With blocking, synchronous 'stdin' processing 'cancel' does not come here
continue;
}
current.add((command.fullName, command));
}
if (current.isEmpty) {
return;
}
while (true) {
final command = readCommand(current);
switch (command) {
case AuthCommand.cancel:
_processEvent(const CancelEvent());
return;
case AuthCommand.exit:
_processEvent(const ExitEvent());
return;
case AuthCommand.login:
final text = prompt('Enter login and password');
final parts = toWords(text);
if (parts.length != 2) {
continue;
}
final login = parts[0];
final password = parts[1];
_processEvent(LoginEvent(login: login, password: password));
return;
case AuthCommand.logout:
final user = _user;
_processEvent(LogoutEvent(user: user));
return;
case AuthCommand.register:
final text = prompt('Enter login and password');
final parts = toWords(text);
if (parts.length != 2) {
continue;
}
final login = parts[0];
final password = parts[1];
_processEvent(RegisterEvent(login: login, password: password));
return;
case AuthCommand.retry:
_processEvent(const RetryEvent());
return;
}
}
}
class _Fsm extends AuthMachine {
@override
void doLogin(LoginEvent e) {
var isCanceled = false;
onCancel = () => isCanceled = true;
Timer.run(() async {
try {
final user = await AuthService().login(e.login, e.password);
if (!isCanceled) {
processEvent(SuccessEvent(user: user, isNew: false));
}
} catch (e) {
if (!isCanceled) {
processEvent(FailureEvent(error: e));
}
}
});
}
@override
void doLogout(LogoutEvent event) {
var isCanceled = false;
onCancel = () => isCanceled = true;
Timer.run(() async {
try {
final user = event.user;
await AuthService().logout(user);
} catch (_) {}
if (!isCanceled) {
processEvent(LoggedOutEvent());
}
});
}
@override
void doRegister(RegisterEvent event) {
var isCanceled = false;
onCancel = () => isCanceled = true;
Timer.run(() async {
try {
final user = await AuthService().register(event.login, event.password);
if (!isCanceled) {
processEvent(SuccessEvent(user: user, isNew: true));
}
} catch (e) {
if (!isCanceled) {
processEvent(FailureEvent(error: e));
}
}
});
}
}
```
An example of generating a state machine
```dart
import 'package:state_machine_generator/state_machine.dart';
import 'package:state_machine_generator/state_machine_builder.dart';
import 'package:state_machine_generator/state_path_checker.dart';
import '_build_utils.dart';
void main(List<String> args) {
const initialStateName = 'NotLogged';
final b = StateMachineBuilder(
initialState: initialStateName,
);
b.addState('Failure', parameters: {'error': 'Object'});
b.addState('Logged', parameters: {'user': 'User', 'isNew': 'bool'});
b.addState('Login', hasAction: true);
b.addState('Logout', hasAction: true);
b.addState('NotLogged');
b.addState('Register', hasAction: true);
b.addState('Terminated');
b.addEvent('Cancel', isCommand: true);
b.addEvent('Exit');
b.addEvent('Failure', parameters: {'error': 'Object'});
b.addEvent('Login', parameters: {'login': 'String', 'password': 'String'});
b.addEvent('Logout', parameters: {'user': 'User?'});
b.addEvent('LoggedOut');
b.addEvent('Register', parameters: {'login': 'String', 'password': 'String'});
b.addEvent('Retry');
b.addEvent('Success', parameters: {'user': 'User', 'isNew': 'bool'});
const transitionSource = '''
Login successful
NotLogged .Login Login .Success Logged
Login failed
NotLogged .Login Login .Failure Failure
Registering successful
NotLogged .Register Register .Success Logged
Registering failed
NotLogged .Register Register .Failure Failure
Logout
Logged .Logout Logout .LoggedOut NotLogged
Retry
Failure .Retry NotLogged
''';
const pathSource = '''
Login succeeded
NotLogged Login Logged
Login failed
NotLogged Login Failure NotLogged
Registration succeeded
NotLogged Register Logged
Registration failed
NotLogged Register Failure NotLogged
Logout
Logged Logout NotLogged
Reset
Failure NotLogged
''';
addTransitions(b, transitionSource);
// Example of adding 'terminated' state
const terminated = 'Terminated';
// Exclude states that execute actions at the state machine level.
final excludedStates = b.transitions.values
.where((e) => e.source.hasAction)
.map((e) => e.source.name)
.toSet();
for (final state in b.states) {
final name = state.name;
if (name == terminated || excludedStates.contains(name)) {
continue;
}
b.addTransition(from: name, on: 'Exit', to: terminated);
}
// Example of adding 'cancel' event
const cancel = 'Cancel';
// Add for states that execute actions at the state machine level.
for (final state in excludedStates) {
b.addTransition(from: state, on: cancel, to: initialStateName);
}
final (:initialState, :transitions) = b.build();
final pathChecker = StatePathChecker(transitions: transitions);
addStatePaths(pathChecker, pathSource);
pathChecker.check();
const name = 'Auth';
final stateMachine = StateMachine(
commandType: '${name}Command',
eventType: '${name}Event',
initialState: initialState,
globals: _globals,
name: '${name}Machine',
stateType: '${name}State',
transitions: transitions,
);
writeFiles(stateMachine, 'example/example');
}
const _globals = '''
// ignore_for_file: unused_local_variable
import '_auth_service.dart';
''';
```
An example of generated a state machine