2017-11-27 13:45:24 +03:00
|
|
|
# frozen_string_literal: true
|
2022-02-10 02:13:57 +03:00
|
|
|
|
|
|
|
require_relative 'markup/attribute_manager' # for PROTECT_ATTR
|
|
|
|
|
2011-07-31 04:19:00 +04:00
|
|
|
##
|
|
|
|
# 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+)*)'
|
|
|
|
|
2022-03-09 01:02:35 +03:00
|
|
|
##
|
|
|
|
# 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
|
|
|
|
|
2011-07-31 04:19:00 +04:00
|
|
|
##
|
|
|
|
# Regular expression to match method references.
|
|
|
|
#
|
|
|
|
# See CLASS_REGEXP_STR
|
|
|
|
|
2022-02-10 02:13:57 +03:00
|
|
|
METHOD_REGEXP_STR = /(
|
|
|
|
(?!\d)[\w#{RDoc::Markup::AttributeManager::PROTECT_ATTR}]+[!?=]?|
|
|
|
|
%|=(?:==?|~)|![=~]|\[\]=?|<(?:<|=>?)?|>[>=]?|[-+!]@?|\*\*?|[\/%\`|&^~]
|
|
|
|
)#{METHOD_ARGS_REGEXP_STR}/.source.delete("\n ").freeze
|
2011-07-31 04:19:00 +04:00
|
|
|
|
|
|
|
##
|
|
|
|
# Regular expressions matching text that should potentially have
|
2018-10-17 09:28:20 +03:00
|
|
|
# cross-reference links generated are passed to add_regexp_handling. Note
|
|
|
|
# that these expressions are meant to pick up text for which cross-references
|
2011-07-31 04:19:00 +04:00
|
|
|
# have been suppressed, since the suppression characters are removed by the
|
|
|
|
# code that is triggered.
|
|
|
|
|
2019-10-25 09:03:18 +03:00
|
|
|
CROSSREF_REGEXP = /(?:^|[\s()])
|
2012-11-27 08:28:14 +04:00
|
|
|
(
|
|
|
|
(?:
|
|
|
|
# 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)
|
|
|
|
|
2021-12-04 12:05:37 +03:00
|
|
|
# Stand-alone method (preceded by a #)
|
|
|
|
| \\?\##{METHOD_REGEXP_STR}
|
|
|
|
|
|
|
|
# Stand-alone method (preceded by ::)
|
|
|
|
| ::#{METHOD_REGEXP_STR}
|
|
|
|
|
2012-11-27 08:28:14 +04:00
|
|
|
# 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
|
2011-07-31 04:19:00 +04:00
|
|
|
|
|
|
|
##
|
|
|
|
# Version of CROSSREF_REGEXP used when <tt>--hyperlink-all</tt> is specified.
|
|
|
|
|
2012-11-27 08:28:14 +04:00
|
|
|
ALL_CROSSREF_REGEXP = /
|
2019-10-26 10:26:48 +03:00
|
|
|
(?:^|[\s()])
|
2012-11-27 08:28:14 +04:00
|
|
|
(
|
|
|
|
(?:
|
|
|
|
# A::B::C.meth
|
|
|
|
#{CLASS_REGEXP_STR}(?:[.#]|::)#{METHOD_REGEXP_STR}
|
2011-07-31 04:19:00 +04:00
|
|
|
|
2012-11-27 08:28:14 +04:00
|
|
|
# A::B::C
|
|
|
|
| #{CLASS_REGEXP_STR}(?=[@\s).?!,;<\000]|\z)
|
2011-07-31 04:19:00 +04:00
|
|
|
|
2021-12-04 12:05:37 +03:00
|
|
|
# Stand-alone method
|
|
|
|
| \\?#{METHOD_REGEXP_STR}
|
|
|
|
|
2012-11-27 08:28:14 +04:00
|
|
|
# Things that look like filenames
|
|
|
|
| (?:\.\.\/)*[-\/\w]+[_\/.][-\w\/.]+
|
2011-07-31 04:19:00 +04:00
|
|
|
|
2012-11-27 08:28:14 +04:00
|
|
|
# Things that have markup suppressed
|
|
|
|
| \\[^\s<]
|
|
|
|
)
|
|
|
|
|
|
|
|
# labels for headings
|
|
|
|
(?:@[\w+%-]+)?
|
|
|
|
)/x
|
|
|
|
|
|
|
|
##
|
|
|
|
# Hash of references that have been looked-up to their replacements
|
2011-07-31 04:19:00 +04:00
|
|
|
|
|
|
|
attr_accessor :seen
|
|
|
|
|
|
|
|
##
|
|
|
|
# Allows cross-references to be created based on the given +context+
|
|
|
|
# (RDoc::Context).
|
|
|
|
|
|
|
|
def initialize context
|
|
|
|
@context = context
|
2012-11-27 08:28:14 +04:00
|
|
|
@store = context.store
|
2011-07-31 04:19:00 +04:00
|
|
|
|
|
|
|
@seen = {}
|
|
|
|
end
|
|
|
|
|
2021-12-04 12:05:37 +03:00
|
|
|
def resolve_method name
|
|
|
|
ref = nil
|
2011-07-31 04:19:00 +04:00
|
|
|
|
|
|
|
if /#{CLASS_REGEXP_STR}([.#]|::)#{METHOD_REGEXP_STR}/o =~ name then
|
|
|
|
type = $2
|
2018-08-27 04:30:18 +03:00
|
|
|
if '.' == type # will find either #method or ::method
|
|
|
|
method = $3
|
|
|
|
else
|
|
|
|
method = "#{type}#{$3}"
|
|
|
|
end
|
2011-07-31 04:19:00 +04:00
|
|
|
container = @context.find_symbol_module($1)
|
|
|
|
elsif /^([.#]|::)#{METHOD_REGEXP_STR}/o =~ name then
|
|
|
|
type = $1
|
2018-08-27 04:30:18 +03:00
|
|
|
if '.' == type
|
|
|
|
method = $2
|
|
|
|
else
|
|
|
|
method = "#{type}#{$2}"
|
|
|
|
end
|
2011-07-31 04:19:00 +04:00
|
|
|
container = @context
|
|
|
|
else
|
2018-08-27 04:30:18 +03:00
|
|
|
type = nil
|
2011-07-31 04:19:00 +04:00
|
|
|
container = nil
|
|
|
|
end
|
|
|
|
|
|
|
|
if container then
|
2018-08-27 04:30:18 +03:00
|
|
|
unless RDoc::TopLevel === container then
|
|
|
|
if '.' == type then
|
|
|
|
if 'new' == method then # AnyClassName.new will be class method
|
|
|
|
ref = container.find_local_symbol method
|
|
|
|
ref = container.find_ancestor_local_symbol method unless ref
|
|
|
|
else
|
|
|
|
ref = container.find_local_symbol "::#{method}"
|
|
|
|
ref = container.find_ancestor_local_symbol "::#{method}" unless ref
|
|
|
|
ref = container.find_local_symbol "##{method}" unless ref
|
|
|
|
ref = container.find_ancestor_local_symbol "##{method}" unless ref
|
|
|
|
end
|
|
|
|
else
|
|
|
|
ref = container.find_local_symbol method
|
|
|
|
ref = container.find_ancestor_local_symbol method unless ref
|
|
|
|
end
|
2011-07-31 04:19:00 +04:00
|
|
|
end
|
|
|
|
end
|
|
|
|
|
2021-12-04 12:05:37 +03:00
|
|
|
ref
|
|
|
|
end
|
|
|
|
|
|
|
|
##
|
|
|
|
# Returns a reference to +name+.
|
|
|
|
#
|
|
|
|
# If the reference is found and +name+ is not documented +text+ will be
|
|
|
|
# returned. If +name+ is escaped +name+ is returned. If +name+ is not
|
|
|
|
# found +text+ is returned.
|
|
|
|
|
|
|
|
def resolve name, text
|
|
|
|
return @seen[name] if @seen.include? name
|
|
|
|
|
2011-07-31 04:19:00 +04:00
|
|
|
ref = case name
|
|
|
|
when /^\\(#{CLASS_REGEXP_STR})$/o then
|
2012-11-27 08:28:14 +04:00
|
|
|
@context.find_symbol $1
|
2011-07-31 04:19:00 +04:00
|
|
|
else
|
2012-11-27 08:28:14 +04:00
|
|
|
@context.find_symbol name
|
2021-12-04 12:05:37 +03:00
|
|
|
end
|
|
|
|
|
|
|
|
ref = resolve_method name unless ref
|
2011-07-31 04:19:00 +04:00
|
|
|
|
2012-11-27 08:28:14 +04:00
|
|
|
# Try a page name
|
2020-08-04 09:46:39 +03:00
|
|
|
ref = @store.page name if not ref and name =~ /^[\w.]+$/
|
2012-11-27 08:28:14 +04:00
|
|
|
|
|
|
|
ref = nil if RDoc::Alias === ref # external alias, can't link to it
|
2011-07-31 04:19:00 +04:00
|
|
|
|
|
|
|
out = if name == '\\' then
|
|
|
|
name
|
|
|
|
elsif name =~ /^\\/ then
|
|
|
|
# we remove the \ only in front of what we know:
|
|
|
|
# other backslashes are treated later, only outside of <tt>
|
|
|
|
ref ? $' : name
|
|
|
|
elsif ref then
|
|
|
|
if ref.display? then
|
|
|
|
ref
|
|
|
|
else
|
|
|
|
text
|
|
|
|
end
|
|
|
|
else
|
|
|
|
text
|
|
|
|
end
|
|
|
|
|
|
|
|
@seen[name] = out
|
|
|
|
|
|
|
|
out
|
|
|
|
end
|
|
|
|
|
|
|
|
end
|
|
|
|
|