aquam 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 756ccfa62e8a668e3f79a7a14d86a3d754a1f9fe
-  data.tar.gz: ddcad78f959438aecdba5ceab40e851b8dbcd95e
+  metadata.gz: b674adab6efcd651b120fdef7af647d72f2a56b6
+  data.tar.gz: a9d6999adf6e44a93dc3d2961b6a47ab41eec00d
 SHA512:
-  metadata.gz: 3c30391f82ffa5d1291a9d54ac0d76ca3dadbbbadec02e6a9ac1e369b406534ae968b2901c8650fa401d6391eec81089d7abb249d5e529d520959038dac824f6
-  data.tar.gz: 134d43c549081bd25537ee095fabb793843d4d859ac33ca17014a4c64e37888a30dfee6d02dca0cf03b42d0c56cdb2dc676b7fbda2e195b1eeeea93740d93be8
+  metadata.gz: c3a6d9e78ab3b119d5605f27fb2069aad30727584b2e982b308528d8e2e53dbbabba41b06ee84abd9db23c15b8cdb54e19fcfb3d5c616b4acaed0691e7b99338
+  data.tar.gz: 035c2d436451a1324a78c3d1b8f3f00d6f384c257b5566824689edcb6fcfb77a47b87f1d89758035c59c4b029855698b68972d4dda10c88263f78fd5181448b8

data/README.md

@@ -1 +1,165 @@
 # aquam
+[![Gem Version](https://badge.fury.io/rb/aquam.png)](http://badge.fury.io/rb/aquam)
+[![Build Status](https://travis-ci.org/emancu/aquam.svg)](https://travis-ci.org/emancu/aquam)
+[![Code Climate](https://codeclimate.com/github/emancu/aquam/badges/gpa.svg)](https://codeclimate.com/github/emancu/aquam)
+[![Dependency Status](https://gemnasium.com/emancu/aquam.svg)](https://gemnasium.com/emancu/aquam)
+
+A Ruby DSL for writing Finite State Machines and validate its transitions'
+
+## Dependencies
+
+`aquam` requires Ruby 2.1.x or later. No more dependencies.
+
+## Installation
+
+    $ gem install aquam
+
+# Getting started
+
+`aquam` helps you to define _Finite State Machines_ with a very simple DSL which
+also will validate events, states and the transition between them.
+
+First of all, you must know that a State Machine should be a different object,
+where you specify the valid states and the transitions fired by the events.
+
+That being said, lets take a look how it works.
+
+## Machine
+
+Basically a Machine consists on
+
+- states
+- events
+- transitions
+
+There are three key words in our DSL that will help you to write your
+own Finite State Machine, plus the `attribute` method.
+
+### Example
+
+```ruby
+class DoorStateMachine < Aquam::Machine
+  state :opened, OpenedDoorState
+  state :closed, ClosedDoorState
+
+  event :open do
+    transition from: :closed, to: :opened
+  end
+
+  event :close do
+    transition from: :opened, to: :closed
+  end
+
+  event :knock do
+    transition from: :opened, to: :opened
+    transition from: :closed, to: :closed
+  end
+end
+```
+
+> NOTE: `OpenedDoorState` and `ClosedDoorState` definitions are missing but
+> we will cover States definition later.
+
+### state
+
+A `state` maps a symbol to a State class.
+It tells to the _machine_ it is a valid state and which class represents it.
+
+```ruby
+state :opened, OpenedDoorState
+```
+
+### event
+
+An `event` is a method which triggers the transition from one _state_ to another.
+Each _state object_ must define **only** the events that are specified here.
+
+```ruby
+event :open do
+  ...
+end
+```
+
+### transition
+
+A `transition` moves the _state machine_ from **state A** to **state B**.
+It can only be defined inside an `event` and you can define multiple transitions.
+
+```ruby
+transition from: :a_valid_state, to: :other_valid_state
+```
+
+### attribute
+
+The `attribute` holds the name of the accessor in your own class where
+the state name (string or symbol) will be stored.
+
+By default uses `:state` as method accessor.
+
+```ruby
+attribute :state
+```
+
+### Extra
+
+Being a subclass of `Aquam::Machine` also gives you some helpful **class methods**:
+
+| Class Method | Description                                      | Example (ruby)                  |
+|:-------------|:-------------------------------------------------|:--------------------------------|
+| states       | `Hash` Valid states mapped to a class            | `{ opened: OpenedDoorState }`   |
+| events       | `Hash` Valid events with all its transitions     | `{ open: { closed: :opened } }` |
+| valid_state? | `Boolean` Check if it is a valid state           | `true`                          |
+| valid_event? | `Boolean` Check if it is a valid event           | `true`                          |
+
+And for **instance methods** it defines:
+
+| Class Method      | Description                              | Example (ruby)                |
+|:------------------|:-----------------------------------------|:------------------------------|
+| current_state     | `Aquam::State` Instance of current state | `#<ClosedDoorState:0x007...>` |
+| trigger           | `Aquam::State` Instance of the new state | `#<ClosedDoorState:0x008...>` |
+| valid_state?      | `Boolean` Check if it is a valid state   | `true`                        |
+| valid_event?      | `Boolean` Check if it is a valid event   | `true`                        |
+| valid_transition? | `Boolean` Check if it is a valid event   | `true`                        |
+
+
+## State
+
+For each state, we define a class that implements the corresponding _events_.
+Every bit of behavior that is *state-dependent* should become a method in the class.
+`aquam` uses metaprogramming to define methods for every single event listed
+in the state machine used.
+
+### Example
+
+```ruby
+class OpenedDoorState < Aquam::State
+  use_machine DoorStateMachine
+
+  def close
+    # Do something
+
+    @object.state = :closed
+  end
+end
+
+class ClosedDoorState < Aquam::State
+  use_machine DoorStateMachine
+
+  def open
+    # Do something
+
+    @object.state = :opened
+  end
+end
+```
+
+### use_machine
+
+This is the only method that you **must** call from every State class,
+in order to define the interface according to the _state machine_.
+Basically, it defines a method for every event defined in the _state machine_.
+
+```ruby
+use_machine DoorStateMachine
+```
+> NOTE: You can not change its value and it is accessible from all subclasses.

data/aquam.gemspec

@@ -1,9 +1,9 @@
 Gem::Specification.new do |s|
   s.name        = 'aquam'
-  s.version     = '0.0.1'
+  s.version     = '0.0.2'
   s.date        = Time.now.strftime('%Y-%m-%d')
   s.summary     = 'DSL to define State Machines'
-  s.description = 'Aquam adds a DSL and validations to define a State Machine'
+  s.description = 'A Ruby DSL for writing Finite State Machines and validate its transitions'
   s.authors     = ['Emiliano Mancuso']
   s.email       = ['emiliano.mancuso@gmail.com']
   s.homepage    = 'http://github.com/emancu/aquam'

data/lib/aquam.rb

@@ -3,5 +3,5 @@ require_relative 'aquam/machine'
 require_relative 'aquam/state'
 
 module Aquam
-  VERSION = '0.0.1'
+  VERSION = '0.0.2'
 end

data/lib/aquam/state.rb

@@ -1,22 +1,5 @@
 module Aquam
   class State
-    # I have to use a class variable because it **must** be the same value
-    # across all the children calsses.
-    #
-    # Also I need it defined always
-    @@state_machine = nil
-
-    def self.state_machine(state_machine = nil)
-      if state_machine && !@@state_machine
-        validate_state_machine state_machine
-
-        @@state_machine = state_machine
-        define_event_methods
-      end
-
-      @@state_machine
-    end
-
     def initialize(object)
       @object = object
     end
@@ -25,22 +8,35 @@ module Aquam
       self.class.state_machine || fail(Aquam::InvalidStateMachineError)
     end
 
-    private
+    class << self
+      def state_machine
+        @state_machine
+      end
 
-    def self.define_event_methods
-      state_machine.events.keys.each do |event|
-        define_method event do
-          fail Aquam::InvalidTransitionError
+      def use_machine(state_machine)
+        @state_machine ||= begin
+           validate_state_machine state_machine
+           define_event_methods state_machine
+
+           state_machine
+         end
+      end
+
+      private
+
+      def define_event_methods(machine)
+        machine.events.keys.each do |event|
+          define_method event do
+            fail Aquam::InvalidTransitionError
+          end
         end
       end
-    end
-    private_class_method :define_event_methods
 
-    def self.validate_state_machine(state_machine)
-      unless state_machine.ancestors.include? Aquam::Machine
-        fail Aquam::InvalidStateMachineError
+      def validate_state_machine(machine)
+        unless machine && machine.ancestors.include?(Aquam::Machine)
+          fail Aquam::InvalidStateMachineError
+        end
       end
     end
-    private_class_method :validate_state_machine
   end
 end

data/test/door_state_machine.rb

@@ -1,14 +1,12 @@
 require 'aquam'
 
-class DoorState < Aquam::State; end
-
-class OpenedDoorState < DoorState
+class OpenedDoorState < Aquam::State
   def close
     @object.state = :closed
   end
 end
 
-class ClosedDoorState < DoorState
+class ClosedDoorState < Aquam::State
   def open
     @object.state = :opened
   end

data/test/state_test.rb

@@ -3,79 +3,86 @@ require_relative 'door_state_machine'
 
 describe Aquam::State do
   after do
-    DoorState.class_variable_set :@@state_machine, nil
+    OpenedDoorState.instance_variable_set :@state_machine, nil
   end
 
-  describe 'state_machine class method' do
+  describe 'use_machine class method' do
     it 'fails if it is not a valid Aquam::Machine class' do
       assert_raises Aquam::InvalidStateMachineError do
-        DoorState.state_machine String
+        OpenedDoorState.use_machine String
       end
     end
 
-    it 'defines the state machine that will be used in the entire hierarchy' do
-      assert_equal nil, DoorState.state_machine
+    it 'defines the state machine that will be used in the state' do
+      assert_equal nil, OpenedDoorState.state_machine
 
-      DoorState.state_machine DoorStateMachine
+      OpenedDoorState.use_machine DoorStateMachine
 
-      assert_equal DoorStateMachine, DoorState.state_machine
+      assert_equal DoorStateMachine, OpenedDoorState.state_machine
     end
 
-    it 'defines the state machine for every sublcass' do
-      class OpenedDoorState < DoorState; end
+    it 'defines two different state machines for two different states' do
+      class OpenedWindowState < Aquam::State; end
+      class WindowStateMachine < Aquam::Machine
+        state :opened, OpenedWindowState
+      end
 
-      DoorState.state_machine DoorStateMachine
+      OpenedDoorState.use_machine DoorStateMachine
+      OpenedWindowState.use_machine WindowStateMachine
 
       assert_equal DoorStateMachine, OpenedDoorState.state_machine
-      assert_equal DoorStateMachine, OpenedDoorState.new(nil).state_machine
+      assert_equal WindowStateMachine, OpenedWindowState.state_machine
+
+      Object.send(:remove_const, :WindowStateMachine)
+      Object.send(:remove_const, :OpenedWindowState)
     end
 
     it 'defines the state machine only once' do
       class WindowStateMachine < Aquam::Machine; end
 
-      DoorState.state_machine DoorStateMachine
-      DoorState.state_machine WindowStateMachine
+      OpenedDoorState.use_machine DoorStateMachine
+      OpenedDoorState.use_machine WindowStateMachine
 
-      assert_equal DoorStateMachine, DoorState.state_machine
+      assert_equal DoorStateMachine, OpenedDoorState.state_machine
 
       Object.send(:remove_const, :WindowStateMachine)
     end
 
     it 'defines all the events as methods' do
-      DoorState.state_machine DoorStateMachine
+      OpenedDoorState.use_machine DoorStateMachine
 
-      assert DoorState.instance_methods.include? :open
-      assert DoorState.instance_methods.include? :close
-      assert DoorState.instance_methods.include? :knock
+      assert OpenedDoorState.instance_methods.include? :open
+      assert OpenedDoorState.instance_methods.include? :close
+      assert OpenedDoorState.instance_methods.include? :knock
     end
 
     it 'fails by default on every event method' do
-      DoorState.state_machine DoorStateMachine
+      OpenedDoorState.use_machine DoorStateMachine
 
       assert_raises Aquam::InvalidTransitionError do
-        DoorState.new(nil).open
+        OpenedDoorState.new(nil).open
       end
 
       assert_raises Aquam::InvalidTransitionError do
-        DoorState.new(nil).close
+        OpenedDoorState.new(nil).close
       end
 
       assert_raises Aquam::InvalidTransitionError do
-        DoorState.new(nil).knock
+        OpenedDoorState.new(nil).knock
       end
     end
   end
 
   describe 'state_machine instance method' do
     it 'returns the state machine class defined' do
-      DoorState.state_machine DoorStateMachine
+      OpenedDoorState.use_machine DoorStateMachine
 
-      assert_equal DoorStateMachine, DoorState.new(nil).state_machine
+      assert_equal DoorStateMachine, OpenedDoorState.new(nil).state_machine
     end
 
     it 'fails if the state machine was not defined' do
       assert_raises Aquam::InvalidStateMachineError do
-        DoorState.new(nil).state_machine
+        OpenedDoorState.new(nil).state_machine
       end
     end
   end

metadata

@@ -1,16 +1,16 @@
 --- !ruby/object:Gem::Specification
 name: aquam
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Emiliano Mancuso
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-01-15 00:00:00.000000000 Z
+date: 2015-01-26 00:00:00.000000000 Z
 dependencies: []
-description: Aquam adds a DSL and validations to define a State Machine
+description: A Ruby DSL for writing Finite State Machines and validate its transitions
 email:
 - emiliano.mancuso@gmail.com
 executables: []