copland 0.8.0

data/lib/copland/configuration-point.rb

@@ -0,0 +1,38 @@
+#--
+# =============================================================================
+# Copyright (c) 2004, Jamis Buck (jgb3@email.byu.edu)
+# 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.
+# 
+#     * The names of its contributors may not 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.
+# =============================================================================
+#++
+
+require 'copland/configuration-point/common'
+require 'copland/configuration-point/errors'
+
+require 'copland/configuration-point/list'
+require 'copland/configuration-point/map'

data/lib/copland/configuration-point/common.rb

@@ -0,0 +1,203 @@
+#--
+# =============================================================================
+# Copyright (c) 2004, Jamis Buck (jgb3@email.byu.edu)
+# 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.
+# 
+#     * The names of its contributors may not 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.
+# =============================================================================
+#++
+
+require 'copland/class-factory'
+require 'copland/errors'
+require 'ostruct'
+
+module Copland
+  module ConfigurationPoint
+
+    # The pool name for all configuration point implementations. (See
+    # Copland::ClassFactory)
+    POOL_NAME = "configuration-point"
+
+    begin
+      # create a new pool in the class factory
+      factory = Copland::ClassFactory.instance
+      factory.create_pool POOL_NAME
+    end
+
+    # Register the given class "+klass+" with the ClassFactory, with the given
+    # name. This will also create a new method on the class, called "type",
+    # which returns +name+.
+    def register( name, klass )
+      klass.class_eval <<-EOF
+        def type
+          #{name.inspect}
+        end
+      EOF
+      Copland::ClassFactory.instance.register( POOL_NAME, name, klass )
+    end
+    module_function :register
+
+    # This module implements the functionality that is common to all
+    # configuration points. By making this a module (as opposed to making it a
+    # class and having all configuration points extend it), you can now have
+    # configuration points that extend existing container classes, and which
+    # simply include this module.
+    module ConfigurationPointFunctionality
+
+      # The name of the configuration point.
+      attr_reader   :name
+
+      # The package instance that owns this configuration point.
+      attr_reader   :owner
+
+      # The (optional) description of this configuration point.
+      attr_accessor :description
+
+      # The (optional) schema that describes the value format of any data
+      # contributed to this configuration point.
+      attr_accessor :schema
+
+      # Initializes the new configuration point with the given owner and name.
+      # The options parameter is optional, and currently does nothing.
+      def initialize( owner, name, options={} )
+        super()
+        @owner = owner
+        @name = name
+      end
+
+      # Return the fully qualified name of this configuration point, which is
+      # the name of the package and the name of the point, separated by a dot.
+      def full_name
+        owner.name + "." + name
+      end
+
+      # Fixate the configuration point. This finalizes certain properties of
+      # the point, such as the schema. Once fixated, fixating a configuration
+      # point again will do nothing.
+      def fixate!
+        extend Fixated
+        if @schema.is_a?( String )
+          @schema = @owner.find_schema( @schema )
+        elsif !@schema.nil?
+          @schema.fixate!
+        end
+      end
+
+      # Contribute the given values to the configuration point. The +values+
+      # parameter must be of the correct type for this configuration point.
+      def contribute( values )
+        assert_correct_type( values )
+        validate_values( values )
+        values = process_values( values )
+        assimilate_values( values )
+      end
+
+      # Obtain a reference to the entity that made the given contribution.
+      # The entity is returned as an object that responds to <tt>:owner</tt>,
+      # which will return the contributing package when invoked.
+      def contributor_of( values )
+        contributor = values.instance_variable_get( :@contributor )
+        if contributor
+          return OpenStruct.new( :owner => contributor )
+        else
+          return self
+        end
+      end
+
+      # Assert that the +values+ parameter is of the correct type for this
+      # configuration point.
+      def assert_correct_type( values )
+        unless values.is_a?( self.class.superclass )
+          raise ContributionTypeMismatch, values.class.inspect
+        end
+      end
+
+      # Assert that the +values+ parameter is valid according to the schema
+      # for this configuration point.
+      def validate_values( values )
+        s = schema
+        if s.respond_to?( :validate )
+          contributor = contributor_of( values )
+          if values.is_a?( Array )
+            values.each do |value|
+              s.validate self, contributor, value
+            end
+          else
+            s.validate self, contributor, values
+          end
+        end
+      end
+
+      # Process and return the +values+ parameter according to the schema
+      # for this configuration point; or if no schema exists, run the
+      # values through the Copland::translate_values method.
+      def process_values( values )
+        s = schema
+        contributor = contributor_of( values )
+        if s.respond_to?( :process )
+          if s.is_a?( Array )
+            values = values.map! { |value|
+              s.process( self, contributor, value )
+            }
+          else
+            values = s.process( self, contributor, values )
+          end
+        else
+          values = Copland::translate_value( contributor.owner.registry,
+            contributor.owner, self, values )
+        end
+
+        return values
+      end
+
+      # Returns false. Once a configuration point is fixated, it will include
+      # the Copland::ConfigurationPoint::ConfigurationPointFunctionality::Fixated
+      # module, which redefines this method, as well as #fixate!.
+      def fixated?
+        false
+      end
+
+      # This module redefines certain methods of a configuration point so that
+      # the point cannot be modified in certain ways any more.
+      module Fixated
+        
+        # Does nothing, which means attempting to fixate a configuration point
+        # that has already been fixated will do nothing.
+        def fixate!
+          # does nothing
+        end
+
+        # Returns +true+.
+        def fixated?
+          true
+        end
+      end
+      
+    end
+
+  end
+end

data/lib/copland/configuration-point/errors.rb

@@ -0,0 +1,44 @@
+#--
+# =============================================================================
+# Copyright (c) 2004, Jamis Buck (jgb3@email.byu.edu)
+# 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.
+# 
+#     * The names of its contributors may not 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.
+# =============================================================================
+#++
+
+require 'copland/errors'
+
+module Copland
+  module ConfigurationPoint
+
+    # An exception class for reporting type mismatches when contributing data
+    # to a configuration point.
+    class ContributionTypeMismatch < CoplandException; end
+
+  end
+end

data/lib/copland/configuration-point/list.rb

@@ -0,0 +1,59 @@
+#--
+# =============================================================================
+# Copyright (c) 2004, Jamis Buck (jgb3@email.byu.edu)
+# 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.
+# 
+#     * The names of its contributors may not 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.
+# =============================================================================
+#++
+
+require 'copland/configuration-point/common'
+require 'copland/configuration-point/errors'
+require 'copland/utils'
+
+module Copland
+  module ConfigurationPoint
+
+    # This is the implementation of a configuration point of type "list".
+    # It is simply an enhanced array.
+    class ListConfigurationPoint < Array
+      include ConfigurationPointFunctionality
+
+      # Contribute values directly the list. The +values+ parameter is assumed
+      # to be an Array, and should have been validated previously against the
+      # configuration point's schema. Also, the values should have been
+      # previously preprocessed. In practice, this method should never be
+      # invoked directly--instead, use the #contribute method instead.
+      def assimilate_values( values )
+        concat values
+      end
+    end
+
+    register "list", ListConfigurationPoint
+
+  end
+end

data/lib/copland/configuration-point/map.rb

@@ -0,0 +1,59 @@
+#--
+# =============================================================================
+# Copyright (c) 2004, Jamis Buck (jgb3@email.byu.edu)
+# 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.
+# 
+#     * The names of its contributors may not 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.
+# =============================================================================
+#++
+
+require 'copland/configuration-point/common'
+require 'copland/configuration-point/errors'
+require 'copland/utils'
+
+module Copland
+  module ConfigurationPoint
+
+    # This is the implementation of a configuration point of type "map".
+    # It is simply an enhanced hash.
+    class MapConfigurationPoint < Hash
+      include ConfigurationPointFunctionality
+
+      # Contribute values directly the map. The +values+ parameter is assumed
+      # to be an Hash, and should have been validated previously against the
+      # configuration point's schema. Also, the values should have been
+      # previously preprocessed. In practice, this method should never be
+      # invoked directly--instead, use the #contribute method instead.
+      def assimilate_values( values )
+        merge! values
+      end
+    end
+
+    register "map", MapConfigurationPoint
+
+  end
+end

data/lib/copland/configuration/errors.rb

@@ -0,0 +1,43 @@
+#--
+# =============================================================================
+# Copyright (c) 2004, Jamis Buck (jgb3@email.byu.edu)
+# 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.
+# 
+#     * The names of its contributors may not 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.
+# =============================================================================
+#++
+
+require 'copland/errors'
+
+module Copland
+  module Configuration
+
+    # Represents an error that occured while parsing a configuration file.
+    class ParserError < CoplandException; end
+
+  end
+end