masterview 0.2.5 → 0.3.0

data/lib/masterview/directive_dsl.rb

@@ -0,0 +1,457 @@
+=begin
+
+Directive DSL
+
+class MyDirective < DirectiveBase
+  attr_arg :obj, :quote => true
+  attr_arg :method { 'override' }
+  attr_arg :foo { |x| x.downcase }
+  attr_arg :collection, :quote => true
+  attr_arg :value_method, :quote => true
+  attr_arg :text_method, :quote => true
+  attr_arg :options, :default => {}
+  attr_arg :html_options, :append_element_attrs => [:common_html, :size]
+  attr_arg :name do |value, args|
+    if value.respond_to?(:include?) and value.include?('=>')
+      args.unshift value
+      nil
+    else
+      value
+    end
+  end
+  attr_arg :params, :varargs => true #collect remaining args (if any) put in array, like *params
+
+  event :before_stag do
+    render erb_content( 'text_area', :obj, :method, :foo )
+  end
+
+  event :content, :render => :nothing #rolls up all content between after_stag and before_etag
+
+  also can be done
+
+  event :content do
+    render :nothing # causes nothing to be rendered
+  end
+
+  event :stag do
+    # unless render something or render :nothing is called, then dcs.render will still occur implicitely
+  end
+
+  event :etag do
+    con = render_result() # get the dcs.render result so we can modify it
+    con.gsub!( /foo/, 'bar' )
+    render con
+  end
+
+  event :element do # this will allow replacement of entire element and children
+    render erb_eval( 'execute something' )
+  end
+end
+
+event listing
+----------------
+before_stag
+stag
+after_stag
+content
+before_etag
+etag
+after_etag
+element
+
+these might not be exposed as events but still using direct methods
+characters
+comment
+
+
+=end
+
+module MasterView
+
+  # The DirectiveProcessing module contains the internal mechanisms
+  # which support the DirectiveDSL notation for attribute argument definition
+  # and document processing event processing definition in directive 
+  # implementation classes.
+  module DirectiveProcessing
+
+  # holds the attr_arg definition, how a positional subargument will be
+  # parsed out of the directive attr_value
+  class AttrArgDef
+    attr_reader :name, :options, :proc
+    def initialize(name, options, proc)
+      @name = name
+      @options = options
+      @proc = proc
+    end
+
+    # returns the optional default if one was specified
+    def optional_default
+      (@options.nil?) ? nil : @options[:default]
+    end
+  end
+
+  # holds the event definition which contains the meat of what will happen
+  # for each parser event. The events are more finely grained than the rexml
+  # listener events.
+  class EventDef
+    BaseEventMapping = {
+      /^(before_|after_)?(child_.*|descendant_.*)?stag$/ => ['\2stag'],
+      /^(before_|after_)?(child_.*|descendant_.*)?etag$/ => ['\2etag'],
+      /^(child_.*|descendant_.*)?content$/ => ['\1etag'],
+      /^(child_.*|descendant_.*)?element$/ => ['\1stag', '\1etag']
+    }
+
+    # true if is valid event name
+    def self.valid_event_mapping?(event_name_sym)
+      event_name_str = event_name_sym.to_s
+      BaseEventMapping.keys.any? { |x| x =~ event_name_str }
+    end
+
+    # returns base method sym array for event_name_sym
+    #  :before_stag => :stag,
+    #  :stag => :stag,
+    #  :after_stag => :stag,
+    #  :content => :etag,
+    #  :before_etag => :etag,
+    #  :etag => :etag,
+    #  :after_etag => :etag,
+    #  :element => :stag, :etag
+    def self.base_methods_from_event(event_name_sym)
+      event_name_str = event_name_sym.to_s
+      base_pair = BaseEventMapping.find {|k,v| k =~ event_name_str }
+      base_name_unsub_array = base_pair[1]
+      base_name_unsub_array.collect { |x| event_name_str.sub(base_pair[0], x).to_sym }
+    end
+
+    # return array of events to check for the base
+    #  :stag => [:before_stag, :stag, :after_stag],
+    #  :etag => [:content, :before_etag, :etag, :after_etag, :element]
+    def self.method_events_from_base(base_sym)
+      base_str = base_sym.to_s
+      if match = base_str.match( /(.*)stag/ )
+        [
+          ('before_'+base_str).to_sym,
+          base_sym,
+          ('after_'+base_str).to_sym
+        ]
+      elsif match = base_str.match( /(.*)etag/ )
+        [
+          (match[1]+'content').to_sym,
+          ('before_'+base_str).to_sym,
+          base_sym,
+          ('after_'+base_str).to_sym,
+          (match[1]+'element').to_sym
+        ]
+      end
+    end
+
+    attr_reader :name, :options, :proc
+
+    def initialize(name, options, proc)
+      raise "Invalid event name=#{name}" unless self.class.valid_event_mapping?(name)
+      @name = name
+      @options = options
+      @proc = proc
+    end
+
+    # execute proc/block in the context of an instance object (instance_eval)
+    def exec(instance_obj)
+      instance_obj.instance_eval &proc unless proc.nil?
+    end
+  end
+
+  class DirectiveClassDef
+    attr_reader :attr_arg_defs, :event_defs
+    def initialize
+      @attr_arg_defs = [] #list in order of position
+      @attr_arg_def_map = {} #map to def from symname
+      @event_defs = {}
+    end
+
+    def add_attr_arg_def(attr_arg_def)
+      if @attr_arg_def_map[attr_arg_def.name].nil? # prevent multiple calls to this, rake calling multiple times?
+        @attr_arg_def_map[attr_arg_def.name] = attr_arg_def
+        @attr_arg_defs.push attr_arg_def
+      end
+    end
+
+    def set_event_def(event_def)
+      @event_defs[event_def.name] = event_def
+    end
+
+    def find_attr_arg_def_by_name(name)
+      @attr_arg_def_map[name]
+    end
+  end
+
+  class RenderAccumulator
+    attr_accessor :render_call_found
+    attr_writer :render_result, :render_result_block
+    def initialize
+      @method_level_accumulator = []
+      reset_event_level_vars
+    end
+
+    def reset_event_level_vars
+      reset_event_level_content_array
+      @render_call_found = false
+      @render_result = nil
+      @render_result_block = nil
+    end
+
+    def reset_event_level_content_array
+      @event_level_accumulator = []
+    end
+
+    def reset_event_level_content_array_render_nothing
+      reset_event_level_content_array
+      @render_call_found = true # we don't want to render anything
+    end
+
+    def method_level_content_array
+      @method_level_accumulator
+    end
+
+    def event_level_content_array
+      @event_level_accumulator
+    end
+
+    def add_event_content_to_method_content
+      @method_level_accumulator.concat @event_level_accumulator
+      @event_level_accumulator = []
+    end
+
+    def replace_all_method_content_with_event_content
+      @method_level_accumulator =  @event_level_accumulator
+      @event_level_accumulator = []
+    end
+
+    def call_render_result_block
+      result = nil
+      unless @render_result_block.nil?
+        result = @render_result_block.call
+        @render_result_block = nil #only allow this call once
+      end
+      result
+    end
+
+    def add_to_event_content(value)
+      @render_call_found = true
+      @event_level_accumulator.push(value)
+    end
+
+  end
+
+  end
+
+  # Mixin for directive implementation classes to support the DSL for
+  # attr_arg attribute value argument parsing and event handler
+  # registration for document template event processing.
+  #
+  # Relies on the mixing class to provide accessor services to
+  # element processing context information (element_attrs, element_tag)
+  # and the attr_value directive attribute value string,
+  # along with erb output services (erb_content, erb_eval).
+  # Assumes DirectiveHelpers also mixed in.
+  #
+  module DirectiveDSL
+
+    module ClassMethods
+      # retrieve my class specific DirectiveClassDef, creating if necessary
+      def directive_class_def
+        @@directive_class_defs ||= {}
+        @@directive_class_defs[object_id] ||= DirectiveProcessing::DirectiveClassDef.new
+      end
+
+      # add a postional subargument parsing def which will be applied to attr_value
+      def attr_arg(name, options={}, &block)
+        self.directive_class_def.add_attr_arg_def(DirectiveProcessing::AttrArgDef.new(name, options, block))
+      end
+
+      # set the definition for an event which will be invoked at appropriate time in
+      # directive rendering lifecycle, also create the base method if it does not
+      # already exist.
+      def event(name, options={}, &block)
+        directive_class_def = self.directive_class_def
+        directive_class_def.set_event_def(DirectiveProcessing::EventDef.new(name, options, block))
+        base_event_name_sym_array = DirectiveProcessing::EventDef.base_methods_from_event(name)
+        base_event_name_sym_array.each do |base_event_name_sym|
+          base_event_name = base_event_name_sym.to_s
+          directive_class_def.set_event_def(DirectiveProcessing::EventDef.new(base_event_name_sym,{},nil)) if directive_class_def.event_defs[base_event_name_sym].nil?
+          event_mapping = DirectiveProcessing::EventDef.method_events_from_base(base_event_name_sym)
+          unless self.class.respond_to?( base_event_name_sym ) or event_mapping.nil? # unless already defined method or no mapping
+            event_eval_code = <<-END
+              def #{base_event_name}(dcs)
+                @method_content_ref ||= {} # create references to content created by method
+                prepare_arg_instance_vars
+                @render_accumulator = DirectiveProcessing::RenderAccumulator.new
+                #{event_mapping.inspect}.each do |full_event_name|
+                  event_def = self.class.directive_class_def.event_defs[full_event_name]
+                  unless event_def.nil?
+                    prepare(event_def)
+                    event_def.exec(self)
+                    handle_render(event_def)
+                  end
+                end
+                @method_content_ref[:#{base_event_name}] = @render_accumulator.method_level_content_array # add reference
+                @method_content_ref[:#{base_event_name}] # return the reference so we can empty later if necessary
+              end
+            END
+            self.class_eval event_eval_code # todo could pass in filename, but would have to use self.to_s.downcase and trim off leading modules
+          end
+        end
+      end
+    end
+
+    # add class methods for DSL declarations to class which is mixing in DirectiveDSL
+    def self.included(mixing_class)  #:nodoc:
+      mixing_class.extend(ClassMethods)
+    end
+
+    def prepare_arg_instance_vars
+      attr_arg_defs = self.class.directive_class_def.attr_arg_defs
+      unless attr_arg_defs.empty? # if we have any attr_arg_defs, prepare the parsed instance vars for these args
+        args = parse(self.attr_value)
+        attr_arg_defs.each do |attr_arg_def|
+          eval_attr_arg(args, attr_arg_def)
+        end
+      end
+    end
+
+    def prepare(event_def)
+      @render_accumulator.reset_event_level_vars
+      case event_def.name.to_s
+        when /^before_(.*_)?stag$/
+        when /^after_(.*_)?stag$/
+        when /^(.*_)?stag$/
+          @render_accumulator.render_result_block = lambda { @render_accumulator.render_result = @directive_call_stack.render }
+        when /^(.*_)?content$/
+          @render_accumulator.render_result_block = lambda { @directive_call_stack.context[:tag].content.join }
+        when /^before_(.*_)?etag$/
+        when /^after_(.*_)?etag$/
+        when /^(.*_)?etag$/
+          @render_accumulator.render_result_block = lambda { @render_accumulator.render_result = @directive_call_stack.render }
+        when /^(.*_)?element$/
+          @render_accumulator.render_result_block = lambda { (
+                                                       @method_content_ref[event_def.name.to_s.sub(/^(.*_)?element$/, '\1stag').to_sym] + # fine proper stag content ref
+                                                       @directive_call_stack.context[:tag].content +
+                                                       @render_accumulator.event_level_content_array).join }
+      end
+    end
+
+    def render_result
+      @render_accumulator.call_render_result_block
+    end
+
+    def render(value)
+      if value == :nothing
+        @render_accumulator.reset_event_level_content_array_render_nothing
+      else
+        @render_accumulator.add_to_event_content(value)
+      end
+    end
+
+    def handle_render(event_def)
+      return if event_def.options[:render] == :nothing and (event_def.name != :content and event_def.name != :element)
+      case event_def.name.to_s
+        when /^before_(.*_)?stag$/
+          @render_accumulator.add_event_content_to_method_content
+        when /^after_(.*_)?stag$/
+          @render_accumulator.add_event_content_to_method_content
+        when /^(.*_)?stag$/
+          render(render_result) unless @render_accumulator.render_call_found # call default dcs.render if render call not made
+          @render_accumulator.add_event_content_to_method_content
+        when /^(.*_)?content$/
+          if event_def.options[:render] == :nothing
+            @directive_call_stack.context[:tag].content = nil
+          else
+            @directive_call_stack.context[:tag].content = @render_accumulator.event_level_content_array
+          end
+        when /^before_(.*_)?etag$/
+          @render_accumulator.add_event_content_to_method_content
+        when /^after_(.*_)?etag$/
+          @render_accumulator.add_event_content_to_method_content
+        when /^(.*_)?etag$/
+          render(render_result) unless @render_accumulator.render_call_found # call default dcs.render if render call not made
+          @render_accumulator.add_event_content_to_method_content
+        when /^(.*_)?element$/  # we need to affect only things on and below our callstack so surrounging directives will render (like if)
+          @method_content_ref[event_def.name.to_s.sub(/^(.*_)?element$/, '\1stag').to_sym].clear # we will zero the stag reference which will clear it from the output
+          @directive_call_stack.context[:tag].content = nil
+          @render_accumulator.reset_event_level_content_array if event_def.options[:render] == :nothing # zero content if render :nothing
+          @render_accumulator.replace_all_method_content_with_event_content # replace everything with event content
+      end
+    end
+
+    # convert symbol name to instance var name, it appends a @ if not
+    # already starting with it. Handles strings or symbols.
+    # returns symbol of complete name :@name
+    def name_to_instance_var_name(name)
+      str_name = name.to_s
+      str_name = '@'+str_name unless str_name[0] == '@'
+      str_name.to_sym
+    end
+
+    # evaluate the attr_arg using the current attr_value, attributes, etc.
+    # This is the method that takes the definition, determines the instance value
+    # and stores it.
+    def eval_attr_arg(args, attr_arg_def)
+      name = attr_arg_def.name
+      options = attr_arg_def.options
+      proc = attr_arg_def.proc
+      instance_var_name = name_to_instance_var_name(name)
+      if(options and options[:varargs])
+        value = args.clone # value set to array of all remaining args
+        args.clear
+      else
+        value = args.shift
+        if options
+          value = quote_if(value) if options[:quote]
+          if merge_array = options[:append_element_attrs]
+            merge_array = [merge_array] unless merge_array.is_a? Array
+            merge_opts = {}
+            merge_array.each do |merge_item|
+              if merge_item == :common_html
+                merge_opts.merge! common_html_options
+              else
+                merge_item_sym = merge_item.to_sym
+                if (v = element_attrs[merge_item_sym]) : merge_opts[merge_item_sym] = v; end
+              end
+            end
+            value = merge_hash_into_str(merge_opts, value)
+          end
+        end
+      end
+      unless proc.nil?
+        if proc.arity < 1 # simply set value to block's return
+          value = proc.call
+        elsif proc.arity == 1 # |x| - pass value into block to allow it to manipulate
+          value = proc.call(value)
+        elsif proc.arity == 2 # |value, args| - pass value and remaining args array
+          value = proc.call(value, args)
+        elsif proc.arity == 3 # |value, args, instance| - pass value, remaining args, and directive instance
+          value = proc.call(value, args, self)
+        end
+      end
+      self.instance_variable_set(instance_var_name, value) # set @foo = value
+    end
+
+    # safely checks for existence of instance variable without throwing NameError
+    # true if instance_variable exists
+    def instance_variable_exists?(instance_variable_name)
+      self.instance_variables.include?(instance_variable_name.to_s)
+    end
+
+    #inside characters, cdata, or comment you can call this to get the characters passed
+    def data
+      @directive_call_stack.context[:content_part]
+    end
+
+    #set the data that will be passed to characters, cdata, or comment directives
+    def data=(data)
+      @directive_call_stack.context[:content_part]=data
+    end
+
+
+  end
+
+end

data/lib/masterview/directive_helpers.rb

@@ -1,9 +1,9 @@
 module MasterView
 
   # Mixin services for directive implementation classes.
-  # 
+  #
   # Subclasses of MasterView::DirectiveBase inherit this mixin.
-  # 
+  #
   module DirectiveHelpers
 
     CRLF = "\r\n"
@@ -18,27 +18,6 @@ module MasterView
     # end of ERB whose evaluation results in content in the document
     ERB_CONTENT_END = ' %>'
 
-    ####OBSOLETE: SWEEP AND REMOVE
-    ERB_START = ERB_EVAL_START #:nodoc:  #WAS: '<% '
-    ERB_EVAL = ERB_CONTENT_START #:nodoc: #WAS: '<%= '
-    ERB_END = ERB_CONTENT_END #:nodoc:  #WAS: ' %>'
-
-    #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 
-    end
-
     # convert render_partial_name to file_name, ex foo/bar to foo/_bar.rhtml
     def render_partial_name_to_file_name(render_partial_name, default_extension)
       pathname = Pathname.for_path(render_partial_name)
@@ -49,22 +28,32 @@ module MasterView
       path = (dir_pathname+filename).to_s
     end
 
-    
-    # find the last string that fully matches exactly the 
+
+    # find the last string that fully matches exactly the
     # parent tags content string array
-    # It looks for something that has been output as a unit in 
+    # It looks for something that has been output as a unit in
     # the array not a substring
-    # returns the ref to the string which you can operate on 
+    # returns the ref to the string which you can operate on
     # using replace
     def find_last_in_parent(tag, full_string)
       ret = nil
       parent = tag.parent
       unless parent.nil?
         parent.content.reverse.each do |str|
-          if str == full_string
-            ret = str
-            break
-          end
+            if str.kind_of? Array # if it is a nested array check inside of it
+                str.reverse.each do |s|
+                    if s == full_string
+                        ret = s
+                        break
+                    end
+                end
+                break if ret
+            else
+                if str == full_string
+                    ret = str
+                    break
+                end
+            end
         end
       end
       ret
@@ -89,124 +78,22 @@ module MasterView
       m[1]
     end
 
-    #returns an array of args by parsing and evaling the str value passed in
-    #uses evaling, so can't have any variables only simple strings, numbers, booleans
-    def parse_eval_into_array(value)
-      return [] if value.nil? || value.empty?
-      val = value.strip
-      args = []
-      until val.empty?
-        if val =~ /^[:'"%\[{&*]/ #starts with quote or ruby lang char
-          v = nil
-          val = '{'+val+'}' if val =~ /^:/ #starts with colon, assume hash so wrap with brackets
-          eval 'v = '+ val #rest is all evaled
-          if v.is_a? Array
-            args += v
-          else 
-            args << v
-          end
-          break
-        else
-          unquoted_string = val.slice!( /^[^,]+/ ) #pull off everything up to a comma
-          unquoted_string.strip!
-          args.push unquoted_string
-          val.slice!( /^,/ ) #strip off comma if exists
-          val.strip!
-        end
-      end
-      args
-    end
-
-    #returns a hash, for values that are not already part of hash it adds them using default_key
-    #uses evaling so it cannot have any variables or non-simple types
-    def parse_eval_into_hash(value, default_key)
-      h = {}
-      a = parse_eval_into_array(value)
-      a.each do |v|
-        if v.is_a?(Hash)
-          h.merge!(v)
-        else #it adds any additional non-hash args using default key, if key,val exists, it changes to array and appends
-          prev = h[default_key]
-          if prev.nil? #nil just add it
-            h[default_key] = v
-          elsif prev.is_a?(Array) #was array, concat
-            h[default_key] = prev+v
-          else #anything else, make it into array
-            h[default_key] = [prev, v]
-          end
-        end
-      end
-      h
-    end
-
     #parse into array of strings, containing the various arguments without evaling
     #looks for %q{}, %q[], hash, array, function call using (), values deliminated by commas,
     def parse(str)
       AttrStringParser.parse(str)
     end
 
-
-    #remove any strings that were prepended to the hashes, typically these are overridden by other values, so 
-    # we need to strip them off leaving only the hashes, returns a string with only hashes
-    def remove_prepended_strings(full_string)
-      return full_string if full_string.nil? || full_string.strip.empty?
-      hashes = full_string.scan( /(\{?)\s*(\S+\s*=>.*)/ ).flatten
-      hashes.join.strip
-    end
-
-    #merge hash_to_merge values into the hash contained in the full_string, hash_arg is zero based index of which
-    #hash this needes to be merged to if there are multiple ones.
-    def merge_into_embedded_hash(full_string, hash_arg, hash_to_merge)
-      return full_string if hash_to_merge.empty? 
-      full_string ||= ""
-      sorted_hash_to_merge = hash_to_merge.sort { |a,b| a.to_s <=> b.to_s } #sort, remember the keys might be symbols so use to_s
-      str_to_merge = sorted_hash_to_merge.collect{ |h,v| "#{h.inspect} => #{v.inspect}" }.join(', ')
-
-      hashes = full_string.scan( /(\{?[^{}]+=>[^{}]+\}?)\s*,?\s*/ ).flatten
-      hash_str = hashes[hash_arg] #be careful to use methods to update string in place or else put back in hash
-
-      if hash_str.nil? 
-        hashes.each do |v| #make sure each prior hash has brackets, since we are adding a hash
-          unless v.index '}'
-            v.insert(0, '{')
-            v.insert(-1, '}')
-          end
-        end
-        hashes[hash_arg] = hash_str = ""
-      end
-
-      closing_brack = hash_str.index '}'
-      if closing_brack
-        hash_str.insert(closing_brack, ', '+str_to_merge)
-      else
-        hash_str << ', ' unless hash_str.empty?
-        hash_str << str_to_merge
-      end
-      
-      hashes.join(', ')
-    end
-
-    #return attributes with lowercase keys
-    def lowercase_attribute_keys(attributes)
-      lcattrs = {}
-      attributes.each { |k,v| lcattrs[k.downcase] = v }
-      lcattrs
-    end
-
-    #return attributes with lowercase keys and values
-    def lowercase_attribute_keys_and_values(attributes)
-      lcattrs = {}
-      attributes.each { |k,v| lcattrs[k.downcase] = v.downcase }
-      lcattrs
+    #add single quotes around string
+    def quote(str, quote_char='\'')
+      quote_char+str+quote_char
     end
 
-    # using hash, symbolize keys, sort keys, serialize to string
-    def symbolize_sort_and_serialize_hash_to_str(hash)
-      symbolized = {}
-      hash.each{ |k,v| symbolized[k.to_sym] = v } #symbolize
-      sorted = symbolized.sort{ |a,b| a[0].to_s <=> b[0].to_s } # sort the keys
-      sorted_strings = sorted.collect{ |k,v| "#{k.inspect} => '#{v}'"} # create strings
-      sorted_strings.join(', ') # finally combine them
+    # adds single quotes around string if it is a simple
+    # word [a-zA-Z0-9_]* otherwise return existing string
+    # also quote if empty string
+    def quote_if(str)
+      (str =~ /^\w*$/) ? quote(str) : str
     end
 
   end