masterview 0.2.5 → 0.3.0

data/lib/masterview/directive_load_path.rb

@@ -0,0 +1,388 @@
+require 'yaml'
+require File.join( File.dirname(__FILE__), 'exceptions' )
+
+module MasterView
+
+  # An InvalidPathError that is raised when an invalid directory path
+  # is encountered on the directive load path.
+  class InvalidDirectivePathError < InvalidPathError
+
+    # the directive load path entry containing the invalid directory path
+    def path_entry
+      @dpe || nil
+    end
+
+    def initialize( dpe, err_msg )
+      super(dpe.dir_path, err_msg)
+      @dpe = dpe
+    end
+
+  end
+
+
+  # The directive load path supports configuring a MasterView application
+  # with a list of directories from which directives are loaded.
+  # 
+  # A MasterView application is always configured with the standard set of
+  # built-in directives, customarily referenced in templates in the 
+  # <code>mv:</code> namespace.  Additional directives can be used by
+  # appending directories containing the directive implementations
+  # to the MasterView load path specified by the Configuration.
+  # 
+  module DirectiveLoadPath
+
+    # File name of metadata specs file in a directives directory
+    # Contains yaml specifications for directive implementations
+    METADATA_SPECS_FILE_NAME = '.metadata'
+
+    DEBUG_MD_DIR_SPECS = false #:nodoc:  ##DEBUG##
+
+    @@path_registry = {} #:nodoc:
+    #cattr_reader :path_registry
+    def self.path_registry  #:nodoc: # special hook for test cases fiddling with system state
+      @@path_registry
+    end
+
+    # Answer the directives load path specs for the current load path
+    def self.current
+      @@path_registry[:current]
+    end
+
+    # Answer the default directives load path specs
+    def self.default_path_specs #:nodoc:
+      @@path_registry[:default]
+    end
+
+    # Install the configured load path
+    def self.default_path_specs=(load_path) #:nodoc:
+      @@path_registry[:default] = load_path.nil?  ? nil : clone_path(load_path)
+      if load_path && ! @@path_registry.has_key?(:current)
+        @@path_registry[:current] = clone_path(load_path) 
+      end
+    end
+
+    # hook for test cases so they can ensure a clean system state
+    def self.reset_current()  #:nodoc:
+      load_path = self.default_path_specs
+      @@path_registry[:current] = load_path.nil?  ? nil : clone_path(load_path)
+    end
+
+    # Answer a clone copy of a directive load path
+    # 
+    # Does a deep_copy to ensure a clean copy of options maps
+    # 
+    def self.clone_path(path)
+      path.collect{ | dpe | dpe.deep_copy }
+    end
+
+    # A PathEntry contains the specification for a directory
+    # on the MasterView directives load path.
+    # 
+    class PathEntry
+
+      # Answer a deep copy so we have a proper clone of the options.
+      def self.copy_options(options)
+        raise ArgumentError, "PathEntry options must be a hash: #{options.inspect}" if ! options.is_a?(Hash)
+        Marshal.load(Marshal.dump(options))
+      end
+
+      # The path name of a directory containing directive implementations
+      # 
+      # The pathname is normalized into an absolute path by the validation checking.
+      # 
+      attr_reader :dir_path
+
+      attr_reader :options
+
+      # Define an entry for a directive path with the path name of 
+      # a directory containing directive implementation classes to be loaded
+      # into the MasterView processing configuration.
+      #
+      # Optionally specify options for the directives loaded
+      # from this directory:
+      # 
+      #     :default - metadata defaults
+      # 
+      # Metadata defaults extend or override any defaults specified
+      # in the dir_path/.metadata file, if defined, allowing application
+      # customization of the default defaults.
+      # 
+      def initialize( dir_path, options=nil )
+        @dir_path = dir_path
+        @options = options.nil? ? {} : self.class.copy_options(options)
+      end
+
+      def inspect #:nodoc:
+        abbrev_class_name = self.class.name.split('::')
+        abbrev_class_name = abbrev_class_name[1..abbrev_class_name.size].join('::')
+        "#{abbrev_class_name}('#{dir_path}', options=#{options.inspect})"
+      end
+
+      # Answer a deep copy so we have a proper clone of the options.
+      def deep_copy()
+        Marshal.load(Marshal.dump(self))
+      end
+
+      # Answer whether the directory exists
+      def exists?
+        File.directory?(dir_path)
+      end
+
+      # The metadata defaults for this directory, if any
+      # 
+      # Metadata defaults specified on a load path entry supplement
+      # any .metadata options specified in the directory itself by
+      # overridding and extending any options defined statically in
+      # the directives directory.
+      # 
+      def metadata_defaults
+        options.fetch(:default, {})
+      end
+
+      # Answer whether directives loaded from this directory use the masterview
+      # namespace by default.
+      # 
+      # This option is ordinarily specified only for builtin masterview directives.
+      # 
+      def use_masterview_namespace #:nodoc:
+        options.fetch(:use_masterview_namespace, false)
+      end
+
+      # Answer whether directives loaded from this directory use the masterview
+      # extensions directive namespace by default.
+      # 
+      def use_extensions_namespace #:nodoc:
+        ! use_masterview_namespace
+      end
+
+      # Validate the directory path entry specification.
+      # 
+      # Ensures that the directory exists and that the entry specification
+      # is normalized to an absolute pathname.
+      def validate
+        if ! File.directory?(dir_path)
+            err_msg = "Invalid directive load path directory: '#{dir_path}'"
+            raise InvalidDirectivePathError.new(self, err_msg)
+        end
+        if @options.has_key?(:default)
+          md_defaults = @options[:default]
+          # raises ArgumentError if props are bad; has side effect of normalizing the prop values
+          DirectiveMetadata.validate_metadata_props! md_defaults
+        end
+      end
+
+      # ensure normalized representation with absolute pathnames and standard options
+      def normalize #:nodoc:
+        @dir_path = File.expand_path( @dir_path )
+        #assert ! (['/', '\\'].contains?dir_path[-1..-1])
+        #tbd: (recursively) ensure keys are symbolized?
+        @options[:default] = {} if ! @options.has_key?(:default)
+        #md_defaults entries were already normalized by side effects of the validation checker
+      end
+
+      # Load the metadata specifications for a directives directory
+      def load_metadata_specs(options={})
+
+        create_if_not_defined = options.fetch(:create_if_not_defined, true)
+
+        md_file_path = "#{dir_path}/#{METADATA_SPECS_FILE_NAME}"
+        dir_has_md_specs = File.file?( md_file_path )
+        if dir_has_md_specs
+          STDOUT.puts "\n###Loading directive metadata specs: #{md_file_path}" if DEBUG_MD_DIR_SPECS
+          md_config_specs = DirectiveLoadPath.load_metadata_specs(md_file_path)
+          md_config_specs[:default] ||= {}  # ensure that there are default specs
+          STDOUT.puts "...md_config_specs=#{md_config_specs.inspect}" if DEBUG_MD_DIR_SPECS
+        elsif create_if_not_defined
+          md_config_specs = { :default => {} }
+        else
+          return nil
+        end
+
+        md_defaults = md_config_specs[:default]
+        if ! md_defaults.has_key?( :description )
+          md_defaults[:description] = "MasterView directive from #{dir_path}"
+        end
+        # raises ArgumentError if props are bad; has side effect of normalizing the prop values
+        DirectiveMetadata.validate_metadata_props! md_defaults
+
+        md_config_specs
+
+      end
+
+    end
+
+    # A directive load Path is a list of PathEntry specifications
+    # for directories containing MasterView directive implementations.
+    # 
+    class Path
+    
+      include Enumerable
+    
+      def initialize() #:nodoc:  #??(entries=[])
+        @entries = []
+        #entries.each { | entry_spec | self << entry_spec }
+      end
+    
+      def [](index)
+        @entries[index]
+      end
+
+      def []=(index, entry)
+        raise ArgumentError, "Invalid entry for {self.class.name}: #{entry.inspect}" if ! entry.is_a?(PathEntry)
+        @entries[index] = entry
+      end
+
+      def <<(entry)
+        if entry.is_a?(String)
+          entry = PathEntry.new(entry)
+        elsif entry.is_a?(Array) && entry.size == 2 && entry[0].is_a?(String) && entry[1].is_a?(Hash)
+          # wow, we're working WAY too hard at this compatability stuff
+          entry = PathEntry.new(entry[0], entry[1])
+        else
+          raise ArgumentError, "Invalid entry for {self.class.name}: #{entry.inspect}" if ! entry.is_a?(PathEntry)
+        end
+        @entries << entry
+      end
+
+      def size
+        @entries.size
+      end
+
+      def empty?
+        @entries.empty?
+      end
+
+      # Calls the given block once for each entry specification on the path, 
+      # passing the element as parameter.
+      def each
+        @entries.each { |dpe| yield(dpe) }
+        self
+      end
+
+      # Calls the given block once for each entry specification on the path, 
+      # passing the element's index as parameter.
+      def each_index
+        @entries.each_index { |index| yield(index) }
+        self
+      end
+
+      def include?(dir_path)
+        dir_path = dir_path.is_a?( PathEntry ) ? dir_path.dir_path : File.expand_path(dir_path)
+        dpe = self.detect{ |dpe| dpe.dir_path == dir_path }
+        ! dpe.nil?
+      end
+
+      # Answer the directory paths
+      def directory_paths
+        dir_paths = []
+        self.each { |dpe| dir_paths << dpe.dir_path }
+        dir_paths
+      end
+
+      # Answer a copy of a directive load path
+      # 
+      # Does a deep_copy to ensure a clean copy of options maps
+      # 
+      def copy()
+        @entries.collect{ | dpe | dpe.deep_copy }
+      end
+
+    end
+
+    # Answer a clean path with a single entry for each directory
+    # and path entries validated and normalize.
+    # 
+    # Specify option :dup_policy ::= { :merge || :use_latest }
+    # for handling options on dup entries (merge or use the
+    # last-defined options).
+    # 
+    # Optionally provide a block arg for handling validation exceptions
+    # 
+    def self.clean_path(path, options)
+
+      dup_policy = options.fetch( :dup_policy, :use_latest )
+      
+      unique_paths = []
+      path_entries = {}
+      path.each { | dpe |
+        begin
+          dpe.validate()
+          dpe.normalize()
+          dir_path = dpe.dir_path
+          if ! unique_paths.include?(dir_path)
+            unique_paths << dir_path
+          else
+            # dup entry - we've already got this dir_path registered
+            if dup_policy == :merge
+              prev_options = path_entries[dir_path].options
+              options = prev_options.merge(dpe.options)
+            else # :use_latest
+              options = dpe.options  # last-registered path entry wins
+            end
+            # replace path entry with merged or replaced options
+            dpe = PathEntry.new(dir_path, options)
+          end
+          path_entries[dir_path] = dpe
+        rescue InvalidDirectivePathError => ex
+          if block_given?
+            yield(ex)
+          else
+            raise
+          end
+        end
+      }
+
+      clean_path = Path.new
+      unique_paths.each { | dir_path | 
+          clean_path << path_entries[dir_path]
+      }
+      clean_path
+
+    end
+
+    # Load a metadata specifications file.
+    # 
+    # Normalizes options hash keys to symbols.
+    # Should ordinarily be used through PathEntry.load_metadata_specs.
+    # 
+    def self.load_metadata_specs(file_path)
+      md_config_specs = YAML::load(IO.read(file_path))
+      #?what does yaml do with an empy file?? return {} if md_config_specs.nil?
+      #assert md_config_specs.is_a?(Hash)
+      symbolize_options_hash_keys(md_config_specs)
+      end
+
+    # do in-place symbolization of keys; recurse
+    def self.symbolize_options_hash_keys(data) #:nodoc:
+      #data.symbolize_keys!
+      original_keys = data.keys()
+      original_keys.each { | key |
+        value = data[key]
+        symbolizing_value = value.is_a?(Hash)
+        value = symbolize_options_hash_keys(value) if symbolizing_value
+        if ! key.is_a?(Symbol)
+          data[key.to_sym] = value
+          data.delete(key)
+        elsif symbolizing_value
+          data[key] = value
+        end
+      }
+      data
+    end
+
+    # Compute the metadata default specs for a directives directory
+    # Path entry options override/extend directory .metadata specs
+    def self.compute_md_defaults(default_md_specs, dir_md_defaults, path_entry_defaults)
+      md_defaults = {}
+      md_defaults.merge! default_md_specs  # we always start with the app-wide defaults
+      md_defaults.merge! dir_md_defaults   # bring in specs from the directory .metadata
+      md_defaults.merge! path_entry_defaults  # and allow app ovveride on path entry config
+      # raises ArgumentError if props are bad
+      # should be superfluous because we've already done this on each individual set of defaults
+      DirectiveMetadata.validate_metadata_props! md_defaults
+      md_defaults
+    end
+
+  end
+  
+end