copland 0.8.0

data/lib/copland/configuration/yaml/loader.rb

@@ -0,0 +1,122 @@
+#--
+# =============================================================================
+# 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 'yaml'
+require 'copland/configuration/yaml/parser'
+
+module Copland
+  module Configuration
+    module YAML
+
+      # This is a visitor used during the initialization of a Registry. The
+      # Copland::Configuration::Loader class is the driver of the
+      # initialization process, and it delegates to visitors. This particular
+      # visitor looks for and processes YAML files that describe packages.
+      class Loader
+
+        # This is the name of the "configuration" yaml file, which allows
+        # parent directories to change certain properties of the processor when
+        # processing their children directories.
+        DEFAULT_YAML_CONFIG_FILE = "copland-config.yml"
+
+        # This is the default name of the package descriptor file.
+        DEFAULT_YAML_PACKAGE_FILE = "package.yml"
+
+        # Create a new YAML::Loader visitor object that feeds into the given
+        # Registry instance.
+        def initialize( registry, loader )
+          @parser = Parser.new( registry, loader )
+          @registry = registry
+          @visited = Hash.new
+        end
+
+        # This is invoked by the driver when a new directory needs to be
+        # visited. The options hash is returned, possibly modified.
+        def process_dir( directory, options )
+          options_filename = File.join( directory,
+            options[ :yaml_options_file ] ||
+            DEFAULT_YAML_CONFIG_FILE )
+
+          if File.exist?( options_filename )
+            options = parse_options_file( options_filename, options )
+          end
+
+          package_filename = File.join( directory,
+            options[ :yaml_package_file ] ||
+            DEFAULT_YAML_PACKAGE_FILE )
+
+          if !@visited[ package_filename ] && File.exist?( package_filename )
+            @visited[ package_filename ] = true
+            parse_package_file( package_filename, options )
+          end
+
+          return options
+        end
+
+        # Finalizes this visitor. This simply calls Registry#fixate!.
+        def finalize!
+          @registry.fixate! unless @registry.fixated?
+        end
+
+        # Parses a YAML-formated options file. The options hash is
+        # duplicated and returned, possibly modified.
+        def parse_options_file( options_filename, options )
+          yaml = ::YAML::load( File::read( options_filename ) )
+
+          options = options.dup
+          yaml.each_pair do |key, value|
+            case key
+              when "yaml-package-file"
+                options[ :yaml_package_file ] = value
+              when "default-service-model"
+                options[ :default_service_model ] = value
+              else
+                warn "invalid Copland configuration option in #{options_filename}: #{key}"
+            end
+          end
+
+          return options
+        end
+        private :parse_options_file
+
+        # Parses a YAML-formatted packag descriptor file. This delegates
+        # to Copland::Configuration::YAML::Parser#parse_file.
+        def parse_package_file( package_filename, options )
+          @parser.parse_file( package_filename, options )
+        end
+        private :parse_package_file
+      end
+
+    end
+  end
+end

data/lib/copland/configuration/yaml/package.rb

@@ -0,0 +1,125 @@
+#--
+# =============================================================================
+# 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'
+require 'copland/package'
+require 'copland/configuration/yaml/service-point'
+require 'copland/configuration/yaml/configuration-point'
+require 'copland/configuration/yaml/utils'
+
+module Copland
+  module Configuration
+    module YAML
+
+      # This delegate is responsible for processing a package descriptor
+      # into a Registry instance.
+      class PackageProcessor
+        include TypeValidator
+
+        # Creates a new PackageProcessor that feeds into the given Registry
+        # instance.
+        def initialize( registry, loader )
+          @registry = registry
+          @loader = loader
+        end
+
+        # The list of recognized key values in a package descriptor.
+        VALID_KEYS = [ "id", "description", "service-points",
+          "configuration-points", "contributions", "require" ]
+
+        # The list of required key values in a package descriptor.
+        REQUIRED_KEYS = [ "id" ]
+
+        # Process the package descriptor +doc+ into the active Registry
+        # instance. The +options+ parameter is used when processing service
+        # and configuration points within this package descriptor.
+        # The new Package instance is added directly to the registry.
+        def process( doc, options={} )
+          ensure_element_type "package definition", doc, Hash
+          validate_elements doc
+
+          package = Package.new( @registry, doc["id"] )
+          @registry.add_package package
+
+          doc.each_pair do |key, value|
+            case key
+              when "id"
+                # already discovered and handled above
+
+              when "description"
+                package.description = value
+
+              when "service-points"
+                ensure_element_type "service-points", value, Hash
+                processor = ServicePointProcessor.new( package, options )
+
+                value.each_pair do |name, definition|
+                  point = processor.process name, definition
+                  package.add_service_point point
+                end
+
+              when "configuration-points"
+                ensure_element_type "configuration-points", value, Hash
+                processor = ConfigurationPointProcessor.new( package, options )
+
+                value.each_pair do |name, definition|
+                  point = processor.process name, definition
+                  package.add_configuration_point point
+                end
+
+              when "contributions"
+                ensure_element_type "contributions", value, Hash
+
+                value.each_pair do |name, value|
+                  package.add_pending_contribution name, value
+                end
+
+              when "require"
+                ensure_element_type "require", value, Array
+                value.each do |name|
+                  @loader.use_library name
+                end
+
+              else
+                raise CoplandBug,
+                  "[BUG] invalid element discovered too late:" +
+                  key.inspect
+            end
+          end
+        end
+
+      end
+
+    end
+  end
+end

data/lib/copland/configuration/yaml/parser.rb

@@ -0,0 +1,71 @@
+#--
+# =============================================================================
+# 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 'yaml'
+require 'copland/configuration/yaml/package'
+
+module Copland
+  module Configuration
+    module YAML
+
+      # Manages the parsing and processing of YAML input into package
+      # instances that can be added to a Registry.
+      class Parser
+
+        # Create a new parser that will feed into the given Registry
+        # instance.
+        def initialize( registry, loader )
+          @registry = registry
+          @package = PackageProcessor.new( @registry, loader )
+        end
+
+        # Parse the file with the given name. The options Hash is optional,
+        # and specifies values that determine how the parse occurs.
+        def parse_file( filename, options={} )
+          parse( File.read( filename ) )
+        end
+
+        # Parse the given +io+ parameter (which must be either an +IO+ object
+        # or a +String+). The options are passed through to the
+        # PackageProcessor instance.
+        def parse( io, options={} )
+          ::YAML.load_documents( io ) do |doc|
+            @package.process doc, options
+          end
+        end
+
+      end
+
+    end
+  end
+end

data/lib/copland/configuration/yaml/schema.rb

@@ -0,0 +1,165 @@
+#--
+# =============================================================================
+# 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/errors'
+require 'copland/configuration/yaml/utils'
+require 'copland/schema'
+
+module Copland
+  module Configuration
+    module YAML
+
+      # This is the delegate assigned with the responsibility for processing
+      # schema elements.
+      class SchemaParser
+        include TypeValidator
+
+        # This is the list of keys recognized by this processor.
+        VALID_KEYS = [ "name", "class", "description", "definition", "type",
+                       "required", "extend" ]
+
+        # This is the list of keys required by this processor.
+        REQUIRED_KEYS = []
+
+        # This is invoked when a schema element has been detected and needs to
+        # be processed. The given point is either a configuration point or a
+        # service point. The schema is returned.
+        def process( point, schema )
+          process_schema point, schema, "schema://"
+        end
+
+        # This is invoked recursively to process each node of the schema. If
+        # the schema is a string, then it is interpreted to be the name of
+        # an external schema.
+        def process_schema( point, schema, path )
+          return schema if schema.is_a?( String )
+
+          ensure_element_type path, schema, Hash
+          validate_elements schema, path
+
+          name = schema[ 'name' ]
+          processor = schema[ 'class' ]
+          required = schema[ 'required' ]
+          description = schema[ 'description' ]
+          definition = schema[ 'definition' ]
+          type = schema[ 'type' ]
+          extend = schema[ 'extend' ]
+
+          ensure_element_type( path + "/name", name, String ) if name
+          ensure_element_type( path + "/class", processor,
+            String ) if processor
+          ensure_element_type( path + "/description", description,
+            String ) if description
+          ensure_element_type( path + "/definition", definition,
+            Hash ) if definition
+          ensure_element_type( path + "/type", type,
+            String ) if type
+          ensure_element_type( path + "/extend", extend,
+            String ) if extend
+
+          unless [ nil, true, false ].include?( required )
+            raise ParserError,
+              "expected 'true' or 'false' value for #{path}/required, " +
+              "but got #{required.inspect}"
+          end
+
+          definition = process_definition( point, definition,
+            path + "/definition" )
+          type = process_type( definition, schema[ 'type' ], path + "/type" )
+
+          node = Schema.new( name,
+                             processor, 
+                             description,
+                             required,
+                             type,
+                             definition,
+                             extend )
+
+          point.owner.add_schema node if node.name
+          node.owner = point.owner
+
+          return node
+        end
+        private :process_schema
+
+        # Processes the 'definition' portion of a schema.
+        def process_definition( point, definition, path )
+          return definition if definition.nil?
+
+          new_hash = Hash.new
+          definition.each_pair do |key, value|
+            new_hash[ key ] = process_schema( point, value,
+              path + "/" + key )
+          end
+
+          return new_hash
+        end
+        private :process_definition
+
+        # Processes the 'type' portion of a schema. If the type is invalid, or
+        # if it conflicts with the type of the definition, then an error is
+        # raised.
+        def process_type( definition, value, path )
+          if !value.nil? && value.downcase != "array" && !definition.nil?
+            raise ParserError,
+              "type must be 'array' or omitted when a subschema definition " +
+              "is provided"
+          end
+
+          value = "any" if value.nil? && definition.nil?
+          return value unless value
+
+          value.downcase!
+
+          [ "any",
+            "boolean",
+            "integer",
+            "real",
+            "service",
+            "log",
+            "configuration",
+            "string",
+            "hash",
+            "array" ].include?( value ) or
+          raise ParserError,
+            "invalid type #{value.inspect} at #{path}"
+
+          return value
+        end
+        private :process_type
+
+      end
+
+    end
+  end
+end