sqlpostgres 1.2.4

data/tools/rdoc/rdoc/parsers/parse_simple.rb

@@ -0,0 +1,37 @@
+# Parse a non-source file. We basically take the whole thing 
+# as one big comment. If the first character in the file
+# is '#', we strip leading pound signs.
+
+
+require "rdoc/code_objects"
+require "markup/simple_markup/preprocess"
+
+module RDoc
+  # See rdoc/parsers/parse_c.rb
+
+  class SimpleParser
+    
+    # prepare to parse a plain file
+    def initialize(top_level, file_name, body, options)
+      
+      preprocess = SM::PreProcess.new(file_name, options.rdoc_include)
+      
+      preprocess.handle(body) do |directive, param|
+        $stderr.puts "Unrecognized directive '#{directive}' in #{file_name}"
+      end
+      
+      @body = body
+      @options = options
+      @top_level = top_level
+    end
+    
+    # Extract the file contents and attach them to the toplevel as a
+    # comment
+    
+    def scan
+      #    @body.gsub(/^(\s\n)+/, '')
+      @top_level.comment = @body
+      @top_level
+    end
+  end
+end

data/tools/rdoc/rdoc/parsers/parserfactory.rb

@@ -0,0 +1,75 @@
+require "rdoc/parsers/parse_simple"
+
+module RDoc
+
+  # A parser is simple a class that implements
+  #
+  #   #initialize(file_name, body, options)
+  #
+  # and
+  #
+  #   #scan
+  #
+  # The initialize method takes a file name to be used, the body of the
+  # file, and an RDoc::Options object. The scan method is then called
+  # to return an appropriately parsed TopLevel code object.
+
+  # The ParseFactory is used to redirect to the correct parser given a filename
+  # extension. This magic works because individual parsers have to register 
+  # themselves with us as they are loaded in. The do this using the following
+  # incantation
+  #
+  #
+  #    require "rdoc/parsers/parsefactory"
+  #    
+  #    module RDoc
+  #    
+  #      class XyzParser
+  #        extend ParseFactory                  <<<<
+  #        parse_files_matching /\.xyz$/        <<<<
+  #    
+  #        def initialize(file_name, body, options)
+  #          ...
+  #        end
+  #    
+  #        def scan
+  #          ...
+  #        end
+  #      end
+  #    end
+
+
+
+  module ParserFactory
+
+    @@parsers = []
+
+    Parsers = Struct.new(:regexp, :parser)
+
+    # Record the fact that a particular class parses files that
+    # match a given extension
+
+    def parse_files_matching(regexp)
+      @@parsers.unshift Parsers.new(regexp, self)
+    end
+
+    # Return a parser that can handle a particular extension
+
+    def ParserFactory.can_parse(file_name)
+      @@parsers.find {|p| p.regexp.match(file_name) }
+    end
+
+    # Find the correct parser for a particular file name. Return a 
+    # SimpleParser for ones that we don't know
+
+    def ParserFactory.parser_for(top_level, file_name, body, options)
+      parser_description = can_parse(file_name)
+      if parser_description
+        parser = parser_description.parser 
+      else
+        parser = SimpleParser
+      end
+      parser.new(top_level, file_name, body, options)
+    end
+  end
+end

data/tools/rdoc/rdoc/rdoc.rb

@@ -0,0 +1,219 @@
+# See README.
+#
+ 
+
+RDOC_VERSION = "0.9.0"
+
+rcs = '$Date: 2003/10/10 08:00:05 $ $Revision: 1.1 $'.
+  gsub(/\$/, '').
+  sub(/Date: /, ': ').
+  sub(/ Revision: (\S+)/) { "(#$1)" }
+
+VERSION_STRING = %{RDoc V} + RDOC_VERSION + rcs
+
+
+require 'rdoc/parsers/parse_rb.rb'
+require 'rdoc/parsers/parse_c.rb'
+require 'rdoc/parsers/parse_f95.rb'
+
+require 'rdoc/parsers/parse_simple.rb'
+require 'rdoc/options'
+
+require 'rdoc/diagram'
+
+require 'find'
+require 'ftools'
+
+# We put rdoc stuff in the RDoc module to avoid namespace
+# clutter.
+#
+# ToDo: This isn't universally true.
+
+module RDoc
+
+  # Exception thrown by any rdoc error. Only the #message part is
+  # of use externally.
+
+  class RDocError < Exception
+  end
+
+  # Encapsulate the production of rdoc documentation. Basically
+  # you can use this as you would invoke rdoc from the command
+  # line:
+  #
+  #    rdoc = RDoc::RDoc.new
+  #    rdoc.document(args)
+  #
+  # where _args_ is an array of strings, each corresponding to
+  # an argument you'd give rdoc on the command line. See rdoc/rdoc.rb 
+  # for details.
+  
+  class RDoc
+
+    ##
+    # This is the list of output generators that we
+    # support
+    
+    Generator = Struct.new(:file_name, :class_name, :key)
+    
+    GENERATORS = {}
+    $:.collect {|d|
+      File::expand_path(d)
+    }.find_all {|d|
+      File::directory?("#{d}/rdoc/generators")
+    }.each {|dir|
+      Dir::entries("#{dir}/rdoc/generators").each {|gen|
+        next unless /(\w+)_generator.rb$/ =~ gen
+        type = $1
+        unless GENERATORS.has_key? type
+          GENERATORS[type] = Generator.new("rdoc/generators/#{gen}",
+                                           "#{type.upcase}Generator".intern,
+                                           type)
+        end
+      }
+    }                                                    
+
+    #######
+    private
+    #######
+
+    ##
+    # Report an error message and exit
+    
+    def error(msg)
+      raise RDocError.new(msg)
+    end
+    
+    ##
+    # Create an output dir if it doesn't exist. If it does
+    # exist, but doesn't contain the flag file <tt>created.rid</tt>
+    # then we refuse to use it, as we may clobber some
+    # manually generated documentation
+    
+    def setup_output_dir(op_dir)
+      flag_file = File.join(op_dir, "created.rid")
+      if File.exist?(op_dir)
+        unless File.directory?(op_dir)
+          error "'#{op_dir}' exists, and is not a directory" 
+        end
+        unless File.file?(flag_file)
+          error "\nDirectory #{op_dir} already exists, but it looks like it\n" +
+            "isn't an RDoc directory. Because RDoc doesn't want to risk\n" +
+            "destroying any of your existing files, you'll need to\n" +
+            "specify a different output directory name (using the\n" +
+            "--op <dir> option).\n\n"
+        end
+      else
+        File.makedirs(op_dir)
+      end
+      File.open(flag_file, "w") {|f| f.puts Time.now }
+    end
+    
+
+    # Given a list of files and directories, create a list
+    # of all the Ruby files they contain. 
+    
+    def normalized_file_list(options, *relative_files)
+      file_list = []
+
+      relative_files.each do |rel_file_name|
+
+        case type = File.ftype(rel_file_name)
+        when "file"
+          file_list << rel_file_name
+        when "directory"
+          next if options.exclude && options.exclude =~ rel_file_name
+          Find.find(rel_file_name) do |fn|
+            next if options.exclude && options.exclude =~ fn
+            next unless ParserFactory.can_parse(fn)
+            next unless File.file?(fn)
+            
+            file_list << fn.sub(%r{\./}, '')
+          end
+        else
+          raise RDocError.new("I can't deal with a #{type} #{rel_file_name}")
+        end
+      end
+      file_list
+    end
+
+    # Parse each file on the command line, recursively entering
+    # directories
+
+    def parse_files(options)
+ 
+      file_info = []
+
+      files = options.files
+      files = ["."] if files.empty?
+
+      file_list = normalized_file_list(options, *files)
+
+      file_list.each do |fn|
+        $stderr.printf("\n%35s: ", File.basename(fn)) unless options.quiet
+        
+        content = File.open(fn, "r") {|f| f.read}
+
+        top_level = TopLevel.new(fn)
+        parser = ParserFactory.parser_for(top_level, fn, content, options)
+        file_info << parser.scan
+      end
+
+      file_info
+    end
+
+
+    public
+
+    ###################################################################
+    #
+    # Format up one or more files according to the given arguments.
+    # For simplicity, _argv_ is an array of strings, equivalent to the
+    # strings that would be passed on the command line. (This isn't a
+    # coincidence, as we _do_ pass in ARGV when running
+    # interactively). For a list of options, see rdoc/rdoc.rb. By
+    # default, output will be stored in a directory called +doc+ below
+    # the current directory, so make sure you're somewhere writable
+    # before invoking.
+    #
+    # Throws: RDocError on error
+
+    def document(argv)
+
+      TopLevel::reset
+
+      options = Options.instance
+      options.parse(argv, GENERATORS)
+    
+      file_info = parse_files(options)
+
+      gen = options.generator
+      
+      $stderr.puts "\nGenerating #{gen.key.upcase}..." unless options.quiet
+      
+      require gen.file_name
+      
+      gen_class = Generators.const_get(gen.class_name)
+      
+      unless file_info.empty?
+        gen = gen_class.for(options)
+
+        pwd = Dir.pwd
+
+        unless options.all_one_file
+          setup_output_dir(options.op_dir)
+          Dir.chdir(options.op_dir)
+        end
+
+        begin
+          Diagram.new(file_info, options).draw if options.diagram
+          gen.generate(file_info)
+        ensure
+          Dir.chdir(pwd)
+        end
+
+      end
+    end
+  end
+end
+

data/tools/rdoc/rdoc/template.rb

@@ -0,0 +1,234 @@
+# Cheap-n-cheerful HTML page template system. You create a 
+# template containing:
+#
+# * variable names between percent signs (<tt>%fred%</tt>)
+# * blocks of repeating stuff:
+#
+#     START:key
+#       ... stuff
+#     END:key
+#
+# You feed the code a hash. For simple variables, the values
+# are resolved directly from the hash. For blocks, the hash entry
+# corresponding to +key+ will be an array of hashes. The block will
+# be generated once for each entry. Blocks can be nested arbitrarily
+# deeply.
+#
+# The template may also contain
+#
+#   IF:key
+#     ... stuff
+#   ENDIF:key
+#
+# _stuff_ will only be included in the output if the corresponding
+# key is set in the value hash.
+#
+# Usage:  Given a set of templates <tt>T1, T2,</tt> etc
+#
+#            values = { "name" => "Dave", state => "TX" }
+#
+#            t = TemplatePage.new(T1, T2, T3)
+#            File.open(name, "w") {|f| t.write_html_on(f, values)}
+#         or
+#            res = ''
+#            t.write_html_on(res, values)
+#
+#
+
+class TemplatePage
+
+  ##########
+  # A context holds a stack of key/value pairs (like a symbol
+  # table). When asked to resolve a key, it first searches the top of
+  # the stack, then the next level, and so on until it finds a match
+  # (or runs out of entries)
+
+  class Context
+    def initialize
+      @stack = []
+    end
+
+    def push(hash)
+      @stack.push(hash)
+    end
+
+    def pop
+      @stack.pop
+    end
+
+    # Find a scalar value, throwing an exception if not found. This
+    # method is used when substituting the %xxx% constructs
+
+    def find_scalar(key)
+      @stack.reverse_each do |level|
+        if val = level[key]
+          return val unless val.kind_of? Array
+        end
+      end
+      raise "Template error: can't find variable '#{key}'"
+    end
+
+    # Lookup any key in the stack of hashes
+
+    def lookup(key)
+      @stack.reverse_each do |level|
+        val = level[key]
+        return val if val
+      end
+      nil
+    end
+  end
+
+  #########
+  # Simple class to read lines out of a string
+
+  class LineReader
+    # we're initialized with an array of lines
+    def initialize(lines)
+      @lines = lines
+    end
+
+    # read the next line 
+    def read
+      @lines.shift
+    end
+
+    # Return a list of lines up to the line that matches
+    # a pattern. That last line is discarded.
+    def read_up_to(pattern)
+      res = []
+      while line = read
+        if pattern.match(line)
+          return LineReader.new(res) 
+        else
+          res << line
+        end
+      end
+      raise "Missing end tag in template: #{pattern.source}"
+    end
+
+    # Return a copy of ourselves that can be modified without
+    # affecting us
+    def dup
+      LineReader.new(@lines.dup)
+    end
+  end
+
+
+
+  # +templates+ is an array of strings containing the templates.
+  # We start at the first, and substitute in subsequent ones
+  # where the string <tt>!INCLUDE!</tt> occurs. For example,
+  # we could have the overall page template containing
+  #
+  #   <html><body>
+  #     <h1>Master</h1>
+  #     !INCLUDE!
+  #   </bost></html>
+  #
+  # and substitute subpages in to it by passing [master, sub_page].
+  # This gives us a cheap way of framing pages
+
+  def initialize(*templates)
+    result = "!INCLUDE!"
+    templates.each do |content|
+      result.sub!(/!INCLUDE!/, content)
+    end
+    @lines = LineReader.new(result.split($/))
+  end
+
+  # Render the templates into HTML, storing the result on +op+ 
+  # using the method <tt><<</tt>. The <tt>value_hash</tt> contains
+  # key/value pairs used to drive the substitution (as described above)
+
+  def write_html_on(op, value_hash)
+    @context = Context.new
+    op << substitute_into(@lines, value_hash).tr("\000", '\\')
+  end
+
+
+  # Substitute a set of key/value pairs into the given template. 
+  # Keys with scalar values have them substituted directly into
+  # the page. Those with array values invoke <tt>substitute_array</tt>
+  # (below), which examples a block of the template once for each 
+  # row in the array.
+  #
+  # This routine also copes with the <tt>IF:</tt>_key_ directive,
+  # removing chunks of the template if the corresponding key
+  # does not appear in the hash, and the START: directive, which
+  # loops its contents for each value in an array
+
+  def substitute_into(lines, values)
+    @context.push(values)
+    skip_to = nil
+    result = []
+
+    while line = lines.read
+
+      case line
+
+      when /^IF:(\w+)/
+        lines.read_up_to(/^ENDIF:#$1/) unless @context.lookup($1)
+
+    when /^IFNOT:(\w+)/
+        lines.read_up_to(/^ENDIF:#$1/) if @context.lookup($1)
+
+      when /^ENDIF:/
+        ;
+
+      when /^START:(\w+)/
+        tag = $1
+        body = lines.read_up_to(/^END:#{tag}/)
+        inner_values = @context.lookup(tag)
+        raise "unknown tag: #{tag}" unless inner_values
+        raise "not array: #{tag}"   unless inner_values.kind_of?(Array)
+        inner_values.each do |vals|
+          result << substitute_into(body.dup, vals)
+        end
+      else
+        result << expand_line(line.dup)
+      end
+    end
+
+    @context.pop
+
+    result.join("\n")
+  end
+
+  # Given an individual line, we look for %xxx% constructs and 
+  # HREF:ref:name: constructs, substituting for each.
+
+  def expand_line(line)
+    # Generate a cross reference if a reference is given,
+    # otherwise just fill in the name part
+
+    line.gsub!(/HREF:(\w+?):(\w+?):/) {
+      ref = @context.lookup($1)
+      name = @context.find_scalar($2)
+
+      if ref and !ref.kind_of?(Array)
+	"<a href=\"#{ref}\">#{name}</a>"
+      else
+	name
+      end
+    }
+
+    # Substitute in values for %xxx% constructs.  This is made complex
+    # because the replacement string may contain characters that are
+    # meaningful to the regexp (like \1)
+
+    line = line.gsub(/%([a-zA-Z]\w*)%/) {
+      val = @context.find_scalar($1) 
+      val.tr('\\', "\000")
+    }
+
+
+    line
+  rescue Exception => e
+    $stderr.puts "Error in template: #{e}"
+    $stderr.puts "Original line: #{line}"
+    exit
+  end
+
+end
+

data/tools/rdoc/rdoc/tokenstream.rb

@@ -0,0 +1,25 @@
+# A TokenStream is a list of tokens, gathered during the parse
+# of some entity (say a method). Entities populate these streams
+# by being registered with the lexer. Any class can collect tokens
+# by including TokenStream. From the outside, you use such an object
+# by calling the start_collecting_tokens method, followed by calls
+# to add_token and pop_token
+
+module TokenStream
+  def token_stream
+    @token_stream
+  end
+
+  def start_collecting_tokens
+    @token_stream = []
+  end
+  def add_token(tk)
+    @token_stream << tk
+  end
+  def add_tokens(tks)
+    tks.each  {|tk| add_token(tk)}
+  end
+  def pop_token
+    @token_stream.pop
+  end
+end

data/tools/rdoc/rdoc.rb

@@ -0,0 +1,9 @@
+require 'rdoc/rdoc'
+
+begin
+  r = RDoc::RDoc.new
+  r.document(ARGV)
+rescue RDoc::RDocError => e
+  $stderr.puts e.message
+  exit(1)
+end