distil 0.11.6 → 0.11.8

data/vendor/pdoc/lib/pdoc/parser.rb

@@ -0,0 +1,109 @@
+require 'rubygems'
+require 'treetop'
+
+FILE_NAMES = %w[basic tags argument_description description ebnf_arguments ebnf_expression section_content documentation]
+
+FILE_NAMES.each { |file_name| require "#{file_name}_nodes" }
+
+%w[ebnf_javascript events].concat(FILE_NAMES).each do |file_name|
+  Treetop.load File.expand_path(File.join(PARSER_DIR, "treetop_files", file_name))
+end
+
+module PDoc
+  class Parser
+    def initialize(string)
+      @string = string
+      @parser = DocumentationParser.new
+      @percentage = 0
+    end
+    
+    # Parses the preprocessed string. Returns an instance
+    # of Documentation::Doc
+    def parse
+      @finished = false
+      result = @parser.parse(pre_process)
+      @finished = true
+      raise ParseError, @parser unless result
+      result
+    end
+    
+    # Preprocess the string before parsing.
+    # Converts "\r\n" to "\n" and avoids edge case
+    # by wrapping the string in line breaks.
+    def pre_process
+      string = @string.gsub(/\r\n/, "\n")
+      string = string.split("\n").map do |line|
+        line.gsub(/\s+$/, '')
+      end.join("\n")
+      "\n#{string}\n"
+    end
+    
+    def completion_percentage
+      if @parser.index
+        ratio = @parser.index.to_f / @parser.input.size.to_f
+        percentage = (ratio * 100).floor
+        @percentage = percentage if percentage > @percentage
+      end
+      "#{@percentage}%"
+    end
+
+    def finished?
+      @finished
+    end
+  end
+  
+  # Thrown by PDoc::Parser if the documentation is malformed.
+  class ParseError < StandardError
+    def initialize(parser)
+      @parser = parser
+      @lines = @parser.input.split("\n").unshift("")
+    end
+    
+    def message
+      <<-EOS
+      
+ParseError: Expected #{expected_string} at line #{line}, column #{column} (byte #{index + 1}) after #{@parser.input[@parser.index...index].inspect}.
+      
+#{source_code}
+      
+      EOS
+    end
+    
+    def line
+      @parser.failure_line
+    end
+    
+    def column
+      @parser.failure_column
+    end
+    
+    def failures
+      @parser.terminal_failures
+    end
+    
+    def index
+      @parser.failure_index
+    end
+    
+    def source_code
+      ((line-2)..(line+2)).map do |index|
+        result = index == line ? "-->" : "   "
+        "#{result} #{index.to_s.rjust(5)} #{@lines[index]}"
+      end.join("\n")
+    end
+    
+    def failure_reason
+      ""
+    end
+    
+    def expected_string
+      if failures.size == 1
+        failures.first.expected_string.inspect
+      else
+        expected = failures.map { |f| f.expected_string.inspect }.uniq
+        last = expected.pop
+        "one of #{expected.join(', ')} or #{last}"
+      end
+    end
+  end
+end

data/vendor/pdoc/lib/pdoc/runner.rb

@@ -0,0 +1,110 @@
+module PDoc
+  require 'yaml'
+  
+  class Runner
+    def initialize(*source_files)
+      options              = source_files.last.is_a?(Hash) ? source_files.pop : {}
+      @source_files        = source_files.empty? ? options[:source_files] : source_files
+      @output_directory    = File.expand_path(options.delete(:destination) || OUTPUT_DIR)
+      @generator           = options.delete(:generator) || Generators::Html::Website
+      @parser              = Parser
+      @serializer          = Serializer
+      @bust_cache          = options.delete(:bust_cache) || false
+      Models.src_code_href = options.delete(:src_code_href)
+      Models.doc_href = options.delete(:doc_href)
+      @generator_options = options
+    end
+    
+    def serialize(files)
+      files.each do |path|
+        File.open(pdoc_file(path), "w+") do |f|
+          f << serialize_file(path)
+        end
+      end
+    end
+    
+    def deserialize(files)
+      results = []
+      files.each do |file|
+        file = pdoc_file(file)
+        File.open(file) do |y|
+          YAML.load_documents(y) { |doc| results << doc }
+        end
+      end
+      results
+    end
+    
+    def new_files
+      @source_files.select do |path|
+        pdoc = pdoc_file(path)
+        !File.exist?(pdoc) || File.mtime(path) > File.mtime(pdoc)
+      end
+    end
+    
+    def run
+      opts = @generator_options
+      puts
+      puts "    Markdown parser:     #{opts[:markdown_parser]}" if opts[:markdown_parser]
+      puts "    Syntax highlighter:  #{opts[:syntax_highlighter]}" if opts[:syntax_highlighter]
+      puts "    Pretty urls:         #{opts[:pretty_urls]}" if opts[:pretty_urls]
+      puts "    Index page:          #{opts[:index_page]}" if opts[:index_page]
+      puts "    Output directory:    #{@output_directory}\n\n"
+      
+      files = @bust_cache ? @source_files : new_files
+      if files.empty?
+        puts "    Restoring serialized documentation from cache.\n\n"
+      else
+        puts "    Parsing JS files for PDoc comments:"
+        start_time = Time.new
+        serialize(files)
+        puts "    Finished parsing files in #{Time.new - start_time} seconds.\n\n"
+      end
+
+      
+      start_time = Time.new
+      data = deserialize(@source_files)
+      root = Treemaker.new(data).root
+      puts "    Building documentation tree. Finished in #{Time.new - start_time} seconds.\n\n"
+      
+      start_time = Time.new
+      puts "    Generating documentation:"
+      @generator.new(root, @generator_options).render(@output_directory)
+      puts "\n    Finished generating documentation in #{Time.new - start_time} seconds.\n\n"
+    end
+    
+    private
+      def serialize_file(path)
+        serializer = @serializer.new
+        serializer.path = path
+        puts "        Parsing #{path}..."
+        File.open(path) do |file|
+          @parser.new(file.read).parse.each do |fragment|
+            fragment.serialize(serializer)
+          end
+        end
+        serializer
+      end
+
+      def pdoc_file(path)
+        name = '.' << File.basename(path, '.js') << '.pdoc.yaml'
+        File.expand_path(File.join(File.dirname(path), name))
+      end
+  end
+  
+  class Serializer
+    attr_accessor :path
+    def initialize
+      @doc_fragments = []
+    end
+    
+    def <<(fragment)
+      fragment = "---\n#{fragment}"
+      fragment << "\nfile: #{path}"
+      @doc_fragments << fragment
+    end
+    
+    def to_s
+      @doc_fragments.join("\n\n")
+    end
+  end
+end

data/vendor/pdoc/lib/pdoc/treemaker.rb

@@ -0,0 +1,94 @@
+module PDoc
+  class Treemaker
+    include Models
+    
+    def initialize(doc_fragments = [])
+      methodized = []
+      doc_fragments.each do |attributes|
+        if attributes['methodized']
+          dups = attributes.dup
+          dups['id'] = methodize_id(dups['id'])
+          dups['type'] = 'instance method'
+          if dups['signatures']
+            dups['signatures'] = dups['signatures'].map do |s|
+              {
+                'signature' => methodize_signature(s['signature']),
+                'return_value' => s['return_value']
+              }
+            end
+          end
+          if dups['alias_of']
+            dups['alias_of'] = methodize_id(dups['alias_of'])
+          end
+          methodized << dups
+          i = instantiate_from(dups)
+          c = instantiate_from(attributes)
+          i.functionalized_self = c
+          c.methodized_self = i
+        else
+          instantiate_from(attributes)
+        end
+      end
+
+      doc_fragments.concat(methodized).each do |attributes|
+        if parent_id = attributes['parent_id']
+          parent = root.find(parent_id)
+          raise "Undocumented object: #{parent_id}." unless parent
+        else
+          parent = root
+        end
+        object = root.find(attributes['id'])
+        object.parent = parent
+        object.attach_to_parent(parent)
+        
+        if superclass_id = attributes['superclass_id']
+          superclass = root.find(superclass_id)
+          raise "Undocumented object: #{superclass_id}." unless superclass
+          object.superclass = superclass
+          superclass.subclasses << object
+        end
+        
+        if included = attributes['included']
+          included.each do |id|
+            mixin = root.find(id)
+            raise "Undocumented object: #{id}." unless mixin
+            object.included_mixins << mixin
+          end
+        end
+        
+        if alias_of_id = attributes['alias_of']
+          alias_of = root.find(alias_of_id)
+          raise "Undocumented object: #{alias_of_id}." unless alias_of
+          object.alias = alias_of
+          alias_of.aliases << object
+        end
+      end
+    end
+    
+    def instantiate_from(attributes)
+      arguments = attributes.delete('arguments')
+      signatures = attributes.delete('signatures')
+      object = Base.instantiate(attributes)
+      arguments.each { |a| Argument.new(a).attach_to_parent(object) } if arguments
+      signatures.each { |s| Signature.new(s).attach_to_parent(object) } if signatures
+      object.register_on(root.registry)
+    end
+    
+    def methodize_signature(sig)
+      sig.sub(/\.([\w\d\$]+)\((.*?)(,\s*|\))/) do
+        first_arg = $2.to_s.strip
+        prefix = first_arg[-1, 1] == '[' ? '([' : '('
+        rest = $3 == ')' ? $3 : ''
+        "##{$1}#{prefix}#{rest}"
+      end
+    end
+    
+    def methodize_id(id)
+      id.sub(/\.([^\.]+)$/) { "##{$1}" }
+    end
+    
+    def root
+      @root ||= Root.new
+    end
+  end
+end

data/vendor/pdoc/lib/pdoc.rb

@@ -0,0 +1,32 @@
+DIR = File.expand_path(File.dirname(__FILE__))
+OUTPUT_DIR    = File.join(DIR, '..', 'output')
+TEMPLATES_DIR = File.join(DIR, '..', 'templates')
+VENDOR_DIR    = File.join(DIR, '..', 'vendor')
+PARSER_DIR    = File.join(DIR, 'pdoc', 'parser')
+
+[DIR, VENDOR_DIR, PARSER_DIR, OUTPUT_DIR, TEMPLATES_DIR].each do |c|
+  $:.unshift(c)
+end
+
+require 'rubygems'
+require 'erb'
+require 'fileutils'
+
+require 'pdoc/error'
+require 'pdoc/runner'
+require 'pdoc/generators'
+require 'pdoc/parser'
+require 'pdoc/models'
+require 'pdoc/treemaker'
+
+module PDoc
+  def self.run(options = {})
+    Runner.new(options.dup).run
+  end
+  
+  def self.copy_templates(template_type, destination)
+    dir = File.expand_path(destination)
+    raise "File already exists: #{destination}" if File.exist?(dir)
+    FileUtils.cp_r("#{TEMPLATES_DIR}/#{template_type}", dir)
+  end
+end

data/vendor/pdoc/pdoc.gemspec

@@ -0,0 +1,31 @@
+Gem::Specification.new do |s|
+  s.name     = "pdoc"
+  s.version  = "0.2.0"
+  s.date     = "2008-11-17"
+  s.summary  = "Inline comment parser and JavaScript documentation generator"
+  s.email    = "tobie.langel@gmail.com"
+  s.homepage = "http://pdoc.org/"
+  s.description = "PDoc is an inline comment parser and JavaScript documentation generator written in Ruby. It is designed for documenting Prototype and Prototype-based libraries."
+  s.has_rdoc = true
+  s.authors  = ["Tobie Langel"]
+  s.files    = [
+		"README.markdown", 
+		"Rakefile", 
+		"pdoc.gemspec"] +
+		Dir['lib/**/*'] +
+        Dir['templates/**/*']
+  
+  s.autorequire = "lib/pdoc.rb"
+  
+  s.bindir = "bin"
+  s.executables = ["pdoc"]
+  s.default_executable = "pdoc"
+  
+  s.test_files = Dir['test/**/*.rb']
+  s.rdoc_options = ["--main", "README.markdown"]
+  s.extra_rdoc_files = ["README.markdown"]
+  s.add_dependency("BlueCloth", ["> 0.0.0"])
+  s.add_dependency("treetop", ["> 0.0.0"])
+  s.add_dependency("oyster", ["> 0.0.0"])
+end
+