apollo 1.0.0 → 1.1.0

data/CHANGELOG.md

@@ -0,0 +1,57 @@
+Apollo Changelog
+================
+
+1.1
+
+* Added state sets. (7498cf0)
+* Unbranded methods. E.g. `Apollo::apollo` -> `Apollo::state_machine` (f8b42b8)
+
+1.0
+---
+This is an initial release of the Apollo fork from [Workflow](http://github.com/geekq/workflow).  The reason I decided to fork Workflow, and in particular change the name, is because I feel that Workflow is an excellent starting point for my needs; however, my desire for Apollo is somewhat different from the desires of the creators of Workflow.  **In no way is my fork (and renaming) intended to be any kind of insult or intellectual rights infringement.**  I chose Workflow for the basis of Apollo because I feel it is the **best** state machine gem available.  I will most certainly maintain the original MIT-LICENSE as apart of Apollo so long as *any* portion of the code is derived from Workflow (which I suspect will always be the case).
+
+* Rebranded modules from "workflow" to "apollo".
+* Using [Jeweler](http://github.com/technicalpickles/jeweler).
+* Removed unnecessary workflow.rb "initializer" file from root of project. (f2ac52a)
+* Extracted Workflow submodules and classes into separated files. (6d4e90f)
+* Changed default "column" name from `workflow_state` to `current_state`. (f562e71)
+* Require reason for `halt` and allow arbitrary exception for `halt!`. (0f903d7)
+
+Original Workflow Changelog
+===========================
+
+### New in the version 0.4.0
+
+* completely rewritten the documentation to match my branch. Every
+  described feature is backed up by an automated test.
+
+### New in the version 0.3.0
+
+Intermixing of transition graph definition (states, transitions)
+on the one side and implementation of the actions on the other side
+for a bigger state machine can introduce clutter.
+
+To reduce this clutter it is now possible to use state entry- and 
+exit- hooks defined through a naming convention. For example, if there
+is a state :pending, then instead of using a
+block:
+
+    state :pending do
+      on_entry do
+        # your implementation here
+      end
+    end
+
+you can hook in by defining method 
+
+    def on_pending_exit(new_state, event, *args)
+      # your implementation here
+    end
+
+anywhere in your class. You can also use a simpler function signature
+like `def on_pending_exit(*args)` if your are not interested in
+arguments.  Please note: `def on_pending_exit()` with an empty list
+would not work.
+
+If both a function with a name according to naming convention and the 
+on_entry/on_exit block are given, then only on_entry/on_exit block is used.

data/{README.markdown → README.md}

@@ -8,7 +8,38 @@ What is apollo?
 > poetry, and the arts; and more. Apollo is the son of Zeus and Leto, and has a twin 
 > sister, the chaste huntress Artemis. [Wikipedia: Dionysus (2010/04/23)](http://en.wikipedia.org/wiki/Apollo)
 
-Apollo is an fork of workflow.
+Apollo is an fork of [Workflow](http://github.com/geekq/workflow).
+
+Resources
+---------
+
+* [Github Project](http://github.com/tekwiz/apollo)
+* [Rdocs on Rdoc.info](http://rdoc.info/projects/tekwiz/apollo)
+* [Wiki on Github](http://wiki.github.com/tekwiz/apollo/)
+* [Issues Tracker on Github](http://github.com/tekwiz/apollo/issues)
+* [Metrics on Caliper](http://getcaliper.com/caliper/project?repo=http%3A%2F%2Frubygems.org%2Fgems%2Fapollo)
+
+Features & Issues
+-----------------
+
+This is a brand new project, so if you find bugs or use cases that would helpful to satisfy, post an [Issue](http://github.com/tekwiz/apollo/issues) on Github.
+
+This project is intended to be a **very** eclectic mix of helpful tools, so please feel free to send pull requests.  That said, make **absolutely sure** your modifications are well tested.  The hodge-podge nature of this project may make it prone to issues, so no code will be pulled-in that is not __fully_tested__.
+
+Note on Patches/Pull Requests
+-----------------------------
+
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a
+  future version unintentionally.
+* Commit, do not mess with rakefile, version, or history.
+  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+* Send me a pull request. Bonus points for topic branches.
+
+### Documentation Warning
+
+Beware that the below documentation has NOT been validated for the changes from Workflow to Apollo.
 
 What is workflow?
 -----------------
@@ -332,106 +363,47 @@ The whole event sequence is as follows:
     * PERSIST WORKFLOW STATE, i.e. transition
     * on_entry
 
-
 Documenting with diagrams
 -------------------------
 
 You can generate a graphical representation of your apollo for
 documentation purposes. S. Apollo::create_apollo_diagram.
 
-
-Earlier versions
-----------------
-
-The `apollo` library was originally written by Ryan Allen.
-
-The version 0.3 was almost completely (including ActiveRecord
-integration, API for accessing apollo specification, 
-method_missing free implementation) rewritten by Vladimir Dobriakov
-keeping the original apollo DSL spirit.
-
-
-Migration from the original Ryan's library
-------------------------------------------
-
-Credit: Michael (rockrep)
-
-Accessing apollo specification
-
-    my_instance.apollo # old
-    MyClass.apollo_spec # new
-
-Accessing states, events, meta, e.g.
-
-    my_instance.apollo.states(:some_state).events(:some_event).meta[:some_meta_tag] # old
-    MyClass.apollo_spec.states[:some_state].events[:some_event].meta[:some_meta_tag] # new
-
-Causing state transitions
-
-    my_instance.apollo.my_event # old
-    my_instance.my_event! # new
-
-when using both a block and a callback method for an event, the block executes prior to the callback
-
-
-Changelog
+Copyright
 ---------
 
-### New in the version 0.4.0
-
-* completely rewritten the documentation to match my branch. Every
-  described feature is backed up by an automated test.
+    Copyright 2010 Travis D. Warlick, Jr.
+    
+    Licensed under the Apache License, Version 2.0 (the "License");
+    you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
+    
+       http://www.apache.org/licenses/LICENSE-2.0
+    
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
 
-### New in the version 0.3.0
+The original work from [Workflow](http://github.com/geekq/workflow)
 
-Intermixing of transition graph definition (states, transitions)
-on the one side and implementation of the actions on the other side
-for a bigger state machine can introduce clutter.
-
-To reduce this clutter it is now possible to use state entry- and 
-exit- hooks defined through a naming convention. For example, if there
-is a state :pending, then instead of using a
-block:
-
-    state :pending do
-      on_entry do
-        # your implementation here
-      end
-    end
-
-you can hook in by defining method 
-
-    def on_pending_exit(new_state, event, *args)
-      # your implementation here
-    end
+    Author: Vladimir Dobriakov, http://www.innoq.com/blog/vd, http://blog.geekq.net/
 
-anywhere in your class. You can also use a simpler function signature
-like `def on_pending_exit(*args)` if your are not interested in
-arguments.  Please note: `def on_pending_exit()` with an empty list
-would not work.
+    Copyright (c) 2008-2009 Vodafone
 
-If both a function with a name according to naming convention and the 
-on_entry/on_exit block are given, then only on_entry/on_exit block is used.
+    Copyright (c) 2007-2008 Ryan Allen, FlashDen Pty Ltd
 
+    Based on the work of Ryan Allen and Scott Barron
 
-Support
--------
+    Licensed under MIT license, see the MIT-LICENSE file.
 
-### Reporting bugs
-
-    http://github.com/geekq/apollo/issues
-
-
-About
------
-
-Author: Vladimir Dobriakov, http://www.innoq.com/blog/vd, http://blog.geekq.net/
-
-Copyright (c) 2008-2009 Vodafone
-
-Copyright (c) 2007-2008 Ryan Allen, FlashDen Pty Ltd
-
-Based on the work of Ryan Allen and Scott Barron
+Earlier versions
+----------------
 
-Licensed under MIT license, see the MIT-LICENSE file.
+The `workflow` library was originally written by Ryan Allen.
 
+The version 0.3 was almost completely (including ActiveRecord
+integration, API for accessing apollo specification, 
+method_missing free implementation) rewritten by Vladimir Dobriakov
+keeping the original apollo DSL spirit.

data/Rakefile

@@ -41,8 +41,8 @@ Rake::RDocTask.new do |rdoc|
 
   rdoc.rdoc_dir = 'rdoc'
   rdoc.title = "Apollo #{version}"
-  rdoc.rdoc_files.include('README*', 'MIT-LICENSE', 'LICENSE', 'VERSION')
+  rdoc.rdoc_files.include('README*', 'MIT-LICENSE', 'LICENSE', 'VERSION', 'CHANGELOG.md')
   rdoc.rdoc_files.include('lib/**/*.rb')
 end
 
-task :clobber => [:clobber_rcov, :clobber_rdoc]
+# task :clobber => [:clobber_rcov, :clobber_rdoc]

data/VERSION

@@ -1 +1 @@
-1.0.0
+1.1.0

data/apollo.gemspec

@@ -5,21 +5,22 @@
 
 Gem::Specification.new do |s|
   s.name = %q{apollo}
-  s.version = "1.0.0"
+  s.version = "1.1.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Travis D. Warlick, Jr."]
-  s.date = %q{2010-04-23}
+  s.date = %q{2010-04-24}
   s.email = %q{warlickt@operissystems.com}
   s.extra_rdoc_files = [
     "LICENSE",
-     "README.markdown"
+     "README.md"
   ]
   s.files = [
     ".gitignore",
+     "CHANGELOG.md",
      "LICENSE",
      "MIT-LICENSE",
-     "README.markdown",
+     "README.md",
      "Rakefile",
      "VERSION",
      "apollo.gemspec",

data/lib/apollo.rb

@@ -1,3 +1,20 @@
+# Copyright 2010 Travis D. Warlick, Jr.
+# 
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+# 
+#    http://www.apache.org/licenses/LICENSE-2.0
+# 
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# Original work from Workflow:
+#     Copyright (c) 2008-2009 Vodafone
+#     Copyright (c) 2007-2008 Ryan Allen, FlashDen Pty Ltd
 module Apollo
   autoload :Event,                        'apollo/event'
   autoload :State,                        'apollo/state'
@@ -23,18 +40,18 @@ module Apollo
   class ApolloDefinitionError < Exception; end
   
   module ClassMethods
-    attr_reader :apollo_spec
-    
-    def apollo_column(column_name=nil)
+    def current_state_column(column_name=nil)
       if column_name
-        @apollo_state_column_name = column_name.to_sym
+        @current_state_column_name = column_name.to_sym
       else
-        @apollo_state_column_name ||= :current_state
+        @current_state_column_name ||= :current_state
       end
-      @apollo_state_column_name
+      @current_state_column_name
     end
 
-    def apollo(&specification)
+    def state_machine(&specification)
+      return @apollo_spec unless block_given?
+      
       @apollo_spec = Specification.new(Hash.new, &specification)
       @apollo_spec.states.values.each do |state|
         state_name = state.name
@@ -53,12 +70,20 @@ module Apollo
           end
         end
       end
+      
+      @apollo_spec.state_sets.keys.each do |set_name|
+        module_eval do
+          define_method "#{set_name}?" do
+            current_state.sets.include?(set_name)
+          end
+        end
+      end
     end
   end
 
   module InstanceMethods
     def current_state
-      loaded_state = load_apollo_state
+      loaded_state = load_current_state
       res = spec.states[loaded_state.to_sym] if loaded_state
       res || spec.initial_state
     end
@@ -76,7 +101,7 @@ module Apollo
       raise NoTransitionAllowed.new(
         "There is no event #{name.to_sym} defined for the #{current_state} state") \
         if event.nil?
-      # This three member variables are a relict from the old apollo library
+      # This three member variables are a relict from the old workflow library
       # TODO: refactor some day
       @halted_because = nil
       @halted = false
@@ -112,10 +137,10 @@ module Apollo
       c = self.class
       # using a simple loop instead of class_inheritable_accessor to avoid
       # dependency on Rails' ActiveSupport
-      until c.apollo_spec || !(c.include? Apollo)
+      until c.state_machine || !(c.include? Apollo)
         c = c.superclass
       end
-      c.apollo_spec
+      c.state_machine
     end
 
     def halt(reason)
@@ -137,7 +162,7 @@ module Apollo
 
     def transition(from, to, name, *args)
       run_on_exit(from, to, name, *args)
-      persist_apollo_state to.to_s
+      persist_current_state to.to_s
       run_on_entry(to, from, name, *args)
     end
 
@@ -173,19 +198,19 @@ module Apollo
       end
     end
 
-    # load_apollo_state and persist_apollo_state
-    # can be overriden to handle the persistence of the apollo state.
+    # load_current_state and persist_current_state
+    # can be overriden to handle the persistence of the current state.
     #
     # Default (non ActiveRecord) implementation stores the current state
     # in a variable.
     #
-    # Default ActiveRecord implementation uses a 'apollo_state' database column.
-    def load_apollo_state
-      @apollo_state if instance_variable_defined? :@apollo_state
+    # Default ActiveRecord implementation uses a 'current_state' database column.
+    def load_current_state
+      @current_state if instance_variable_defined? :@current_state
     end
 
-    def persist_apollo_state(new_value)
-      @apollo_state = new_value
+    def persist_current_state(new_value)
+      @current_state = new_value
     end
   end
 
@@ -200,21 +225,21 @@ module Apollo
     end
   end
 
-  # Generates a `dot` graph of the apollo.
+  # Generates a `dot` graph of the state machine.
   # Prerequisite: the `dot` binary.
   # You can use it in your own Rakefile like this:
   #
   #     namespace :doc do
-  #       desc "Generate a graph of the apollo."
-  #       task :apollo do
-  #         Apollo::create_apollo_diagram(Order.new)
+  #       desc "Generate a graph of the state machine."
+  #       task :state_machine do
+  #         Apollo::create_state_diagram(Order.new)
   #       end
   #     end
   #
   # You can influence the placement of nodes by specifying
   # additional meta information in your states and transition descriptions.
   # You can assign higher `doc_weight` value to the typical transitions
-  # in your apollo. All other states and transitions will be arranged
+  # in your state machine. All other states and transitions will be arranged
   # around that main line. See also `weight` in the graphviz documentation.
   # Example:
   #
@@ -223,21 +248,21 @@ module Apollo
   #     end
   #
   #
-  # @param klass A class with the Apollo mixin, for which you wish the graphical apollo representation
+  # @param klass A class with the Apollo mixin, for which you wish the graphical state machine representation
   # @param [String] target_dir Directory, where to save the dot and the pdf files
   # @param [String] graph_options You can change graph orientation, size etc. See graphviz documentation
-  def self.create_apollo_diagram(klass, target_dir, graph_options='rankdir="LR", size="7,11.6", ratio="fill"')
-    apollo_name = "#{klass.name.tableize}_apollo"
-    fname = File.join(target_dir, "generated_#{apollo_name}")
+  def self.create_state_diagram(klass, target_dir, graph_options='rankdir="LR", size="7,11.6", ratio="fill"')
+    state_machine_name = "#{klass.name.tableize}_state_machine"
+    fname = File.join(target_dir, "generated_#{state_machine_name}")
     File.open("#{fname}.dot", 'w') do |file|
       file.puts %Q|
-digraph #{apollo_name} {
+digraph #{state_machine_name} {
   graph [#{graph_options}];
   node [shape=box];
   edge [len=1];
       |
 
-      klass.apollo_spec.states.each do |state_name, state|
+      klass.state_machine.states.each do |state_name, state|
         file.puts %Q{  #{state.name} [label="#{state.name}"];}
         state.events.each do |event_name, event|
           meta_info = event.meta

data/lib/apollo/active_record_instance_methods.rb

@@ -1,24 +1,24 @@
 module Apollo
   module ActiveRecordInstanceMethods
-    def load_apollo_state
-      read_attribute(self.class.apollo_column)
+    def load_current_state
+      read_attribute(self.class.current_state_column)
     end
 
-    # On transition the new apollo state is immediately saved in the
+    # On transition the new current state is immediately saved in the
     # database.
-    def persist_apollo_state(new_value)
-      update_attribute self.class.apollo_column, new_value
+    def persist_current_state(new_value)
+      update_attribute self.class.current_state_column, new_value
     end
 
     private
 
-    # Motivation: even if NULL is stored in the apollo_state database column,
+    # Motivation: even if NULL is stored in the current_state database column,
     # the current_state is correctly recognized in the Ruby code. The problem
     # arises when you want to SELECT records filtering by the value of initial
     # state. That's why it is important to save the string with the name of the
     # initial state in all the new records.
     def write_initial_state
-      write_attribute self.class.apollo_column, current_state.to_s
+      write_attribute self.class.current_state_column, current_state.to_s
     end
   end
 end

data/lib/apollo/specification.rb

@@ -1,9 +1,10 @@
 module Apollo
   class Specification
-    attr_accessor :states, :initial_state, :meta, :on_transition_proc
+    attr_accessor :states, :initial_state, :meta, :on_transition_proc, :state_sets
 
     def initialize(meta = {}, &specification)
       @states = Hash.new
+      @state_sets = Hash.new
       @meta = meta
       instance_eval(&specification)
     end
@@ -11,6 +12,8 @@ module Apollo
     private
 
     def state(name, meta = {:meta => {}}, &events_and_etc)
+      validate_state_name(name)
+      
       # meta[:meta] to keep the API consistent..., gah
       new_state = State.new(name, meta[:meta])
       @initial_state = new_state if @states.empty?
@@ -18,6 +21,21 @@ module Apollo
       @scoped_state = new_state
       instance_eval(&events_and_etc) if events_and_etc
     end
+    
+    def state_set(name, *state_names)
+      validate_state_set_name(name)
+      
+      set = Set.new
+      state_names.each do |state_name|
+        if state = @states[state_name]
+          set << state
+          state.sets << name
+        else
+          raise ApolloDefinitionError, "Unknown state: #{state}"
+        end
+      end
+      @state_sets[name] = set
+    end
 
     def event(name, args = {}, &action)
       target = args[:to] || args[:to]
@@ -39,5 +57,17 @@ module Apollo
     def on_transition(&proc)
       @on_transition_proc = proc
     end
+    
+    def validate_state_name(name)
+      if @state_sets[name]
+        raise ApolloDefinitionError, "State name conflicts with state set name: #{name}"
+      end
+    end
+    
+    def validate_state_set_name(name)
+      if @states[name]
+        raise ApolloDefinitionError, "State set name conflicts with state name: #{name}"
+      end
+    end
   end
 end

data/lib/apollo/state.rb

@@ -1,9 +1,9 @@
 module Apollo
   class State
-    attr_accessor :name, :events, :meta, :on_entry, :on_exit
+    attr_accessor :name, :events, :meta, :on_entry, :on_exit, :sets
 
     def initialize(name, meta = {})
-      @name, @events, @meta = name, Hash.new, meta
+      @name, @events, @meta, @sets = name, Hash.new, meta, Set.new
     end
 
     def to_s
@@ -14,4 +14,4 @@ module Apollo
       name.to_sym
     end
   end
-end
+end

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 1
+  - 1
   - 0
-  - 0
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors: 
 - Travis D. Warlick, Jr.
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-04-23 00:00:00 -05:00
+date: 2010-04-24 00:00:00 -05:00
 default_executable: 
 dependencies: []
 
@@ -26,12 +26,13 @@ extensions: []
 
 extra_rdoc_files: 
 - LICENSE
-- README.markdown
+- README.md
 files: 
 - .gitignore
+- CHANGELOG.md
 - LICENSE
 - MIT-LICENSE
-- README.markdown
+- README.md
 - Rakefile
 - VERSION
 - apollo.gemspec