confuse 0.1.8 → 1.0.0

data/README.md

@@ -1,12 +1,15 @@
-# Configuration
+# Confuse
 
-TODO: Write a gem description
+This gem is used to simplify specifying and reading configuration.
+
+You can define what you expect to be configured, and this can be read from ini
+files, yaml files or environment variables.
 
 ## Installation
 
 Add this line to your application's Gemfile:
 
-    gem 'configuration'
+    gem 'confuse'
 
 And then execute:
 
@@ -18,7 +21,112 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+Basic usage:
+
+    config = Confuse.config do |conf|
+      conf.add_item :foo, :description => 'Foo', :default => 1
+    end
+
+    config[:foo]
+    config.foo
+
+Types:
+
+You can choose where and your config is stored by passing a :path variable to
+Confuse.config:
+
+    config = Confuse.config :path => 'config.ini' do |conf|
+      conf.add_item :foo, :description => 'Foo', :default => 1
+    end
+
+Confuse will attempt to work out the type of file from the extension (Supports
+.ini for ini files, and .yml or .yaml for yaml files). You can override this by
+passing in a :type option:
+
+    config = Confuse.config :path => 'foo.conf' :type => :yaml do |conf|
+      conf.add_item :foo, :description => 'Foo', :default => 1
+    end
+
+If no type or path is given, it will default to environment variables.
+
+Environment variables have one extra feature, which is the ability to provide a
+prefix:
+
+
+    config = Confuse.config :prefix => 'FOO' :type => :yaml do |conf|
+      conf.add_item :foo, :description => 'Foo', :default => 1
+    end
+
+This means Confuse will lookup environment varialbles with that prefix with an
+underscore followed by the configuration name. If none is given, it will lookup
+environment variables as is.
+
+Namespaces:
+
+You can separate your configuration into different namespaces:
+
+    config = Confuse.config :type => :env do |conf|
+      conf.add_namespace :foo do |ns|
+        ns.add_item :foo, :description => 'Foo', :default => 1
+      end
+    end
+
+For simplicity, you can fetch these items using a single []:
+
+    config[:foo_bar]
+
+Or a method call:
+
+    config.foo_bar
+
+However, beware of adding an item at the top level with the same name.
+
+Check:
+
+If you want to make sure all your configuration items are in place before
+running the program you can call .check on it.
+
+    config = Confuse.config do |conf|
+      conf.add_item :foo, :description => 'Foo', :default => 1
+    end
+
+    config.check
+
+If any of the items haven't been set, and don't have a default value, an
+exception will be thrown. If you don't care about certain variables, you can
+pass :required => false to them (or give them a default value).
+
+Use a different source:
+
+If you want to use a source that isn't an ini file or yaml file, or environment
+variable. It is very easy to create your own one. It simply needs to be a class
+that has an initialize that takes a hash, and a [] method that takes a
+namespace and a key argument.
+
+    class MyOwnSource
+      def initialize(options = {})
+        ...
+      end
+
+      def [](namespace, key)
+        ...
+      end
+    end
+
+    Confuse::Source.register(:foo, MyOwnSource)
+
+    definition = Confuse.config, :type => :foo do |conf|
+      conf.add_item :foo
+    end
+
+    config = Confuse::Config.new(definition, my_own_source)
+
+If your class takes a :path variable, it will autodetect the extension for
+whatever you register. You can register more than one extension if you wish.
+
+You could use this to store data in whatever fancy file format you like, or
+perhaps even a database table, or one of those fancy NoSQL datastores, you
+could even write your config in Ruby code.
 
 ## Contributing
 

data/Rakefile

@@ -1 +1,8 @@
 require "bundler/gem_tasks"
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs.push 'lib'
+  t.test_files = FileList['test/test_*.rb']
+  t.verbose = true
+end

data/confuse.gemspec

@@ -22,4 +22,5 @@ Gem::Specification.new do |spec|
 
   spec.add_development_dependency 'bundler', '~> 1.3'
   spec.add_development_dependency 'minitest'
+  spec.add_development_dependency 'rake'
 end

data/example/env_example.rb

@@ -0,0 +1,10 @@
+#!/usr/bin/env ruby
+# coding: utf-8
+
+require 'confuse'
+
+config = Confuse.config :prefix => 'CONF' do |conf|
+  conf.add_item :foo, :description => "How many Foo's are there?", :default => 1
+end
+
+puts config.foo

data/example/example.ini

@@ -0,0 +1 @@
+foo = 10

data/example/example.yaml

@@ -0,0 +1 @@
+:foo: 10

data/example/ini_example.rb

@@ -0,0 +1,10 @@
+#!/usr/bin/env ruby
+# coding: utf-8
+
+require 'confuse'
+
+config = Confuse.config :path => 'example/example.ini' do |conf|
+  conf.add_item :foo, :description => "How many Foo's are there?", :default => 1
+end
+
+puts config.foo

data/example/yaml_example.rb

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+# coding: utf-8
+
+require 'confuse'
+
+config = Confuse.config :path => 'example/example.yaml' do |conf|
+
+  conf.add_item :foo, :description => "How many Foo's are there?", :default => 1
+end
+
+puts config.foo

data/lib/confuse.rb

@@ -1,11 +1,30 @@
+# coding: utf-8
+
 require 'confuse/version'
 
+require 'confuse/key_splitter'
 require 'confuse/config'
-require 'confuse/config_item'
-require 'confuse/config_mixin'
-require 'confuse/dsl'
+require 'confuse/item'
+require 'confuse/definition'
 require 'confuse/namespace'
+require 'confuse/source'
+require 'confuse/errors'
 
+# Top level namespace for confuse gem
 module Confuse
-end
+  class << self
+    def define(&block)
+      Definition.new(&block)
+    end
 
+    def source(options = {})
+      Source.create(options)
+    end
+
+    def config(options = {}, &block)
+      definition = Definition.new(&block)
+      source = Source.create(options)
+      Config.new(definition, source)
+    end
+  end
+end

data/lib/confuse/config.rb

@@ -1,48 +1,37 @@
-require 'confuse/config_mixin'
-require 'confuse/dsl'
+# coding: utf-8
 
 module Confuse
-  # The default module used for configuration.
-  module Config
-    extend ConfigMixin
-  end
+  class Config
+    def initialize(definition, source)
+      @definition = definition
+      @source = source
+    end
 
-  # Super class for configuration in order to have multiple instances.
-  class ConfigBase
-    include ConfigMixin
-    extend DSL
+    def respond_to?(name)
+      @definition.defines?(name) || super
+    end
 
-    def namespaces
-      @namespaces ||= {}
+    def method_missing(name, *_args)
+      self[name] if respond_to?(name)
     end
 
-    def initialize(options = {})
-      load_namespaces(self.class.namespaces.clone)
-      paths = options[:paths] || []
-      if paths.flatten.empty?
-        read_files(self.class.config_path.flatten)
-      else
-        read_files(paths.flatten)
-      end
-      options[:conf].tap { |conf| conf && mixin_config!(conf) }
+    def [](name)
+      namespace, key = @definition.namespace_and_key(name)
+      lookup(namespace, key)
     end
 
-    def config
-      self
+    def lookup(namespace, key)
+      @source[namespace, key] || @definition.default(namespace, key)
     end
 
-    def self.params_hash
-      namespaces.reduce({}) do |memo, (name, namespace)|
-        namespace.keys.each do |key|
-          item = namespace.get_item(key)
-          memo[:"#{name}_#{key}"] = {
-            :type => item.type,
-            :doc => item.description,
-            :default => item.default_value }
+    # check items have a value. Will raise Undefined error if a required item
+    # has no value.
+    def check
+      @definition.namespaces.each do |(namespace, ns)|
+        ns.items.each do |key, _|
+          lookup(namespace, key)
         end
-        memo
       end
     end
-
   end
 end

data/lib/confuse/definition.rb

@@ -0,0 +1,52 @@
+# coding: utf-8
+
+module Confuse
+  class Definition
+    def initialize(&block)
+      @default_namespace = :default
+      block.call(self)
+    end
+
+    def defines?(name)
+      !!find_item_by_name(name)
+    end
+
+    def default(namespace, key)
+      (item = find_item(namespace, key)) && item.default
+    end
+
+    def add_namespace(name, &block)
+      new_namespace = Namespace.new(&block)
+      namespaces[name.to_sym] = new_namespace
+    end
+
+    def add_item(name, opts = {})
+      namespaces[@default_namespace].add_item(name, opts)
+    end
+
+    def namespaces
+      @namespaces ||= {
+        @default_namespace => Namespace.new(&(Proc.new {}))
+      }
+    end
+
+    def namespace_and_key(name)
+      KeySplitter.new(name).split.find { |(ns, _)| namespaces[ns]  } ||
+        [nil, name]
+    end
+
+    private
+
+    def find_item_by_name(name)
+      namespace, key = namespace_and_key(name)
+    end
+
+    def find_item(namespace, key)
+      (ns = find_namespace(namespace)) && ns[key]
+    end
+
+    def find_namespace(name)
+      namespaces[name || @default_namespace]
+    end
+  end
+end

data/lib/confuse/errors.rb

@@ -0,0 +1,12 @@
+# coding: utf-8
+
+module Confuse
+  module Errors
+    class Undefined < StandardError
+      def initialize(name)
+        @name = name
+        super
+      end
+    end
+  end
+end

data/lib/confuse/item.rb

@@ -0,0 +1,20 @@
+# coding: utf-8
+
+module Confuse
+  # An {Item} is a class for storing a description piece of config.
+  class Item
+    def initialize(key, opts = {})
+      @key = key
+      @default, @description = opts.values_at(:default, :description)
+      @required = opts.key?(:required) ? opts[:required] : true
+    end
+
+    attr_reader :description, :required
+
+    def default
+      res = @default
+      raise Errors::Undefined.new(@key) if @required && !res
+      res
+    end
+  end
+end

data/lib/confuse/key_splitter.rb

@@ -0,0 +1,40 @@
+# coding: utf-8
+
+module Confuse
+  # This class encapsulates the code required to support searching for items
+  # with a single key item even for nested items.
+  # config[:foo_bar] instead of config[:foo][:bar]
+  class KeySplitter
+    def initialize(key)
+      @key = key
+    end
+
+    def split
+      possible_namespaces.map do |ns|
+        [ns, rest_of_key(ns)]
+      end
+    end
+
+    # Returns an array of possible namespaces based on splitting the key at
+    # every underscore.
+    def possible_namespaces
+      namespaces = []
+      key = @key.to_s
+      while (index = key.rindex('_'))
+        key = key[0, index]
+        namespaces << key.to_sym
+      end
+      namespaces
+    end
+
+    # Returns the rest of the key for a given namespace
+    def rest_of_key(namespace)
+      return nil if @key == namespace
+
+      key = @key.to_s
+
+      index = key.index(namespace.to_s) && (namespace.to_s.length + 1)
+      key[index, key.length].to_sym if index
+    end
+  end
+end

data/lib/confuse/namespace.rb

@@ -1,75 +1,22 @@
-require 'confuse/config_item'
+# coding: utf-8
 
 module Confuse
   # A {Namespace} is a container to keep configuration data seperate from the
   # rest of the config.
   class Namespace
-
-    attr_reader :items, :supress_warnings_flag, :strict_flag
+    attr_reader :items
 
     def initialize(&block)
       @items = {}
-      @supress_warnings_flag = false
-      @strict_flag = false
-      instance_eval(&block)
-    end
-
-    def define(name, &block)
-      @items[name] = ConfigItem.new(name, &block)
-    end
-
-    def supress_warnings
-      @supress_warnings_flag = true
-    end
-
-    def strict
-      @strict_flag = true
-    end
-
-    def [](key, config = nil)
-      value = (i = get_item(key)) && i.value
-      if value.respond_to?(:call) && !config.nil?
-        value.call(config)
-      else
-        value
-      end
+      block.call(self) if block_given?
     end
 
-    def []=(key, value)
-      item = get_item(key) || create_new_key(key, value)
-      item && item.value = value
+    def add_item(name, opts = {})
+      @items[name] = Item.new(name, opts)
     end
 
-    def keys
-      @items.keys
-    end
-
-    def create_new_key(key, value)
-      if @supress_warnings_flag
-        puts "Warning: config includes unknown option '#{key}'"
-      end
-      @items[key] = ConfigItem.new(key, &nil) unless @strict_flag
-    end
-
-    def get_item(key)
+    def [](key)
       @items[key]
     end
-
-    def merge!(namespace)
-      @strict_flag = namespace.strict
-      @supress_warnings_flag = namespace.supress_warnings
-      @items.merge! namespace.clone.items
-    end
-
-    def clone
-      c = super
-      items = @items.reduce({}) do |m, (k, v)|
-        m[k] = v.clone
-        m
-      end
-      c.instance_variable_set(:"@items", items)
-      c
-    end
-
   end
 end