pdoc 0.2.0

data/lib/pdoc/models/instance_method.rb

@@ -0,0 +1,18 @@
+module PDoc
+  module Models
+    class InstanceMethod < Entity
+      include Callable
+      attr_accessor :functionalized_self
+      def attach_to_parent(parent)
+        parent.instance_methods << self
+      end
+      
+      def to_hash
+        f = functionalized_self
+        super.merge({
+          :functionalized_self => f ? f.id : nil
+        })
+      end
+    end
+  end
+end

data/lib/pdoc/models/instance_property.rb

@@ -0,0 +1,9 @@
+module PDoc
+  module Models
+    class InstanceProperty < Entity
+      def attach_to_parent(parent)
+        parent.instance_properties << self
+      end
+    end
+  end
+end

data/lib/pdoc/models/mixin.rb

@@ -0,0 +1,10 @@
+module PDoc
+  module Models
+    class Mixin < Entity
+      include Container
+      def attach_to_parent(parent)
+        parent.mixins << self
+      end
+    end
+  end
+end

data/lib/pdoc/models/namespace.rb

@@ -0,0 +1,10 @@
+module PDoc
+  module Models
+    class Namespace < Entity
+      include Container
+      def attach_to_parent(parent)
+        parent.namespaces << self
+      end
+    end
+  end
+end

data/lib/pdoc/models/root.rb

@@ -0,0 +1,27 @@
+module PDoc
+  module Models
+    class Root
+      include Container
+      
+      def sections
+        @sections ||= []
+      end
+      
+      def sections?
+        @sections && !@sections.empty?
+      end
+      
+      def registry
+        @registry ||= {}
+      end
+      
+      def find(id)
+        registry[id]
+      end
+      
+      def parent
+        nil
+      end
+    end
+  end
+end

data/lib/pdoc/models/section.rb

@@ -0,0 +1,19 @@
+module PDoc
+  module Models
+    class Section < Base
+      include Container
+      
+      def attach_to_parent(parent)
+        parent.sections << self
+      end
+      
+      def name
+        @name ||= @id.sub(' section', '')
+      end
+      
+      def normalized_name
+        super.downcase
+      end
+    end
+  end
+end

data/lib/pdoc/models/signature.rb

@@ -0,0 +1,27 @@
+module PDoc
+  module Models
+    class Signature < Base
+      attr_reader :return_value
+      def attach_to_parent(parent)
+        parent.signatures << self
+      end
+      
+      #TODO API cleanup
+      
+      def to_s
+        @signature
+      end
+      
+      def name
+        @signature
+      end
+      
+      def to_hash
+        {
+          :name => name,
+          :return_value => return_value
+        }
+      end
+    end
+  end
+end

data/lib/pdoc/models/utility.rb

@@ -0,0 +1,11 @@
+module PDoc
+  module Models
+    class Utility < Entity
+      include Callable
+      
+      def attach_to_parent(parent)
+        parent.utilities << self
+      end
+    end
+  end
+end

data/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/lib/pdoc/parser/argument_description_nodes.rb

@@ -0,0 +1,21 @@
+module ArgumentDescription
+  class ArgumentDescription < Treetop::Runtime::SyntaxNode
+    def name
+      first.argument_name.name.text_value
+    end
+    
+    def types
+      if first.arg_types.empty?
+        []
+      else
+        args = first.arg_types.elements.last
+        [args.argument_type.text_value].concat(args.more.elements.map{ |e| e.argument_type.text_value })
+      end
+    end
+    
+    def description
+      more_lines = more.elements.map{ |l| l.to_s.strip }.reject { |l| l.empty? }
+      [first.description.text_value.strip].concat(more_lines).join(" ")
+    end
+  end
+end

data/lib/pdoc/parser/basic_nodes.rb

@@ -0,0 +1,31 @@
+module Basic
+  class BlankLine < Treetop::Runtime::SyntaxNode
+    def to_s
+      ""
+    end
+  end
+
+  class TextLine < Treetop::Runtime::SyntaxNode
+    def to_s
+      text.text_value
+    end
+  end
+
+  class Line < Treetop::Runtime::SyntaxNode
+  end
+
+  class CommentStart < Treetop::Runtime::SyntaxNode
+  end
+
+  class CommentEnd < Treetop::Runtime::SyntaxNode
+  end
+
+  class LineBreak < Treetop::Runtime::SyntaxNode
+  end
+
+  class Char < Treetop::Runtime::SyntaxNode
+  end
+
+  class Space < Treetop::Runtime::SyntaxNode
+  end
+end

data/lib/pdoc/parser/description_nodes.rb

@@ -0,0 +1,42 @@
+module Description
+  class Text < Treetop::Runtime::SyntaxNode
+    include Enumerable
+    def each
+      elements.map { |e| e.to_s }.each { |tag| yield tag }
+    end
+    
+    def join(sep = "\n")
+      outdent.join(sep).strip
+    end
+    
+    def to_s
+      join
+    end
+    
+    def excerpt
+      
+    end
+    
+    def inspect
+      text = truncate(15).gsub(/\n/, " ").strip.inspect
+      "#<#{self.class} #{text}>"
+    end
+    
+    def truncate(num = 30)
+      to_s.length < num ? to_s : to_s.slice(0..num) << "..."
+    end
+    
+    def outdent
+      range = tab_length..-1
+      map { |l| l.slice(range) }
+    end
+    
+    private
+      def tab_length
+        reject { |l| l =~ /^\s*$/ }.map do |line|
+          line = line.slice(/^\s*/)
+          line ? line.length : 0
+        end.min || 0
+      end
+  end
+end

data/lib/pdoc/parser/documentation_nodes.rb

@@ -0,0 +1,483 @@
+module Documentation
+  class Doc < Treetop::Runtime::SyntaxNode
+    include Enumerable
+    
+    def tags
+      @tags ||= elements.first.elements.map { |e| e.elements.last }
+    end
+
+    def each
+      tags.each { |tag| yield tag }
+    end
+    
+    # find_by_name allows you to search through all the documented instances based on the 
+    # instances Base#full_name.
+    # For example:
+    #
+    #     PDoc::Parser.new("prototype.js").parse.root.find_by_name("Element#update")
+    #
+    # Return an instance of InstanceMethod corresponding to "Element#update".
+    def find_by_name(name)
+      find { |e| e.full_name == name }
+    end
+    
+    def inspect
+      to_a.inspect
+    end
+    
+    # Returns the total number of documented instances
+    def size
+      to_a.length
+    end
+    
+    def name
+      "Home"
+    end
+    
+    def serialize(serializer)
+      each { |obj| obj.serialize(serializer) }
+    end
+  end
+  
+  module Memoized
+    def method_added(method_name)
+      if instance_method(method_name).arity.zero?
+        avoid_infinite_method_added_loop do
+          memoize(method_name)
+        end
+      end
+    end
+    
+    def memoize(method_name)
+      sanitized_name = method_name.to_s
+      sanitized_name = sanitized_name.sub(/!$/, '_bang')
+      sanitized_name = sanitized_name.sub(/\?$/, '_question_mark')
+      complete_name = "#{sanitized_name}_#{object_id.abs}"
+      
+      class_eval(<<-EVAL, __FILE__, __LINE__)
+        alias compute_#{complete_name} #{method_name}    # alias compute_section_12235760 section
+                                                         # 
+        def #{method_name}                               # def section
+          unless defined?(@#{complete_name})             #   unless defined?(@section_12235760)
+            @#{complete_name} = compute_#{complete_name} #     @section_12235760 = compute_section_12235760
+          end                                            #   end
+          @#{complete_name}                              #   @section_12235760
+        end                                              # end
+      EVAL
+    end
+    
+    def avoid_infinite_method_added_loop
+      unless @memoizing
+        @memoizing = true
+        yield
+        @memoizing = false
+      end
+    end
+  end
+  
+  class Base < Treetop::Runtime::SyntaxNode
+    extend Memoized
+    
+    # Returns an instance of Doc (the root of the tree outputed by the PDoc::Parser).
+    def root
+      parent.parent.parent
+    end
+    
+    # True if the instance was tagged as deprecated.
+    def deprecated?
+      tags.include?("deprecated")
+    end
+    
+    # If instance is tagged as an alias, alias_of returns the corresponding object.
+    # It will return nil otherwise.
+    def alias_of
+      tag = tags.find { |tag| tag.name == "alias of" }
+      tag.value if tag
+    end
+    
+    def related_to
+      tag = tags.find { |tag| tag.name == "related to" }
+      tag.value if tag
+    end
+    
+    # Returns an instance of Tags::Tags.
+    def tags
+      start.elements.last.empty? ? [] : start.elements.last
+    end
+    
+    # Returns the instance's class name.
+    def klass_name
+      ebnf.klass_name
+    end
+    
+    # Returns the instance's name. For example:
+    #     root.find_by_name("Element#update").name
+    #     # -> "update"
+    def name
+      ebnf.name
+    end
+    
+    # Returns the instance's full_name. For example:
+    #     root.find_by_name("Element#update").full_name
+    #     # -> "Element#update"
+    def full_name
+      ebnf.full_name
+    end
+    
+    # Returns the instance's namespace_string. Note that event if the instance is an method or property,
+    # the klass_name is not included in that string. So for example:
+    #
+    #     root.find_by_name("Ajax.Request#request").namespace_string
+    #     # -> "Ajax"
+    def namespace_string
+      ebnf.namespace
+    end
+    
+    # Returns the Klass instance if object is a class, nil otherwise.
+    def klass
+      nil
+    end
+    
+    # Returns the instance's closests namespace or nil when instance or instance's
+    # Klass is a global.
+    def namespace
+      @namespace ||= namespace_string.empty? ? nil : root.find_by_name(namespace_string)
+    end
+    
+    # If instance is a global, returns its Section. Else its Namespace.
+    def doc_parent
+      namespace ? namespace : section
+    end
+    
+    def ebnf_expressions
+      ebnf.elements.map { |e| e.elements.last }
+    end
+    
+    def description
+      text.to_s
+    end
+    
+    def signature
+      ebnf.text_value.strip
+    end
+    
+    def inspect
+      "#<#{self.class} #{full_name}>"
+    end
+    
+    def src_code_line
+      input.line_of(interval.last) - 1
+    end
+    
+    def parent_id
+      namespace_string.empty? ? section_name : namespace_string
+    end
+    
+    def section_name
+      if tags.include?('section')
+        value = tags.find { |tag| tag.name == 'section' }.value
+        "#{value} section"
+      end
+    end
+    
+    def to_yaml
+      str = "id: #{full_name.inspect}"
+      str << "\nparent_id: #{parent_id.inspect}" if parent_id
+      str << "\ntype: #{type}"
+      str << "\nsuperclass_id: #{superclass.inspect}" if respond_to?(:superclass) && superclass
+      str << "\nincluded: #{mixins.inspect}" if respond_to?(:mixins) && !mixins.empty?
+      str << "\nline_number: #{src_code_line}"
+      str << "\ndeprecated: true" if deprecated?
+      str << "\nalias_of: #{alias_of.inspect}" if respond_to?(:alias_of) && alias_of
+      str << "\nrelated_to: #{related_to.inspect}" if respond_to?(:related_to) && related_to
+      str << "\ndescription: |\n#{indent(description)}\n"
+    end
+    
+    def serialize(serializer)
+      serializer << to_yaml
+    end
+    
+    private
+    def indent(str, prefix = '  ')
+      str.split($/).map { |line| "#{prefix}#{line}" } * $/
+    end
+  end
+  
+  class Section < Base
+    # Returns section's name
+    def name
+      section.name
+    end
+
+    # Returns section's full_name
+    def full_name
+      "#{section.name} section"
+    end
+
+    # Returns section's title
+    def title
+      section.title
+    end
+
+    # Returns section's description
+    def description
+      section.description
+    end
+
+    # Returns section's text
+    def text
+      section.text
+    end
+    
+    # Returns nil.
+    def klass_name
+      nil
+    end
+    
+    # Returns false.
+    def global?
+      false
+    end
+    
+    # Returns nil.
+    def namespace
+      nil
+    end
+    
+    # Returns an empty string.
+    def namespace_string
+      ""
+    end
+    
+    # Returns nil.
+    def section
+      nil
+    end
+    
+    # Returns nil.
+    def doc_parent
+      nil
+    end
+    
+    # Returns "section".
+    def type
+      "section"
+    end
+  end
+  
+  class Method < Base
+    def klass
+      namespace
+    end
+    
+    def klass_name
+      ebnf_expressions.first.klass_name
+    end
+
+    def full_name
+      ebnf_expressions.first.full_name
+    end
+
+    def name
+      ebnf_expressions.first.name
+    end
+
+    def methodized?
+      ebnf_expressions.first.methodized?
+    end
+    
+    def namespace_string
+      ebnf_expressions.first.namespace
+    end
+    
+    def arguments
+      args = argument_descriptions.elements
+      args ? args.first.elements :  []
+    end
+    
+    def signature
+      ebnf_expressions.first.signature
+    end
+
+    def returns
+      ebnf_expressions.first.returns
+    end
+    
+    def fires
+      events.empty? ? [] : events.to_a
+    end
+    
+    def signatures
+      ebnf_expressions
+    end
+    
+    def serialize(serializer)
+      str = to_yaml
+      str << "\nmethodized: true" if respond_to?(:methodized?) && methodized?
+      
+      serialize_signatures(str)
+      
+      serialize_arguments(str) unless arguments.empty?
+      
+      serializer << str
+    end
+    
+    def serialize_signatures(str)
+      str << "\nsignatures:"
+      ebnf_expressions.each do |ebnf|
+        str << "\n -"
+        str << "\n  signature: #{ebnf.signature.inspect}"
+        str << "\n  return_value: #{ebnf.returns.inspect}" if ebnf.returns
+      end
+    end
+    
+    def serialize_arguments(str)
+      str << "\narguments:"
+      arguments.each do |arg|
+        str << "\n -"
+        str << "\n  name: #{arg.name}"
+        str << "\n  types: [#{arg.types.join(', ')}]" unless arg.types.empty?
+        str << "\n  description: >"
+        str << "\n    #{arg.description}\n"
+      end
+    end
+  end
+  
+  class Property < Base
+    def klass
+      namespace
+    end
+    
+    def signature
+      ebnf.signature
+    end
+    
+    def returns
+      ebnf.returns
+    end
+    
+    def serialize(serializer)
+      str = to_yaml
+      
+      str << "\nsignatures:"
+      str << "\n -"
+      str << "\n  signature: #{signature.inspect}"
+      str << "\n  return_value: #{returns.inspect}"
+
+      serializer << str
+    end
+  end
+  
+  class KlassMethod < Method
+    def klass
+      namespace.is_a?(Klass) ? namespace : nil
+    end
+    
+    def klass_name
+      klass ? klass.name : nil
+    end
+    
+    def type
+      "class method"
+    end
+  end
+  
+  class Utility < Method
+    def type
+      "utility"
+    end
+  end
+  
+  class InstanceMethod < Method
+    def type
+      "instance method"
+    end
+  end
+  
+  class Constructor < Method
+    def namespace_string
+      ebnf_expressions.first.namespace
+    end
+    
+    def type
+      "constructor"
+    end
+  end
+  
+  class KlassProperty < Property
+    def type
+      "class property"
+    end
+  end
+  
+  class InstanceProperty < Property
+    def type
+      "instance property"
+    end
+  end
+  
+  class Constant < Base
+    def klass
+      namespace.is_a?(Klass) ? namespace : nil
+    end
+    
+    def klass_name
+      klass ? klass.name : nil
+    end
+    
+    def returns
+      ebnf.returns
+    end
+    
+    def signature
+      ebnf.signature
+    end
+    
+    def type
+      "constant"
+    end
+  end
+  
+  class Namespace < Base
+    def mixins
+      ebnf.mixins.map { |m| m.full_name }
+    end
+    
+    def mixin?
+      false
+    end
+    
+    def klass?
+      false
+    end
+    
+    def type
+      "namespace"
+    end
+  end
+  
+  class Klass < Namespace
+    def klass?
+      true
+    end
+    
+    def superclass
+      sc = ebnf.superklass
+      sc.text_value if sc
+    end
+    
+    def type
+      "class"
+    end
+  end
+  
+  class Mixin < Namespace
+    def mixin?
+      true
+    end
+    
+    def type
+      "mixin"
+    end
+  end
+end