configurable 0.7.0 → 1.0.0

data/lib/cdoc.rb

@@ -1,413 +0,0 @@
-# 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
-
-unless Object.const_defined?(:TokenStream)
-  TokenStream = RDoc::TokenStream
-  Options = RDoc::Options
-end
-
-# CDoc hooks into and extends RDoc to make Configurable documentation available
-# as attributes.  CDoc provides an extension to the standard RDoc HTMLGenerator
-# and template.
-#
-# === Usage
-# To generate task documentation with configuration information, CDoc must be
-# loaded and the appropriate flags passed to rdoc . Essentially what you want
-# is:
-#
-#   % rdoc --fmt cdoc --template cdoc/cdoc_html_template [file_names....]
-#
-# Unfortunately, there is no way to load or require a file into the rdoc
-# utility directly; the above code causes an 'Invalid output formatter' error.
-# However, CDoc is easy to utilize from a Rake::RDocTask:
-#
-#   require 'rake'
-#   require 'rake/rdoctask'
-#
-#   desc 'Generate documentation.'
-#   Rake::RDocTask.new(:rdoc) do |rdoc|
-#     require 'cdoc'
-#     rdoc.template = 'cdoc/cdoc_html_template'
-#     rdoc.options << '--fmt' << 'cdoc'
-#
-#     # specify whatever else you need
-#     # rdoc.rdoc_files.include(...)
-#   end
-#
-# Now execute the rake task like:
-#
-#   % rake rdoc
-#
-# === Implementation
-#
-# RDoc is a beast to utilize in a non-standard way. One way to make RDoc parse
-# unexpected flags like 'config' or 'config_attr' is to use the '--accessor' 
-# option (see 'rdoc --help' or the RDoc documentation for more details).
-#
-# CDoc hooks into the '--accessor' parsing process to pull out configuration
-# attributes and format them into their own Configuration section on an RDoc
-# html page. When 'cdoc' is specified as an rdoc option, CDoc in effect sets
-# accessor flags for all the standard Task configuration methods, and then
-# extends the RDoc::RubyParser handle these specially.
-#
-# If cdoc is not specified as the rdoc format, CDoc does not affect the RDoc
-# output.  Similarly, the configuration attributes will not appear in the 
-# output unless you specify a template that utilizes them.
-#
-# ==== Namespace conflicts
-#
-# RDoc creates a namespace conflict with other libraries that define RubyToken
-# and RubyLex in the Object namespace (the prime example being IRB). CDoc checks
-# for such a conflict and redfines the RDoc versions of RubyToken and RubyLex 
-# within the RDoc namespace.  Essentially:
-#
-#   original constant    redefined constant
-#   RubyToken            RDoc::RubyToken
-#   RubyLex              RDoc::RubyLex
-#
-# The redefinition should not affect the existing (non RDoc) RubyToken and 
-# RubyLex constants, but if you directly use the RDoc versions after loading
-# CDoc, you should be aware that they must be accessed through the new 
-# constants.  Unfortunatley the trick is not seamless.  The RDoc RubyLex makes
-# a few calls to the RubyLex class method 'debug?'... these will be issued to
-# the existing (non RDoc) RubyLex method and not the redefined 
-# RDoc::RubyLex.debug?
-#
-# In addition, because of the RubyLex calls, the RDoc::RubyLex cannot be fully
-# hidden when CDoc is loaded before the conflicting RubyLex; you cannot load
-# CDoc before loading IRB without raising warnings.  
-#
-# Luckily all these troubles can be avoided very easily by not loading CDoc or
-# RDoc when you're in irb.  On the plus side, going against what I just said,
-# you can now access/use RDoc within irb by requiring <tt>'cdoc'</tt>.
-#
-#-- 
-# Note that tap-0.10.0 heavily refactored CDoc functionality out of the old CDoc
-# and into Lazydoc, and changed the declaration syntax for configurations.  These
-# changes also affected the implementation of CDoc.  Mostly the changes are hacks
-# to get the old system to work in the new system... as hacky as the old CDoc was,
-# now this CDoc is hacky AND may have cruft.  Until it breaks completely, I leave
-# it as is... ugly and hard to fathom.
-#
-module CDoc
-
-  # Encasulates information about the configuration.  Designed to be utilized
-  # by the CDocHTMLGenerator as similarly as possible to standard attributes.
-  class ConfigAttr < RDoc::Attr # :nodoc:
-    # Contains the actual declaration for the config attribute. ex:  "c [:key, 'value']      # comment"
-    attr_accessor :config_declaration, :default
-    
-    def initialize(*args)
-      @comment = nil # suppress a warning in Ruby 1.9
-      super
-    end
-    
-    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(add_default=true)
-      # this would include the trailing comment...
-      # text_comment = text.to_s.sub(/^#--.*/m, '')
-      #original_comment.to_s + text_comment + (default && add_default ? " (#{default})" : "")
-      comment = original_comment.to_s.strip
-      comment = desc.to_s if comment.empty?
-      comment + (default && add_default ? " (<tt>#{default}</tt>)" : "")
-    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*#\s?(.*)/
-            line = $1.to_s
-          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| 
-        res = c.find_class_or_module_named(name)
-        return res if res
-      end
-      nil
-    end
-    
-    def configurations
-      @attributes.select do |attribute|
-        attribute.kind_of?(CDoc::ConfigAttr)
-      end
-    end
-    
-    def find_configuration_named(name)
-      @attributes.each do |attribute|
-        next unless attribute.kind_of?(CDoc::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 
-  # CDoc::ConfigAttr instances in the place of RDoc::Attr instances during attribute
-  # parsing. 
-  module ConfigParser # :nodoc:
-    include RDoc::RubyToken
-    include TokenStream
-             
-    CONFIG_ACCESSORS = ['config', 'config_attr']        
-
-    # 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 CDoc::ConfigAttr.  For example:
-    #
-    #   class ConfigClass
-    #     include Configurable
-    #     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
-      
-      key_tk = nil
-      value_tk = nil
-
-      tks.each do |token|
-        next if token.kind_of?(TkSPACE)
-        
-        if key_tk == nil
-          case token
-          when TkSYMBOL then key_tk = token
-          when TkLPAREN then next
-          else break
-          end
-        else
-          case token
-          when TkCOMMA then value_tk = token
-          else
-            value_tk = token if value_tk.kind_of?(TkCOMMA)
-            break
-          end
-        end
-      end
-
-      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)
-        text = nil unless tmp.document_self
-      end
-      
-      tks.reverse_each {|token| unget_tk(token) }
-      return if key_tk == nil || text == nil
-      
-      arg = key_tk.text[1..-1]
-      default = nil
-      if value_tk
-        if text =~ /(.*):no_default:(.*)/
-          text = $1 + $2
-        else
-          default = value_tk.text
-        end
-      end
-      att = CDoc::ConfigAttr.new(text, arg, "RW", comment)
-      att.config_declaration = get_tkread
-      att.default = default
-       
-      context.add_attribute(att)
-    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', 'config_attr'
-          parse_config(context, single,  tk, comment)
-      else
-        super
-      end
-    end
-  end
-end
-
-# Register the CDoc 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['cdoc'] = Generator.new(
-  "cdoc/cdoc_html_generator.rb",
-  "CDocHTMLGenerator".intern,
-  "cdoc")
-
-# Add the extended accessors to context classes.
-module RDoc # :nodoc:
-  class CodeObject # :nodoc:
-    include CDoc::CodeObjectAccess  
-  end
-  
-  class ClassModule # :nodoc:
-    include CDoc::ClassModuleAccess
-  end
-end
-
-# Override methods in Options to in effect incorporate the accessor 
-# flags for CDoc parsing. (see 'rdoc/options')  Raise an error if an
-# accessor flag has already been specified. 
-class Options # :nodoc:
-  alias cdoc_original_parse parse
-  
-  def parse(argv, generators)
-    cdoc_original_parse(argv, generators)
-    return unless @generator_name == 'cdoc'
-    
-    accessors = CDoc::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("cdoc 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 CDoc::InitializeConfigParser 
-  end
-end

data/lib/cdoc/cdoc_html_generator.rb

@@ -1,38 +0,0 @@
-require 'rdoc/generators/html_generator'
-
-# Defines a specialized generator so it can be called for using a --fmt option.
-class CDocHTMLGenerator < Generators::HTMLGenerator  # :nodoc:
-end
-
-module Generators # :nodoc:
-  const_set(:RubyToken, RDoc::RubyToken)
-
-  class HtmlClass < ContextUser # :nodoc:
-    alias cdoc_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?(CDoc::ConfigAttr)
-      end
-      
-      # set the context attributes to JUST the regular 
-      # attributes and process as usual.
-      @context.attributes.clear.concat attributes
-      values = cdoc_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