Dramatic changes

.gitignore

@@ -6,3 +6,6 @@ coverage/
 doc/api/
 pkg/
 tmp/**/*
+start_mongod.sh
+spec/fixtures/db/
+doc

.travis.yml

@@ -0,0 +1,21 @@
+language: ruby
+rvm:
+  - 1.9.2
+  - 1.9.3
+#script: bundle exec rake test
+script: bundle exec rake spec
+#before_install:
+  #- gem update --system
+  #- gem --version
+env:
+  - USE_PLYMOUTH="no"
+branches:
+  only:
+    - master
+notifications:
+  email:
+    recipients:
+      - [email protected]
+    on_succes: change
+# [always|never|change]
+    on_failure: always

Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    app_config (1.0.1)
+    app_config (2.0.2)
 
 GEM
   remote: http://rubygems.org/
@@ -39,6 +39,6 @@ DEPENDENCIES
   maruku
   mongo
   rake
-  rspec (~> 2.10.0)
+  rspec
   simplecov
   yard

README.md

@@ -1,4 +1,4 @@
-# AppConfig
+# AppConfig [![Build Status](https://secure.travis-ci.org/DSIW/app_config.png)](http://travis-ci.org/DSIW/app_config) [![Dependency Status](https://gemnasium.com/DSIW/app_config.png)](https://gemnasium.com/DSIW/app_config)
 
 An easy to use, customizable library to easily store and retrieve application
 (or library) configuration, API keys or basically anything in 'key/value' pairs.
@@ -10,21 +10,40 @@ Usage is simple.  Just pass either a hash of options, or a block, to {AppConfig.
 
 In it's simplest form, you can use it like so:
 
-    AppConfig.setup(:admin_email => '[email protected]')
-    # ..or..
-    AppConfig.setup do |config|
+    config = AppConfig.setup do |config|
       config[:admin_email] = '[email protected]'
+      # Other setter:
+      # config["admin_email"] = '[email protected]'
+      # config.admin_email = '[email protected]'
     end
 
-    # Strings or symbols as keys.
-    AppConfig[:admin_email] # => '[email protected]'
+    # Strings or symbols or dynamic methods as keys.
+    config[:admin_email]  #=> '[email protected]'
+    config["admin_email"] #=> '[email protected]'
+    config.admin_email    #=> '[email protected]'
 
 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.
 
+If you like to use the {AppConfig::Configurable} module, see how easy it is:
+
+    module Client
+      include Configurable
+
+      def set_config
+        # Use it everywhere you want
+        config.api_url     = "http://example.com/api/"
+        config.api_key     = "2H28dsaa4"
+        config.api_version = "2"
+      end
+    end
+
+Please scroll down to the last chapter for more informtation and details.
+
+
 ## Deprecation Note
 
-Version `1.0` is \***not**\* backwards compatible with `0.7.1`!  See the [wiki](https://github.com/Oshuma/app_config/wiki)
+Version `2.0` is ***not*** backwards compatible with `1.0` and `0.7.1`!  See the [wiki](https://github.com/Oshuma/app_config/wiki)
 for upgrade instructions.
 
 
@@ -39,14 +58,34 @@ Given this YAML file:
 
 Use it like so:
 
-    AppConfig.setup(:yaml => '/path/to/app_config.yml')
+    config = AppConfig.setup(:yaml => '/path/to/app_config.yml')
 
     # Later on...
-    # Strings or symbols as keys.
-    AppConfig['admin_email'] # => '[email protected]'
-    AppConfig[:api_name]     # => 'Supr Webz 2.0'
-    AppConfig[:api_key]      # => 'SUPERAWESOMESERVICE'
+    # Strings or symbols or dynamic methods as keys.
+    config['admin_email'] #=> '[email protected]'
+    config.api_name       #=> 'Supr Webz 2.0'
+    config[:api_key]      #=> 'SUPERAWESOMESERVICE'
+
+### Create the YAML file, if it doesn't exist
 
+I like to create the YAML file, if it doesn't exist
+
+    config = AppConfig.setup(:yaml => '/path/to/file_doesnt_exist.yml', :create => true)
+    # File will be created with all non-existing directories.
+
+    # Later on...
+    config['admin_email'] = '[email protected]'
+    config['admin_email'] #=> '[email protected]'
+
+### Save all changes automatically
+
+When you use your config sometimes, it would be nice, if your config will be saved automatically to your YAML file.
+
+    config = AppConfig.setup(:yaml => '/path/to/app_config.yml', :save_changes => true)
+
+    # Later on...
+    config['admin_email'] #=> '[email protected]'
+    # YAML file will be written and includes 'admin_email'.
 
 ## AppConfig::Storage::Mongo
 
@@ -60,13 +99,12 @@ constant for the default Mongo connection options.
       :collection => 'app_config'   # default
     }
 
-    AppConfig.setup(:mongo => mongo_opts)
+    config = AppConfig.setup(:mongo => mongo_opts)
 
-    AppConfig[:admin_email]
-    # => '[email protected]'
+    config[:admin_email] #=> '[email protected]'
 
     # Override an existing value (saves to the database):
-    AppConfig[:admin_email] = '[email protected]'
+    config[:admin_email] = '[email protected]'
 
 The values are read/saved (by default) to the `app_config` database and
 `app_config` collection.  These defaults can be overridden, however, which
@@ -75,7 +113,6 @@ might lend well to versioned configurations; collection names such as
 
     AppConfig.setup(:mongo => { :collection => 'app_config_v2' })
 
-
 ## Environment Mode
 
 There's also an 'environment mode' where you can organize the config
@@ -91,12 +128,44 @@ sort of like the Rails database config. Given this YAML file:
 Set the `:env` option to your desired environment.
 
     # Rails.root/config/initializers/app_config.rb
-    AppConfig.setup({
+    config = config.setup({
       :yaml => "#{Rails.root}/config/app_config.yml",
       :env  => Rails.env  # or any string
     })
 
     # Uses the given environment section of the config.
-    AppConfig[:title]
+    config[:title]
     # => 'Production Mode'
 
+## Module Configurable
+
+You can include the module `Configurable` to have access to your configuration in all your code.
+This module is created to include it in all classes where you want to have access to your configuration.
+
+
+### Forcing or reloading
+
+Your access by _config_ is cached. So if you'd like to have another object, you could do this by passing :force or :reload.
+
+    config.object_id #=> 123456
+    config(:force => true).object_id #=> 654321
+    # ..or..
+    config(:reload => true)
+
+#### New object, because :force is set
+    config(:force => true)
+
+#### New object, because :force is set and block is given
+    config(:force => true) { |config| config[:key] = "value" }
+
+#### New object, because :force isn't set and block is given
+    config { |config| config[:key] = "value" }
+
+#### No new object, because :force is false and block is given
+    config(:force => false) { |config| config[:key] = "value" }
+
+#### Creates a new object and YAML file will be empty
+    config(:yaml => "path/to/file.yml", :force => true, :save_changes => true)
+    File.read("path/to/file.yml") #=> "--- {}"
+
+See {AppConfig::Configurable#config} for datails.

app_config.gemspec

@@ -16,7 +16,7 @@ Gem::Specification.new do |s|
   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 'rspec'
   s.add_development_dependency 'simplecov'
   s.add_development_dependency 'yard'
 

lib/app_config.rb

@@ -1,81 +1,93 @@
 require 'core_ext/hashish'
 
+# @example Usage
+#   config = AppConfig.setup do |config|
+#     config[:key] = "value"
+#     config[:newkey] = "newvalue"
+#   end
+#   config[:tmp] = "/tmp"
+#   config[:newkey] #=> "newvalue"
+#   config.tmp #=> "/tmp"
+#
+#   config.key # raises ArgumentError, because Hash#key needs an argument.
+#   # But you can use:
+#   config._key #=> "value"
 module AppConfig
-  VERSION = '1.0.2'
+  # Version of this Gem.
+  VERSION = '2.0.3'
 
-  autoload :Error,   'app_config/error'
-  autoload :Storage, 'app_config/storage'
+  autoload :Error,        'app_config/error'
+  autoload :Storage,      'app_config/storage'
+  autoload :Configurable, 'app_config/configurable'
+  autoload :Force,        'util/force'
 
   class << self
 
-    # Accepts an `options` hash or a block.
+    # Accepts an _options_ hash or a block.
     # See each storage method's documentation for their specific options.
     #
     # Valid storage methods:
-    # * `:memory` - {AppConfig::Storage::Memory AppConfig::Storage::Memory}
-    # * `:mongo` - {AppConfig::Storage::Mongo AppConfig::Storage::Mongo}
-    # * `:yaml` - {AppConfig::Storage::YAML AppConfig::Storage::YAML}
-    def setup(options = {}, &block)
-      @@options = options
-
-      if @@options[:yaml]
-        @@storage = AppConfig::Storage::YAML.new(@@options.delete(:yaml))
-      elsif @@options[:mongo]
-        @@storage = AppConfig::Storage::Mongo.new(@@options.delete(:mongo))
+    # * *:memory* - {AppConfig::Storage::Memory AppConfig::Storage::Memory}
+    # * *:mongo* - {AppConfig::Storage::Mongo AppConfig::Storage::Mongo}
+    # * *:yaml* - {AppConfig::Storage::YAML AppConfig::Storage::YAML}
+    #
+    # @param options [Hash]
+    #
+    # It will be configured by the _options_ hash. _options_ can have the following
+    # keys:
+    # * *:yaml*: Path to YAML file.
+    # * *:mongo*: Options for MongoDB database.
+    # * *:create*: This will create the specified YAML file. (:yaml has to be included.)
+    # * *:save_changes*: Every change in your storage object will be saved in your YAML file. (:yaml has to be included.)
+    #
+    # @yieldparam [Storage] config
+    #
+    # @note Your yielded block will be returned.
+    #
+    # @example Initialization without
+    #   config = AppConfig.setup
+    #   config.class #=> AppConfig::Storage::Memory
+    #
+    # @example Initialization with :yaml
+    #   config = AppConfig.setup(:yaml => "/path/to/file.yml")
+    #   config.class #=> AppConfig::Storage::YAML
+    #
+    # @example Initialization with :mongo
+    #   config = AppConfig.setup(:mongo => {:username => "usename", :password => "password"})
+    #   config.class #=> AppConfig::Storage::Mongo
+    #
+    # @return [Storage] config
+    def setup(options = {})
+      @options = options
+
+      if @options[:yaml]
+        @storage = AppConfig::Storage::YAML.new(@options.delete(:yaml), @options)
+      elsif @options[:mongo]
+        @storage = AppConfig::Storage::Mongo.new(@options.delete(:mongo))
       else
-        @@storage = AppConfig::Storage::Memory.new(@@options)
+        @storage = AppConfig::Storage::Memory.new({}, @options)
       end
 
-      yield @@storage if block_given?
+      yield storage if block_given?
 
-      to_hash
+      storage
     end
 
-    # Returns `true` if {AppConfig.setup AppConfig.setup} has been called.
+    # @return true if {AppConfig.setup AppConfig.setup} has been called.
     def setup?
-      !!(defined?(@@storage) && !@@storage.empty?)
-    end
-
-    # Clears the `@@storage`.
-    def reset!
-      if defined?(@@storage)
-        remove_class_variable(:@@storage)
-        true
-      else
-        false
-      end
-    end
-
-    # Access the configured `key`'s value.
-    def [](key)
-      setup unless setup?
-      storage[key]
-    end
-
-    # Set a new `value` for `key` (persistence depends on the type of Storage).
-    def []=(key, value)
-      setup unless setup?
-      storage[key] = value
-    end
-
-    def empty?
-      storage.empty?
-    end
-
-    def to_hash
-      setup? ? storage.to_hash : Hashish.new
+      !!(defined?(@storage) && [email protected]?)
     end
 
     private
 
     def environment
-      (@@options[:environment] || @@options[:env]) || nil
+      (@options[:environment] || @options[:env]) || nil
     end
     alias_method :env, :environment
 
-    # Returns the `@@storage` contents, which is what is exposed as the configuration.
+    # @return the `@storage` contents, which is what is exposed as the configuration.
     def storage
-      environment ? @@storage[environment] : @@storage
+      environment ? @storage[environment] : @storage
     end
 
   end # self