== Welcome to AppMode

AppMode provides easy management of "states". This gem can be used to indicate
the state that a class, module, library, script, or application is running in.

== Getting Started

1. Install AppMode at the command prompt if you haven't yet:

    gem install app_mode

2. Require the gem in your gemfile:

    gem 'app_mode', '~> 1.0.0'

3. Require the gem wherever you need state management:

    require 'app_mode'

== Usage

There are two ways to use this gem.

1. Create an object that handles the state of the module, class, or application:

   This is the recommended method for managing the states of gems or libraries.
   The reason is that the second method is global and changing the state in
   a gem or library means the state will change in the application, too.
   Therefore, it is better to localize the state to the gem or library.

   See notes below on the :dynamic state, which is the default.

    my_mode =

    my_mode.state = :test

    if my_mode == :development
      # Development code.

    if my_mode.test
      # Test code.

   Or specify the state you want to use when initializing the object:

    my_mode =

   If you would like to use states other than those provided, you are free
   to do so:

    my_mode =, [:red, :yellow, :green, :blue])

    my_mode.state = :yellow

      # Green code.

   The :dynamic state is still valid with custom states:

    my_mode =, [:red, :yellow, :green, :blue])

2. Use the class methods:
   This method is really only recommended for the end application. The initial
   state will be set dynamically, so there is nothing to do except use it.

    if AppMode.state == :development
      # Development code.

    AppMode.state = :test

    if AppMode.test
      # Test code.

== Usage in libraries/gems

Following these guidelines consumers of your library or gem will still have
access to the state of your gem and can control it, if need be. Otherwise,
changing AppMode.state to :development could put every gem that uses AppMode
into "development" mode, which is probably not what you want to have happen
to your gem or anyone else's.

The following method is recommended for use in libraries or gems:

  module MyModule
    MyModuleMode =


  class MyClass
    MyClassMode =

== A Word on States

* StateManager assumes the following default "states":





* There is a fifth state (:dynamic), which will tell StateManager to determine
  the state by examining the stack trace. It is only available when initializing
  a new StateManager object and assumes that the first state is 'development',
  the second is 'test', the third is 'rake', and the last one (not the fourth)
  is 'production'. If less than four states are specified, the last one will be
  used for multiple states. For example, if the states specified are
  [:orange, :apple, :grape], :grape will be used for both rake and production.

* Only states in the list when the StateManager object were created are valid.
  For example, the following code will generate errors:

   my_mode =, [:red, :green]) #=> RuntimeError: Invalid environment setting: 'blue'.

   my_mode =, [:red, :green])

   my_mode.state = :development #=> RuntimeError: Invalid environment setting: 'development'.

   if              #=> RuntimeError: Invalid environment setting: 'blue'.
     # Blue code.

* If you are unsure that a state is in the list, there are two ways to check:

  Check for inclusion in the array of valid states:

   my_mode =, [:red, :green])

   if my_mode.valid_states.include?(:purple) && my_mode.purple
     # Purple code.

  Use equivalency:

   my_mode =, [:red, :green])

   if my_mode.state == :purple
     # Purple code.

* If you are compelled to change the states for the global AppMode class,
  that may be done by using the setup method, which accepts the same
  arguments as Passing in a state of :dynamic will allow it
  to set the state as it is intended.

* Although this document explains how to do so,
  it is best to leave AppMode (its valid states and its state) unaltered,
  as such changes are global and could have unexpected results when other code
  (such as gems) may be relying on the default settings, even though
  it is recommended that they have their own object that should
  be made available to your code.

== Additional Documentation

 rake rdoc:app

== License

RakeTasks is released under the {LGPLv3 license}[link:../../license/lgplv3].