Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/veelenga/aasm.cr
:arrows_clockwise: Easy to use finite state machine for Crystal classes
https://github.com/veelenga/aasm.cr
aasm crystal state-machine
Last synced: about 2 months ago
JSON representation
:arrows_clockwise: Easy to use finite state machine for Crystal classes
- Host: GitHub
- URL: https://github.com/veelenga/aasm.cr
- Owner: veelenga
- License: mit
- Created: 2016-01-16T23:14:45.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2022-11-19T13:24:42.000Z (almost 2 years ago)
- Last Synced: 2024-06-21T18:12:19.212Z (3 months ago)
- Topics: aasm, crystal, state-machine
- Language: Crystal
- Homepage: http://veelenga.github.io/aasm.cr
- Size: 652 KB
- Stars: 51
- Watchers: 3
- Forks: 5
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-crystal - aasm.cr - Easy to use finite state machine for Crystal classes (Misc)
- awesome-crystal - aasm.cr - Easy to use finite state machine for Crystal classes (Misc)
- awesome-crystal - aasm.cr - Easy to use finite state machine for Crystal classes (Misc)
README
# aasm.cr [![Build Status](https://travis-ci.org/veelenga/aasm.cr.svg?branch=master)](https://travis-ci.org/veelenga/aasm.cr)
Aasm stands for **"Acts As State Machine"** which means that some abstract object can act as a [finite state machine](https://en.wikipedia.org/wiki/Finite-state_machine) and can be in one of a finite number of states at a time; can change one state to another when initiated by a triggering event.
## Getting Started
Adding a state machine to a Crystal class is as simple as including `AASM` module and writing `act_as_state_machine` method where you can define **states** and **events** with their **transitions**:
```crystal
class Transaction
include AASMdef act_as_state_machine
aasm.state :pending, initial: true
aasm.state :active, enter: -> { puts "Just got activated" }
aasm.state :completedaasm.event :activate do |e|
e.transitions from: :pending, to: :active
endaasm.event :complete do |e|
e.transitions from: :active, to: :completed
end
end
endt = Transaction.new.tap &.act_as_state_machine
t.state #=> :pending
t.next_state #=> :active
t.fire :activate # Just got activated
t.state #=> :active
t.next_state #=> :completed
```### States
State can be defined using `aasm.state` method passing the name and options:
```crystal
aasm.state :passive, initial: true
```#### State options
Currently state supports the following options:
- `initial` : `Bool` **optional** - indicates whether this state is initial or not. If initial state not specified, first one will be considered as initial
- `guard` : `(-> Bool)` **optional** - a callback, that gets evaluated once state is getting entered. State will not enter if guard returns false
- `enter` : `(->)` **optional** - a hook, that gets evaluated once state entered.### Events
Event can be defined using `aasm.state` method passing the name and a block with transitions:
```crystal
aasm.event :delete do |e|
e.transitions from: :active, to: :deleted
end
```Event has to be defined after state definition. In other case `NoSuchStateException` will be raise.
#### Event options
Currently event supports the following options:
- `before` : `(->)` **optional** - a callback, that gets evaluated once before changing a state
- `after` : `(->)` **optional** - a callback, that gets evaluated once after changing a state.### Transitions
Transition can be defined on event with `transitions` method passing options:
```crystal
aasm.event :complete do |e|
e.transitions from: [:pending, :active], to: :deleted
end
```#### Transition options
Currently transition supports the following options:
- `from` : `(Symbol | Array(Symbol))` **required** - state (or states) from which state of state machine can be changed when event fired
- `to` : `Symbol` **required** - state to which state of state machine will change when event fired.## More examples
### One state machine (circular)
```crystal
class CircularStateMachine
include AASMdef act_as_state_machine
aasm.state :startedaasm.event :restart do |e|
e.transitions from: :started, to: :started
end
end
end
```### Two states machine
```crystal
class TwoStateMachine
include AASMdef act_as_state_machine
assm.state :active
aasm.state :deletedaasm.event :delete do |e|
e.transitions from: :active, to: :deleted
end
end
end
```### Three states machine
```crystal
class ThreeStatesMachine
include AASMdef act_as_state_machine
aasm.state :pending, initial: true
aasm.state :active
aasm.state :completedaasm.event :activate do |e|
e.transitions from: :pending, to: :active
end
aasm.event :complete do |e|
e.before { puts "completing..." }
e.after { puts "completed" }
e.transitions from: [:active, :pending], to: :completed
end
end
end
```