sleeping_king_studios-docs 0.1.0

data/lib/sleeping_king_studios/docs/data/see_tags/class_method_tag.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require 'sleeping_king_studios/docs/data/see_tags'
+
+module SleepingKingStudios::Docs::Data::SeeTags
+  # Data object representing a @see tag with a class method link.
+  class ClassMethodTag < SleepingKingStudios::Docs::Data::SeeTags::NamespaceItemTag # rubocop:disable Layout/LineLength
+    DEFINITION_PREFIX =
+      '(::)?[[:upper:]][[:alnum:]]*(::[[:upper:]][[:alnum:]]*)*'
+    private_constant :DEFINITION_PREFIX
+
+    METHOD_SUFFIX =
+      '([[[:lower:]][[:digit:]]_\+\-\*\/\[\]\<\>])+[=?]'
+    private_constant :METHOD_SUFFIX
+
+    CLASS_METHOD_PATTERN =
+      /\A(#{DEFINITION_PREFIX})?\.#{METHOD_SUFFIX}?\z/
+    private_constant :CLASS_METHOD_PATTERN
+
+    LEGACY_CLASS_METHOD_PATTERN =
+      /\A(#{DEFINITION_PREFIX})?::([[[:lower:]][[:digit:]]_])+\z/
+    private_constant :LEGACY_CLASS_METHOD_PATTERN
+
+    class << self
+      # Checks if the given tag object is a reference to a class method.
+      #
+      # @param native [YARD::Tags::Tag] the tag object.
+      #
+      # @return [true, false] true if the tag object is a reference; otherwise
+      #   false.
+      def match?(native)
+        name = native.name.sub(/\.\z/, '')
+
+        name.match?(CLASS_METHOD_PATTERN) ||
+          name.match?(LEGACY_CLASS_METHOD_PATTERN)
+      end
+      alias matches? match?
+    end
+
+    # @return [true, false] true if the referenced class method is an attribute;
+    #   otherwise false.
+    def attribute?
+      return @attribute unless @attribute.nil?
+
+      return @attribute = false unless exists?
+
+      native_method = registry.find do |obj|
+        obj.type == :method &&
+          obj.scope == :class &&
+          obj.path == normalized_path
+      end
+
+      @attribute = native_method.is_attribute?
+    end
+
+    # @return [String] the reference type.
+    def type
+      attribute? ? 'class-attribute' : 'class-method'
+    end
+
+    private
+
+    def normalized_path
+      return @normalized_path if @normalized_path
+
+      @normalized_path = absolute_path? ? reference : qualified_path
+
+      return @normalized_path if @normalized_path.include?('.')
+
+      @normalized_path = @normalized_path.reverse.sub('::', '.').reverse
+    end
+
+    def query_registry(name)
+      registry_query.class_method_exists?(name)
+    end
+
+    def split_legacy_reference
+      scoped          = relative_path? ? qualified_path : reference
+      segments        = scoped.split('::')
+      @reference_name = segments.pop
+      @namespace      = segments.join('::')
+    end
+
+    def split_method_reference
+      scoped          = relative_path? ? qualified_path : reference
+      segments        = scoped.split('.')
+      @reference_name = segments.pop
+      @namespace      = segments.last
+    end
+
+    def split_reference
+      if reference.include?('.')
+        split_method_reference
+      else
+        split_legacy_reference
+      end
+    end
+  end
+end

data/lib/sleeping_king_studios/docs/data/see_tags/constant_tag.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require 'sleeping_king_studios/docs/data/see_tags'
+
+module SleepingKingStudios::Docs::Data::SeeTags
+  # Data object representing a @see tag with a constant link.
+  class ConstantTag < SleepingKingStudios::Docs::Data::SeeTags::NamespaceItemTag
+    DEFINITION_PREFIX =
+      '(::)?[[:upper:]][[:alnum:]]*(::[[:upper:]][[:alnum:]]*)*'
+    private_constant :DEFINITION_PREFIX
+
+    CONSTANT_PATTERN =
+      /\A((#{DEFINITION_PREFIX})?::)?[[:upper:]]([[[:upper:]][[:digit:]]_])*\z/
+
+    private_constant :CONSTANT_PATTERN
+
+    class << self
+      # Checks if the given tag object is a reference to a constant.
+      #
+      # @param native [YARD::Tags::Tag] the tag object.
+      #
+      # @return [true, false] true if the tag object is a reference; otherwise
+      #   false.
+      def match?(native)
+        native.name.sub(/\.\z/, '').match?(CONSTANT_PATTERN)
+      end
+      alias matches? match?
+    end
+
+    # @return [String] the label used to generate the reference link.
+    def reference
+      @reference ||= super.sub(/\A::/, '')
+    end
+    alias label reference
+
+    # @return [String] the reference type.
+    def type
+      'constant'
+    end
+
+    private
+
+    def query_registry(name)
+      registry_query.constant_exists?(name)
+    end
+
+    def relative_path?
+      return @relative_path = false if native.name.start_with?('::')
+
+      super
+    end
+
+    def split_reference
+      scoped          = relative_path? ? qualified_path : reference
+      segments        = scoped.split('::')
+      @reference_name = segments.pop
+      @namespace      = segments.join('::')
+    end
+  end
+end

data/lib/sleeping_king_studios/docs/data/see_tags/definition_tag.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require 'sleeping_king_studios/docs/data/see_tags'
+
+module SleepingKingStudios::Docs::Data::SeeTags
+  # Data object representing a @see tag with a definition link.
+  class DefinitionTag < SleepingKingStudios::Docs::Data::SeeTags::ReferenceTag
+    DEFINITION_PATTERN =
+      /\A(::)?[[:upper:]][[:alnum:]]*(::[[:upper:]][[:alnum:]]*)*\z/
+    private_constant :DEFINITION_PATTERN
+
+    class << self
+      # Checks if the given tag object is a reference to a class or module.
+      #
+      # @param native [YARD::Tags::Tag] the tag object.
+      #
+      # @return [true, false] true if the tag object is a reference; otherwise
+      #   false.
+      def match?(native)
+        native.name.sub(/\.\z/, '').match?(DEFINITION_PATTERN)
+      end
+      alias matches? match?
+    end
+
+    # @return [String, nil] the path used to generate the reference link.
+    def path
+      return slugify_path(qualified_path) if relative_path?
+
+      return slugify_path(reference) if absolute_path?
+
+      nil
+    end
+
+    # @return [String] the label used to generate the reference link.
+    def reference
+      @reference ||= super.sub(/\A::/, '')
+    end
+    alias label reference
+
+    private
+
+    def query_registry(name)
+      registry_query.definition_exists?(name)
+    end
+
+    def relative_path?
+      return false if native.name.start_with?('::')
+
+      super
+    end
+  end
+end

data/lib/sleeping_king_studios/docs/data/see_tags/instance_method_tag.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require 'sleeping_king_studios/docs/data/see_tags'
+
+module SleepingKingStudios::Docs::Data::SeeTags
+  # Data object representing a @see tag with an instance method link.
+  class InstanceMethodTag < SleepingKingStudios::Docs::Data::SeeTags::NamespaceItemTag # rubocop:disable Layout/LineLength
+    DEFINITION_PREFIX =
+      '(::)?[[:upper:]][[:alnum:]]*(::[[:upper:]][[:alnum:]]*)*'
+    private_constant :DEFINITION_PREFIX
+
+    METHOD_SUFFIX =
+      '([[[:lower:]][[:digit:]]_\+\-\*\/\[\]\<\>])+[=?]'
+    private_constant :METHOD_SUFFIX
+
+    INSTANCE_METHOD_PATTERN =
+      /\A(#{DEFINITION_PREFIX})?##{METHOD_SUFFIX}?\z/
+    private_constant :INSTANCE_METHOD_PATTERN
+
+    class << self
+      # Checks if the given tag object is a reference to an instance method.
+      #
+      # @param native [YARD::Tags::Tag] the tag object.
+      #
+      # @return [true, false] true if the tag object is a reference; otherwise
+      #   false.
+      def match?(native)
+        native.name.sub(/\.\z/, '').match?(INSTANCE_METHOD_PATTERN)
+      end
+      alias matches? match?
+    end
+
+    # @return [true, false] true if the referenced class method is an attribute;
+    #   otherwise false.
+    def attribute?
+      return @attribute unless @attribute.nil?
+
+      return @attribute = false unless exists?
+
+      method_path = absolute_path? ? reference : qualified_path
+
+      native_method = registry.find do |obj|
+        obj.type == :method &&
+          obj.scope == :instance &&
+          obj.path == method_path
+      end
+
+      @attribute = native_method.is_attribute?
+    end
+
+    # @return [String] the reference type.
+    def type
+      attribute? ? 'instance-attribute' : 'instance-method'
+    end
+
+    private
+
+    def query_registry(name)
+      registry_query.instance_method_exists?(name)
+    end
+
+    def split_reference
+      scoped          = relative_path? ? qualified_path : reference
+      segments        = scoped.split('#')
+      @reference_name = segments.pop
+      @namespace      = segments.last
+    end
+  end
+end

data/lib/sleeping_king_studios/docs/data/see_tags/link_tag.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require 'sleeping_king_studios/docs/data/see_tags'
+
+module SleepingKingStudios::Docs::Data::SeeTags
+  # Data object representing a @see tag with a link.
+  class LinkTag < SleepingKingStudios::Docs::Data::SeeTags::Base
+    # Pattern used to match external links. YARD seems to use the presence of a
+    # protocol to identify a link, so "http://foo" is a valid link, but
+    # "www.example.com" is not.
+    LINK_PATTERN = %r{\A\w+://\w+}
+    private_constant :LINK_PATTERN
+
+    class << self
+      # Checks if the given tag object is a link.
+      #
+      # @param native [YARD::Tags::Tag] the tag object.
+      #
+      # @return [true, false] true if the tag object is a link; otherwise false.
+      def match?(native)
+        native.name.match?(LINK_PATTERN)
+      end
+      alias matches? match?
+    end
+
+    # Generates a JSON-compatible representation of the tag.
+    #
+    # Returns a Hash with the following keys:
+    #
+    # - 'label': The label used to generate the link.
+    # - 'path': The path used to generate the link.
+    # - 'text': The text to display for the tag.
+    # - 'type': The string 'link'.
+    def as_json
+      {
+        'label' => label,
+        'path'  => path,
+        'text'  => text,
+        'type'  => 'link'
+      }
+    end
+
+    # @return [String] the label used to generate the link.
+    def label
+      path
+    end
+
+    # @return [String] the path used to generate the link.
+    def path
+      @path ||= native.name.sub(/\.\z/, '')
+    end
+  end
+end

data/lib/sleeping_king_studios/docs/data/see_tags/namespace_item_tag.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require 'sleeping_king_studios/docs/data/see_tags'
+
+module SleepingKingStudios::Docs::Data::SeeTags
+  # Data object representing a @see tag with a constant or method link.
+  #
+  # @abstract
+  class NamespaceItemTag < SleepingKingStudios::Docs::Data::SeeTags::ReferenceTag # rubocop:disable Layout/LineLength
+    # (see SleepingKingStudios::Docs::Data::SeeTags::Base#initialize)
+    def initialize(native:, parent:)
+      super
+
+      split_reference
+    end
+
+    # @return [true, false] true if the constant is defined by the tagged
+    #   object; otherwise false.
+    def local?
+      return @local unless @local.nil?
+
+      @local = namespace == parent.name.to_s
+    end
+
+    # @return [String, nil] the path used to generate the reference link.
+    def path
+      return "##{type}-#{slugify(reference_name)}" if local?
+
+      return "#{namespace_path}##{type}-#{slugify(reference_name)}" if exists?
+
+      nil
+    end
+
+    # @return [String] the reference type.
+    def type
+      'reference'
+    end
+
+    private
+
+    attr_reader \
+      :namespace,
+      :reference_name
+
+    def namespace_path
+      return '/' if namespace.empty?
+
+      slugify_path(namespace)
+    end
+
+    def split_reference
+      @namespace      = ''
+      @reference_name = ''
+    end
+  end
+end

data/lib/sleeping_king_studios/docs/data/see_tags/reference_tag.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require 'sleeping_king_studios/docs/data/see_tags'
+
+module SleepingKingStudios::Docs::Data::SeeTags
+  # Data object representing a @see tag with a reference link.
+  #
+  # @abstract
+  class ReferenceTag < SleepingKingStudios::Docs::Data::SeeTags::Base
+    SEPARATORS = ['::', '.', '#'].freeze
+    private_constant :SEPARATORS
+
+    # Generates a JSON-compatible representation of the tag.
+    #
+    # Returns a Hash with the following keys:
+    #
+    # - 'label': The label used to generate the reference link.
+    # - 'path': The path used to generate the reference link.
+    # - 'text': The text to display for the tag.
+    # - 'type': The string 'reference'.
+    def as_json
+      {
+        'label' => label,
+        'path'  => path,
+        'text'  => text,
+        'type'  => 'reference'
+      }
+    end
+
+    # Checks if the referenced code object exists in the registry.
+    #
+    # @return [true, false] true if the referenced code object exists; otherwise
+    #   false.
+    def exists?
+      relative_path? || absolute_path?
+    end
+
+    # @return [String, nil] the path used to generate the reference link.
+    def path
+      nil
+    end
+
+    # @return [String] the label used to generate the reference link.
+    def reference
+      @reference ||= native.name.sub(/\.\z/, '')
+    end
+    alias label reference
+
+    private
+
+    def absolute_path?
+      return @absolute_path unless @absolute_path.nil?
+
+      @absolute_path = query_registry(reference)
+    end
+
+    def query_registry(_)
+      false
+    end
+
+    def registry_query
+      @registry_query ||=
+        SleepingKingStudios::Docs::RegistryQuery.new(registry:)
+    end
+
+    def qualified_path
+      return @qualified_path if @qualified_path
+
+      if SEPARATORS.any? { |sep| reference.start_with?(sep) }
+        return @qualified_path = "#{parent.path}#{reference}"
+      end
+
+      @qualified_path = "#{parent.path}::#{reference}"
+    end
+
+    def relative_path?
+      return @relative_path unless @relative_path.nil?
+
+      return @relative_path = false if parent.root?
+
+      @relative_path = query_registry(qualified_path)
+    end
+
+    def slugify_path(path)
+      path
+        .sub(/\A::/, '')
+        .split('::')
+        .map { |str| slugify(str) }
+        .join('/')
+    end
+  end
+end

data/lib/sleeping_king_studios/docs/data/see_tags/text_tag.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require 'sleeping_king_studios/docs/data/see_tags'
+
+module SleepingKingStudios::Docs::Data::SeeTags
+  # Data object representing a plain text @see tag.
+  class TextTag < SleepingKingStudios::Docs::Data::SeeTags::Base
+    class << self
+      # Checks if the given tag object is plain text.
+      #
+      # @param native [YARD::Tags::Tag] the tag object.
+      #
+      # @return [true, false] true if the tag object is plain text; otherwise
+      #   false.
+      def match?(native)
+        native.name == '_'
+      end
+      alias matches? match?
+    end
+
+    # Generates a JSON-compatible representation of the tag.
+    #
+    # Returns a Hash with the following keys:
+    #
+    # - 'text': The text to display for the tag.
+    def as_json
+      { 'text' => text }
+    end
+  end
+end

data/lib/sleeping_king_studios/docs/data/see_tags/unstructured_tag.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require 'sleeping_king_studios/docs/data/see_tags'
+
+module SleepingKingStudios::Docs::Data::SeeTags
+  # Data object representing an unstructured @see tag.
+  class UnstructuredTag < SleepingKingStudios::Docs::Data::SeeTags::Base
+    class << self
+      # @overload match?(native)
+      #   Always returns true.
+      #
+      #   @param native [YARD::Tags::Tag] the tag object.
+      #
+      #   @return [true] true for all tags.
+      def match?(_native)
+        true
+      end
+      alias matches? match?
+    end
+
+    # Generates a JSON-compatible representation of the tag.
+    #
+    # Returns a Hash with the following keys:
+    #
+    # - 'text': The text to display for the tag.
+    def as_json
+      { 'text' => text }
+    end
+
+    # The text to display when rendering the tag.
+    #
+    # @return [String] the text to display.
+    def text
+      @text ||= "#{native.name} #{native.text}".strip
+    end
+  end
+end

data/lib/sleeping_king_studios/docs/data/see_tags.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require 'sleeping_king_studios/docs/data'
+
+module SleepingKingStudios::Docs::Data
+  # Namespace for objects representing YARD @see tags.
+  module SeeTags
+    autoload :Base,
+      'sleeping_king_studios/docs/data/see_tags/base'
+    autoload :ClassMethodTag,
+      'sleeping_king_studios/docs/data/see_tags/class_method_tag'
+    autoload :ConstantTag,
+      'sleeping_king_studios/docs/data/see_tags/constant_tag'
+    autoload :DefinitionTag,
+      'sleeping_king_studios/docs/data/see_tags/definition_tag'
+    autoload :InstanceMethodTag,
+      'sleeping_king_studios/docs/data/see_tags/instance_method_tag'
+    autoload :LinkTag,
+      'sleeping_king_studios/docs/data/see_tags/link_tag'
+    autoload :NamespaceItemTag,
+      'sleeping_king_studios/docs/data/see_tags/namespace_item_tag'
+    autoload :ReferenceTag,
+      'sleeping_king_studios/docs/data/see_tags/reference_tag'
+    autoload :TextTag,
+      'sleeping_king_studios/docs/data/see_tags/text_tag'
+    autoload :UnstructuredTag,
+      'sleeping_king_studios/docs/data/see_tags/unstructured_tag'
+
+    class << self
+      # Creates a wrapper object for the given @see tag.
+      #
+      # @param native [YARD::Tags::Tag] the YARD object representing the @see
+      #   tag.
+      # @param parent [YARD::Tags::Tag] the YARD object representing the parent
+      #   object, which contains the @see tag.
+      #
+      # @return [SleepingKingStudios::Docs::Data::SeeTags::Base] the wrapped
+      #   object representing the @see tag.
+      def build(native:, parent:)
+        build_text_tag(native:, parent:) ||
+          build_link_tag(native:, parent:) ||
+          build_constant_tag(native:, parent:) ||
+          build_class_method_tag(native:, parent:) ||
+          build_definition_tag(native:, parent:) ||
+          build_instance_method_tag(native:, parent:) ||
+          build_unstructured_tag(native:, parent:)
+      end
+
+      private
+
+      def build_class_method_tag(native:, parent:)
+        return unless ClassMethodTag.match?(native)
+
+        ClassMethodTag.new(native:, parent:)
+      end
+
+      def build_constant_tag(native:, parent:)
+        return unless ConstantTag.match?(native)
+
+        # Special check for ambiguous definitions, e.g. HTTP, NASA.
+        constant_tag = ConstantTag.new(native:, parent:)
+
+        return constant_tag if constant_tag.exists?
+
+        definition_tag = DefinitionTag.new(native:, parent:)
+
+        # If neither the constant nor the definition exists, and the format
+        # matches a constant, assume it is a constant.
+        definition_tag.exists? ? definition_tag : constant_tag
+      end
+
+      def build_definition_tag(native:, parent:)
+        return unless DefinitionTag.match?(native)
+
+        DefinitionTag.new(native:, parent:)
+      end
+
+      def build_link_tag(native:, parent:)
+        return unless LinkTag.match?(native)
+
+        LinkTag.new(native:, parent:)
+      end
+
+      def build_instance_method_tag(native:, parent:)
+        return unless InstanceMethodTag.match?(native)
+
+        InstanceMethodTag.new(native:, parent:)
+      end
+
+      def build_text_tag(native:, parent:)
+        return unless TextTag.match?(native)
+
+        TextTag.new(native:, parent:)
+      end
+
+      def build_unstructured_tag(native:, parent:)
+        UnstructuredTag.new(native:, parent:)
+      end
+    end
+  end
+end

data/lib/sleeping_king_studios/docs/data/types/grammar.treetop

@@ -0,0 +1,49 @@
+grammar TypesSpecifierList
+  rule type_list
+    type ',\s+'r type_list / type
+  end
+
+  rule type
+    parameterized_type / ordered_type / key_value_type / identifier_with_whitespace
+  end
+
+  # Parameterized types.
+
+  rule key_value_type
+    identifier_with_whitespace '{' type_list '\s*=>\s*'r type_list '}'
+  end
+
+  rule ordered_type
+    identifier_with_whitespace '<(' type_list ')>'
+  end
+
+  rule parameterized_type
+    identifier_with_whitespace '<' type_list '>'
+  end
+
+  # Identifiers.
+
+  rule identifier_with_whitespace
+    '\s*'r identifier '\s*'r
+  end
+
+  rule identifier
+    class_method / instance_method / literal
+  end
+
+  rule class_method
+    '.' method_name
+  end
+
+  rule instance_method
+    '#' method_name
+  end
+
+  rule literal
+    '[^#\. ,=\<\>\(\)\{\}]+'r
+  end
+
+  rule method_name
+    literal / '<<' / '<=>' / '<=' / '<' / '===' / '==' / '>=' / '>>' / '>'
+  end
+end