app_mode

== 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 = StateManager.new

   my_mode.state = :test

   if my_mode == :development

   Development code.

   end

   if my_mode.test

   Test code.

   end

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

   my_mode = StateManager.new(:development)

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

   my_mode = StateManager.new(:blue, [:red, :yellow, :green, :blue])

   my_mode.state = :yellow

   if my_mode.green

   Green code.

   end

   The :dynamic state is still valid with custom states:

   my_mode = StateManager.new(:dynamic, [: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.

   end

   AppMode.state = :test

   if AppMode.test

   Test code.

   end

== 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 = StateManager.new end

or

class MyClass MyClassMode = StateManager.new end

== A Word on States

• StateManager assumes the following default "states":

  :development

  :test

  :rake

  :production

• 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 = StateManager.new(:blue, [:red, :green]) #=> RuntimeError: Invalid environment setting: 'blue'.

  my_mode = StateManager.new(:dynamic, [:red, :green])

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

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

  Blue code.

  end

• 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 = StateManager.new(:red, [:red, :green])

  if my_mode.valid_states.include?(:purple) && my_mode.purple

  Purple code.

  end

  Use equivalency:

  my_mode = StateManager.new(:red, [:red, :green])

  if my_mode.state == :purple

  Purple code.

  end

• 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 StateManager.new. 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].

link:../../license/lgplv3.png