figgy 0.0.1 → 0.9.0

data/.gitignore

@@ -4,3 +4,4 @@ Gemfile.lock
 pkg/*
 coverage
 tmp/
+.yardoc/

data/README.md

@@ -0,0 +1,46 @@
+# figgy
+
+Provides convenient access to configuration files in various formats, with
+support for overriding the values based on environment, hostname, locale, or
+any other arbitrary thing you happen to come up with.
+
+## Travis-CI Build Status
+[![Build Status](https://secure.travis-ci.org/pd/figgy.png)](http://travis-ci.org/pd/figgy)
+
+## Documentation
+[yardocs](http://rdoc.info/github/pd/figgy/master/frames)
+
+## Installation
+
+Just like everything else these days. In your Gemfile:
+
+    gem 'figgy'
+
+## Overview
+
+Set it up (say, in a Rails initializer):
+
+    AppConfig = Figgy.build do |config|
+      config.root = Rails.root.join('etc')
+
+      # config.foo is read from etc/foo.yml
+      config.define_overlay :default, nil
+
+      # config.foo is then updated with values from etc/production/foo.yml
+      config.define_overlay(:environment) { Rails.env }
+
+      # Maybe you need to load XML files?
+      config.define_handler 'xml' do |contents|
+        Hash.from_xml(contents)
+      end
+    end
+
+Access it as a dottable, indifferent-access hash:
+
+    AppConfig.foo.some_key
+    AppConfig["foo"]["some_key"]
+    AppConfig[:foo].some_key
+
+## Thanks
+
+This was written on [Enova Financial's](http://www.enovafinancial.com) dime/time.

data/lib/figgy/configuration.rb

@@ -1,8 +1,25 @@
 class Figgy
   class Configuration
-    attr_reader :root, :overlays
-    attr_accessor :always_reload, :preload, :freeze
+    # The directory in which to search for configuration files
+    attr_reader :root
 
+    # The list of defined overlays
+    attr_reader :overlays
+
+    # Whether to reload a configuration file each time it is accessed
+    attr_accessor :always_reload
+
+    # Whether to load all configuration files upon creation
+    # @note This does not prevent +:always_reload+ from working.
+    attr_accessor :preload
+
+    # Whether to freeze all loaded objects. Useful in production environments.
+    attr_accessor :freeze
+
+    # Constructs a new {Figgy::Configuration Figgy::Configuration} instance.
+    #
+    # By default, uses a +root+ of the current directory, and defines handlers
+    # for +.yml+, +.yaml+, +.yml.erb+, +.yaml.erb+, and +.json+.
     def initialize
       self.root = Dir.pwd
       @handlers = []
@@ -29,42 +46,68 @@ class Figgy
       @root = File.expand_path(path)
     end
 
+    # @see #always_reload=
     def always_reload?
       !!@always_reload
     end
 
+    # @see #preload=
     def preload?
       !!@preload
     end
 
+    # @see #freeze=
     def freeze?
       !!@freeze
     end
 
+    # Adds an overlay named +name+, found at +value+.
+    #
+    # If a block is given, yields to the block to determine +value+.
+    #
+    # @param name an internal name for the overlay
+    # @param value the value of the overlay
+    # @example An environment overlay
+    #   config.define_overlay(:environment) { Rails.env }
     def define_overlay(name, value = nil)
       value = yield if block_given?
       @overlays << [name, value]
     end
 
+    # Adds an overlay using the combined values of other overlays.
+    #
+    # @example Searches for files in 'production_US'
+    #   config.define_overlay :environment, 'production'
+    #   config.define_overlay :country, 'US'
+    #   config.define_combined_overlay :environment, :country
     def define_combined_overlay(*names)
       combined_name = names.join("_").to_sym
       value = names.map { |name| overlay_value(name) }.join("_")
       @overlays << [combined_name, value]
     end
 
+    # @return [Array<String>] the list of directories to search for config files
     def overlay_dirs
       return [@root] if @overlays.empty?
       overlay_values.map { |v| v ? File.join(@root, v) : @root }.uniq
     end
 
+    # Adds a new handler for files with any extension in +extensions+.
+    #
+    # @example Adding an XML handler
+    #   config.define_handler 'xml' do |body|
+    #     Hash.from_xml(body)
+    #   end
     def define_handler(*extensions, &block)
       @handlers += extensions.map { |ext| [ext, block] }
     end
 
+    # @return [Array<String>] the list of recognized extensions
     def extensions
       @handlers.map { |ext, handler| ext }
     end
 
+    # @return [Proc] the handler for a given filename
     def handler_for(filename)
       match = @handlers.find { |ext, handler| filename =~ /\.#{ext}$/ }
       match && match.last

data/lib/figgy/finder.rb

@@ -4,6 +4,18 @@ class Figgy
       @config = config
     end
 
+    # Searches for files defining the configuration key +name+, merging each
+    # instance found with the previous. In this way, the overlay configuration
+    # at +production/foo.yml+ can override values in +foo.yml+.
+    #
+    # If the contents of the file were a Hash, Figgy will translate it into
+    # a {Figgy::Hash Figgy::Hash} and perform deep-merging for all overlays. This
+    # allows you to override only a single key deep within the configuration, and to
+    # access it using dot-notation, symbol keys or string keys.
+    #
+    # @param [String] name the configuration file to load
+    # @return Whatever was in the config file loaded
+    # @raise [Figgy::FileNotFound] if no config file could be found for +name+
     def load(name)
       result = files_for(name).reduce(nil) do |result, file|
         object = @config.handler_for(file).call(File.read(file))
@@ -18,10 +30,13 @@ class Figgy
       deep_freeze(to_figgy_hash(result))
     end
 
+    # @param [String] name the configuration key to search for
+    # @return [Array<String>] the paths to all files to load for configuration key +name+
     def files_for(name)
       Dir[*file_globs(name)]
     end
 
+    # @return [Array<String>] the names of all unique configuration keys
     def all_key_names
       Dir[*file_globs].map { |file| File.basename(file).sub(/\..+$/, '') }.uniq
     end

data/lib/figgy/store.rb

@@ -1,4 +1,5 @@
 class Figgy
+  # The backing object for a {Figgy} instance.
   class Store
     def initialize(finder, config)
       @finder = finder
@@ -6,6 +7,10 @@ class Figgy
       @cache  = {}
     end
 
+    # Retrieve the value for a key, expiring the cache and/or loading it
+    # if necessary.
+    #
+    # @raise [Figgy::FileNotFound] if no config file could be found for +name+
     def get(key)
       key = key.to_s
       @cache.delete(key) if @config.always_reload?
@@ -15,5 +20,15 @@ class Figgy
         @cache[key] = @finder.load(key)
       end
     end
+
+    # @return [Array<String>] the list of currently loaded keys
+    def keys
+      @cache.keys
+    end
+
+    # @return [Integer] the current size of the cache
+    def size
+      @cache.size
+    end
   end
 end

data/lib/figgy/version.rb

@@ -1,3 +1,3 @@
 class Figgy
-  VERSION = "0.0.1"
+  VERSION = "0.9.0"
 end

data/lib/figgy.rb

@@ -8,9 +8,24 @@ require "figgy/hash"
 require "figgy/finder"
 require "figgy/store"
 
+# An instance of Figgy is the object used to provide access to your
+# configuration files. This does very little but recognize missing
+# methods and go look them up as a configuration key.
+#
+# To create a new instance, you probably want to use +Figgy.build+:
+#
+#   MyConfig = Figgy.build do |config|
+#     config.root = '/path/to/my/configs'
+#   end
+#   MyConfig.foo.bar #=> read from /path/to/my/configs/foo.yml
+#
+# This should maybe be a BasicObject or similar, to provide as many
+# available configuration keys as possible. Maybe.
 class Figgy
   FileNotFound = Class.new(StandardError)
 
+  # @yield [Figgy::Configuration] an object to set things up with
+  # @return [Figgy] a Figgy instance using the configuration
   def self.build(&block)
     config = Configuration.new
     block.call(config)
@@ -30,4 +45,13 @@ class Figgy
   def method_missing(m, *args, &block)
     @store.get(m)
   end
+
+  def inspect
+    if @store.size > 0
+      key_names = @store.keys.sort
+      "#<Figgy (#{@store.size} keys): #{key_names.join(' ')}>"
+    else
+      "#<Figgy (empty)>"
+    end
+  end
 end

data/spec/figgy_spec.rb

@@ -14,6 +14,20 @@ describe Figgy do
     expect { test_config.values }.to raise_error(Figgy::FileNotFound)
   end
 
+  it "has a useful #inspect method" do
+    write_config 'values', 'foo: 1'
+    write_config 'wtf', 'bar: 2'
+
+    config = test_config
+    config.inspect.should == "#<Figgy (empty)>"
+
+    config.values
+    config.inspect.should == "#<Figgy (1 keys): values>"
+
+    config.wtf
+    config.inspect.should == "#<Figgy (2 keys): values wtf>"
+  end
+
   context "multiple extensions" do
     it "supports .yaml" do
       write_config 'values.yaml', 'foo: 1'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: figgy
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.9.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-10-21 00:00:00.000000000 Z
+date: 2011-10-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json
-  requirement: &70234275187800 !ruby/object:Gem::Requirement
+  requirement: &70227241849560 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70234275187800
+  version_requirements: *70227241849560
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: &70234275187060 !ruby/object:Gem::Requirement
+  requirement: &70227241848860 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +32,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70234275187060
+  version_requirements: *70227241848860
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &70234275186200 !ruby/object:Gem::Requirement
+  requirement: &70227241847880 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,10 +43,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70234275186200
+  version_requirements: *70227241847880
 - !ruby/object:Gem::Dependency
   name: simplecov
-  requirement: &70234275185340 !ruby/object:Gem::Requirement
+  requirement: &70227241845880 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -54,10 +54,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70234275185340
+  version_requirements: *70227241845880
 - !ruby/object:Gem::Dependency
   name: aruba
-  requirement: &70234275184520 !ruby/object:Gem::Requirement
+  requirement: &70227241842760 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -65,10 +65,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70234275184520
+  version_requirements: *70227241842760
 - !ruby/object:Gem::Dependency
   name: heredoc_unindent
-  requirement: &70234275177120 !ruby/object:Gem::Requirement
+  requirement: &70227241840320 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -76,7 +76,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70234275177120
+  version_requirements: *70227241840320
 description: Access YAML, JSON (and ...) configuration files with ease
 email:
 - pd@krh.me
@@ -88,7 +88,7 @@ files:
 - .rvmrc
 - .travis.yml
 - Gemfile
-- README
+- README.md
 - Rakefile
 - figgy.gemspec
 - lib/figgy.rb
@@ -126,3 +126,4 @@ summary: Configuration file reading
 test_files:
 - spec/figgy_spec.rb
 - spec/spec_helper.rb
+has_rdoc: 

data/README

@@ -1,21 +0,0 @@
-In Gemfile:
-
-    gem 'figgy'
-
-Configure (say, in a Rails initializer):
-
-    APP_CONFIG = Figgy.build do |config|
-      config.root = Rails.root.join('etc')
-
-      # config.foo is read from etc/foo.yml
-      config.define_overlay :default, nil
-
-      # config.foo is then updated with values from etc/production/foo.yml
-      config.define_overlay(:environment) { Rails.env }
-    end
-
-Access it as a dottable, indifferent-access hash:
-
-    APP_CONFIG["foo"]["some_key"]
-    APP_CONFIG[:foo].some_key
-    APP_CONFIG.foo[:some_key]