docrb 0.2.0 → 0.3.0

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

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

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

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

data/lib/docrb/doc_compiler/doc_blocks.rb

@@ -1,111 +0,0 @@
-# frozen_string_literal: true
-
-module Docrb
-  class DocCompiler
-    # DocBlocks provides utilities for annotating and formatting documentation
-    # blocks.
-    class DocBlocks
-      # Internal: Transforms a provided reference on a given parent by a
-      # ttempting to resolve it into a specific object.
-      #
-      # ref    - Reference to be resolved
-      # parent - The reference's parent
-      #
-      # Returns the reference itself by augmenting it with :ref_type and
-      # :ref_path information.
-      def self.process_reference(ref, parent)
-        return process_method_reference(ref, parent) if ref[:ref_type] == :method
-        return ref if ref[:ref_type] != :ambiguous
-
-        resolved = parent.resolve_ref(ref)
-        if resolved.nil?
-          ref[:ref_type] = :not_found
-          return ref
-        end
-        ref[:ref_type] = resolved.type
-        ref[:ref_path] = resolved.path
-        ref
-      end
-
-      def self.process_method_reference(ref, parent)
-        if (resolved = parent.resolve_ref(ref))
-          ref[:ref_path] = resolved.path
-        end
-        ref
-      end
-
-      # Internal: Processes a identifier on a provided parent. Returns an
-      # augmented reference with extra location information whenever it can
-      # be resolved.
-      #
-      # id     - Identifier to be processed
-      # parent - Parent on which the identifier appeared.
-      def self.process_identifier(id, parent)
-        resolved = parent.resolve(id[:contents].to_sym)
-        if resolved.nil?
-          puts "Unresolved: #{id[:contents]} on #{parent.path}"
-          return {
-            type: :span,
-            contents: Markdown.inline("`#{id[:contents]}`")
-          }
-        end
-        {
-          type: :ref,
-          ref_type: resolved.type,
-          ref_path: resolved.path,
-          contents: id[:contents]
-        }
-      end
-
-      # Internal: Formats a given TextBlock object by expanding its contents
-      # into markdown annotations and attempting to resolve references and
-      # identifiers.
-      #
-      # Returns the updated block list.
-      def self.format_text_block(block, parent)
-        unless block[:contents].is_a? Array
-          block[:contents] = Markdown.inline(block[:contents])
-          return block
-        end
-        block[:contents].map! do |c|
-          case c[:type]
-          when :span
-            c[:contents] = Markdown.inline(c[:contents])
-          when :ref
-            c = process_reference(c, parent)
-          when :camelcase_identifier
-            c = process_identifier(c, parent)
-          end
-          c
-        end
-        block
-      end
-
-      # Public: Updates a given documentation block by augmenting markdown
-      # elements, references, fields and identifiers.
-      #
-      # doc    - Documentation block to be processed
-      # parent - The parent container to which the block belongs to.
-      #
-      # Returns the updated block.
-      def self.prepare(doc, parent: nil)
-        return unless doc
-
-        doc[:contents].map! do |block|
-          case block[:type]
-          when :text_block
-            format_text_block(block, parent)
-          when :code_example
-            block[:contents] = Markdown.render_source(block[:contents])
-          when :field_block
-            block[:contents] = block[:contents].transform_values { |v| format_text_block(v, parent) }
-          else
-            puts "Skipped block with type #{block[:type]}"
-          end
-          block
-        end
-        doc
-      end
-    end
-  end
-end

data/lib/docrb/doc_compiler/doc_class.rb

@@ -1,43 +0,0 @@
-# frozen_string_literal: true
-
-module Docrb
-  class DocCompiler
-    # DocClass represents a documented class
-    class DocClass < BaseContainer
-      attr_accessor :inherits, :attributes
-
-      # Initializes a new instance with the provided parent, file, and object.
-      #
-      # parent   - The parent container holding this class definition.
-      # filename - The filename defining this class.
-      # obj      - The parsed class data.
-      def initialize(parent, filename, obj)
-        @inherits = nil
-        @attributes = ObjectContainer.new(self, DocAttribute, always_append: true)
-        super
-      end
-
-      def appended(filename, obj)
-        obj.fetch(:attr_accessor, []).each do |att|
-          @attributes.push(filename, att).accessor!
-        end
-
-        obj.fetch(:attr_reader, []).each do |att|
-          @attributes.push(filename, att).reader!
-        end
-
-        obj.fetch(:attr_writer, []).each do |att|
-          @attributes.push(filename, att).writer!
-        end
-      end
-
-      # Returns a Hash representation of this class definition
-      def to_h
-        super.to_h.merge({
-                           inherits:,
-                           attributes: merged_attributes.transform_values { |v| unpack(v) }
-                         })
-      end
-    end
-  end
-end

data/lib/docrb/doc_compiler/doc_method.rb

@@ -1,66 +0,0 @@
-# frozen_string_literal: true
-
-module Docrb
-  class DocCompiler
-    # DocMethod represents a documented method
-    class DocMethod < Resolvable
-      attr_reader :parent, :type, :name, :args, :doc, :visibility,
-                  :overriden_by, :defined_by
-
-      # Initializes a new DocMethod instance with a given parent, path, and
-      # object.
-      #
-      # parent   - The object holding the represented method
-      # filename - The filename on which the method is defined on
-      # obj      - The method definition itself
-      def initialize(parent, filename, obj)
-        super()
-        @parent = parent
-        @type = obj[:type]
-        @name = obj[:name]
-        @args = obj[:args]
-        @doc = obj[:doc]
-        @visibility = obj[:visibility]
-        @overriden_by = nil
-        @defined_by = FileRef.new(nil, filename, obj)
-      end
-
-      # Public: Marks this method as being overriden by a provided object in
-      # a given filename. This method initializes a new DocMethod instance using
-      # this instance's parent, the provided filename and object, and invokes
-      # #override! on it.
-      #
-      # filename - The filename defining the override for this method
-      # obj      - The object representing the override for this method
-      def override(filename, obj)
-        override! DocMethod.new(@parent, filename, obj)
-      end
-
-      # Public: Marks this method as being overriden by the provided method
-      #
-      # method - DocMethod object overriding this method's implementation
-      def override!(method)
-        @overriden_by = method
-      end
-
-      def inspect
-        type = @type == :def ? "method" : "singleton method"
-        overriden = overriden_by.nil? ? "" : " overriden"
-        "#<DocMethod:#{format("0x%08x", object_id * 2)} #{visibility} #{type} #{name}#{overriden}>"
-      end
-
-      # Public: Returns a Hash representation of this method
-      def to_h
-        {
-          type:,
-          name:,
-          args:,
-          doc: DocBlocks.prepare(doc, parent: self),
-          visibility:,
-          overriden_by:,
-          defined_by: defined_by&.to_h
-        }
-      end
-    end
-  end
-end

data/lib/docrb/doc_compiler/doc_module.rb

@@ -1,9 +0,0 @@
-# frozen_string_literal: true
-
-module Docrb
-  class DocCompiler
-    # DocModule represents a documented Module object
-    class DocModule < BaseContainer
-    end
-  end
-end

data/lib/docrb/doc_compiler/file_ref.rb

@@ -1,41 +0,0 @@
-# frozen_string_literal: true
-
-module Docrb
-  class DocCompiler
-    # FileRef represents a file reference. This class is used to represent
-    # definition metadata of objects in files. Instances of this class
-    # indicates filenames and boundaries for a represented object.
-    class FileRef
-      attr_reader :filename, :start_at, :end_at
-
-      # Initializes a new FileRef instance.
-      #
-      # _parent  - Unused.
-      # filename - Path to the file being referenced
-      # obj      - The object being referenced in the provided filename
-      #
-      def initialize(_parent, filename, obj)
-        @filename = filename
-        @start_at, @end_at = obj.values_at(:start_at, :end_at)
-      end
-
-      # Public: Returns the source code portion of the represented reference
-      def ruby_source
-        f = File.read(filename).split("\n")[start_at - 1..end_at - 1]
-        f.join("\n")
-      end
-
-      # Public: Returns the reference's Hash representation
-      def to_h
-        source = ruby_source
-        {
-          filename:,
-          start_at:,
-          end_at:,
-          source:,
-          markdown_source: Markdown.render_source(source)
-        }
-      end
-    end
-  end
-end

data/lib/docrb/doc_compiler/object_container.rb

@@ -1,68 +0,0 @@
-# frozen_string_literal: true
-
-module Docrb
-  class DocCompiler
-    # ObjectContainer implements utilities for representing a container of
-    # objects with a common type.
-    class ObjectContainer
-      extend Forwardable
-
-      attr_reader :objects
-
-      # Initializes a new container with a given parent, containing objects with
-      # a provided class and options.
-      #
-      # parent - The container's parent
-      # cls    - The class of represented items
-      # **opts - Options list. Currently, only `always_append` is supported,
-      #          which indicates that all objects provided to the instance must
-      #          be appended regardless of their type.
-      def initialize(parent, cls, **opts)
-        @cls = cls
-        @objects = []
-        @opts = opts
-        @parent = parent
-      end
-
-      def_delegators :@objects, :length, :each, :map, :find, :filter, :first, :[], :to_json
-
-      # Pushes a new object into the container. May raise ArgumentError in case
-      # the object being pushed is not compatible with the container's base
-      # object.
-      #
-      # filename - Name of the file which defines the object being pushed
-      # obj      - The object being pushed
-      #
-      # Returns the new instance representing the pushed object.
-      def push(filename, obj)
-        if @cls.method_defined?(:name) &&
-           (instance = @objects.find { |o| o.name == obj[:name] }) &&
-           !@opts.fetch(:always_append, false)
-
-          return instance.merge(filename, obj) if instance.respond_to? :merge
-          return instance.override(filename, obj) if instance.respond_to? :override
-          return instance.append(filename, obj) if instance.respond_to? :append
-
-          raise ArgumentError, "cannot handle existing object #{obj[:name]} for container of type #{@cls.name}"
-        end
-
-        inst = @cls.new(@parent, filename, obj)
-        @objects << inst
-        inst
-      end
-
-      def inspect
-        opts = []
-        opts << "always_append" if @opts[:always_append]
-        count = if @objects.count.zero?
-                  "empty"
-                else
-                  "#{@objects.length} object#{@objects.length == 1 ? "" : "s"}"
-                end
-        obj_id = format("0x%08x", object_id * 2)
-        opts_repr = opts.empty? ? "" : " #{opts.join(", ")}"
-        "#<ObjectContainer:#{obj_id} containing #{@cls.name}, #{count}#{opts_repr}>"
-      end
-    end
-  end
-end