masterview 0.2.5 → 0.3.0

data/lib/masterview/directive_metadata.rb

@@ -0,0 +1,377 @@
+module MasterView
+
+  # Mixin for directives to provide metadata specifications
+  # 
+  # All directives have a standard set of metadata properties:
+  #     :attribute_name - the (unqualified) directive attribute name
+  #     :namespace - the namespace name for the qualified directive name
+  #     :attribute_qname - the fully-qualified directive name (ns:attribute)
+  #     :priority - the DirectivePriority for processing
+  # 
+  # Additional properties can be set to provide documentation and usage 
+  # information (:summary, :description) or to record custom settings.
+  # 
+  #--
+  #TBD: How can we automatically extract directive rdoc from its class??
+  #++
+  # 
+  module DirectiveMetadata
+
+    DEBUG_MD_INSTALLATION = false  #:nodoc:
+    DEBUG_MD_PROPS = false #:nodoc:
+
+    # well-known metadata properties
+    MARKUP_PROPERTY_NAMES = [ :namespace, :namespace_prefix, :attribute_name, :attribute_qname ] #:nodoc:
+    PROCESSING_PROPERTY_NAMES = [ :priority ] #:nodoc:
+    DOC_PROPERTY_NAMES = [ :summary, :description ] #:nodoc:
+    STANDARD_PROPERTY_NAMES = MARKUP_PROPERTY_NAMES + PROCESSING_PROPERTY_NAMES + DOC_PROPERTY_NAMES  #:nodoc:
+    HARDENED_PROPERTY_NAMES = MARKUP_PROPERTY_NAMES + PROCESSING_PROPERTY_NAMES  #:nodoc:
+
+    # implementation hack for DirectiveMetadata class var
+    # putting class var @@metadata_values got muddled by subclassing, punt to this scheme
+    DirectiveMetadataRegistry = {} #:nodoc:
+
+    #convenience constants defined to allow priority to directives
+    #higher priority (lower value) will be executed first in chain
+    module DirectivePriorities
+      Highest = 0
+      UltraHigh = 0x3FFFFFFF/16
+      VeryHigh =   0x3FFFFFFF/8
+      High =   0x3FFFFFFF/4
+      MediumHigh = 0x3FFFFFFF/3
+      Medium = 0x3FFFFFFF/2
+      MediumLow = (0x3FFFFFFF/3)*2
+      Low =    (0x3FFFFFFF/4)*3
+      VeryLow = (0x3FFFFFFF/8)*7
+      UltraLow = (0x3FFFFFFF/16)*15
+      Lowest = 0x3FFFFFFF
+      # convenience
+      Default = Medium
+    end
+
+    PriorityNames = [] #:nodoc:
+    PrioritiesMap = {} #:nodoc:
+    DirectivePriorities.constants.each { | const_name |
+        level_name = const_name.to_s  #??? 
+        next if level_name == 'Default'  # only record real names
+        PriorityNames << level_name
+        PrioritiesMap[DirectivePriorities.const_get(const_name)] = level_name
+    }
+    # Answer the name of a priority level
+    def self.get_priority_name(priority) #:nodoc:
+      PrioritiesMap.fetch( priority, priority.to_s )  #?? "%08x" % priority
+    end
+
+    def self.get_priority_label(priority) #:nodoc:
+      name = get_priority_name(priority)
+      # 'default (Med)' was  nicer, but admin page doesn't format width properly
+      name = 'default' if priority == DirectivePriorities::Default
+      name
+    end
+
+    # Answer whether a name is a legal XML markup identifier.
+    # Used to validate attribute and namespace names for directives.
+    # 
+    def self.validate_xml_identifier(name)
+      #todo: add re defn to verify syntactically legal xml id
+      # XML 1.0 spec: A Name is a token beginning with a letter or one of a few
+      # punctuation characters, and continuing with letters, digits, hyphens, 
+      # underscores, colons, or full stops, together known as name characters.
+      #TODO: name =~ /^[a-zA-Z](\w|-|_)*$/
+      true
+    end
+
+    # Ensure that a set of metadata values are valid and consistent.
+    # This is a banger because it takes liberties normalizing the properties.
+    def self.validate_metadata_props!(md_props)
+
+      md_prop_name = :attribute_name
+      if md_props.has_key?( md_prop_name )
+        attr_name = md_props[md_prop_name]
+        raise ArgumentError, "Invalid #{md_prop_name.inspect} '#{attr_name}'" if ! DirectiveMetadata.validate_xml_identifier(attr_name)
+      end
+
+      # allow :namespace_name as a synonym for :namespace
+      md_prop_name = :namespace_name
+      if md_props.has_key?( md_prop_name )
+        ns_name = md_props[md_prop_name]
+        if md_props.has_key?(:namespace)
+          # we actually ought to just unconditionally complain, it's silly and redundant to do both of these
+          other_ns_name = md_props[:namespace]
+          raise ArgumentError, "Inconsistent namespace settigs (:namespace='#{other_ns_name}', :namespace_name='#{ns_name}')" if other_ns_name != ns_name
+        else
+          md_props[:namespace] = ns_name
+        end
+        # always get rid of :namespace_name, we just want to record :namespace
+        md_props.delete(md_prop_name)
+      end
+
+      md_prop_name = :namespace
+      if md_props.has_key?( md_prop_name )
+        ns_name = md_props[md_prop_name]
+        raise ArgumentError, "Invalid #{md_prop_name.inspect} '#{ns_name}'" if ns_name[-1..-1] == ':'
+        raise ArgumentError, "Invalid #{md_prop_name.inspect} '#{ns_name}'" if ! DirectiveMetadata.validate_xml_identifier(ns_name)
+        # ensure both namespace props we use are present and consistent
+        ns_prefix = "#{ns_name}:"
+        if md_props.has_key?( :namespace_prefix )
+          ns_prefix_prop = md_props[:namespace_prefix]
+          raise ArgumentError, "Inconsistent namespace settings (:namespace='#{ns_name}', :namespace_prefix='#{ns_prefix_prop}')" if ns_prefix_prop != ns_prefix
+        else
+          md_props[:namespace_prefix] = ns_prefix
+        end
+      end
+      
+      md_prop_name = :namespace_prefix
+      if md_props.has_key?( md_prop_name )
+        ns_prefix = md_props[md_prop_name]
+        raise ArgumentError, "Invalid #{md_prop_name.inspect} '#{ns_prefix}'" if ns_prefix[-1..-1] != ':'
+        ns_name = ns_prefix[0...-1]
+        raise ArgumentError, "Invalid #{md_prop_name.inspect} '#{ns_prefix}'" if ! DirectiveMetadata.validate_xml_identifier(ns_name)        
+        # ensure namespace settings are both present and consistent
+        if md_props.has_key?( :namespace )
+          ns_name_prop = md_props[:namespace]
+          raise ArgumentError, "Inconsistent namespace settings (:namespace='#{ns_name_prop}', :namespace_prefix='#{ns_prefix}')" if ns_name_prop != ns_name
+        else
+          md_props[:namespace] = ns_name
+        end
+      end
+
+      md_prop_name = :priority
+      if md_props.has_key?( md_prop_name )
+        priority = md_props[md_prop_name]
+        if priority.is_a?( String ) || priority.is_a?( Symbol )
+          begin
+            priority = 'Default' if [ 'default', :default ].include?(priority)  #synonyms
+            priority = DirectiveMetadata::DirectivePriorities.const_get(priority)
+            md_props[md_prop_name] = priority
+          rescue NameError
+            #invalid priority name - fall through to error code below
+          end
+        end
+        priority_range = (DirectiveMetadata::DirectivePriorities::Highest..DirectiveMetadata::DirectivePriorities::Lowest)
+        raise ArgumentError, "Invalid #{md_prop_name.inspect}: #{md_props[md_prop_name].inspect}" if ! (priority_range.include? priority)
+      end
+
+      if DEBUG_MD_PROPS
+        err_msg = "BAD DIRECTIVE MD PROPS: #{md_props.inspect}"
+        raise RuntimeError, err_msg if md_props.has_key?(:namespace_name)  # temp check on internal impl rework cutover
+        raise RuntimeError, err_msg if (md_props.has_key?(:namespace) && ! md_props.has_key?(:namespace_prefix))
+        raise RuntimeError, err_msg if (md_props.has_key?(:namespace_prefix) && ! md_props.has_key?(:namespace))
+        #??raise RuntimeError, err_msg if md_props.has_key?(:attribute_qname)???
+      end
+
+    end
+
+    module ClassMethods
+
+      # the metadata values for the directive class
+      def metadata_values #:nodoc:
+        return DirectiveMetadataRegistry[self.name] || {}
+      end
+      def self.extended(base)  #:nodoc: 
+        STDOUT.puts "...adding #{self} into #{base} (id=#{base.object_id})" if DEBUG_MD_INSTALLATION
+        #base.class_eval '@@metadata_values = {}'
+        #md_accessor_code = <<-END
+        #  def #{base}.metadata_values 
+        #      @@metadata_values ||= {}
+        #  end
+        #END
+        #base.class_eval md_accessor_code
+        DirectiveMetadataRegistry[base.name] = {}
+        STDOUT.puts "...#{base}.@@metadata_values=#{base.metadata_values.object_id}" if DEBUG_MD_INSTALLATION
+      end
+      def self.inherited(directive_class)  #:nodoc: 
+        STDOUT.puts "\n###inherited #{self} in #{directive_class} (id=#{directive_class.object_id})" if DEBUG_MD_INSTALLATION
+        #directive_class.class_eval '@@metadata_values = {}'
+        #md_accessor_code = <<-END
+        #  def #{directive_class}.metadata_values 
+        #      @@metadata_values ||= {}
+        #  end
+        #END
+        #directive_class.class_eval md_accessor_code
+        DirectiveMetadataRegistry[directive_class.name] = {}
+        STDOUT.puts "...#{directive_class}.@@metadata_values=#{directive_class.metadata_values.object_id}" if DEBUG_MD_INSTALLATION
+      end
+
+      # Answer the (unqualified) attribute name of the directive
+      def attribute_name
+        metadata_values[:attribute_name] || default_directive_name
+      end
+
+      def namespace
+        metadata_values[:namespace] || default_namespace_prefix[0...-1]
+      end
+
+      ##ISSUE: deprecate this??
+      def namespace_name
+        namespace
+      end
+
+      def namespace_prefix
+        metadata_values[:namespace_prefix] || default_namespace_prefix
+      end
+
+      # Answer the fully-qualified attribute name of the directive
+      def attribute_qname
+        metadata_values[:attribute_qname] || "#{namespace}:#{attribute_name}"
+      end
+
+      def priority
+        metadata_values[:priority] || DirectivePriorities::Default
+      end
+
+      # Answer the default directive attribute name for a directive class.
+      # 
+      # If not explicitly specified, lowercased name of the class is
+      # assumed to be the attribute name used in template markup.
+      #
+      def default_directive_name #:nodoc:
+        simple_name = self.name.split(':').last # strip off module qualifiers
+        simple_name = simple_name.downcase_first_letter
+        # convert camel-case class name FooBar to snake-case foo_bar
+        simple_name.gsub( /[A-Z]/ ) { |letter| "_#{letter.downcase}" }
+      end
+
+      # Answer the default namespace prefix for a directive class.
+      # 
+      def default_namespace_prefix #:nodoc:
+        # this is a bit squirrelly to rely on module namespace convention
+        # masterview brings in String#starts_with? from facets, thank you
+        if self.name.starts_with?('MasterView::Directives::')
+          MasterView::ConfigSettings.namespace_prefix
+        else
+          MasterView::ConfigSettings.namespace_prefix_extensions
+        end
+      end
+
+      # Declare metadata properties of the directive
+      # Specify one more prop_name => value entries
+      # :attibute_name, :namespace, :summary, :description
+      def metadata(md_props)
+        md_props = md_props.clone
+        DirectiveMetadata.validate_metadata_props!(md_props)
+        if ! DirectiveMetadataRegistry.has_key?( self.name )
+          DirectiveMetadataRegistry[self.name] = {}
+          STDOUT.puts "...#{self}.@@metadata_values=#{self.metadata_values.object_id} <metadata decl>" if DEBUG_MD_INSTALLATION
+        else 
+          # ISSUE: not clear why we need to do this, but something's getting initialized
+          # by initial class load/include/extend magic that I can't figure out.
+          # This probably is safe, there should be exactly one metadata decl in
+          # a directive implementation and it should probably always have a clean
+          # point of view.
+          # [DJL 06-Oct-2006]
+          DirectiveMetadataRegistry[self.name].clear()
+        end
+        metadata_values.merge! md_props
+      end
+
+      # Fill in any defaults and ensure that all required metadata properties are defined.
+      # 
+      # Ordinarily done exactly once by the directive loading mechanisms.
+      # 
+      def harden_metadata(defaults={})
+        trace_enabled = DEBUG_MD_PROPS || DEBUG_MD_INSTALLATION
+        if ! DirectiveMetadataRegistry.has_key?( self.name )
+          DirectiveMetadataRegistry[self.name] = {}
+          STDOUT.puts "...#{self}.@@metadata_values=#{self.metadata_values.inspect} (id=#{self.metadata_values.object_id}) <harden_metadata>" if trace_enabled
+          STDOUT.puts "...DirectiveMetadataRegistry=#{DirectiveMetadataRegistry.inspect}" if trace_enabled
+        end
+        dc_md = metadata_values
+        STDOUT.puts "\n****HARDENING: #{self}.metadata_values=#{dc_md.inspect} (id=#{dc_md.object_id})" if trace_enabled
+        # install any defaults for properties which aren't explicitly set
+        md_to_add = defaults.reject { |key, value| dc_md.has_key?( key ) }
+        #assert ! md_to_add.equal?(defaults), 'safe to mess with our own copy now'
+        DirectiveMetadata.validate_metadata_props!( md_to_add )  # this should check and normalize any namespace-related entries
+        raise RuntimeError, "BAD: attr naming inappropriate in md defaults #{md_to_add.inspect}" if md_to_add.has_key?(:attribute_name) || md_to_add.has_key?(:attribute_qname)
+        # ensure that required properties are set
+        if ! dc_md.has_key?( :attribute_name )
+          md_to_add[:attribute_name] = default_directive_name
+        end
+        if ! dc_md.has_key?( :priority )
+          md_to_add[:priority] = DirectivePriorities::Default
+        end
+        if ! dc_md.has_key?( :namespace )
+          raise RuntimeError, "BUG: inconsistent #{self.name}.metadata_values ns entries: #{dc_md.inspect}" if dc_md.has_key?(:namespace_prefix) || dc_md.has_key?(:attribute_qname)
+          if md_to_add.has_key?( :namespace )
+            #ok, we'll fill in namespace from defaults
+            # quadruple-check programming errors in this mess until this stuff stabilizes [DJL 06-Oct-2006]
+            raise RuntimeError, 'BUG: validate_metadata_props! did not handle defaults normalization: #{md_to_add.inspect}' if ! md_to_add.has_key?(:namespace_prefix)
+          elsif md_to_add.has_key?( :namespace_prefix )
+            # quadruple-check programming errors in this mess until this stuff stabilizes [DJL 06-Oct-2006]
+            raise RuntimeError, 'BUG: validate_metadata_props! did not handle defaults normalization: #{md_to_add.inspect}'
+          else
+            default_prefix = default_namespace_prefix
+            md_to_add[:namespace] = default_prefix[0...-1]
+            md_to_add[:namespace_prefix] = default_prefix
+          end
+        end
+        if ! dc_md.has_key?( :namespace_prefix )
+          # we should have just taken care of this
+          raise RuntimeError, "BUG: inconsistent #{self.name}.metadata_values ns entries: #{dc_md.inspect}" if dc_md.has_key?(:namespace) || dc_md.has_key?(:attribute_qname)
+          raise RuntimeError, "BUG: incorrect construction of #{self.name} md_to_add: #{md_to_add}" if ! (md_to_add.has_key?(:namespace) && md_to_add.has_key?(:namespace_prefix))
+        end
+        dc_md.merge! md_to_add
+        #assert dc_md.has_key?( :namespace) && dc_md.has_key?( :namespace_prefix)
+        if true  # ! dc_md.has_key?( :attribute_qname )
+          # just always do this, there's something funky about load/include/extend
+          # somehow we're getting backstop defaults in ahead of even the first class load
+          # I do not understand something subtle, so giving up and just hammering here [DJL 06-Oct-2006]
+          dc_md[:attribute_qname] = "#{dc_md[:namespace]}:#{dc_md[:attribute_name]}"
+        end
+        #???dc_md[:hardened] = true???
+        #??dc_md.freeze
+        if DEBUG_MD_PROPS
+          # quadruple-check programming errors in this mess until this stuff stabilizes [DJL 06-Oct-2006]
+          oops = false
+          HARDENED_PROPERTY_NAMES.each { |md_prop_name| oops = true if ! metadata_values.has_key?(md_prop_name) }
+          if oops
+            raise RuntimeError, "BAD MD HARDENING IN #{self.name}: #{metadata_values.inspect}"
+          end
+          if metadata_values[:namespace_prefix] != "#{metadata_values[:namespace]}:"
+            raise RuntimeError, "BAD MD HARDENING IN #{self.name}: #{metadata_values.inspect}"
+          end
+          if metadata_values[:attribute_qname] != "#{metadata_values[:namespace]}:#{metadata_values[:attribute_name]}"
+            raise RuntimeError, "BAD MD HARDENING IN #{self.name}: #{metadata_values.inspect}"
+          end
+        end
+        STDOUT.puts "...HARDENED MD: #{self.metadata_values.inspect}\n" if DEBUG_MD_PROPS
+      end
+
+    end #ClassMethods
+
+    # add class methods for DSL declarations to class which is mixing in DirectiveMetadata
+    def self.included(base)  #:nodoc:
+      STDOUT.puts "\n####Mixing #{self} into #{base} (id=#{base.object_id})" if DEBUG_MD_INSTALLATION
+      base.extend(ClassMethods)
+    end
+
+    # Answer the (unqualified) attribute name used in template document markup 
+    # for this directive.
+    def attribute_name
+      self.class.attribute_name
+    end
+
+    def namespace
+      self.class.namespace
+    end
+
+    def namespace_name
+      self.class.namespace_name
+    end
+
+    def namespace_prefix
+      self.class.namespace_prefix
+    end
+
+    # Answer the fully-qualified attribute name of the directive
+    def attribute_qname
+      self.class.attribute_qname
+    end
+
+    def priority
+      return self.class.priority
+    end
+
+  end
+
+end