app_mode 0.0.1

data/Gemfile

@@ -0,0 +1,5 @@
+source "http://rubygems.org"
+
+group :rake do
+  gem 'rake', '~> 0.8.7'
+end

data/Gemfile.lock

@@ -0,0 +1,10 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    rake (0.8.7)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  rake (~> 0.8.7)

data/README

@@ -0,0 +1,151 @@
+== 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', '~> 0.0.1'
+
+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 = AppMode.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 = AppMode.new(:development)
+
+   If you would like to use states other than those provided, you are free
+   to do so:
+
+    my_mode = AppMode.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 = AppMode.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.
+   Only the default states (see "A Word on States" below) are available
+   using this method.
+
+    if AppMode.state == :development
+      # Development code.
+    end
+
+    AppMode.state = :test
+
+    if AppMode.test
+      # Test code.
+    end
+
+== Usage in libraries/gems
+
+The following method is recommended for use in libraries or gems:
+
+  module MyModule
+    MyModuleMode = AppMode.new
+  end
+
+or
+
+  class MyClass
+    MyClassMode = AppMode.new
+  end
+
+== A Word on States
+
+* AppMode assumes the following default "states":
+
+  :development
+
+  :test
+
+  :rake
+
+  :production
+
+* There is a fifth state (:dynamic), which will tell AppMode to determine
+  the state by examining the stack trace. It is only available when initializing
+  a new AppMode 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 AppMode object were created are valid.
+  For example, the following code will generate errors:
+
+   my_mode = AppMode.new(:blue, [:red, :green]) #=> RuntimeError: Invalid environment setting: 'blue'.
+
+   my_mode = AppMode.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 = AppMode.new(:red, [:red, :green])
+
+   if my_mode.valid_states.include?(:purple) && my_mode.purple
+     # Purple code.
+   end
+
+  Use equivalency:
+
+   my_mode = AppMode.new(:red, [:red, :green])
+
+   if my_mode.state == :purple
+     # Purple code.
+   end
+
+== Additional Documentation
+
+ rake rdoc:app
+
+== License
+
+AppMode is released under the GPLv3 license.

data/app_mode.gemspec

@@ -0,0 +1,24 @@
+Gem::Specification.new do |s|
+  s.name = 'app_mode'
+  s.version = '0.0.1'
+
+  s.summary = 'Application state management.'
+  s.description = 'AppMode provides state management for ' +
+    'modules, classes, libraries, and applications.'
+
+  s.author   = 'Travis Herrick'
+  s.email    = 'tthetoad@gmail.com'
+  s.homepage = 'http://www.bitbucket.org/ToadJamb/gems_app_mode'
+
+  s.license = 'GPLV3'
+
+  s.extra_rdoc_files << 'README'
+
+  s.require_paths = ['lib']
+  s.files = Dir['lib/**/*.rb', '*']
+  s.test_files = Dir['test/**/*.rb']
+
+  s.add_development_dependency 'rake', '~> 0.8.7'
+
+  s.has_rdoc = true
+end

data/lib/app_mode.rb

@@ -0,0 +1,3 @@
+gem_name = File.basename(__FILE__, '.rb')
+
+require_relative File.join(gem_name, gem_name)

data/lib/app_mode/app_mode.rb

@@ -0,0 +1,184 @@
+# This file contains a class to manage information about the mode that the
+# executing code is running in.
+
+#--
+################################################################################
+#                      Copyright (C) 2011 Travis Herrick                       #
+################################################################################
+#                                                                              #
+#                                 \v^V,^!v\^/                                  #
+#                                 ~%       %~                                  #
+#                                 {  _   _  }                                  #
+#                                 (  *   -  )                                  #
+#                                 |    /    |                                  #
+#                                  \   _,  /                                   #
+#                                   \__.__/                                    #
+#                                                                              #
+################################################################################
+# This program is free software: you can redistribute it                       #
+# and/or modify it under the terms of the GNU General Public License           #
+# as published by the Free Software Foundation,                                #
+# either version 3 of the License, or (at your option) any later version.      #
+#                                                                              #
+# Commercial licensing may be available for a fee under a different license.   #
+################################################################################
+# This program is distributed in the hope that it will be useful,              #
+# but WITHOUT ANY WARRANTY;                                                    #
+# without even the implied warranty of MERCHANTABILITY                         #
+# or FITNESS FOR A PARTICULAR PURPOSE.                                         #
+# See the GNU General Public License for more details.                         #
+#                                                                              #
+# You should have received a copy of the GNU General Public License            #
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.        #
+################################################################################
+#++
+
+# This class manages the mode that the executing code is running in.
+class AppMode
+  attr_reader :state, :valid_states
+
+  # Tracks a global mode setting.
+  @@mode = nil
+
+  class << self
+    # Override the send method.
+    #
+    # This was implemented to cover the case where test is used as a state.
+    # In that case, the default behavior was to call the private
+    # test method from Kernel. This prevents that behavior in cases where a
+    # public method is available via method_missing in this class.
+    def send(method, *args)
+      return method_missing(method, *args) if respond_to_missing?(method, false)
+      super
+    end
+
+    # Initializes the global mode setting.
+    def setup(*args)
+      @@mode = self.new(*args)
+    end
+
+    ########################################################################
+    private
+    ########################################################################
+
+    # Passes missing methods on to the instance.
+    def method_missing(method, *args, &block)
+      setup unless @@mode
+      @@mode.send method, *args
+    end
+
+    # Ensure that the object knows what it can respond to via method_missing.
+    # ==== Input
+    # [method : Symbol] The method to check for a response to.
+    # [include_private : Boolean] Whether to include private methods.
+    # ==== Output
+    # [Boolean] Whether the object will respond to the specified method.
+    def respond_to_missing?(method, include_private)
+      return true if @@mode.respond_to?(method, include_private)
+      super
+    end
+  end
+
+  # Constructor.
+  # ==== Input
+  # [env : Symbol] The environment that the mode should be set to.
+  # [valid_states : Array : (:development, :test, :production)] Valid states.
+  # ==== Notes
+  # <tt>env</tt> must be a member of <tt>states</tt>.
+  # ==== Examples
+  #  Mode.new                     #=> <Mode @state=:production, @valid_states=[:development, :test, :production]>
+  #  Mode.new(:test)              #=> <Mode @state=:test, @valid_states=[:development, :test, :production]>
+  #  Mode.new(:dev, [:abc, :dev]) #=> <Mode @state=:dev, @valid_states=[:abc, :dev]>
+  def initialize(
+      state        = :dynamic,
+      valid_states = [:development, :test, :rake, :production])
+    @state = state
+    @valid_states = valid_states
+    set_state @state
+  end
+
+  # Sets the environment instance variable.
+  # ==== Input
+  # [value : Symbol] The value that will be used for the environment.
+  def state=(value)
+    set_state value
+  end
+
+  # Override the send method.
+  #
+  # This was implemented to cover the case where test is used as a state.
+  # In that case, the default behavior was to call the private
+  # test method from Kernel. This prevents that behavior in cases where a
+  # public method is available via method_missing in this class.
+  def send(method, *args)
+    return method_missing(method, *args) if respond_to_missing?(method, false)
+    super
+  end
+
+  ############################################################################
+  private
+  ############################################################################
+
+  # Returns the appropriate state to use when setting the state dynamically.
+  # ==== Output
+  # [Symbol] The state that should be used when setting the state dynamically.
+  def dynamic_state
+    call = origin
+    return @valid_states[0] unless call.sub(/^\.\//, '').match(/\//)
+    return @valid_states[1] if call.match(/rake_test_loader\.rb/)
+    return @valid_states[2] if call.match(%r[/bin/rake])
+    return @valid_states.last
+  end
+
+  # Returns the current working directory.
+  # ==== Notes
+  # This method is overridden during tests.
+  def getwd
+    Dir.getwd
+  end
+
+  # Returns the first call in the stack.
+  # ==== Output
+  # [String] The file that made the first call in the stack.
+  # ==== Notes
+  # This method is overridden during tests.
+  def origin
+    caller.last
+  end
+
+  # Allows the getting of the mode.
+  # ==== Input
+  # [method : Symbol] The method that was called.
+  # [*args : Array] Any arguments that were passed in.
+  # [&block : Block] A block, if specified.
+  def method_missing(method, *args, &block)
+    return method == @state if respond_to_missing?(method, false)
+    super
+  end
+
+  # Ensure that the object knows what it can respond to via method_missing.
+  # ==== Input
+  # [method : Symbol] The method to check for a response to.
+  # [include_private : Boolean] Whether to include private methods.
+  # ==== Output
+  # [Boolean] Indicates whether the object will respond to the specified method.
+  def respond_to_missing?(method, include_private)
+    return true if @valid_states.include?(method)
+    super
+  end
+
+  # Sets the state.
+  # ==== Input
+  # [value : Symbol] The value to use for the state.
+  def set_state(value)
+    unless @valid_states.include?(value) || value == :dynamic
+      raise "Invalid environment setting: '#{value}'."
+    end
+
+    if value == :dynamic
+      @state = dynamic_state || @valid_states.last
+    else
+      @state = value
+    end
+  end
+end

data/rakefile

@@ -0,0 +1,16 @@
+root_path = File.expand_path(File.dirname(__FILE__))
+require 'bundler'
+Bundler.require :rake
+require 'rake/testtask'
+require 'rake/rdoctask'
+require 'rake/clean'
+require 'tempfile'
+
+task :default => [:tests]
+
+# Include any ruby files in the tasks folder.
+task_files = Dir[File.join(root_path, 'tasks', '*.rb')]
+
+task_files.each do |rake_file|
+  require rake_file
+end

data/test/app_mode_test.rb

@@ -0,0 +1,289 @@
+#--
+################################################################################
+#                      Copyright (C) 2011 Travis Herrick                       #
+################################################################################
+#                                                                              #
+#                                 \v^V,^!v\^/                                  #
+#                                 ~%       %~                                  #
+#                                 {  _   _  }                                  #
+#                                 (  *   -  )                                  #
+#                                 |    /    |                                  #
+#                                  \   _,  /                                   #
+#                                   \__.__/                                    #
+#                                                                              #
+################################################################################
+# This program is free software: you can redistribute it                       #
+# and/or modify it under the terms of the GNU General Public License           #
+# as published by the Free Software Foundation,                                #
+# either version 3 of the License, or (at your option) any later version.      #
+#                                                                              #
+# Commercial licensing may be available for a fee under a different license.   #
+################################################################################
+# This program is distributed in the hope that it will be useful,              #
+# but WITHOUT ANY WARRANTY;                                                    #
+# without even the implied warranty of MERCHANTABILITY                         #
+# or FITNESS FOR A PARTICULAR PURPOSE.                                         #
+# See the GNU General Public License for more details.                         #
+#                                                                              #
+# You should have received a copy of the GNU General Public License            #
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.        #
+################################################################################
+#++
+
+require_relative 'require'
+
+class AppModeTest < Test::Unit::TestCase
+  include AppModeSupport
+
+  def setup
+    @class.setup
+    super
+  end
+
+  def test_class_type
+    assert_equal AppMode, @class
+  end
+
+  ############################################################################
+  # Instance tests.
+  ############################################################################
+
+  def test_default_settings
+    create
+
+    assert_equal :production, @obj.state
+    assert_equal states(:default), @obj.valid_states
+
+    assert_true @obj.production
+    assert_false @obj.development
+    assert_false @obj.test
+  end
+
+  def test_setting_state
+    create :test
+
+    assert_equal :test, @obj.state
+    assert_true @obj.test
+
+    assert_nothing_raised { @obj.state = :development }
+
+    assert_equal :development, @obj.state
+    assert_true @obj.development
+  end
+
+  def test_new_object
+    create :test
+    assert_equal :test, @obj.state
+    assert_false @obj.development
+    assert_true @obj.test
+    assert_false @obj.rake
+    assert_false @obj.production
+
+    create :development
+    assert_equal :development, @obj.state
+    assert_true @obj.development
+    assert_false @obj.test
+    assert_false @obj.rake
+    assert_false @obj.production
+
+    create :production
+    assert_equal :production, @obj.state
+    assert_false @obj.development
+    assert_false @obj.test
+    assert_false @obj.rake
+    assert_true @obj.production
+
+    create :rake
+    assert_equal :rake, @obj.state
+    assert_false @obj.development
+    assert_false @obj.test
+    assert_true @obj.rake
+    assert_false @obj.production
+  end
+
+  def test_dynamic_state
+    assert_nothing_raised { create :dynamic }
+    assert_false @obj.development
+    assert_false @obj.test
+    assert_false @obj.rake
+    assert_true @obj.production
+
+    assert_nothing_raised { create :dynamic, states(:dev) }
+    assert_true @obj.dev_dev
+    assert_false @obj.dev_test
+    assert_false @obj.dev_rake
+    assert_false @obj.dev_prod
+
+    assert_nothing_raised { create :dynamic, states(:test) }
+    assert_false @obj.test_dev
+    assert_true @obj.test_test
+    assert_false @obj.test_rake
+    assert_false @obj.test_prod
+
+    assert_nothing_raised { create :dynamic, states(:rake) }
+    assert_false @obj.rake_dev
+    assert_false @obj.rake_test
+    assert_true @obj.rake_rake
+    assert_false @obj.rake_prod
+
+    assert_nothing_raised { create :dynamic, states(:prod) }
+    assert_false @obj.prod_dev
+    assert_false @obj.prod_test
+    assert_false @obj.prod_rake
+    assert_true @obj.prod_prod
+
+    assert_raise(NoMethodError) { @obj.dynamic }
+    assert_raise(NoMethodError) { @obj.test }
+  end
+
+  def test_dynamic_state_with_less_than_ideal_number_of_states
+    [
+      :dev,
+      :test,
+      :rake,
+      :prod,
+    ].each do |state|
+      state_array = states(state)[0..3]
+      end_value = state_array.length - 1
+
+      (0..end_value).each do |i|
+        assert_nothing_raised { create :dynamic, states(state)[0..i] }
+        case i
+          when 0
+            assert_true @obj.send("#{state}_dev")
+          when 1
+            case state
+              when :dev
+                assert_true @obj.dev_dev
+              else
+                assert_true @obj.send("#{state}_test")
+            end
+          when 2
+            case state
+              when :dev
+                assert_true @obj.dev_dev
+              when :test
+                assert_true @obj.test_test
+              else
+                assert_true @obj.send("#{state}_rake")
+            end
+          when 3
+            case state
+              when :dev
+                assert_true @obj.dev_dev
+              when :test
+                assert_true @obj.test_test
+              when :rake
+                assert_true @obj.rake_rake
+              when :prod
+                assert_true @obj.prod_prod
+            end
+        end
+      end
+    end
+  end
+
+  def test_invalid_state
+    assert_raise(RuntimeError) { create :invalid }
+    assert_raise(NoMethodError) { create :test; @obj.invalid }
+  end
+
+  def test_respond_to
+    create :test
+
+    method_list.each_value do |method|
+      assert_respond_to @obj, method
+    end
+
+    states(:default).each do |method|
+      assert_respond_to @obj, method
+    end
+
+    assert_not_respond_to @obj, :invalid
+  end
+
+  # This test exists because of Kernel::test.
+  def test_send_method
+    create :test
+    assert_equal :test, @obj.send(:state)
+    assert_false @obj.send(:development)
+    assert_true @obj.send(:test)
+    assert_false @obj.send(:rake)
+    assert_false @obj.send(:production)
+
+    create :development, [:development, :production]
+    assert_equal :development, @obj.send(:state)
+    assert_true @obj.send(:development)
+    assert_false @obj.send(:production)
+    assert_raise(ArgumentError) { @obj.send(:test) }
+  end
+
+  ############################################################################
+  # Class tests.
+  ############################################################################
+
+  def test_class_default_settings
+    assert_equal :production, @class.state
+    assert_equal states(:default), @class.valid_states
+
+    assert_false @class.development
+    assert_false @class.test
+    assert_false @class.rake
+    assert_true @class.production
+  end
+
+  def test_class_setting_state
+    assert_nothing_raised { @class.state = :test }
+
+    assert_equal :test, @class.state
+    assert_true @class.test
+
+    assert_nothing_raised { @class.state = :development }
+
+    assert_equal :development, @class.state
+    assert_true @class.development
+  end
+
+  def test_class_invalid_state
+    assert_raise(RuntimeError) { @class.setup :invalid }
+    assert_raise(NoMethodError) { @class.invalid }
+  end
+
+  def test_class_respond_to
+    @class.state = :test
+
+    method_list.each_value do |method|
+      assert_respond_to @class, method
+    end
+
+    states(:default).each do |method|
+      assert_respond_to @class, method
+    end
+
+    assert_not_respond_to @class, :invalid
+  end
+
+  # This test exists because of Kernel::test.
+  def test_class_send_method
+    @class.state = :test
+    assert_equal :test, @class.send(:state)
+    assert_false @class.send(:development)
+    assert_true @class.send(:test)
+    assert_false @class.send(:rake)
+    assert_false @class.send(:production)
+
+    @class.setup :development, [:development, :production]
+    assert_equal :development, @class.send(:state)
+    assert_true @class.send(:development)
+    assert_false @class.send(:production)
+    assert_raise(ArgumentError) { @class.send(:test) }
+  end
+
+  ############################################################################
+  private
+  ############################################################################
+
+  def create(*args)
+    @obj = @class.new(*args)
+  end
+end