docrb 0.2.0

data/lib/docrb/comment_parser/text_block.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Docrb
+  class CommentParser
+    # TextBlock represents an array of characters to be built into a single
+    # text block.
+    class TextBlock
+      def initialize(text = nil)
+        @buffer = [text].compact
+      end
+
+      def <<(obj)
+        @buffer << obj
+        @text = nil
+      end
+
+      def empty?
+        @buffer.empty?
+      end
+
+      def match?(regexp)
+        regexp.match? text
+      end
+
+      def last
+        @buffer.last
+      end
+
+      def text
+        @text ||= @buffer.join
+      end
+
+      def subs!(index)
+        @text = nil
+        @buffer = @buffer[index...]
+      end
+
+      def to_h
+        { type: :text_block, contents: text.gsub(/\n  /, " ") }
+      end
+    end
+  end
+end

data/lib/docrb/comment_parser.rb

@@ -0,0 +1,272 @@
+# frozen_string_literal: true
+
+module Docrb
+  # CommentParser implements a small parser for matching comment's contents to
+  # relevant references and annotations.
+  class CommentParser
+    COMMENT_METHOD_REF_REGEXP = /(?:([A-Z][a-zA-Z0-9_]*::)*([A-Z][a-zA-Z0-9_]*))?(::|\.|#)([A-Za-z_][a-zA-Z0-9_@]*[!?]?)(?:\([a-zA-Z0-9=_,\s*]+\))?/
+    COMMENT_SYMBOL_REGEXP = /:(!|[@$][a-z_][a-z0-9_]*|[a-z_][a-z0-9_]*|[a-z_][a-z0-9_]*[?!]?)/i
+    CAMELCASE_IDENTIFIER_REGEXP = /[A-Z][a-z]+(?:[A-Z][a-z]+)+/
+    INTERNAL_ANNOTATION_REGEXP = /^internal:/i
+    PUBLIC_ANNOTATION_REGEXP = /^public:/i
+    PRIVATE_ANNOTATION_REGEXP = /^private:/i
+    DEPRECATED_ANNOTATION_REGEXP = /^deprecated:/i
+    VISIBILITY_ANNOTATIONS = {
+      internal: INTERNAL_ANNOTATION_REGEXP,
+      public: PUBLIC_ANNOTATION_REGEXP,
+      private: PRIVATE_ANNOTATION_REGEXP,
+      depreacated: DEPRECATED_ANNOTATION_REGEXP
+    }.freeze
+    CARRIAGE = "\r"
+    LINE_BREAK = "\n"
+    SPACE = " "
+    DASH = "-"
+
+    autoload :TextBlock, "docrb/comment_parser/text_block"
+    autoload :FieldListParser, "docrb/comment_parser/field_list_parser"
+    autoload :CodeExampleParser, "docrb/comment_parser/code_example_parser"
+    autoload :FieldBlock, "docrb/comment_parser/field_block"
+    autoload :CodeExampleBlock, "docrb/comment_parser/code_example_block"
+
+    # Parses a given comment for a given object type.
+    #
+    # type:    - Type of the object's to which the comment data belongs to
+    # comment: - A string containing the object's documentation.
+    #
+    # Returns a Hash containing the parsed content for the comment.
+    def self.parse(type:, comment:)
+      new(type).parse(comment)
+    end
+
+    # Internal: Initializes a new parser with a provided type
+    #
+    # type - Type of the object being documented
+    def initialize(type)
+      @type = type
+      @components = []
+      @current = TextBlock.new
+      @last_char = nil
+      @current_char = nil
+      @meta = {}
+    end
+
+    # Intenral: Loads the provided data into the parser and executes all steps
+    # required to extract relevant information and annotations.
+    #
+    # data - String containing the comment being parsed
+    #
+    # Returns a Hash containing the parsed content for the comment.
+    def parse(data)
+      load(data)
+      coalesce_field_list
+      detect_code_example
+
+      infer_visibility_from_doc if %i[def defs].include? @type
+
+      data = to_h
+      data[:contents] = detect_references(data[:contents])
+      data
+    end
+
+    # Internal: Attempts to infer an object visiblity based on the comment's
+    # prefix. Supported visibility options are `public:`, `private:`, and
+    # `internal:`. Annotations are case-insensitive.
+    # This method also removes the detected annotation from the comment block,
+    # to reduce clutter in the emitted documentation.
+    def infer_visibility_from_doc
+      return if @components.empty?
+
+      item = @components.first
+      return unless item.is_a? TextBlock
+      return unless (annotation = VISIBILITY_ANNOTATIONS.find { |_k, v| v.match?(item.text) })
+
+      item.subs! item.text.index(":") + 1
+      @meta[:doc_visibility_annotation] = annotation.first
+    end
+
+    # Internal: Commits the current text block being processed by #load
+    def commit_current!
+      @components << @current if @current && !@current.empty?
+      @current = TextBlock.new
+    end
+
+    # Internal: Loads a given stirng into the parser, by splitting it into
+    # text blocks.
+    def load(text)
+      text.each_char do |c|
+        @last_char = @current_char
+        @current_char = c
+        next if c == CARRIAGE
+
+        if @last_char == LINE_BREAK && (c == LINE_BREAK)
+          commit_current!
+          next
+        end
+        @current << c
+      end
+      commit_current!
+    end
+
+    # Internal: Attempts to find and split field lists from the loaded comment.
+    def coalesce_field_list
+      return if @field_list_coalesced
+
+      @field_list_coalesced = true
+
+      new_contents = []
+      has_field_list = false
+
+      @components.each do |block|
+        unless has_field_list
+          parser = FieldListParser.new(block.text)
+          if parser.detect
+            has_field_list = true
+            new_contents << FieldBlock.new(parser.result)
+            next
+          end
+        end
+        new_contents << block
+      end
+
+      @components = new_contents
+    end
+
+    # Internal: Attempts to find and extract code examples contained within the
+    # comment
+    def detect_code_example
+      return if @code_examples_detected
+
+      @code_examples_detected = true
+
+      @components = CodeExampleParser.process(@components)
+    end
+
+    # Internal: Attempts to detect references on a provided list of blocks
+    #
+    # on - List of blocks to process
+    #
+    # Returns an updated list of blocks with references transformed into
+    # specialised structures.
+    def detect_references(on)
+      new_contents = []
+
+      on.each do |block|
+        case block[:type]
+        when :text_block
+          block[:contents] = detect_text_references(block[:contents])
+        when :field_block
+          block[:contents] = detect_field_references(block[:contents])
+        end
+        new_contents << block
+      end
+
+      new_contents
+    end
+
+    # Internal: Attempts to detect references on a text object.
+    #
+    # text - Text data to have references transformed into specialised objects
+    #
+    # Returns an array containing the updated text data
+    def detect_text_references(text)
+      changed = true
+      text, changed = update_next_reference(text) while changed
+      text
+    end
+
+    # Internal: Attempts to detect field references on a given field object.
+    #
+    # Returns a new hash containing the field's data post-processed with
+    # reference annotations
+    def detect_field_references(field)
+      field
+        .transform_values do |v|
+          { type: :text_block, contents: detect_text_references(v) }
+        end
+    end
+
+    def process_comment_method_reference(contents, match)
+      class_path, target, invocation, name = match.to_a.slice(1...)
+      class_path&.gsub!(/::$/, "")
+      reference_type = invocation == "#" ? :method : :ambiguous
+      begin_at = match.begin(0)
+      end_at = match.end(0)
+      left_slice = contents[0...begin_at]
+      right_slice = contents[end_at...]
+      item = {
+        type: :ref,
+        ref_type: reference_type,
+        name:,
+        target:,
+        class_path:,
+        contents: match[0]
+      }
+      [
+        { type: :span, contents: left_slice },
+        item,
+        { type: :span, contents: right_slice }
+      ].reject { |i| i[:contents].empty? }
+    end
+
+    def process_simple_symbol(type, contents, match)
+      begin_at = match.begin(0)
+      end_at = match.end(0)
+      left_slice = contents[0...begin_at]
+      right_slice = contents[end_at...]
+      [
+        { type: :span, contents: left_slice },
+        { type:, contents: match[0] },
+        { type: :span, contents: right_slice }
+      ].reject { |i| i[:contents].empty? }
+    end
+
+    def update_string_reference(contents)
+      updated = false
+      if (match = COMMENT_METHOD_REF_REGEXP.match(contents))
+        contents = process_comment_method_reference(contents, match)
+        updated = true
+      elsif (match = COMMENT_SYMBOL_REGEXP.match(contents))
+        contents = process_simple_symbol(:sym_ref, contents, match)
+        updated = true
+      elsif (match = CAMELCASE_IDENTIFIER_REGEXP.match(contents))
+        contents = process_simple_symbol(:camelcase_identifier, contents, match)
+        updated = true
+      end
+      [contents, updated]
+    end
+
+    # Internal: Recursivelly updates a given value until all references are
+    # processed.
+    #
+    # contents - Contents to be processed
+    #
+    # Returns a new array containing the processed contents
+    def update_next_reference(contents)
+      return update_string_reference(contents) if contents.is_a? String
+
+      new_contents = []
+      changed = false
+      contents.each do |block|
+        if block[:type] == :span
+          updated, ok = update_next_reference(block[:contents])
+          if ok
+            changed = true
+            next new_contents.append(*updated)
+          end
+        end
+        new_contents << block
+      end
+
+      [new_contents, changed]
+    end
+
+    # Public: Returns a hash by merging contents and metadata obtained through
+    # the parsing process.
+    def to_h
+      @meta.merge({
+                    type: @type,
+                    contents: @components.map(&:to_h)
+                  })
+    end
+  end
+end

data/lib/docrb/doc_compiler/base_container/computations.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+module Docrb
+  class DocCompiler
+    class BaseContainer
+      # Module Computations implements utility methods to handle hierarchy and
+      # nesting.
+      module Computations
+        # Recursively computes all dependants of the receiver.
+        # This method expands all references into concrete representations.
+        def compute_dependants
+          return if @compute_dependants
+
+          @compute_dependants = true
+
+          classes.each(&:compute_dependants)
+          modules.each(&:compute_dependants)
+
+          extends.each do |ref|
+            resolve_ref(ref)&.compute_dependants
+          end
+          includes.each do |ref|
+            resolve_ref(ref)&.compute_dependants
+          end
+
+          return unless (parent_name = @inherits)
+
+          @parent_class = resolve(parent_name)
+          return unless @parent_class
+
+          @parent_class.compute_dependants
+        end
+
+        # Returns a Hash containing all methods for the container, along with
+        # inherited and included ones.
+        def merged_instance_methods
+          return @merged_instance_methods if @merged_instance_methods
+
+          compute_dependants
+
+          methods = {}
+          @parent_class&.merged_instance_methods&.each do |k, v|
+            methods[k] = { source: :inheritance, definition: v }
+          end
+
+          includes.each do |ref|
+            next unless (container = resolve_container(ref))
+
+            container.merged_instance_methods.each do |k, v|
+              methods[k] = { source: :inclusion, definition: v, overriding: methods[k] }
+            end
+          end
+
+          defs.each do |m|
+            methods[m.name] = { source: :source, definition: m, overriding: methods[m.name] }
+          end
+
+          methods
+        end
+
+        # Returns a hash containing all class methods for the container, along
+        # with inherited and extended ones.
+        def merged_class_methods
+          return @merged_class_methods if @merged_class_methods
+
+          compute_dependants
+
+          methods = {}
+          @parent_class&.merged_class_methods&.each do |k, v|
+            methods[k] = { source: :inheritance, definition: v }
+          end
+
+          includes.each do |ref|
+            next unless (container = resolve_container(ref))
+
+            container.merged_class_methods.each do |k, v|
+              methods[k] = { source: :extension, definition: v, overriding: methods[k] }
+            end
+          end
+
+          sdefs.each do |m|
+            methods[m.name] = { source: :source, definition: m, overriding: methods[m.name] }
+          end
+
+          methods
+        end
+
+        # Returns a hash containing all attributes for the container, along with
+        # inherited ones.
+        def merged_attributes
+          return @merged_attributes if @merged_attributes
+
+          compute_dependants
+
+          attrs = {}
+          @parent_class&.merged_attributes&.each do |k, v|
+            attrs[k] = { source: :inheritance, definition: v }
+          end
+
+          attributes.each do |m|
+            attrs[m.name] = { source: :source, definition: m, overriding: attrs[m.name] }
+          end
+
+          attrs
+        end
+
+        # Deprecated: Use #merged_instance_methods.
+        def all_defs
+          return @all_defs if @all_defs
+
+          compute_dependants
+
+          methods = {}
+          @parent_class&.all_defs&.each do |k, v|
+            methods[k] = v
+          end
+
+          includes.each do |ref|
+            resolve_ref(ref)&.all_defs&.each do |met|
+              if methods.key? met.name
+                methods[key].override! met
+                next
+              end
+
+              methods[met.name] = met
+            end
+          end
+
+          defs.each do |met|
+            if methods.key? met.name
+              methods[met.name].override! met
+              next
+            end
+
+            methods[met.name] = met
+          end
+
+          @all_defs = methods
+        end
+
+        # Deprecated: Use #merged_class_methods.
+        def all_sdefs
+          return @all_sdefs if @all_sdefs
+
+          compute_dependants
+
+          methods = {}
+
+          @parent_class&.all_sdefs&.each do |k, v|
+            methods[k] = v
+          end
+
+          extends.each do |ref|
+            resolve_ref(ref)&.all_defs&.each do |met|
+              if methods.key? met.name
+                methods[met.name].override! met
+                next
+              end
+
+              methods[met.name] = met
+            end
+          end
+
+          @sdefs.each do |met|
+            if methods.key? met.name
+              methods[met.name].override! met
+              next
+            end
+
+            methods[met.name] = met
+          end
+
+          @all_sdefs = methods
+        end
+      end
+    end
+  end
+end

data/lib/docrb/doc_compiler/base_container.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Docrb
+  class DocCompiler
+    # BaseContainer represents a container for methods, classes, modules and
+    # attributes.
+    class BaseContainer < Resolvable
+      require_relative "./base_container/computations"
+      include Computations
+
+      attr_accessor :extends, :includes, :classes, :modules, :defs, :sdefs,
+                    :type, :name, :defined_by, :parent, :doc
+
+      # Initialises a new BaseContainer instance with a provided parent,
+      # filename and represented object.
+      def initialize(parent, filename, obj)
+        super()
+        @parent = parent
+        @type = obj[:type]
+        @name = obj[:name]
+        @extends = []
+        @includes = []
+        @classes = ObjectContainer.new(self, DocClass)
+        @modules = ObjectContainer.new(self, DocModule)
+        @defs = ObjectContainer.new(self, DocMethod)
+        @sdefs = ObjectContainer.new(self, DocMethod)
+        @defined_by = ObjectContainer.new(nil, FileRef)
+        append(filename, obj)
+      end
+
+      # Appends a new object defined by the provided file to this container
+      def <<(filename, obj)
+        append(filename, obj)
+      end
+
+      # Appends a new class defined by the provided file to this container
+      def append_class(filename, cls)
+        @classes.push filename, cls
+      end
+
+      def inspect
+        ext = "#{extends.length} extend#{extends.length == 1 ? "" : "s"}"
+        inc = "#{includes.length} include#{includes.length == 1 ? "" : "s"}"
+        cls = "#{classes.length} class#{classes.length == 1 ? "" : "es"}"
+        mod = "#{modules.length} module#{modules.length == 1 ? "" : "s"}"
+        de = "#{defs.length} def#{defs.length == 1 ? "" : "s"}"
+        sde = "#{sdefs.length} sdef#{sdefs.length == 1 ? "" : "s"}"
+
+        "#<#{self.class.name}:#{format("0x%08x",
+                                       object_id * 2)} #{@type} #{@name} #{ext}, #{inc}, #{cls}, #{mod}, #{de}, #{sde}>"
+      end
+
+      # Attempts to append a given object defined in a provided filename.
+      # Raises ArgumentError in case the object can't be added to the container
+      # due to type contraints.
+      #
+      # filename - Filename defining the object being appended
+      # obj      - The object definition to be appended to this container.
+      def append(filename, obj)
+        raise ArgumentError, "cannot append obj of type #{obj[:type]} into #{@name} (#{@type})" if obj[:type] != @type
+
+        raise ArgumentError, "cannot append obj named #{obj[:name]} into #{@name} (#{@type})" if obj[:name] != @name
+
+        unless (doc = obj[:doc]).nil?
+          @defined_by.push(filename, obj)
+          @doc = doc
+        end
+
+        obj.fetch(:classes, []).each { |c| @classes.push(filename, c) }
+        obj.fetch(:modules, []).each { |m| @modules.push(filename, m) }
+        obj.fetch(:extend, []).each { |e| @extends << e }
+        obj.fetch(:include, []).each { |i| @includes << i }
+        obj.fetch(:methods, []).each do |met|
+          if met[:type] == :def
+            @defs.push(filename, met)
+          else
+            @sdefs.push(filename, met)
+          end
+        end
+
+        @inherits = obj.fetch(:inherits, nil) if obj[:type] == :class
+
+        appended(filename, obj)
+      end
+
+      # Courtesy method. This method is called whenever a new object is
+      # appended to the container. Inheriting classes can override it to perform
+      # further operations on the appended object.
+      def appended(filename, obj); end
+
+      # Intenral: Recursively unpacks a given element by checking its
+      # :definition and :overriding keys.
+      #
+      # Returns the updated element.
+      def unpack(elem)
+        return unless elem
+
+        elem.tap do |e|
+          inner = e[:definition]
+          e[:definition] = inner.is_a?(Hash) ? unpack(inner) : inner.to_h
+          e[:overriding] = unpack(e[:overriding])
+        end
+      end
+
+      # Returns a Hash representation of the current container along with its
+      # children.
+      def to_h
+        {
+          type:,
+          name:,
+          doc: DocBlocks.prepare(doc, parent: self),
+          defined_by: defined_by.map(&:to_h),
+          defs: merged_instance_methods.transform_values { |v| unpack(v) },
+          sdefs: merged_class_methods.transform_values { |v| unpack(v) },
+          classes: classes.map(&:to_h),
+          modules: modules.map(&:to_h),
+          includes: includes.map(&:to_h),
+          extends: extends.map(&:to_h)
+        }
+      end
+    end
+  end
+end

data/lib/docrb/doc_compiler/doc_attribute.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Docrb
+  class DocCompiler
+    # DocAttribute represents a single attribute defined on a class.
+    class DocAttribute < Resolvable
+      attr_reader :parent, :defined_by, :name, :docs, :type, :writer_visibility,
+                  :reader_visibility
+
+      def initialize(parent, filename, obj)
+        super()
+        @parent = parent
+        @defined_by = [filename]
+        @name = obj[:name]
+        @docs = obj[:docs]
+        @type = nil
+        @writer_visibility = obj[:writer_visibility]
+        @reader_visibility = obj[:reader_visibility]
+      end
+
+      # Marks the current attribute as an accessor.
+      #
+      # Returns the attribute's instance for chaining.
+      def accessor!
+        @type = :accessor
+        self
+      end
+
+      # Marks the current attribute as an reader.
+      #
+      # Returns the attribute's instance for chaining.
+      def reader!
+        @type = :reader
+        self
+      end
+
+      # Marks the current attribute as an writer.
+      #
+      # Returns the attribute's instance for chaining.
+      def writer!
+        @type = :writer
+        self
+      end
+
+      # Returns a Hash representing this attribute
+      def to_h
+        {
+          defined_by:,
+          name:,
+          docs:,
+          type:,
+          writer_visibility:,
+          reader_visibility:
+        }
+      end
+    end
+  end
+end