app_config 0.7.1 → 1.0.0

data/.gitignore

@@ -1,5 +1,8 @@
+.rbenv-*
 .rvmrc
+.yardoc/
 *.gem
+coverage/
 doc/api/
 pkg/
 tmp/**/*

data/.rspec

@@ -0,0 +1 @@
+--color

data/Gemfile.lock

@@ -1,25 +1,34 @@
 PATH
   remote: .
   specs:
-    app_config (0.7.0)
+    app_config (0.7.1)
 
 GEM
   remote: http://rubygems.org/
   specs:
     bson (1.3.1)
     bson_ext (1.3.1)
-    diff-lcs (1.1.2)
+    diff-lcs (1.1.3)
+    maruku (0.6.0)
+      syntax (>= 1.0.0)
     mongo (1.3.1)
       bson (>= 1.3.1)
-    rspec (2.6.0)
-      rspec-core (~> 2.6.0)
-      rspec-expectations (~> 2.6.0)
-      rspec-mocks (~> 2.6.0)
-    rspec-core (2.6.2)
-    rspec-expectations (2.6.0)
-      diff-lcs (~> 1.1.2)
-    rspec-mocks (2.6.0)
-    sqlite3 (1.3.3)
+    multi_json (1.3.6)
+    rake (0.9.2.2)
+    rspec (2.10.0)
+      rspec-core (~> 2.10.0)
+      rspec-expectations (~> 2.10.0)
+      rspec-mocks (~> 2.10.0)
+    rspec-core (2.10.1)
+    rspec-expectations (2.10.0)
+      diff-lcs (~> 1.1.3)
+    rspec-mocks (2.10.1)
+    simplecov (0.6.4)
+      multi_json (~> 1.0)
+      simplecov-html (~> 0.5.3)
+    simplecov-html (0.5.3)
+    syntax (1.0.0)
+    yard (0.8.2)
 
 PLATFORMS
   ruby
@@ -27,6 +36,9 @@ PLATFORMS
 DEPENDENCIES
   app_config!
   bson_ext
+  maruku
   mongo
-  rspec (>= 2.6.0)
-  sqlite3
+  rake
+  rspec (~> 2.10.0)
+  simplecov
+  yard

data/README.md

@@ -0,0 +1,97 @@
+# AppConfig
+
+An easy to use, customizable library to easily store and retrieve application
+(or library) configuration, API keys or basically anything in 'key/value' pairs.
+
+
+## Usage
+
+Usage is simple.  Just pass either a hash of options, or a block, to {AppConfig.setup}.
+
+In it's simplest form, you can use it like so:
+
+    AppConfig.setup(:admin_email => 'admin@example.com')
+    # ..or..
+    AppConfig.setup do |config|
+      config[:admin_email] = 'admin@example.com'
+    end
+
+    # Strings or symbols as keys.
+    AppConfig[:admin_email] # => 'admin@example.com'
+
+You may also specify the storage method along with options specific to that storage method.
+Check the [wiki](https://github.com/Oshuma/app_config/wiki) for more usage examples.
+
+
+## AppConfig::Storage::YAML
+
+Given this YAML file:
+
+    ---
+    admin_email: 'admin@example.com'
+    api_name:    'Supr Webz 2.0'
+    api_key:     'SUPERAWESOMESERVICE'
+
+Use it like so:
+
+    AppConfig.setup(:yaml => '/path/to/app_config.yml')
+
+    # Later on...
+    # Strings or symbols as keys.
+    AppConfig['admin_email'] # => 'admin@example.com'
+    AppConfig[:api_name]     # => 'Supr Webz 2.0'
+    AppConfig[:api_key]      # => 'SUPERAWESOMESERVICE'
+
+
+## AppConfig::Storage::Mongo
+
+You can pass a `:mongo` options hash to {AppConfig.setup} which should contain
+configuration values for a Mongo database.  Check the {AppConfig::Storage::Mongo::DEFAULTS}
+constant for the default Mongo connection options.
+
+    mongo_opts = {
+      :host       => 'localhost',   # default
+      :database   => 'app_config',  # default
+      :collection => 'app_config'   # default
+    }
+
+    AppConfig.setup(:mongo => mongo_opts)
+
+    AppConfig[:admin_email]
+    # => 'admin@example.com'
+
+    # Override an existing value (saves to the database):
+    AppConfig[:admin_email] = 'other_admin@example.com'
+
+The values are read/saved (by default) to the `app_config` database and
+`app_config` collection.  These defaults can be overridden, however, which
+might lend well to versioned configurations; collection names such as
+`app_config_v1`, `app_config_v2`, etc.
+
+    AppConfig.setup(:mongo => { :collection => 'app_config_v2' })
+
+
+## Environment Mode
+
+There's also an 'environment mode' where you can organize the config
+sort of like the Rails database config. Given this YAML file:
+
+    # Rails.root/config/app_config.yml
+    development:
+      title: 'Development Mode'
+
+    production:
+      title: 'Production Mode'
+
+Set the `:env` option to your desired environment.
+
+    # Rails.root/config/initializers/app_config.rb
+    AppConfig.setup({
+      :yaml => "#{Rails.root}/config/app_config.yml",
+      :env  => Rails.env  # or any string
+    })
+
+    # Uses the given environment section of the config.
+    AppConfig[:title]
+    # => 'Production Mode'
+

data/Rakefile

@@ -1,5 +1,5 @@
 require 'bundler'
-require 'rake/rdoctask'
+require 'rdoc/task'
 require 'rspec/core/rake_task'
 
 Bundler::GemHelper.install_tasks
@@ -12,24 +12,22 @@ task :console do
 end
 
 desc 'Run the specs'
-RSpec::Core::RakeTask.new(:spec) do |t|
-  t.rspec_opts = [ "--color" ]
-end
+RSpec::Core::RakeTask.new(:spec)
+
+task :doc => [ 'doc:clean', 'doc:api' ]
 
-namespace :docs do
-  Rake::RDocTask.new do |rd|
-    rd.title = "AppConfig API"
-    rd.main = "README.rdoc"
-    rd.rdoc_dir = "#{File.dirname(__FILE__)}/doc/api"
-    rd.rdoc_files.include("README.rdoc", "lib/**/*.rb")
-    rd.options << "--all"
+namespace :doc do
+  require 'yard'
+  YARD::Rake::YardocTask.new(:api) do |t|
+    t.files = ['README.rdoc', 'lib/**/*.rb']
+    t.options = [
+      '--output-dir', 'doc/api',
+      '--markup', 'markdown'
+    ]
   end
-end
 
-desc 'Build the API docs'
-task :docs do
-  Rake::Task['docs:rerdoc'].invoke
-  STDOUT.puts "Copying Javascript files..."
-  doc_root = "#{File.dirname(__FILE__)}/doc"
-  system("cp -r #{doc_root}/js #{doc_root}/api/")
+  desc 'Remove YARD Documentation'
+  task :clean do
+    system("rm -rf #{File.dirname(__FILE__)}/doc/api")
+  end
 end

data/app_config.gemspec

@@ -12,15 +12,19 @@ Gem::Specification.new do |s|
   s.summary = %q{Quick and easy application configuration.}
   s.description = %q{An easy to use, customizable library to easily store and retrieve application configuration.}
 
-  s.add_development_dependency('bson_ext')
-  s.add_development_dependency('mongo')
-  s.add_development_dependency('rspec', '>= 2.6.0')
-  s.add_development_dependency('sqlite3')
+  s.add_development_dependency 'bson_ext'
+  s.add_development_dependency 'maruku'
+  s.add_development_dependency 'mongo'
+  s.add_development_dependency 'rake'
+  s.add_development_dependency 'rspec', '~> 2.10.0'
+  s.add_development_dependency 'simplecov'
+  s.add_development_dependency 'yard'
 
   s.has_rdoc = true
   s.rdoc_options = ["--inline-source", "--charset=UTF-8"]
 
+  s.require_paths = ["lib"]
   s.files = `git ls-files`.split("\n")
+
   s.test_files = `git ls-files -- {test,spec,features}/*`.split("\n")
-  s.require_paths = ["lib"]
 end

data/lib/app_config/base.rb

@@ -1,38 +1,32 @@
 module AppConfig
 
-  require 'uri'
-
   # The Base storage class.
   # Acts as a wrapper for the different storage methods.
   #
   # See each storage method's documentation for their specific options.
   #
   # Valid storage methods:
-  # * :memory (AppConfig::Storage::Memory)
-  # * :mongo (AppConfig::Storage::Mongo)
-  # * :sqlite (AppConfig::Storage::Sqlite)
-  # * :yaml (AppConfig::Storage::YAML)
-  #
-  # TODO: Purge AppConfig options (ie, those not related to the user-end).
+  # * `:memory` - {AppConfig::Storage::Memory AppConfig::Storage::Memory}
+  # * `:mongo` - {AppConfig::Storage::Mongo AppConfig::Storage::Mongo}
+  # * `:yaml` - {AppConfig::Storage::YAML AppConfig::Storage::YAML}
   class Base
 
-    # TODO: All these DEFAULTS constants are kinda annoying.
-    DEFAULTS = {
-      :storage_method => :memory,
-    }
-
-    # Accepts either a hash of +options+ or a block (which overrides
-    # any options passed in the hash).
+    # Accepts either a hash of `options` or a block (which overrides any options passed in the hash).
     def initialize(options = {}, &block)
-      @options = DEFAULTS.merge(options)
-      yield @options if block_given?
+      @options = options
 
-      determine_storage_method if @options[:uri]
-      @storage_method = initialize_storage_method
-      @storage = @storage_method.data
+      if @options[:yaml]
+        @storage = AppConfig::Storage::YAML.new(@options.delete(:yaml))
+      elsif @options[:mongo]
+        @storage = AppConfig::Storage::Mongo.new(@options.delete(:mongo))
+      else
+        @storage = AppConfig::Storage::Memory.new(@options)
+      end
+
+      yield @storage if block_given?
     end
 
-    # Access the <tt>key</tt>'s value in storage.
+    # Access the `key`'s value in storage.
     def [](key)
       if storage.respond_to?(:[])
         storage[key]
@@ -62,7 +56,7 @@ module AppConfig
     end
     alias_method :env, :environment
 
-    # Returns the <tt>@storage</tt> contents, which is what is exposed
+    # Returns the `@storage` contents, which is what is exposed
     # as the configuration.
     def storage
       environment ? @storage[environment] : @storage
@@ -72,36 +66,5 @@ module AppConfig
       storage.to_hash
     end
 
-    private
-
-    # Sets the storage_method depending on the URI given.
-    def determine_storage_method
-      uri = URI.parse(@options.delete(:uri))
-      case uri.scheme
-      when 'sqlite'
-        @options[:storage_method] = :sqlite
-        @options[:database] = uri.path
-      when 'yaml'
-        @options[:storage_method] = :yaml
-        @options[:path] = uri.path
-      end
-    end
-
-    # This decides how to load the data, based on the +storage_method+.
-    def initialize_storage_method
-      @storage_method = case @options[:storage_method]
-      when :memory
-        AppConfig::Storage::Memory.new(@options)
-      when :mongo
-        AppConfig::Storage::Mongo.new(@options)
-      when :sqlite
-        AppConfig::Storage::Sqlite.new(@options)
-      when :yaml
-        AppConfig::Storage::YAML.new(@options)
-      else
-        raise AppConfig::Error::UnknownStorageMethod
-      end
-    end
-
   end # Base
 end # AppConfig

data/lib/app_config/storage/base.rb

@@ -4,16 +4,26 @@ module AppConfig
 
       attr_reader :data
 
-      # DEPRECATED
-      def self.load(options)
-        STDERR.puts("DEPRECATED: AppConfig::Storage::Base.load() has been deprecated")
-        new(options).data
-      end
-
       def initialize(options)
         @options = options
       end
 
+      def [](key)
+        @data[key]
+      end
+
+      def []=(key, value)
+        @data[key] = value
+      end
+
+      def empty?
+        @data.empty?
+      end
+
+      def to_hash
+        @data.to_hash
+      end
+
     end # BaseStorage
   end # Storage
 end # AppConfig

data/lib/app_config/storage/mongo.rb

@@ -1,24 +1,18 @@
-begin
-  require 'mongo'
-rescue LoadError
-  require 'rubygems'
-  require 'mongo'
-end
-
 module AppConfig
   module Storage
 
+    require 'mongo'
+
     # Mongo storage method.
-    # FIXME: Come up with a way of removing stale config entries.
     class Mongo < Storage::Base
 
       DEFAULTS = {
-        :host => 'localhost',
-        :port => '27017',
-        :database => 'app_config',
+        :host       => 'localhost',
+        :port       => '27017',
+        :database   => 'app_config',
         :collection => 'app_config',
-        :user => nil,
-        :password => nil
+        :user       => nil,
+        :password   => nil
       }
 
       def initialize(options)

data/lib/app_config/storage/yaml.rb

@@ -6,18 +6,13 @@ module AppConfig
     # YAML storage method.
     class YAML < Storage::Base
 
-      DEFAULTS = {
-        :path => File.expand_path(File.join(ENV['HOME'], '.app_config.yml'))
-      }
+      DEFAULT_PATH = File.expand_path(File.join(ENV['HOME'], '.app_config.yml'))
 
-      # Loads @data with the YAML file located at +path+.
-      # @data will be the Hashish that is accessed with AppConfig[:key].
+      # Loads `@data` with the YAML file located at `path`.
+      # `@data` will be the Hashish that is accessed with `AppConfig[:key]`.
       #
-      # Defaults to $HOME/.app_config.yml
-      def initialize(options)
-        super(DEFAULTS.merge(options))
-        path = @options[:path] || DEFAULTS[:path]
-
+      # Defaults to `$HOME/.app_config.yml`
+      def initialize(path = DEFAULT_PATH)
         # Make sure to use the top-level YAML module here.
         @data = Hashish.new(::YAML.load_file(path))
       end

data/lib/app_config/storage.rb

@@ -3,7 +3,6 @@ module AppConfig
     autoload :Base,   'app_config/storage/base'
     autoload :Memory, 'app_config/storage/memory'
     autoload :Mongo,  'app_config/storage/mongo'
-    autoload :Sqlite, 'app_config/storage/sqlite'
     autoload :YAML,   'app_config/storage/yaml'
   end
 end

data/lib/app_config.rb

@@ -1,47 +1,49 @@
-$LOAD_PATH.unshift File.dirname(__FILE__)
-
-# AppConfig stuff.
 require 'core_ext/hashish'
 
 module AppConfig
-  VERSION = '0.7.1'
+  VERSION = '1.0.0'
 
-  autoload :Base, 'app_config/base'
-  autoload :Error, 'app_config/error'
+  autoload :Base,    'app_config/base'
+  autoload :Error,   'app_config/error'
   autoload :Storage, 'app_config/storage'
 
   class << self
 
-    # Accepts an +options+ hash or a block.
-    # See AppConfig::Base for valid storage methods.
-    # TODO: This should probably return true/false.
+    # Accepts an `options` hash or a block.
+    # See {AppConfig::Base AppConfig::Base} for valid storage methods.
     def setup(options = {}, &block)
       @@storage = AppConfig::Base.new(options, &block)
     end
 
-    # Returns +true+ if +AppConfig.setup()+ has been called.
+    # Returns `true` if {AppConfig.setup AppConfig.setup} has been called.
     def setup?
-      defined?(@@storage) && !@@storage.empty?
+      !!(defined?(@@storage) && !@@storage.empty?)
     end
 
-    # Clears the <tt>@@storage</tt>.
+    # Clears the `@@storage`.
     def reset!
-      @@storage = Hashish.new
+      if defined?(@@storage)
+        remove_class_variable(:@@storage)
+        true
+      else
+        false
+      end
     end
 
-    # Access the configured <tt>key</tt>'s value.
+    # Access the configured `key`'s value.
     def [](key)
       setup unless setup?
       @@storage[key]
     end
 
-    # Set a new <tt>value</tt> for <tt>key</tt> (persistence depends on the type of Storage).
+    # Set a new `value` for `key` (persistence depends on the type of Storage).
     def []=(key, value)
+      setup unless setup?
       @@storage[key] = value
     end
 
     def to_hash
-      @@storage.to_hash
+      setup? ? @@storage.to_hash : Hashish.new
     end
 
   end # self

data/lib/core_ext/hashish.rb

@@ -1,7 +1,7 @@
 # Stolen from Rails Active Support and renamed to Hashish.
 #
 # This class has dubious semantics and we only have it so that
-# people can write params[:key] instead of params['key']
+# people can write `params[:key]` instead of `params['key']`
 # and they get the same value for both keys.
 class Hashish < Hash
   def initialize(constructor = {})
@@ -26,23 +26,21 @@ class Hashish < Hash
 
   # Assigns a new value to the hash:
   #
-  #   hash = HashWithIndifferentAccess.new
-  #   hash[:key] = "value"
-  #
+  #     hash = HashWithIndifferentAccess.new
+  #     hash[:key] = "value"
   def []=(key, value)
     regular_writer(convert_key(key), convert_value(value))
   end
 
   # Updates the instantized hash with values from the second:
   #
-  #   hash_1 = HashWithIndifferentAccess.new
-  #   hash_1[:key] = "value"
-  #
-  #   hash_2 = HashWithIndifferentAccess.new
-  #   hash_2[:key] = "New Value!"
+  #     hash_1 = HashWithIndifferentAccess.new
+  #     hash_1[:key] = "value"
   #
-  #   hash_1.update(hash_2) # => {"key"=>"New Value!"}
+  #     hash_2 = HashWithIndifferentAccess.new
+  #     hash_2[:key] = "New Value!"
   #
+  #     hash_1.update(hash_2) # => {"key"=>"New Value!"}
   def update(other_hash)
     other_hash.each_pair { |key, value| regular_writer(convert_key(key), convert_value(value)) }
     self
@@ -52,11 +50,10 @@ class Hashish < Hash
 
   # Checks the hash for a key matching the argument passed in:
   #
-  #   hash = HashWithIndifferentAccess.new
-  #   hash["key"] = "value"
-  #   hash.key? :key  # => true
-  #   hash.key? "key" # => true
-  #
+  #     hash = HashWithIndifferentAccess.new
+  #     hash["key"] = "value"
+  #     hash.key? :key  # => true
+  #     hash.key? "key" # => true
   def key?(key)
     super(convert_key(key))
   end
@@ -65,18 +62,17 @@ class Hashish < Hash
   alias_method :has_key?, :key?
   alias_method :member?, :key?
 
-  # Fetches the value for the specified key, same as doing hash[key]
+  # Fetches the value for the specified key, same as doing `hash[key]`.
   def fetch(key, *extras)
     super(convert_key(key), *extras)
   end
 
   # Returns an array of the values at the specified indices:
   #
-  #   hash = HashWithIndifferentAccess.new
-  #   hash[:a] = "x"
-  #   hash[:b] = "y"
-  #   hash.values_at("a", "b") # => ["x", "y"]
-  #
+  #     hash = HashWithIndifferentAccess.new
+  #     hash[:a] = "x"
+  #     hash[:b] = "y"
+  #     hash.values_at("a", "b") # => ["x", "y"]
   def values_at(*indices)
     indices.collect {|key| self[convert_key(key)]}
   end

data/spec/app_config/storage/mongo_spec.rb

@@ -1,10 +1,11 @@
-require File.expand_path(File.dirname(__FILE__) + '/../../spec_helper')
+require 'spec_helper'
 
+# TODO: Drop the Mongo test db before running specs.
 describe AppConfig::Storage::Mongo do
 
-  before(:each) do
+  before(:all) do
     AppConfig.reset!
-    config_for_mongo(:api_key => 'SEEKRET_KEY')
+    config_for_mongo
   end
 
   it 'should have some values' do
@@ -12,7 +13,14 @@ describe AppConfig::Storage::Mongo do
   end
 
   it 'should update the values' do
+    pending 'Needs a little work...'
+    AppConfig.class_variable_get(:@@storage).
+      instance_variable_get(:@storage).should_receive(:save!)
     AppConfig[:api_key] = 'SOME_NEW_API_KEY'
+
+    # now reload the config options and check the value
+    AppConfig.reset!
+    config_for_mongo({}, false)  # use default options and do not load test data
     AppConfig[:api_key].should == 'SOME_NEW_API_KEY'
   end
 end

data/spec/app_config/storage/yaml_spec.rb

@@ -1,4 +1,4 @@
-require File.expand_path(File.dirname(__FILE__) + '/../../spec_helper')
+require 'spec_helper'
 
 describe AppConfig::Storage::YAML do
 
@@ -9,15 +9,10 @@ describe AppConfig::Storage::YAML do
 
   it 'should raise file not found' do
     lambda do
-      config_for_yaml(:path => 'not/a/real/file.yml')
+      config_for_yaml(:yaml => 'not/a/real/file.yml')
     end.should raise_error(Errno::ENOENT)
   end
 
-  it 'parses the URI properly' do
-    AppConfig.setup(:uri => "yaml://#{fixture('app_config.yml')}")
-    AppConfig[:api_key].should_not be_nil
-  end
-
   it 'saves the new value in memory' do
     config_for_yaml
     AppConfig[:new_key] = 'new value'

data/spec/app_config/storage_spec.rb

@@ -1,9 +1,4 @@
 require 'spec_helper'
 
 describe AppConfig::Storage do
-
-  it 'responds to .setup()' do
-    AppConfig.should respond_to(:setup)
-  end
-
 end

data/spec/app_config_spec.rb

@@ -32,15 +32,13 @@ describe AppConfig do
   end
 
   it 'to_hash() returns an empty hash if storage not set' do
-    # # First, reset the storage variable.
-    # AppConfig.send(:class_variable_set, :@@storage, nil)
     AppConfig.reset!
     AppConfig.to_hash.should == {}
   end
 
   describe 'environment mode' do
     it 'should load the proper environment' do
-      config_for_yaml(:path => fixture('env_app_config.yml'),
+      config_for_yaml(:yaml => fixture('env_app_config.yml'),
                       :env  => 'development')
       AppConfig[:api_key].should_not be_nil
     end

data/spec/core_ext/hashish_spec.rb

@@ -1,4 +1,4 @@
-require File.expand_path(File.dirname(__FILE__) + '/../spec_helper')
+require 'spec_helper'
 
 describe Hashish do
   before(:each) do