universals 0.0.2

data/README

@@ -0,0 +1,69 @@
+Universals
+==========
+Everyone knows that global variables are bad. Sometimes though there are values
+that need to visible to all aspects of your code. Universals is a library that
+provides a class that allows for the aggregation of application or library wide
+data values. The Universe class becomes a centralized location for the storage
+or retrieval of such values. This avoids the need to use global variables or to
+pass such values down through the stack to the places they are actually used
+while avoiding the namespace pollution of global variables.
+
+Installing The Library
+----------------------
+The Universals library is provided as a Ruby gem and thus can be installed with
+a line such as...
+
+   $> gem install universals
+
+Using The Library
+-----------------
+The library contains a single class called Universe. This class acts very much
+like a Hash (with a few restrictions). Universe has mixed in Singleton and so
+there should only ever be one instance of the class that can be accessed using
+code such as the following...
+
+   Universals::Universe.instance
+   
+The value returned from this call can be treated like a Hash in that values can
+be set under keys using the array assignment operator like so...
+
+   Universals::Universe.instance["my_value"] = "Blah-de-blah"
+   
+Note that key names must be a String object. In addition, as the class makes the
+stored values available as properties on the Universe instance (see later for
+more details), the key must conform to many of the rules for method names. It
+can only start with a letter (upper or lower case) or an underscore and the
+remainder of the name must be made up of letters, underscores or numbers. The
+key may end with either '!' or '?'. Names ending with '=' or containing '[' or
+']' are explicitly excluded as they would be confusing. If you try to set a
+value on a Universe instance that does not conform to these rules then you will
+receive an exception for your trouble.
+
+As was mention previously, the Universe class makes values stored within it
+available as properties on the object itself. So, the value set in the previous
+example could be accessed using code such as...
+
+   Universals::Universe.instance.my_value
+
+Likewise, values can be set as if they were properties on the object. So, the
+following are valid assignments...
+
+   Universals::Universe.instance.my_value = 12345
+   Universals::Universe.instance.other_value = "Something else."
+   
+As the Universe class is a singleton, any values assigned into it can be
+retrieved anywhere. Note, that no effort has been made to make the Universe
+class thread safe. It is recommended that you assign all of the values needed
+to the object in a single place and thereafter treat the object as read only
+if you want to use it in multi-threaded code.
+
+Deferred Evaluation
+-------------------
+If you want to defer the evaluation of a value you can, instead of directly
+storing the value under it's key, store a Proc that evaluates to the correct
+value under the key. The next time this key is explicitly fetched from the
+Universe instance the Proc will be called (with no parameters) and the value
+it returns will be set under the key instead. Using this technique you can
+defer the creation of items until they are actually used, allowing them to be
+created at more appropriate points in the code and avoiding the possible
+overhead associated with the values creation.

data/lib/universals.rb

@@ -0,0 +1,8 @@
+# ! /usr/bin/env ruby
+#
+# Copyright (c) 2012, Peter Wood
+# See the license.txt for details of the licensing of the code in this file.
+
+require 'universals/version'
+require 'universals/exceptions'
+require 'universals/universe'

data/lib/universals/exceptions.rb

@@ -0,0 +1,40 @@
+#! /usr/bin/env ruby
+#
+# Copyright (c), 2012 Peter Wood
+# See the license.txt for details of the licensing of the code in this file.
+
+require 'stringio'
+
+module Universals
+   # This class provides the exception class used by the Universals library.
+   class UniversalsError < StandardError
+      # Attribute accessor/mutator declarations.
+      attr_accessor :verbose
+
+      # Constructor for the UniversalsError class.
+      #
+      # ==== Parameters
+      # message::  The message to be associated with the error.
+      # cause::    Any underlying exception to be associated with the error.
+      #            Defaults to nil.
+      def initialize(message, cause=nil, verbose=true)
+         super(message)
+         @cause   = cause
+         @verbose = verbose
+      end
+
+      # This method fetches a stringified interpretation of an exception.
+      def to_s()
+         text = StringIO.new
+         text << super
+         if @verbose
+            text << "\n" + self.backtrace.join("\n")
+            if !@cause.nil?
+               text << "\n\nCause: #{@cause}"
+               text << "\n" + @cause.backtrace.join("\n")
+            end
+         end
+         text.string
+      end
+   end
+end

data/lib/universals/universe.rb

@@ -0,0 +1,161 @@
+#! /usr/bin/env ruby
+#
+# Copyright (c), 2012 Peter Wood
+# See the license.txt for details of the licensing of the code in this file.
+
+require 'singleton'
+
+module Universals
+   # The Universals class includes the Ruby Singleton mixin and provides a
+   # single source location to store and retrieve data that is used across
+   # the entirety of an application or libraries code base. This avoids having
+   # to use global variables or to have to pass data elements around. The class
+   # behaves very much like a Hash, mapping keys to values. The class also
+   # makes the values stored within it available as properties, so all values
+   # stored within a Universe must be stored under String keys with names that
+   # conform to standard Ruby method naming criteria.
+   class Universe
+      # Mixin the singleton stuff.
+      include Singleton
+      
+      # Mixin the enumerable stuff.
+      include Enumerable
+      
+      # Constructor for the Universe class.
+      def initialize
+         @values = {}
+      end
+
+      # This method is used to check whether a property is stored under a given
+      # key within a Universe object.
+      #
+      # ==== Parameters
+      # key::  The key to perform the check for.
+      def has_property?(key)
+         @values.include?(key)
+      end
+
+      # This method fetches the value associated with a given key.
+      #
+      # ==== Parameters
+      # key::      The key for the value to be retrieved.
+      # default::  The default to return if the key does not exist within the
+      #            Universe object. Defaults to nil.
+      def get_property(key, default=nil)
+         value = @values.fetch(key, default)
+         if value.respond_to?(:call)
+            value        = value.call
+            @values[key] = value
+         end
+         value
+      end
+
+      # This method assigns a value under a specified key within a Universe
+      # object. Existing entries will be overwritten by this method.
+      def set_property(key, value)
+         validate_name(key)
+         @values[key] = value
+      end
+
+      # This method allows multiple values to be set on the Universe object
+      # in a single request.
+      #
+      # ==== Parameters
+      # values::  A Hash of the values to be set on the object. Keys should be
+      #           adhere to the standard name requirements for the Universe
+      #           object or an exception will be raised. Values specified in
+      #           this way will override values already in the object.
+      def set(values={})
+         values.each {|name, value| set_property(name, value)}
+      end
+
+      # Implementation of the each() method for the Universe class.
+      def each(&block)
+         @values.each(&block)
+      end
+
+      # This method fetches a count of the number of items held within an
+      # instance of the Universe class.
+      def size
+         @values.size
+      end
+      
+      # This method fetches the key associated with a value stored in the
+      # Universe instance.
+      #
+      # ==== Parameters
+      # value::  The value to retrieve the key for.
+      def key(value)
+         @values.key(value)
+      end
+      
+      # This method fetches a collection of the keys stored within a Universe
+      # instance.
+      def keys
+         @values.keys
+      end
+      
+      # This method fetches a collection of the values stored within a Universe
+      # instance.
+      def values
+         @values.values
+      end
+
+      # This method deletes all entries from a Universe instance.
+      def clear
+         @values.clear
+      end
+
+      # This method overrides the default respond_to?() method to provide
+      # customer property handling for Universe objects.
+      #
+      # ==== Parameters
+      # name::  The name of the method to perform the check for.
+      def respond_to?(name)
+         @hash.include?(name) || super(name)
+      end
+
+      # This method is invoked whenever a method invocation takes place
+      # against a Universe object but an existing explicit method cannot be
+      # found to meet the call.
+      #
+      # ==== Parameters
+      # name::       The name of the method invoked.
+      # arguments::  A collection of the arguments passed to the method call.
+      # block::      Any block associated with the method call.
+      def method_missing(name, *arguments, &block)
+         if @values.include?(name.to_s)
+            get_property(name.to_s)
+         elsif name.to_s[-1, 1] == "="
+            property = name.to_s
+            property = property[0, property.length - 1]
+            set_property(property, arguments[0])
+            self
+         else
+            super
+         end
+      end
+
+      # Class aliases.
+      alias :[] :get_property
+      alias :[]= :set_property
+      alias :include? :has_property?
+      
+      private
+      
+      # This method is used internally by the class to determine whether a key
+      # is valid for use with a Universe object.
+      def validate_name(name)
+         if !name.kind_of?(String)
+            raise UniversalsError.new("The key '#{name}' cannot be used in a "\
+                                      "Universe object as it is not a String.")
+         end
+         
+         if /^[a-zA-Z_]+[a-zA-Z_0-9]*[\?!]?$/.match(name).nil?
+            raise UniversalsError.new("The key '#{name}' cannot be used in a "\
+                                      "Universe object as it is not a valid "\
+                                      "method name.")
+         end
+      end
+   end
+end

data/lib/universals/version.rb

@@ -0,0 +1,11 @@
+# ! /usr/bin/env ruby
+#
+# Copyright (c) 2012, Peter Wood
+# See the license.txt for details of the licensing of the code in this file.
+
+module Universals
+   MAJOR_VERSION             = 0
+   MINOR_VERSION             = 0
+   BUILD_VERSION             = 2
+   VERSION                   = "#{MAJOR_VERSION}.#{MINOR_VERSION}.#{BUILD_VERSION}"
+end

data/license.txt

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) 2011 Peter Wood
+
+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.

metadata

@@ -0,0 +1,52 @@
+--- !ruby/object:Gem::Specification
+name: universals
+version: !ruby/object:Gem::Version
+  version: 0.0.2
+  prerelease: 
+platform: ruby
+authors:
+- Black North
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-01-21 00:00:00.000000000 Z
+dependencies: []
+description: Universals provides a simple singleton class that can be used to store
+  and retrieve data that is used throughout and application and thereby avoid global
+  variables.
+email: ruby@blacknorth.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/universals.rb
+- lib/universals/version.rb
+- lib/universals/universe.rb
+- lib/universals/exceptions.rb
+- license.txt
+- README
+homepage: https://github.com/free-beer/Universals
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: A library to provide a source for application wide data.
+test_files: []