tap 0.7.9 → 0.8.0

data/lib/tap/support/tdoc/config_attr.rb

@@ -0,0 +1,338 @@
+# RDoc creates a namespace conflict with IRB within 'rdoc/parsers/parse_rb'
+# In that file, RubyToken and RubyLex get defined in the Object namespace,
+# which will conflict with prior definitions from, for instance, IRB.  
+#
+# This code redefines the RDoc RubyToken and RubyLex within the RDoc 
+# namespace.  RDoc is not affected because all includes and uses of 
+# RubyToken and RubyLex are set when RDoc is loaded.  The single exception
+# I know of are several calls to class methods of RubyLex (ex RubyLex.debug?).
+# These calls will be routed to the existing RubyLex.
+#
+# Uses of the existing RubyToken and RubyLex (as by irb) should be 
+# unaffected as the constants are reset after RDoc loads.
+#
+if Object.const_defined?(:RubyToken) || Object.const_defined?(:RubyLex)
+  class Object # :nodoc:
+    old_ruby_token = const_defined?(:RubyToken) ? remove_const(:RubyToken) : nil
+    old_ruby_lex = const_defined?(:RubyLex) ? remove_const(:RubyLex) : nil
+  
+    require 'rdoc/rdoc'
+
+    # if by chance rdoc has ALREADY been loaded then requiring
+    # rdoc will not reset RubyToken and RubyLex... in this case
+    # the old constants are what you want.
+    new_ruby_token = const_defined?(:RubyToken) ? remove_const(:RubyToken) : old_ruby_token
+    new_ruby_lex = const_defined?(:RubyLex) ? remove_const(:RubyLex) : old_ruby_lex
+    
+    RDoc.const_set(:RubyToken, new_ruby_token)
+    RDoc.const_set(:RubyLex, new_ruby_lex)
+  
+    const_set(:RubyToken, old_ruby_token) unless old_ruby_token == nil
+    const_set(:RubyLex, old_ruby_lex) unless old_ruby_lex == nil
+  end
+else
+  require 'rdoc/rdoc'
+
+  if Object.const_defined?(:RubyToken) && !RDoc.const_defined?(:RubyToken)
+    class Object # :nodoc:
+      RDoc.const_set(:RubyToken, remove_const(:RubyToken))
+    end
+  end 
+  
+  if Object.const_defined?(:RubyLex) && !RDoc.const_defined?(:RubyLex)
+    class Object # :nodoc:
+      RDoc.const_set(:RubyLex, remove_const(:RubyLex))
+      RDoc::RubyLex.const_set(:RubyLex, RDoc::RubyLex)
+    end
+  end
+end
+
+module Tap
+  module Support
+    class TDoc
+    
+      # Encasulates information about the configuration.  Designed to be utilized
+      # by the TDocHTMLGenerator as similarly as possible to standard attributes.
+      class ConfigAttr < RDoc::Attr
+        # Contains the actual declaration for the config attribute. ex:  "c [:key, 'value']      # comment"
+        attr_accessor :config_declaration
+        
+        alias original_comment comment
+        
+        def desc
+          case text.to_s 
+          when /^#--(.*)/ then $1.strip
+          when /^#(.*)/ then $1.strip
+          else
+            nil
+          end
+        end
+        
+        # The description for the config.  Comment is formed from the standard 
+        # attribute comment and the text following the attribute, which is slightly
+        # different than normal:
+        #
+        #   # standard comment
+        #   attr_accessor :attribute              
+        #
+        #  # standard comment
+        #  config_accessor :config    # ...added to standard comment
+        #
+        #  c [:key, 'value']           # hence you can comment inline like this.
+        #
+        # The comments for each of these will be:
+        # attribute:: standard comment
+        # config:: standard comment ...added to standard comment
+        # key:: hence you can comment inline like this.
+        #
+        def comment
+          text_comment = text.to_s.sub(/^#--.*/m, '')
+          original_comment.to_s + text_comment
+        end
+      end
+      
+      module CodeObjectAccess # :nodoc:
+        def comment_sections(section_regexp=//, normalize_comments=false)
+          res = {}
+
+          section = nil
+          lines = []
+          comment_lines = comment.split(/\r?\n/)
+          comment_lines << nil
+          comment_lines.each do |line|
+            case line
+            when nil, /^\s*#\s*=+(.*)/
+              next_section = (line == nil ? nil : $1.to_s.strip)
+
+              if section =~ section_regexp
+                lines << "" unless normalize_comments
+                res[section] = lines.join("\n") unless section == nil
+              end
+
+              section = next_section
+              lines = []
+            else
+              if normalize_comments
+                line =~ /^\s*#(.*)/
+                line = $1.to_s.strip
+              end
+
+              lines << line
+            end
+          end
+
+          res
+        end
+      end
+      
+      module ClassModuleAccess # :nodoc:
+        def find_class_or_module_named(name)
+          return self if full_name == name
+          (@classes.values + @modules.values).each do |c| 
+            return c if c.find_class_or_module_named(name)
+          end
+          nil
+        end
+        
+        def configurations
+          @attributes.select do |attribute|
+            attribute.kind_of?(TDoc::ConfigAttr)
+          end
+        end
+        
+        def find_configuration_named(name)
+          @attributes.each do |attribute|
+            next unless attribute.kind_of?(TDoc::ConfigAttr)
+            return attribute if attribute.name == name
+          end
+          nil
+        end
+      end
+  
+      # Overrides the new method automatically extend the new object with
+      # ConfigParser.  Intended to be used like:
+      #   RDoc::RubyParser.extend InitializeConfigParser
+      module InitializeConfigParser # :nodoc:
+        def new(*args)
+          parser = super
+          parser.extend ConfigParser
+          parser.config_mode = 'config_accessor'
+          parser
+        end
+      end
+      
+      # Provides methods extending an RDoc::RubyParser such that the parser will produce 
+      # TDoc::ConfigAttr instances in the place of RDoc::Attr instances during attribute
+      # parsing. 
+      module ConfigParser # :nodoc:
+        include RDoc::RubyToken
+        include TokenStream
+                 
+        CONFIG_ACCESSORS = ['config', 'declare_config', 'config_reader', 'config_writer', 'config_accessor']        
+        attr_accessor :config_mode
+        
+        # Returns the current config_rw mode, based on the config_mode flag.
+        def config_rw
+          case self.config_mode
+          when "config_accessor" then "RW"
+          when "declare_config" then nil
+          when "config_reader"   then "R"
+          when "config_writer"   then "W"
+          else
+            raise "unknown config mode: #{self.config_mode}"
+          end
+        end
+        
+        # Gets tokens until the next TkNL
+        def get_tk_to_nl
+          tokens = []
+          while !(tk = get_tk).kind_of?(TkNL)
+            tokens.push tk
+          end
+          unget_tk(tk)
+          tokens
+        end
+
+        # Works like the original parse_attr_accessor, except that the arg
+        # name is parsed from the config syntax and added attribute will
+        # be a TDoc::ConfigAttr.  For example:
+        #
+        #   class TaskDoc < Tap::Task
+        #     config [:key, 'value']   # comment
+        #   end
+        #
+        # produces an attribute named :key in the current config_rw mode.
+        #
+        # (see 'rdoc/parsers/parse_rb' line 2509)
+        def parse_config(context, single, tk, comment)
+          tks = get_tk_to_nl
+            
+          text = ""
+          if tks.last.kind_of?(TkCOMMENT)
+            text = tks.last.text.chomp("\n").chomp("\r")
+            unget_tk(tks.last)
+              
+            # If nodoc is given, don't document
+              
+            tmp = RDoc::CodeObject.new
+            read_documentation_modifiers(tmp, RDoc::ATTR_MODIFIERS)
+            return unless tmp.document_self
+          end
+              
+          key_tk = tks.select {|tk| tk.kind_of?(TkSYMBOL)}.first
+          return if key_tk.nil?
+          
+          arg = key_tk.text[1..-1]
+          att = TDoc::ConfigAttr.new(text, arg, config_rw, comment)
+          att.config_declaration = get_tkread
+          
+          # TODO -- it would be nice to read the default value here...
+          
+          context.add_attribute(att)
+        end
+        
+        # Works like the original parse_attr_accessor, except that the added
+        # attribute will be a TDoc::ConfigAttr.  config_mode is updated to the input
+        # token name, such that, for example, if tk.name == 'config_accessor' 
+        # then config_rw will return 'RW'.
+        #
+        # (see 'rdoc/parsers/parse_rb' line 2509)
+        def parse_config_accessor(context, single,  tk, comment)
+          self.config_mode = tk.name 
+          
+          tks = get_tk_to_nl
+          is_config_mode_flag = tks.select do |tk| 
+            !tk.kind_of?(TkSPACE) && !tk.kind_of?(TkCOMMENT) 
+          end.empty?
+
+          # If no args are given, take this as a flag for c
+          return if is_config_mode_flag
+            
+          tks.reverse_each {|tk| unget_tk(tk) }
+          args = parse_symbol_arg
+          read = get_tkread
+          rw = "?"
+          
+          # If nodoc is given, don't document any of them
+
+          tmp = RDoc::CodeObject.new
+          read_documentation_modifiers(tmp, RDoc::ATTR_MODIFIERS)
+          return unless tmp.document_self
+
+          for name in args
+	          att = TDoc::ConfigAttr.new(get_tkread, name, config_rw, comment)
+            context.add_attribute(att)
+          end  
+        end
+        
+        # Overrides the standard parse_attr_accessor method to hook in parsing
+        # of the config accessors.  If the input token is not named as one of the
+        # CONFIG_ACCESSORS, it will be processed normally.
+        def parse_attr_accessor(context, single, tk, comment)
+          case tk.name
+          when 'config'
+              parse_config(context, single,  tk, comment)
+          when 'declare_config', 'config_reader', 'config_writer', 'config_accessor'
+              parse_config_accessor(context, single, tk, comment)
+          else
+            super
+          end
+        end
+      end
+    end
+  end
+end
+
+# Register the TDoc generator (in case you want to actually use it).
+# method echos RDoc generator registration (see 'rdoc/rdoc' line 76)
+Generator = Struct.new(:file_name, :class_name, :key)
+RDoc::RDoc::GENERATORS['tdoc'] = Generator.new(
+  "tap/support/tdoc/tdoc_html_generator.rb",
+  "TDocHTMLGenerator".intern,
+  "tdoc")
+
+# Add the extended accessors to context classes.
+module RDoc # :nodoc:
+  class CodeObject # :nodoc:
+    include Tap::Support::TDoc::CodeObjectAccess  
+  end
+  
+  class ClassModule # :nodoc:
+    include Tap::Support::TDoc::ClassModuleAccess
+  end
+end
+
+# Override methods in Options to in effect incorporate the accessor 
+# flags for TDoc parsing. (see 'rdoc/options')  Raise an error if an
+# accessor flag has already been specified. 
+class Options # :nodoc:
+  alias tdoc_original_parse parse
+  
+  def parse(argv, generators)
+    tdoc_original_parse(argv, generators)
+    return unless @generator_name == 'tdoc'
+    
+    accessors = Tap::Support::TDoc::ConfigParser::CONFIG_ACCESSORS
+    
+    # check the config_accessor_flags for accessor conflicts
+    extra_accessor_flags.each_pair do |accessor, flag|
+      if accessors.include?(accessor)
+        raise OptionList.error("tdoc format already handles the accessor '#{accessor}'")
+      end
+    end
+    
+    # extra_accessors will be nil if no extra accessors were 
+    # specifed, otherwise it'll be a regexp like /^(...)$/
+    # the string subset assumes
+    #   regexp.to_s # => /(?-mix:^(...)$)/  
+    @extra_accessors ||= /^()$/ 
+    current_accessors_str = @extra_accessors.to_s[9..-4]
+    
+    # echos the Regexp production code in rdoc/options.rb
+    # (see the parse method, line 501)
+    re = '^(' + current_accessors_str + accessors.map{|a| Regexp.quote(a)}.join('|') + ')$' 
+    @extra_accessors = Regexp.new(re)
+    
+    RDoc::RubyParser.extend Tap::Support::TDoc::InitializeConfigParser 
+  end
+end

data/lib/tap/support/tdoc/tdoc_html_generator.rb

@@ -0,0 +1,38 @@
+require 'rdoc/generators/html_generator'
+
+# Defines a specialized generator so it can be called for using a --fmt option.
+class TDocHTMLGenerator < Generators::HTMLGenerator  # :nodoc:
+end
+
+module Generators # :nodoc:
+  const_set(:RubyToken, RDoc::RubyToken)
+
+  class HtmlClass < ContextUser # :nodoc:
+    alias tdoc_original_value_hash value_hash
+    
+    def value_hash
+      # split attributes into configurations and regular attributes
+      configurations, attributes = @context.attributes.partition do |attribute|
+        attribute.kind_of?(Tap::Support::TDoc::ConfigAttr)
+      end
+      
+      # set the context attributes to JUST the regular 
+      # attributes and process as usual.
+      @context.attributes.clear.concat attributes
+      values = tdoc_original_value_hash
+      
+      # set the context attributes to the configurations
+      # and echo the regular processing to produce a list
+      # of configurations
+      @context.attributes.clear.concat configurations
+      @context.sections.each_with_index do |section, i|
+        secdata = values["sections"][i]
+ 
+        al = build_attribute_list(section)
+        secdata["configurations"] = al unless al.empty?
+      end 
+
+      values
+    end
+  end
+end

data/lib/tap/support/tdoc/tdoc_html_template.rb

@@ -0,0 +1,42 @@
+require 'rdoc/generators/template/html/html'
+
+#
+# Add a template for documenting configurations.  Do so by inserting in the 
+# template into the content regions used to template html.
+# (see  'rdoc/generators/html_generator' line 864)
+#
+[
+RDoc::Page::BODY, 
+RDoc::Page::FILE_PAGE, 
+RDoc::Page::METHOD_LIST].each do |content|
+  
+  # this substitution method duplicates the attribute template for configurations
+  # (see rdoc\generators\template\html line 523)
+  #
+  #IF:attributes
+  #    <div id="attribute-list">
+  #      <h3 class="section-bar">Attributes</h3>
+  #
+  #      <div class="name-list">
+  #        <table>
+  #START:attributes
+  #        <tr class="top-aligned-row context-row">
+  #          <td class="context-item-name">%name%</td>
+  #IF:rw
+  #          <td class="context-item-value">&nbsp;[%rw%]&nbsp;</td>
+  #ENDIF:rw
+  #IFNOT:rw
+  #          <td class="context-item-value">&nbsp;&nbsp;</td>
+  #ENDIF:rw
+  #          <td class="context-item-desc">%a_desc%</td>
+  #        </tr>
+  #END:attributes
+  #        </table>
+  #      </div>
+  #    </div>
+  #ENDIF:attributes
+  #
+  content.gsub!(/IF:attributes.*?ENDIF:attributes/m) do |match|
+    match + "\n\n" + match.gsub(/attributes/, 'configurations').gsub(/Attributes/, 'Configurations')
+  end
+end

data/lib/tap/support/versions.rb

@@ -57,7 +57,39 @@ module Tap
       #
       def deversion(path)
         path =~ /^(.*)-(\d(\.?\d)*)(.*)?/ ? [$1 + $4, $2] : [path, nil]
-      end
+      end
+      
+      # A <=>  comparison for versions.  compare_versions can take strings, 
+      # integers, or even arrays representing the parts of a version.
+      #
+      #   compare_versions("1.0.0", "0.9.9")                  # => 1
+      #   compare_versions(1.1, 1.1)                               # => 0
+      #   compare_versions([0,9], [0,9,1])                    # => -1
+      def compare_versions(a,b)
+        a, b = [a,b].collect {|item| to_integer_array(item) }
+        
+        # equalize the lengths of the integer arrays
+        d = b.length - a.length
+        case 
+        when d < 0 then b.concat Array.new(-d, 0)
+        when d > 0 then a.concat Array.new(d, 0)
+        end 
+      
+        a <=> b
+      end
+      
+      private
+      
+      # Converts an input argument (typically a string  or an array) 
+      # to  an array of integers.  Splits version string on "."
+      def to_integer_array(arg)
+        arr = case arg
+        when Array then arg
+        else arg.to_s.split('.')
+        end
+        arr.collect {|i| i.to_i}
+      end
+      
     end
   end
 end