docrb 0.2.0 → 0.3.0

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: docrb
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Victor Gama
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-02-21 00:00:00.000000000 Z
+date: 2023-10-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: docrb-html
@@ -16,56 +16,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.2'
+        version: '0.3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.2'
+        version: '0.3'
 - !ruby/object:Gem::Dependency
-  name: parser
+  name: docrb-parser
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.2'
+        version: '0.1'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.2'
-- !ruby/object:Gem::Dependency
-  name: redcarpet
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.6'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '3.6'
-- !ruby/object:Gem::Dependency
-  name: rouge
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '4.1'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '4.1'
+        version: '0.1'
 description: An opinionated documentation parser
 email:
 - hey@vito.io
@@ -87,26 +59,7 @@ files:
 - docrb.gemspec
 - exe/docrb
 - lib/docrb.rb
-- lib/docrb/comment_parser.rb
-- lib/docrb/comment_parser/code_example_block.rb
-- lib/docrb/comment_parser/code_example_parser.rb
-- lib/docrb/comment_parser/field_block.rb
-- lib/docrb/comment_parser/field_list_parser.rb
-- lib/docrb/comment_parser/text_block.rb
 - lib/docrb/doc_compiler.rb
-- lib/docrb/doc_compiler/base_container.rb
-- lib/docrb/doc_compiler/base_container/computations.rb
-- lib/docrb/doc_compiler/doc_attribute.rb
-- lib/docrb/doc_compiler/doc_blocks.rb
-- lib/docrb/doc_compiler/doc_class.rb
-- lib/docrb/doc_compiler/doc_method.rb
-- lib/docrb/doc_compiler/doc_module.rb
-- lib/docrb/doc_compiler/file_ref.rb
-- lib/docrb/doc_compiler/object_container.rb
-- lib/docrb/markdown.rb
-- lib/docrb/module_extensions.rb
-- lib/docrb/resolvable.rb
-- lib/docrb/ruby_parser.rb
 - lib/docrb/spec.rb
 - lib/docrb/version.rb
 homepage: https://github.com/heyvito/docrb
@@ -132,7 +85,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.2
+rubygems_version: 3.4.10
 signing_key:
 specification_version: 4
 summary: An opinionated documentation parser

data/lib/docrb/comment_parser/code_example_block.rb

@@ -1,36 +0,0 @@
-# frozen_string_literal: true
-
-module Docrb
-  class CommentParser
-    # CodeExampleBlock represents a list of characters of a code example
-    class CodeExampleBlock
-      attr_reader :code
-
-      def initialize
-        @code = []
-      end
-
-      def <<(text_block)
-        @code << "\n" unless empty?
-        @code << text_block.text
-      end
-
-      def empty?
-        @code.empty?
-      end
-
-      def normalize
-        @code
-          .map { |txt| txt.split("\n") }
-          .map { |item| item.empty? ? "" : item }
-          .flatten
-          .map { |line| line.gsub(/^\s{2}/, "") }
-          .join("\n")
-      end
-
-      def to_h
-        { type: :code_example, contents: normalize }
-      end
-    end
-  end
-end

data/lib/docrb/comment_parser/code_example_parser.rb

@@ -1,29 +0,0 @@
-# frozen_string_literal: true
-
-module Docrb
-  class CommentParser
-    # CodeExampleParser attempts to extract code examples from a documentation
-    # block.
-    class CodeExampleParser
-      def self.process(components)
-        new_components = []
-        code_example_group = CodeExampleBlock.new
-        components.each do |c|
-          if !c.is_a?(TextBlock) || !c.text.start_with?("  ")
-            unless code_example_group.empty?
-              new_components << code_example_group
-              code_example_group = CodeExampleBlock.new
-            end
-            new_components << c
-            next
-          end
-
-          code_example_group << c
-        end
-
-        new_components << code_example_group unless code_example_group.empty?
-        new_components
-      end
-    end
-  end
-end

data/lib/docrb/comment_parser/field_block.rb

@@ -1,18 +0,0 @@
-# frozen_string_literal: true
-
-module Docrb
-  class CommentParser
-    # FieldBlock represents a list of fields obtained by FieldListParser
-    class FieldBlock
-      attr_reader :fields
-
-      def initialize(fields)
-        @fields = fields
-      end
-
-      def to_h
-        { type: :field_block, contents: fields }
-      end
-    end
-  end
-end

data/lib/docrb/comment_parser/field_list_parser.rb

@@ -1,90 +0,0 @@
-# frozen_string_literal: true
-
-module Docrb
-  class CommentParser
-    # FieldListParser parses a field block (representing arguments of an method,
-    # for instance) into a specialised structure.
-    class FieldListParser
-      FIELD_FORMAT_REGEXP = /^([a-z_][0-9a-z_]*:?)\s+- /i
-
-      def initialize(text)
-        @text = text
-        @data = []
-        @current = []
-        @result = {}
-        @dash_index = nil
-      end
-
-      def detect
-        @text.each_char do |c|
-          next @current << c unless c == LINE_BREAK
-          return false unless handle_linebreak
-        end
-        return false unless handle_linebreak
-
-        flush_current_field!
-        true
-      end
-
-      def handle_linebreak
-        return true if @current.empty?
-
-        # Here's a linebreak. Handle it as needed.
-        @current = @current.join
-        if infer_field_alignment(@current)
-          flush_current_field!
-          @data << @current
-        else
-          # This is not a field. May be a continuation.
-          # Can it be a continuation?
-          return false if @data.empty?
-
-          # Yep. It may be. Is it?
-          return false unless continuation?(@current)
-
-          # It is. Append to data.
-          @data << @current.strip
-        end
-        @current = []
-        true
-      end
-
-      def flush_current_field!
-        return if @data.empty?
-
-        data = @data.join(" ")
-        @data = []
-        field_name = FIELD_FORMAT_REGEXP.match(data)[1]
-        text = data.slice(@dash_index + 1...).strip
-        @result[field_name] = text
-      end
-
-      def continuation?(line)
-        return false unless @dash_index
-
-        # until dash_index, we should have spaces
-        return false if line.length < @dash_index
-
-        return false unless line.slice(0..@dash_index + 1).strip.empty?
-
-        true
-      end
-
-      def infer_field_alignment(line)
-        # is the line a field?
-        return false unless FIELD_FORMAT_REGEXP.match?(line)
-
-        if @dash_index
-          # does it match the same alignment?
-          return false if line[@dash_index] != DASH
-        else
-          @dash_index = line.index(DASH)
-        end
-
-        true
-      end
-
-      attr_reader :result
-    end
-  end
-end

data/lib/docrb/comment_parser/text_block.rb

@@ -1,43 +0,0 @@
-# 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

@@ -1,272 +0,0 @@
-# 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