hopsoft-fig 0.8.2

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2008 Hopsoft LLC
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,78 @@
+=Fig
+
+===DRY up those magic numbers and hard coded strings into something more managable.  Fig is the smart way to manage stuff that really belongs in a config file instead of scattered throughout your code.
+
+==Why
+
+I know that Ruby is a dynamic language and that hard coded values aren't as big a deal, but...
+it's still good practice to have a centralized place to hold certain settings.
+
+I used to create a globally available Hash to store this stuff, but have always wanted something more powerful and elegant.
+
+
+==What
+
+Fig is a simple to use configuration management tool for Ruby applications and libraries.  
+
+The primary features are: 
+* Multiple configuration files
+* Dynamic updating and re-loading of configuration files
+* Simple dot-notation access to configuration settings
+* YAML access to configuration settings
+* Safe options to request settings that may not exist
+* Interpolation to help DRY up configuration files through reuse of settings
+* Thread safe
+
+==How
+
+The simplest way to get started is to watch the 10 minute tutorial.
+
+
+
+===Installation
+
+Fig is availabe as both a Gem and as a Rails Plugin.
+
+====To install as a Gem:
+
+First, be sure that Github has been added as a gem source. (This only needs to be done once.)
+  gem sources -a http://gems.github.com
+
+Second, install the Gem.
+  sudo gem install hopsoft-fig
+
+====To install as a Rails Plugin:
+  script/plugin install git://github.com/hopsoft/fig.git
+
+
+===Usage
+Create a YAML file that will serve as one of the configuration files you plan to use.  In a Rails application, I usually create the file config/app.yml, but you can name the file anything you like and can save it to any location within your appliation or library.
+
+Require Fig either explicitly or implicitly.  In a Rails application, I generally do this in environment.rb.
+  # implicit
+  require 'hopsoft/fig'
+  # explicit
+  gem 'hopsoft-fig'
+
+Instantiate a Fig object that is globally available to your application.  In a Rails application, I generally do this in environment.rb.
+  APP_CONFIG = Fig.new(RAILS_ROOT + '/config/app.yml')
+
+Start using your settings.
+  puts APP_CONFIG.settings.message
+  puts APP_CONFIG.yaml['message']
+  puts APP_CONFIG.get_setting('message')
+  # returns nil instead of an error when the setting doesn't exist
+  puts APP_CONFIG.get_setting('some.nested.setting.that.may.not.exist')
+  
+Reuse settings in your YAML file (This is a great way to apply the DRY principle to your configuration settings):
+  name: Nathan Hopkins
+  message: {fig:name} says hello.
+ 
+  puts APP_CONFIG.get_setting('message')
+  # outputs -> Nathan Hopkins says hello.
+
+Update the YAML file and load the changes without restarting your application.
+  APP_CONFIG.load
+
+
+Copyright (c) 2008 Hopsoft LLC, released under the MIT license

data/Rakefile

@@ -0,0 +1,13 @@
+require 'echoe'
+
+Echoe.new('fig', '0.8.2') do |p|
+  p.description = "The smart way to manage configuration settings for your Ruby applications."
+  p.url = "http://github.com/natehop/fig"
+  p.author = "Nathan Hopkins, Hopsoft LLC"
+  p.email = "natehop@gmail.com"
+  p.ignore_pattern = ["nbproject*"]
+  p.development_dependencies = []
+  puts p.class
+end
+
+Dir["#{File.dirname(__FILE__)}/tasks/*.rake"].sort.each {|file| load file}

data/fig.gemspec

@@ -0,0 +1,32 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{fig}
+  s.version = "0.8.2"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Nathan Hopkins, Hopsoft LLC"]
+  s.date = %q{2009-03-15}
+  s.description = %q{The smart way to manage configuration settings for your Ruby applications.}
+  s.email = %q{natehop@gmail.com}
+  s.extra_rdoc_files = ["README.rdoc", "lib/fig.rb", "lib/string.rb", "tasks/fig_tasks.rake"]
+  s.files = ["README.rdoc", "install.rb", "MIT-LICENSE", "test/test.yml", "test/test2.yml", "test/string_test.rb", "test/fig_test.rb", "Manifest", "uninstall.rb", "Rakefile", "init.rb", "lib/fig.rb", "lib/string.rb", "tasks/fig_tasks.rake", "fig.gemspec"]
+  s.has_rdoc = true
+  s.homepage = %q{http://github.com/natehop/fig}
+  s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Fig", "--main", "README.rdoc"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = %q{fig}
+  s.rubygems_version = %q{1.3.1}
+  s.summary = %q{The smart way to manage configuration settings for your Ruby applications.}
+  s.test_files = ["test/string_test.rb", "test/fig_test.rb"]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 2
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+    else
+    end
+  else
+  end
+end

data/init.rb

@@ -0,0 +1,2 @@
+require 'string'
+require 'fig'

data/install.rb

@@ -0,0 +1 @@
+# Install hook code here

data/lib/fig.rb

@@ -0,0 +1,132 @@
+require 'yaml'
+require 'ostruct'
+require 'thread'
+require File.dirname(__FILE__) + '/string'
+
+class Fig
+ 
+  # Constructor...
+  #
+  # ===Params
+  # * *file_path* - Path to the config file that should be loaded.
+  def initialize(file_path)
+    @lock = Mutex.new
+    @file_path = file_path
+    load
+  end
+
+  # Returns the config file file as a YAML Hash.
+  def yaml
+    copy = {}
+    @lock.synchronize do
+      copy.merge!(@yaml)
+    end
+    copy
+  end
+
+
+  # Returns an OpenStruct object representation of the config file.
+  # This allows you to access config settings with dot notation.
+  def settings
+    copy = OpenStruct.new
+    @lock.synchronize do 
+      copy.marshal_load(@settings.marshal_dump)
+    end
+    copy
+  end
+
+  # The safest way to get a config setting.
+  # Requesting a non-exsisting key, will simply return a nil value instead of raising an error.
+  #
+  # Examples:
+  # Fig.get_setting('some.nested.setting')
+  #
+  # ===Params
+  # * *key* - A case insensivie config key
+  #
+  # *Returns* The value of the config setting requested.
+  #   This may be the value itself or an OpenStruct containing child args
+  def get_setting(key)
+    setting = nil
+
+    @lock.synchronize do
+      setting = @settings
+      keys = key.to_s.downcase.split(/\./)
+
+      keys.each do |k|
+        item = eval("setting.#{k}")
+        return nil unless item
+        setting = item
+      end
+    end
+
+    setting
+  end
+
+  # Loads the config file and builds the internal Fig objects.
+  # Can be used to reload the file when changes have been made.
+  def load
+    yaml = YAML.load_file(@file_path)
+    yaml.each {|k, v| interpolate_setting(yaml, v)}
+    settings = OpenStruct.new
+    add_hash(settings, yaml)
+
+    @lock.synchronize do  
+      @yaml = yaml
+      @settings = settings
+    end
+  rescue
+    puts "Failed to load file: #{@file_path}\n#{$!}"
+  end
+
+private
+
+  # Invoked recursively to implicitly interpolate all settings for the passed value.
+  # Config values that contain the pattern /{fig:/ are implicitly interpolated,
+  # replacing the "fig" placeholder with the actual value from elsewhere in the config file.  
+  #  
+  # Example:
+  #   name: Nathan Hopkins
+  #   message: "This is a test! Hello #{fig:example.name}"
+  #
+  # ===Params
+  # * *value* [_Object_] The value to interpolate.
+  def interpolate_setting(yaml, value)
+    if value.is_a?(Hash)
+      value.each {|k,v| interpolate_setting(yaml, v) }
+    elsif value.is_a?(String)
+      pattern = /\{fig:/i
+      start = value.index(pattern, 0)
+      replace = {}
+      
+      while start
+        finish = value.index(/\}/, start)
+        key = value[(start + 1)..(finish - 1)]
+        replace[key] = eval("yaml['#{key.sub(/^fig:/i, "").gsub(/\./, "']['")}'].to_s")  
+        start = value.index(pattern, finish)
+      end
+      
+      value.interpolate(replace, true)
+    end
+  end
+  
+  # Recursively adds a hash to an OpenStruct object, ultimately creating a complete OpenStruct object with attributes
+  # for all key/value pairs in the Hash.
+  # 
+  # ===Params
+  # * *obj* - The OpenStruct object to add Hash args to.
+  # * *hash* - The Hash to pull args from.
+  def add_hash(obj, hash)
+    return unless hash
+
+    hash.each do |key, value|
+      if value.class == Hash
+        eval "obj.#{key} = OpenStruct.new"
+        add_hash(eval("obj.#{key}"), value)
+      else
+        eval "obj.#{key.downcase} = value"  
+      end
+    end
+  end
+   
+end

data/lib/string.rb

@@ -0,0 +1,48 @@
+class String
+
+  # Allows various forms of string interpolation.
+  # Addd to make it easier to dynamically replace YAML config values;
+  # howerver, this will likely come in handy elsewhere.
+  #
+  # Examples:
+  #   "Hello! My name is ?".interpolate("Nathan Hopkins")
+  #   "Hello! My first name is ? and my last name is ?".interpolate(["Nathan", "Hopkins"])
+  #   'Hello! My first name is {first_name} and my last name is {last_name}'.interpolate(:first_name => "Nathan", :last_name => "Hopkins")
+  #
+  # ===Params
+  # * *args* [Symbol, String, Array, Hash] The value(s) used to replace segments of the string.
+  # * *in_place* [Boolean] Indicates if the value should edited in place.
+  #   Be careful when doing this, you may end up with unexpected results!
+  #
+  # ===Returns
+  # The new string after interpolation.
+  def interpolate(args, in_place=false)
+    args = [args] unless args.is_a?(Array) || args.is_a?(Hash)
+
+    if args.is_a?(Array)
+      x = -1
+
+      if in_place
+        self.gsub!(/\?/) do |s|
+          x += 1
+          args[x]
+        end
+      else
+        return self.gsub(/\?/) do |s|
+          x += 1
+          args[x]
+        end
+      end
+    elsif args.is_a?(Hash)
+      if in_place
+        args.each {|k, v| self.gsub!(/\{#{k.to_s}\}/i, v.to_s)}
+      else
+        new_string = String.new(self)
+        args.each {|k, v| new_string.gsub!(/\{#{k.to_s}\}/i, v.to_s)}
+        return new_string
+      end
+    end
+
+    return self
+  end
+end

data/tasks/fig_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :fig do
+#   # Task goes here
+# end

data/test/fig_test.rb

@@ -0,0 +1,89 @@
+require 'test/unit'
+require 'fileutils'
+require File.dirname(__FILE__) + '/../lib/fig'
+
+class FigTest < Test::Unit::TestCase
+  @@fig = Fig.new(File.dirname(__FILE__) + '/test.yml')
+  
+  def test_yaml_values
+    assert @@fig.yaml
+    assert @@fig.yaml['name'] == 'Nathan Hopkins'
+    assert @@fig.yaml['message'] == 'Hello there Nathan Hopkins'
+    assert @@fig.yaml['name2'] == 'Page Hopkins'
+    assert @@fig.yaml['message2'] == 'Hello there Page Hopkins'
+    assert @@fig.yaml['list'].is_a?(Array)
+    assert @@fig.yaml['list'].length == 6
+    assert @@fig.yaml['parent']['name'] == 'Nathan Hopkins'
+    assert @@fig.yaml['parent']['child']['name'] == 'Emma Hopkins'
+
+    assert_raise NoMethodError do
+     @@fig.yaml['some']['complete']['garbage']
+    end
+  end
+
+  def test_settings_values
+    assert @@fig.settings
+    assert @@fig.settings.name == 'Nathan Hopkins'
+    assert @@fig.settings.message == 'Hello there Nathan Hopkins'
+    assert @@fig.settings.name2 == 'Page Hopkins'
+    assert @@fig.settings.message2 == 'Hello there Page Hopkins'
+    assert @@fig.settings.list.is_a?(Array)
+    assert @@fig.settings.list.length == 6
+    assert @@fig.settings.parent.name == 'Nathan Hopkins'
+    assert @@fig.settings.parent.child.name == 'Emma Hopkins'
+
+    assert_raise NoMethodError do
+     @@fig.settings.some.complete.garbage
+    end
+  end
+
+  def test_get_setting
+    assert @@fig.get_setting('name') == 'Nathan Hopkins'
+    assert @@fig.get_setting('message') == 'Hello there Nathan Hopkins'
+    assert @@fig.get_setting('name2') == 'Page Hopkins'
+    assert @@fig.get_setting('message2') == 'Hello there Page Hopkins'
+    assert @@fig.get_setting('list').is_a?(Array)
+    assert @@fig.get_setting('list').length == 6
+    assert @@fig.get_setting('parent').name == 'Nathan Hopkins'
+    assert @@fig.get_setting('parent').child.name == 'Emma Hopkins'
+    assert @@fig.get_setting('some.complete.garbage') == nil
+  end
+
+  def test_change_and_reload
+    dir_name = File.dirname(__FILE__)
+    orig_file = dir_name + '/test.yml'
+    new_file = dir_name + '/test2.yml'
+    bak_file = dir_name + '/test.yml.bak'
+
+    # make a backup
+    FileUtils.rm(bak_file) if File.exist?(bak_file)
+    FileUtils.cp orig_file, bak_file
+
+    # swap files
+    FileUtils.mv new_file, orig_file, :force => true
+
+    # verify that the file swap didn't change anything implicitly
+    test_get_setting 
+
+    # reload
+    @@fig.load
+    
+    # test new settings
+    assert @@fig.get_setting('name') == 'Jeff Hopkins'
+    assert @@fig.get_setting('message') == 'Hello there Jeff Hopkins'
+    assert @@fig.get_setting('name2') == 'Marie Hopkins'
+    assert @@fig.get_setting('message2') == 'Hello there Marie Hopkins'
+    assert @@fig.get_setting('list').is_a?(Array)
+    assert @@fig.get_setting('list').length == 6
+    assert @@fig.get_setting('parent').name == 'Jeff Hopkins'
+    assert @@fig.get_setting('parent').child.name == 'Nathan Hopkins'
+    assert @@fig.get_setting('some.complete.garbage') == nil
+
+    # switch back
+    FileUtils.mv orig_file, new_file, :force => true
+    FileUtils.mv bak_file, orig_file, :force => true
+    @@fig.load
+  end
+
+
+end

data/test/string_test.rb

@@ -0,0 +1,54 @@
+require 'test/unit'
+require File.dirname(__FILE__) + '/../lib/string'
+
+class StringTest < Test::Unit::TestCase
+
+  def test_interpolate_with_string
+    orig = "Hello! My name is ?"
+    interpolated = orig.interpolate("Nathan Hopkins")
+    expected = "Hello! My name is Nathan Hopkins"
+    assert_not_equal orig, interpolated, "Should not have mutated in place"
+    assert_equal expected, interpolated
+
+    interpolated = orig.interpolate("Nathan Hopkins", true)
+    assert_equal orig, interpolated, "Should have mutated in place"
+    assert_equal expected, interpolated
+  end
+
+  def test_interpolate_with_symbol
+    orig = "Hello! My name is ?"
+    interpolated = orig.interpolate(:Nathan)
+    expected = "Hello! My name is Nathan"
+    assert_not_equal orig, interpolated, "Should not have mutated in place"
+    assert_equal expected, interpolated
+
+    interpolated = orig.interpolate(:Nathan, true)
+    assert_equal orig, interpolated, "Should have mutated in place"
+    assert_equal expected, interpolated
+  end
+
+  def test_interpolate_with_array
+    orig = "Hello! My first name is ? and my last name is ?"
+    interpolated = orig.interpolate(["Nathan", :Hopkins])
+    expected = "Hello! My first name is Nathan and my last name is Hopkins"
+    assert_not_equal orig, interpolated, "Should not have mutated in place"
+    assert_equal expected, interpolated
+
+    interpolated = orig.interpolate(["Nathan", :Hopkins], true)
+    assert_equal orig, interpolated, "Should have mutated in place"
+    assert_equal expected, interpolated
+  end
+
+  def test_interpolate_with_hash
+    orig = 'Hello! My first name is {first_name} and my last name is {last_name}'
+    interpolated = orig.interpolate(:first_name => "Nathan", :last_name => :Hopkins)
+    expected = "Hello! My first name is Nathan and my last name is Hopkins"
+    assert_not_equal orig, interpolated, "Should not have mutated in place"
+    assert_equal expected, interpolated
+
+    interpolated = orig.interpolate({:first_name => "Nathan", :last_name => :Hopkins}, true)
+    assert_equal orig, interpolated, "Should have mutated in place"
+    assert_equal expected, interpolated
+  end
+
+end

data/test/test.yml

@@ -0,0 +1,9 @@
+name: Nathan Hopkins
+message: Hello there {fig:name}
+message2: Hello there {fig:name2}
+name2: Page Hopkins
+list: [a, b, c, d, e, f]
+parent:
+  name: '{fig:name}'
+  child:
+    name: Emma Hopkins

data/test/test2.yml

@@ -0,0 +1,9 @@
+name: Jeff Hopkins
+message: Hello there {fig:name}
+message2: Hello there {fig:name2}
+name2: Marie Hopkins
+list: [a, b, c, d, e, f]
+parent:
+  name: '{fig:name}'
+  child:
+    name: Nathan Hopkins

data/uninstall.rb

@@ -0,0 +1 @@
+# Uninstall hook code here

metadata

@@ -0,0 +1,76 @@
+--- !ruby/object:Gem::Specification 
+name: hopsoft-fig
+version: !ruby/object:Gem::Version 
+  version: 0.8.2
+platform: ruby
+authors: 
+- Nathan Hopkins, Hopsoft LLC
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-03-15 00:00:00 -07:00
+default_executable: 
+dependencies: []
+
+description: The smart way to manage configuration settings for your Ruby applications.
+email: natehop@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+- lib/fig.rb
+- lib/string.rb
+- tasks/fig_tasks.rake
+files: 
+- README.rdoc
+- install.rb
+- MIT-LICENSE
+- test/test.yml
+- test/test2.yml
+- test/string_test.rb
+- test/fig_test.rb
+- Manifest
+- uninstall.rb
+- Rakefile
+- init.rb
+- lib/fig.rb
+- lib/string.rb
+- tasks/fig_tasks.rake
+- fig.gemspec
+has_rdoc: true
+homepage: http://github.com/natehop/fig
+post_install_message: 
+rdoc_options: 
+- --line-numbers
+- --inline-source
+- --title
+- Fig
+- --main
+- README.rdoc
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "1.2"
+  version: 
+requirements: []
+
+rubyforge_project: fig
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: The smart way to manage configuration settings for your Ruby applications.
+test_files: 
+- test/string_test.rb
+- test/fig_test.rb