<commit_before>[![Build Status](https://travis-ci.org/geekq/workflow.png?branch=master)](https://travis-ci.org/geekq/workflow)


What is workflow?
-----------------

Workflow is a finite-state-machine-inspired API for modeling and
interacting with what we tend to refer to as 'workflow'.

A lot of business modeling tends to involve workflow-like concepts, and
the aim of this library is to make the expression of these concepts as
clear as possible, using similar terminology as found in state machine
theory.

So, a workflow has a state. It can only be in one state at a time. When
a workflow changes state, we call that a transition. Transitions occur
on an event, so events cause transitions to occur. Additionally, when an
event fires, other arbitrary code can be executed, we call those actions.
So any given state has a bunch of events, any event in a state causes a
transition to another state and potentially causes code to be executed
(an action). We can hook into states when they are entered, and exited
from, and we can cause transitions to fail (guards), and we can hook in
to every transition that occurs ever for whatever reason we can come up
with.

Now, all that's a mouthful, but we'll demonstrate the API bit by bit
with a real-ish world example.

Let's say we're modeling article submission from journalists. An article
is written, then submitted. When it's submitted, it's awaiting review.
Someone reviews the article, and then either accepts or rejects it.
Here is the expression of this workflow using the API:

    class Article
      include Workflow
      workflow do
        state :new do
          event :submit, :transitions_to => :awaiting_review
        end
        state :awaiting_review do
          event :review, :transitions_to => :being_reviewed
        end
        state :being_reviewed do
          event :accept, :transitions_to => :accepted
          event :reject, :transitions_to => :rejected
        end
        state :accepted
        state :rejected
      end
    end

Nice, isn't it!

Note: the first state in the definition (`:new` in the example, but you
can name it as you wish) is used as the initial state - newly created
objects start their life cycle in that state.

Let's create an article instance and check in which state it is:

    article = Article.new
    article.accepted? # => false
    article.new? # => true

You can also access the whole `current_state` object including the list
of possible events and other meta information:

    article.current_state
    => #<Workflow::State:0x7f1e3d6731f0 @events={
      :submit=>#<Workflow::Event:0x7f1e3d6730d8 @action=nil,
        @transitions_to=:awaiting_review, @name=:submit, @meta={}>},
      name:new, meta{}

On Ruby 1.9 and above, you can check whether a state comes before or
after another state (by the order they were defined):

    article.current_state
    => being_reviewed
    article.current_state < :accepted
    => true
    article.current_state >= :accepted
    => false
    article.between? :awaiting_review, :rejected
    => true

Now we can call the submit event, which transitions to the
<tt>:awaiting_review</tt> state:

    article.submit!
    article.awaiting_review? # => true

Events are actually instance methods on a workflow, and depending on the
state you're in, you'll have a different set of events used to
transition to other states.

It is also easy to check, if a certain transition is possible from the
current state . `article.can_submit?` checks if there is a `:submit`
event (transition) defined for the current state.

<commit_msg>Between called on state, not object itself<commit_after>[![Build Status](https://travis-ci.org/geekq/workflow.png?branch=master)](https://travis-ci.org/geekq/workflow)


What is workflow?
-----------------

Workflow is a finite-state-machine-inspired API for modeling and
interacting with what we tend to refer to as 'workflow'.

A lot of business modeling tends to involve workflow-like concepts, and
the aim of this library is to make the expression of these concepts as
clear as possible, using similar terminology as found in state machine
theory.

So, a workflow has a state. It can only be in one state at a time. When
a workflow changes state, we call that a transition. Transitions occur
on an event, so events cause transitions to occur. Additionally, when an
event fires, other arbitrary code can be executed, we call those actions.
So any given state has a bunch of events, any event in a state causes a
transition to another state and potentially causes code to be executed
(an action). We can hook into states when they are entered, and exited
from, and we can cause transitions to fail (guards), and we can hook in
to every transition that occurs ever for whatever reason we can come up
with.

Now, all that's a mouthful, but we'll demonstrate the API bit by bit
with a real-ish world example.

Let's say we're modeling article submission from journalists. An article
is written, then submitted. When it's submitted, it's awaiting review.
Someone reviews the article, and then either accepts or rejects it.
Here is the expression of this workflow using the API:

    class Article
      include Workflow
      workflow do
        state :new do
          event :submit, :transitions_to => :awaiting_review
        end
        state :awaiting_review do
          event :review, :transitions_to => :being_reviewed
        end
        state :being_reviewed do
          event :accept, :transitions_to => :accepted
          event :reject, :transitions_to => :rejected
        end
        state :accepted
        state :rejected
      end
    end

Nice, isn't it!

Note: the first state in the definition (`:new` in the example, but you
can name it as you wish) is used as the initial state - newly created
objects start their life cycle in that state.

Let's create an article instance and check in which state it is:

    article = Article.new
    article.accepted? # => false
    article.new? # => true

You can also access the whole `current_state` object including the list
of possible events and other meta information:

    article.current_state
    => #<Workflow::State:0x7f1e3d6731f0 @events={
      :submit=>#<Workflow::Event:0x7f1e3d6730d8 @action=nil,
        @transitions_to=:awaiting_review, @name=:submit, @meta={}>},
      name:new, meta{}

On Ruby 1.9 and above, you can check whether a state comes before or
after another state (by the order they were defined):

    article.current_state
    => being_reviewed
    article.current_state < :accepted
    => true
    article.current_state >= :accepted
    => false
    article.current_state.between? :awaiting_review, :rejected
    => true

Now we can call the submit event, which transitions to the
<tt>:awaiting_review</tt> state:

    article.submit!
    article.awaiting_review? # => true

Events are actually instance methods on a workflow, and depending on the
state you're in, you'll have a different set of events used to
transition to other states.

It is also easy to check, if a certain transition is possible from the
current state . `article.can_submit?` checks if there is a `:submit`
event (transition) defined for the current state.


{'fraction_non_alphanumeric': 0.07048702650201193, 'fraction_numerical': 0.005550159567087554, 'mean_word_length': 3.533333333333333, 'pattern_counts': {'":': 0, '<': 13, '<?xml version=': 0, '>': 37, 'https://': 4, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5766182', 'n_tokens_mistral': 1991, 'n_tokens_neox': 1914, 'n_words': 950}