construct 0.1.0

data/LICENSE

@@ -0,0 +1,25 @@
+Copyright (c) 2009 Kyle Kingsbury <aphyr@aphyr.com>
+All rights reserved.
+ 
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+ 
+  * Redistributions of source code must retain the above copyright notice,
+    this list of conditions and the following disclaimer.
+  * Redistributions in binary form must reproduce the above copyright notice,
+    this list of conditions and the following disclaimer in the documentation
+    and/or other materials provided with the distribution.
+  * Neither the name of this project nor the names of its contributors may be
+    used to endorse or promote products derived from this software without
+    specific prior written permission.
+ 
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/README

@@ -0,0 +1,78 @@
+Construct is extensible, persistent, structured configuration for Ruby and
+humans with text editors. What do I mean?
+
+You have a ruby program. Maybe it's a Ramaze app. It needs to store some
+configuration data. It should be easily serialized to YAML so anyone can edit
+the file easily. It should support nested structures. It should minimize
+typing, and make access unambiguous. It should take no effort to create and
+extend multi-layer configuration with many data types and accessors. Moreover,
+it should allow you to define a schema for the options that are available,
+making documentation easy. That's where Construct comes in.
+
+  gem install construct
+
+  config = Construct.new
+
+Hey, we have a configuration object. Let's describe a web site. Keys are always symbols, but can be accessed via methods just like an OpenStruct.
+
+  config.name = "Aphyr"
+  config.base_url = "http://aphyr.com"
+
+And getting at them is easy, too.
+
+  config.name
+    => "Aphyr"
+
+If the key you want is already a method, just use config#[] and config#[]=. Construct converts strings to symbols for you..
+
+How about a database connection? Those parameters all belong together.
+
+  config.db = {
+    :user => 'cr',
+    :password => 'some password',
+  }
+
+Secretly, Construct converted that hash into another Construct. You can chain
+methods to easily access nested options.
+
+  config.db.user
+    => 'cr'
+
+Databases need a host. Let's define a host field.
+
+  config.db.schema[:host] = {
+    :default => '127.0.0.1',
+    :desc => 'The host the database adapter connects to.'
+  }
+  config.db.host
+    => '127.0.0.1'
+
+You can override this, naturally.
+
+  config.db.host = 'db.aphyr.com'
+  config.db.host
+    => 'db.aphyr.com'
+
+And it serializes neatly to YAML. Keys are expressed as strings, to save typing and make things look clean.
+
+  config.to_yaml =>
+  --- 
+  db: 
+    user: cr
+    password: some password
+  name: Aphyr
+  base_url: http://aphyr.com
+
+Hey, this is easy! Now let's load that configuration from a string.
+
+  config = Construct.load yaml
+
+Maybe you need to implement extra logic in your config--perhaps you can specify either a db hash as shown above, or a connection string. Just subclass Construct::Construct or define methods directly on the construct.
+
+  class DBConfig < Construct::Construct
+    def db_str
+      self[:db_str] || make_db_string_from_hash(db)
+    end
+  end
+
+Problem solved. Now get back to having fun instead of worrying about configuration!

data/lib/construct.rb

@@ -0,0 +1,135 @@
+class Construct
+  # Construct is extensible, persistent, structured configuration for
+  # Ruby and humans with text editors.
+ 
+  APP_NAME = 'Construct'
+  APP_VERSION = '0.1.0'
+  APP_AUTHOR = 'Kyle Kingsbury'
+  APP_EMAIL = 'aphyr@aphyr.com'
+  APP_URL = 'http://aphyr.com'
+  APP_COPYRIGHT = 'Copyright (c) 2009 Kyle Kingsbury <aphyr@aphyr.com>. All rights reserved.'
+
+  require 'yaml'
+
+  YAML::add_domain_type("aphyr.com,2009", "construct") do |type, val|
+    # Not implemented ;)
+    Construct.load(val)
+  end
+  yaml_as "tag:aphyr.com,2009:construct"
+  yaml_as "tag:yaml.org,2002:map"
+
+  # Load a construct from a YAML string
+  def self.load(yaml)
+    hash = YAML::load(yaml)
+    new(hash)
+  end
+
+  attr_accessor :schema, :data
+
+  def initialize(data = {}, schema = {})
+    @data = Hash.new
+    data.each do |key, value|
+      self[key] = value
+    end
+    @schema = schema
+  end
+
+  def ==(other)
+    @schema == other.schema and @data == other.data
+  end
+
+  def [](key)
+    key = key.to_sym if String === key
+
+    if @data.include? key
+      @data[key]
+    elsif @schema.include? key
+      @schema[key][:default]
+    end 
+  end
+
+  # Assign a value to a key. Constructs accept only symbols as values,
+  # and will convert strings to symbols when necessary. They will also
+  # implicitly convert Hashes as values into Constructs when possible. Hence
+  # you can do:
+  #
+  # construct.people = {:mary => 'Awesome', :joe => 'suspicious'}
+  # construct.people.mary # => 'Awesome'
+  def []=(key, value)
+    key = key.to_sym if String === key
+    raise ArgumentError.new('construct only accepts symbols (and strings) as keys.') unless key.is_a? Symbol
+
+    # Convert suitable hashes into Constructs
+    if value.is_a? Hash
+      if value.keys.all? { |k| 
+            k.is_a? String or k.is_a? Symbol
+          }
+        value = Construct.new(value)
+      end
+    end
+
+    @data[key] = value
+  end
+
+  # Clears the data in the construct.
+  def clear
+    @data.clear
+  end
+
+  # Defines a new field in the schema. Fields are :default and :desc.
+  def define(key, options = {})
+    key = key.to_sym if String === key
+    @schema[key] = options
+  end
+
+  # delete simply removes the value from the data hash, but leaves the schema
+  # unchanged.  Hence the construct may still respond to include? if the
+  # schema defines that field. Use #schema.delete(:key) to remove the key
+  # entirely.
+  def delete(key)
+    key = key.to_sym if String === key
+    @data.delete key
+  end
+
+  # Returns true if the construct has a value set for, or the schema defines,
+  # the key.
+  def include?(*args)
+    @data.include?(*args) or @schema.include?(*args)
+  end
+
+  # Returns the keys, both set in the construct and specified in the schema.
+  def keys
+    @data.keys | @schema.keys
+  end
+
+  def load(str)
+  end
+
+  def method_missing(meth, *args)
+    meth_s = meth.to_s
+    if meth_s[-1..-1] == '='
+      # Assignment
+      if args.size != 1
+        raise ArgumentError.new("#{meth} takes exactly one argument")
+      end
+
+      self[meth_s[0..-2]] = args[0]
+    elsif include? meth
+      self[meth]
+    else
+      raise NoMethodError.new('no such key in construct')
+    end
+  end
+
+  # Dumps the data (not the schema!) of this construct to YAML. Keys are
+  # expressed as strings.
+  def to_yaml(opts = {})
+    YAML::quick_emit(self, opts) do |out|
+      out.map(taguri, to_yaml_style) do |map|
+        @data.each do |key, value|
+          map.add(key.to_s, value)
+        end
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,55 @@
+--- !ruby/object:Gem::Specification 
+name: construct
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Kyle Kingsbury
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-07-12 00:00:00 -05:00
+default_executable: 
+dependencies: []
+
+description: 
+email: aphyr@aphyr.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/construct.rb
+- LICENSE
+- README
+has_rdoc: true
+homepage: http://aphyr.com
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: 1.8.5
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: construct
+rubygems_version: 1.3.1
+signing_key: 
+specification_version: 2
+summary: Extensible, persistent, structured configuration for Ruby.
+test_files: []
+