# frozen_string_literal: true

##
# RDoc::CrossReference is a reusable way to create cross references for names.

class RDoc::CrossReference

  ##
  # Regular expression to match class references
  #
  # 1. There can be a '\\' in front of text to suppress the cross-reference
  # 2. There can be a '::' in front of class names to reference from the
  #    top-level namespace.
  # 3. The method can be followed by parenthesis (not recommended)

  CLASS_REGEXP_STR = '\\\\?((?:\:{2})?[A-Z]\w*(?:\:\:\w+)*)'

  ##
  # Regular expression to match a single method argument.

  METHOD_ARG_REGEXP_STR = '[\w.+*/=<>-]+'

  ##
  # Regular expression to match method arguments.

  METHOD_ARGS_REGEXP_STR = /(?:\((?:#{METHOD_ARG_REGEXP_STR}(?:,\s*#{METHOD_ARG_REGEXP_STR})*)?\))?/.source

  ##
  # Regular expression to match method references.
  #
  # See CLASS_REGEXP_STR

  METHOD_REGEXP_STR = /(
    (?!\d)[\w]+[!?=]?|
    %|=(?:==?|~)|![=~]|\[\]=?|<(?:<|=>?)?|>[>=]?|[-+!]@?|\*\*?|[\/%\`|&^~]
  )#{METHOD_ARGS_REGEXP_STR}/.source.delete("\n ").freeze

  ##
  # Regular expressions matching text that should potentially have
  # cross-reference links generated are passed to add_regexp_handling. Note
  # that these expressions are meant to pick up text for which cross-references
  # have been suppressed, since the suppression characters are removed by the
  # code that is triggered.

  CROSSREF_REGEXP = /(?:^|[\s()])
                     (
                      (?:
                       # A::B::C.meth
                       #{CLASS_REGEXP_STR}(?:[.#]|::)#{METHOD_REGEXP_STR}

                       # A::B::C
                       # The stuff after CLASS_REGEXP_STR is a
                       # nasty hack.  CLASS_REGEXP_STR unfortunately matches
                       # words like dog and cat (these are legal "class"
                       # names in Fortran 95).  When a word is flagged as a
                       # potential cross-reference, limitations in the markup
                       # engine suppress other processing, such as typesetting.
                       # This is particularly noticeable for contractions.
                       # In order that words like "can't" not
                       # be flagged as potential cross-references, only
                       # flag potential class cross-references if the character
                       # after the cross-reference is a space, sentence
                       # punctuation, tag start character, or attribute
                       # marker.
                       | #{CLASS_REGEXP_STR}(?=[@\s).?!,;<\000]|\z)

                       # Stand-alone method (preceded by a #)
                       | \\?\##{METHOD_REGEXP_STR}

                       # Stand-alone method (preceded by ::)
                       | ::#{METHOD_REGEXP_STR}

                       # Things that look like filenames
                       # The key thing is that there must be at least
                       # one special character (period, slash, or
                       # underscore).
                       | (?:\.\.\/)*[-\/\w]+[_\/.][-\w\/.]+

                       # Things that have markup suppressed
                       # Don't process things like '\<' in \<tt>, though.
                       # TODO: including < is a hack, not very satisfying.
                       | \\[^\s<]
                      )

                      # labels for headings
                      (?:@[\w+%-]+(?:\.[\w|%-]+)?)?
                     )/x

  ##
  # Version of CROSSREF_REGEXP used when <tt>--hyperlink-all</tt> is specified.

  ALL_CROSSREF_REGEXP = /
                     (?:^|[\s()])
                     (
                      (?:
                       # A::B::C.meth
                       #{CLASS_REGEXP_STR}(?:[.#]|::)#{METHOD_REGEXP_STR}

                       # A::B::C
                       | #{CLASS_REGEXP_STR}(?=[@\s).?!,;<\000]|\z)

                       # Stand-alone method
                       | \\?#{METHOD_REGEXP_STR}

                       # Things that look like filenames
                       | (?:\.\.\/)*[-\/\w]+[_\/.][-\w\/.]+

                       # Things that have markup suppressed
                       | \\[^\s<]
                      )

                      # labels for headings
                      (?:@[\w+%-]+)?
                     )/x

  ##
  # Hash of references that have been looked-up to their replacements

  attr_accessor :seen

  ##
  # Allows cross-references to be created based on the given +context+
  # (RDoc::Context).

  def initialize(context)
    @context = context
    @store   = context.store

    @seen = {}
  end

  ##
  # Returns a method, attribute or constant reference to +name+
  # if it exists in the containing context object. It returns
  # nil otherwise.
  #
  # For example, this method would decompose name = 'A::CONSTANT' into a
  # container object A and a symbol 'CONSTANT', and it would try to find
  # 'CONSTANT' in A.

  def resolve_local_symbol(name)
    ref = nil
    type = nil
    container = nil

    case name
    when /#{CLASS_REGEXP_STR}::([A-Z]\w*)\z/o then
      symbol = $2
      container = @context.find_symbol_module($1)
    when /#{CLASS_REGEXP_STR}([.#]|::)#{METHOD_REGEXP_STR}/o then
      type = $2
      if '.' == type # will find either #method or ::method
        symbol = $3
      else
        symbol = "#{type}#{$3}"
      end
      container = @context.find_symbol_module($1)
    when /^([.#]|::)#{METHOD_REGEXP_STR}/o then
      type = $1
      if '.' == type
        symbol = $2
      else
        symbol = "#{type}#{$2}"
      end
      container = @context
    end

    if container then
      unless RDoc::TopLevel === container then
        if '.' == type then
          if 'new' == symbol then # AnyClassName.new will be class method
            ref = container.find_local_symbol symbol
            ref = container.find_ancestor_local_symbol symbol unless ref
          else
            ref = container.find_local_symbol "::#{symbol}"
            ref = container.find_ancestor_local_symbol "::#{symbol}" unless ref
            ref = container.find_local_symbol "##{symbol}" unless ref
            ref = container.find_ancestor_local_symbol "##{symbol}" unless ref
          end
        else
          ref = container.find_local_symbol symbol
          ref = container.find_ancestor_local_symbol symbol unless ref
        end
      end
    end

    ref
  end

  ##
  # Returns a reference to +name+.
  #
  # If the reference is found and +name+ is not documented +nil+ will be
  # returned.  If +name+ is not found +nil+ is returned.

  def resolve(name)
    return @seen[name] if @seen.include? name

    ref = @context.find_symbol name

    ref = resolve_local_symbol name unless ref

    # Try a page name
    ref = @store.page name if not ref and name =~ /^[\w.\/]+$/

    ref = nil if RDoc::Alias === ref # external alias, can't link to it

    ref = nil unless ref&.display?

    @seen[name] = ref

    ref
  end

end
