Class: RDoc::Parser::Ruby

# File 'lib/rdoc/parser/ruby.rb', line 135

attr_reader :container, :singleton, :in_proc_block

# File 'lib/rdoc/parser/ruby.rb', line 135

attr_reader :container, :singleton, :in_proc_block

# File 'lib/rdoc/parser/ruby.rb', line 134

attr_accessor :visibility

# File 'lib/rdoc/parser/ruby.rb', line 578

def add_attributes(names, rw, line_no)
  comment, directives, type_signature_lines = consecutive_comment(line_no)
  handle_code_object_directives(@container, directives) if directives
  return unless @container.document_children

  names.each do |symbol|
    a = RDoc::Attr.new(symbol.to_s, rw, comment, singleton: @singleton)
    a.store = @store
    a.line = line_no
    a.type_signature_lines = type_signature_lines
    record_location(a)
    handle_modifier_directive(a, line_no)
    @container.add_attribute(a) if should_document?(a)
    a.visibility = visibility # should set after adding to container
  end
end

# File 'lib/rdoc/parser/ruby.rb', line 756

def add_constant(constant_name, rhs_name, start_line, end_line, alias_path: nil)
  comment, directives = consecutive_comment(start_line)
  handle_code_object_directives(@container, directives) if directives
  owner, name = find_or_create_lexical_constant_owner_name(constant_name)
  return unless owner

  constant = RDoc::Constant.new(name, rhs_name, comment)
  constant.store = @store
  constant.line = start_line
  constant.is_alias_for_path = alias_path
  record_location(constant)
  handle_modifier_directive(constant, start_line)
  handle_modifier_directive(constant, end_line)
  owner.add_constant(constant)
  return unless alias_path
  mod =
    if alias_path.start_with?('::')
      @store.find_class_or_module(alias_path)
    else
      full_name = resolve_constant_path(alias_path)
      @store.find_class_or_module(full_name)
    end
  if mod && constant.document_self
    a = owner.add_module_alias(mod, alias_path, constant, @top_level)
    a.store = @store
    a.line = start_line
    record_location(a)
  end
end

# File 'lib/rdoc/parser/ruby.rb', line 618

def add_extends(names, line_no) # :nodoc:
  add_includes_extends(names, RDoc::Extend, line_no)
end

# File 'lib/rdoc/parser/ruby.rb', line 612

def add_includes(names, line_no) # :nodoc:
  add_includes_extends(names, RDoc::Include, line_no)
end

# File 'lib/rdoc/parser/ruby.rb', line 597

def add_includes_extends(names, rdoc_class, line_no) # :nodoc:
  comment, directives = consecutive_comment(line_no)
  handle_code_object_directives(@container, directives) if directives
  names.each do |name|
    resolved_name = resolve_constant_path(name)
    ie = @container.add(rdoc_class, resolved_name || name, '')
    ie.store = @store
    ie.line = line_no
    ie.comment = comment
    record_location(ie)
  end
end

# File 'lib/rdoc/parser/ruby.rb', line 624

def add_method(method_name, receiver_name:, receiver_fallback_type:, visibility:, singleton:, params:, calls_super:, block_params:, tokens:, start_line:, args_end_line:, end_line:)
  receiver = receiver_name ? find_or_create_lexical_module_path(receiver_name, receiver_fallback_type) : @container
  comment, directives, type_signature_lines = consecutive_comment(start_line)
  handle_code_object_directives(@container, directives) if directives

  internal_add_method(
    method_name,
    receiver,
    comment: comment,
    directives: directives,
    modifier_comment_lines: [start_line, args_end_line, end_line].uniq,
    line_no: start_line,
    visibility: visibility,
    singleton: singleton,
    params: params,
    calls_super: calls_super,
    block_params: block_params,
    tokens: tokens,
    type_signature_lines: type_signature_lines
  )
end

# File 'lib/rdoc/parser/ruby.rb', line 788

def add_module_or_class(module_name, start_line, end_line, is_class: false, superclass_name: nil, superclass_expr: nil)
  comment, directives = consecutive_comment(start_line)
  handle_code_object_directives(@container, directives) if directives
  return unless @container.document_children

  owner, name = find_or_create_lexical_constant_owner_name(module_name)
  return unless owner

  if is_class
    # RDoc::NormalClass resolves superclass name despite of the lack of module nesting information.
    # We need to fix it when RDoc::NormalClass resolved to a wrong constant name
    if superclass_name
      superclass_full_path = resolve_constant_path(superclass_name)
      superclass = @store.find_class_or_module(superclass_full_path) if superclass_full_path
      superclass_full_path ||= superclass_name
      superclass_full_path = superclass_full_path.sub(/^::/, '')
    end
    # add_class should be done after resolving superclass
    mod = owner.classes_hash[name] || owner.add_class(RDoc::NormalClass, name, superclass_name || superclass_expr || '::Object')
    if superclass_name
      if superclass
        mod.superclass = superclass
      elsif (mod.superclass.is_a?(String) || mod.superclass.name == 'Object') && mod.superclass != superclass_full_path
        mod.superclass = superclass_full_path
      end
    end
  else
    mod = owner.modules_hash[name] || owner.add_module(RDoc::NormalModule, name)
  end

  mod.store = @store
  mod.line = start_line
  record_location(mod)
  handle_modifier_directive(mod, start_line)
  handle_modifier_directive(mod, end_line)
  mod.add_comment(comment, @top_level) if comment
  mod
end

# File 'lib/rdoc/parser/ruby.rb', line 341

def call_node_name_arguments(call_node) # :nodoc:
  return [] unless call_node.arguments
  call_node.arguments.arguments.map do |arg|
    case arg
    when Prism::SymbolNode
      arg.value
    when Prism::StringNode
      arg.unescaped
    end
  end || []
end

# File 'lib/rdoc/parser/ruby.rb', line 533

def change_method_to_module_function(names)
  @container.set_visibility_for(names, :private, false)
  new_methods = []
  @container.methods_matching(names) do |m|
    s_m = m.dup
    record_location(s_m)
    s_m.singleton = true
    new_methods << s_m
  end
  new_methods.each do |method|
    case method
    when RDoc::AnyMethod then
      @container.add_method(method)
    when RDoc::Attr then
      @container.add_attribute(method)
    end
    method.visibility = :public
  end
end

# File 'lib/rdoc/parser/ruby.rb', line 509

def change_method_visibility(names, visibility, singleton: @singleton)
  new_methods = []
  @container.methods_matching(names, singleton) do |m|
    if m.parent != @container
      m = m.dup
      record_location(m)
      new_methods << m
    else
      m.visibility = visibility
    end
  end
  new_methods.each do |method|
    case method
    when RDoc::AnyMethod then
      @container.add_method(method)
    when RDoc::Attr then
      @container.add_attribute(method)
    end
    method.visibility = visibility
  end
end

# File 'lib/rdoc/parser/ruby.rb', line 461

def consecutive_comment(line_no)
  return unless @unprocessed_comments.first&.first == line_no
  _line_no, start_line, text = @unprocessed_comments.shift
  parse_comment_text_to_directives(text, start_line)
end

# File 'lib/rdoc/parser/ruby.rb', line 493

def extract_section_comment(comment_text, prefix_line_count) # :nodoc:
  prefix = comment_text.lines[0...prefix_line_count].join
  comment_text.delete_prefix!(prefix)
  # Comment is already normalized and doesn't end with a newline
  comment_text.delete_suffix!(prefix.chomp)
  comment_text
end

# File 'lib/rdoc/parser/ruby.rb', line 834

def extract_type_signature!(text, start_line)
  return nil unless text.include?('#:')

  lines = text.lines
  sig_lines, doc_lines = lines.partition { |l| l.match?(RBS_SIG_LINE) }
  return nil if sig_lines.empty?

  first_sig_line = start_line + lines.index(sig_lines.first)
  text.replace(doc_lines.join)
  type_signature_lines = sig_lines.map { |l| l.sub(RBS_SIG_LINE, '').strip }.reject(&:empty?)
  return nil if type_signature_lines.empty?

  warn_invalid_type_signature(type_signature_lines, first_sig_line)
  type_signature_lines
end

# File 'lib/rdoc/parser/ruby.rb', line 740

def find_or_create_lexical_constant_owner_name(constant_path)
  const_path, colon, name = constant_path.rpartition('::')
  if colon.empty? # class Foo
    # Within `class C` or `module C`, owner is C(== current container)
    # Within `class <<C`, owner is C.singleton_class
    # but RDoc don't track constants of a singleton class of module
    [(@singleton ? nil : @container), name]
  elsif const_path.empty? # class ::Foo
    [@top_level, name]
  else # `class Foo::Bar` or `class ::Foo::Bar`
    [find_or_create_lexical_module_path(const_path, :module), name]
  end
end

# File 'lib/rdoc/parser/ruby.rb', line 691

def find_or_create_lexical_module_path(module_name, create_mode)
  root_name, *path, name = module_name.split('::')
  add_module = ->(mod, name, mode) {
    case mode
    when :class
      mod.add_class(RDoc::NormalClass, name, 'Object').tap { |m| m.store = @store }
    when :module
      mod.add_module(RDoc::NormalModule, name).tap { |m| m.store = @store }
    end
  }
  if root_name.empty?
    mod = @top_level
  else
    @module_nesting.reverse_each do |nesting, singleton|
      next if singleton
      mod = nesting.get_module_named(root_name)
      break if mod
      # If a constant is found and it is not a module or class, RDoc can't document about it.
      # Return an anonymous module to avoid wrong document creation.
      return RDoc::NormalModule.new(nil) if nesting.find_constant_named(root_name)
    end
    last_nesting, = @module_nesting.reverse_each.find { |_, singleton| !singleton }
    return mod || add_module.call(last_nesting, root_name, create_mode) unless name
    mod ||= add_module.call(last_nesting, root_name, :module)
  end
  path.each do |name|
    mod = mod.get_module_named(name) || add_module.call(mod, name, :module)
  end
  mod.get_module_named(name) || add_module.call(mod, name, create_mode)
end

# File 'lib/rdoc/parser/ruby.rb', line 553

def handle_code_object_directives(code_object, directives) # :nodoc:
  directives.each do |directive, (param)|
    @preprocess.handle_directive('', directive, param, code_object)
  end
end

# File 'lib/rdoc/parser/ruby.rb', line 355

def handle_meta_method_comment(comment, directives, node)
  handle_code_object_directives(@container, directives)
  is_call_node = node.is_a?(Prism::CallNode)
  singleton_method = false
  visibility = @visibility
  attributes = rw = line_no = method_name = nil
  directives.each do |directive, (param, line)|
    case directive
    when 'attr', 'attr_reader', 'attr_writer', 'attr_accessor'
      attributes = [param] if param
      attributes ||= call_node_name_arguments(node) if is_call_node
      rw = directive == 'attr_writer' ? 'W' : directive == 'attr_accessor' ? 'RW' : 'R'
    when 'method'
      method_name = param if param
      line_no = line
    when 'singleton-method'
      method_name = param if param
      line_no = line
      singleton_method = true
      visibility = :public
    end
  end

  if attributes
    attributes.each do |attr|
      a = RDoc::Attr.new(attr, rw, comment, singleton: @singleton)
      a.store = @store
      a.line = line_no
      record_location(a)
      @container.add_attribute(a)
      a.visibility = visibility
    end
  elsif line_no || node
    method_name ||= call_node_name_arguments(node).first if is_call_node
    if node
      tokens = syntax_highlighted_tokens(node)
      line_no = node.location.start_line
    else
      tokens = []
    end
    internal_add_method(
      method_name,
      @container,
      comment: comment,
      directives: directives,
      dont_rename_initialize: false,
      line_no: line_no,
      visibility: visibility,
      singleton: @singleton || singleton_method,
      params: nil,
      calls_super: false,
      block_params: nil,
      tokens: tokens,
    )
  end
end

# File 'lib/rdoc/parser/ruby.rb', line 334

def handle_modifier_directive(code_object, line_no) # :nodoc:
  if (comment_text = @modifier_comments[line_no])
    _text, directives = @preprocess.parse_comment(comment_text, line_no, :ruby)
    handle_code_object_directives(code_object, directives)
  end
end

# File 'lib/rdoc/parser/ruby.rb', line 423

def handle_standalone_consecutive_comment_directive(comment, directives, start_with_sharp_sharp, line_no, start_line) # :nodoc:
  if start_with_sharp_sharp && start_line != @first_non_meta_comment_start_line
    node = @line_nodes[line_no]
    handle_meta_method_comment(comment, directives, node)
  elsif normal_comment_treat_as_ghost_method_for_now?(directives, line_no) && start_line != @first_non_meta_comment_start_line
    handle_meta_method_comment(comment, directives, nil)
  else
    handle_code_object_directives(@container, directives)
  end
end

# File 'lib/rdoc/parser/ruby.rb', line 330

def has_modifier_nodoc?(line_no) # :nodoc:
  @modifier_comments[line_no]&.match?(/\A#\s*:nodoc:/)
end

# File 'lib/rdoc/parser/ruby.rb', line 646

private def internal_add_method(method_name, container, comment:, dont_rename_initialize: false, directives:, modifier_comment_lines: nil, line_no:, visibility:, singleton:, params:, calls_super:, block_params:, tokens:, type_signature_lines: nil) # :nodoc:
  meth = RDoc::AnyMethod.new(method_name, singleton: singleton)
  meth.comment = comment
  handle_code_object_directives(meth, directives) if directives
  modifier_comment_lines&.each do |line|
    handle_modifier_directive(meth, line)
  end
  return unless should_document?(meth)

  if directives && (call_seq, = directives['call-seq'])
    meth.call_seq = call_seq.lines.map(&:chomp).reject(&:empty?).join("\n") if call_seq
  end
  meth.name ||= meth.call_seq[/\A[^()\s]+/] if meth.call_seq
  meth.name ||= 'unknown'
  meth.store = @store
  meth.line = line_no
  container.add_method(meth) # should add after setting singleton and before setting visibility
  meth.visibility = visibility
  meth.params ||= params || '()'
  meth.calls_super = calls_super
  meth.block_params ||= block_params if block_params
  meth.type_signature_lines = type_signature_lines
  record_location(meth)
  meth.start_collecting_tokens(:ruby)
  tokens.each do |token|
    meth.token_stream << token
  end

  # Rename after add_method to register duplicated 'new' and 'initialize'
  # defined in c and ruby.
  if !dont_rename_initialize && method_name == 'initialize' && !singleton
    if meth.dont_rename_initialize
      meth.visibility = :protected
    else
      meth.name = 'new'
      meth.singleton = true
      meth.visibility = :public
    end
  end
end

# File 'lib/rdoc/parser/ruby.rb', line 417

def normal_comment_treat_as_ghost_method_for_now?(directives, line_no) # :nodoc:
  # Meta method comment should start with `##` but some comments does not follow this rule.
  # For now, RDoc accepts them as a meta method comment if there is no node linked to it.
  !@line_nodes[line_no] && INVALID_GHOST_METHOD_ACCEPT_DIRECTIVE_LIST.any? { |directive| directives.has_key?(directive) }
end

# File 'lib/rdoc/parser/ruby.rb', line 471

def parse_comment_text_to_directives(comment_text, start_line) # :nodoc:
  type_signature_lines = extract_type_signature!(comment_text, start_line)
  comment_text, directives = @preprocess.parse_comment(comment_text, start_line, :ruby)
  comment = RDoc::Comment.new(comment_text, @top_level, :ruby)
  comment.normalized = true
  comment.line = start_line
  markup, = directives['markup']
  comment.format = markup&.downcase || @markup
  if (section, directive_line = directives['section'])
    # If comment has :section:, it is not a documentable comment for a code object
    comment.text = extract_section_comment(comment_text, directive_line - start_line)
    @container.set_current_section(section, comment)
    return
  end
  @preprocess.run_post_processes(comment, @container)
  [comment, directives, type_signature_lines]
end

# File 'lib/rdoc/parser/ruby.rb', line 309

def parse_comment_tomdoc(container, comment, line_no, start_line)
  return unless signature = RDoc::TomDoc.signature(comment)

  name, = signature.split %r%[ \(]%, 2

  meth = RDoc::AnyMethod.new name
  record_location(meth)
  meth.line = start_line
  meth.call_seq = signature
  return unless meth.name

  meth.start_collecting_tokens(:ruby)
  node = @line_nodes[line_no]
  tokens = node ? syntax_highlighted_tokens(node) : []
  tokens.each { |token| meth.token_stream << token }

  container.add_method meth
  meth.comment = comment
  @stats.add_method meth
end

# File 'lib/rdoc/parser/ruby.rb', line 259

def prepare_comments(comments)
  current = []
  consecutive_comments = [current]
  @modifier_comments = {}
  comments.each do |comment|
    if comment.is_a? Prism::EmbDocComment
      consecutive_comments << [comment] << (current = [])
    elsif comment.location.start_line_slice.match?(/\S/)
      text = comment.slice
      text = RDoc::Encoding.change_encoding(text, @encoding) if @encoding
      @modifier_comments[comment.location.start_line] = text
    elsif current.empty? || current.last.location.end_line + 1 == comment.location.start_line
      current << comment
    else
      consecutive_comments << (current = [comment])
    end
  end
  consecutive_comments.reject!(&:empty?)

  # Example: line_no = 5, start_line = 2, comment_text = "# comment_start_line\n# comment\n"
  # 1| class A
  # 2|   # comment_start_line
  # 3|   # comment
  # 4|
  # 5|   def f; end # comment linked to this line
  # 6| end
  @unprocessed_comments = consecutive_comments.map! do |comments|
    start_line = comments.first.location.start_line
    line_no = comments.last.location.end_line + (comments.last.location.end_column == 0 ? 0 : 1)
    texts = comments.map do |c|
      c.is_a?(Prism::EmbDocComment) ? c.slice.lines[1...-1].join : c.slice
    end
    text = texts.join("\n")
    text = RDoc::Encoding.change_encoding(text, @encoding) if @encoding
    line_no += 1 while @lines[line_no - 1]&.match?(/\A\s*$/)
    [line_no, start_line, text]
  end

  # The first comment is special. It defines markup for the rest of the comments.
  _, first_comment_start_line, first_comment_text = @unprocessed_comments.first
  if first_comment_text && @lines[0...first_comment_start_line - 1].all? { |l| l.match?(/\A\s*$/) }
    _text, directives = @preprocess.parse_comment(first_comment_text, first_comment_start_line, :ruby)
    markup, = directives['markup']
    @markup = markup.downcase if markup
  end
end

# File 'lib/rdoc/parser/ruby.rb', line 233

def prepare_line_nodes(node) # :nodoc:
  case node
  when Prism::CallNode, Prism::DefNode
    @line_nodes[node.location.start_line] ||= node
  end
  node.compact_child_nodes.each do |child|
    prepare_line_nodes(child)
  end
end

# File 'lib/rdoc/parser/ruby.rb', line 436

def process_comments_until(line_no_until)
  while !@unprocessed_comments.empty? && @unprocessed_comments.first[0] <= line_no_until
    line_no, start_line, text = @unprocessed_comments.shift
    if @markup == 'tomdoc'
      comment = RDoc::Comment.new(text, @top_level, :ruby)
      comment.format = 'tomdoc'
      parse_comment_tomdoc(@container, comment, line_no, start_line)
      @preprocess.run_post_processes(comment, @container)
    elsif (comment_text, directives = parse_comment_text_to_directives(text, start_line))
      handle_standalone_consecutive_comment_directive(comment_text, directives, text.start_with?(/#\#$/), line_no, start_line)
    end
  end
end

# File 'lib/rdoc/parser/ruby.rb', line 192

def record_location(container) # :nodoc:
  case container
  when RDoc::ClassModule then
    @top_level.add_to_classes_or_modules container
  end

  container.record_location @top_level
end

# File 'lib/rdoc/parser/ruby.rb', line 724

def resolve_constant_path(constant_path)
  owner_name, path = constant_path.split('::', 2)
  return constant_path if owner_name.empty? # ::Foo, ::Foo::Bar
  mod = nil
  @module_nesting.reverse_each do |nesting, singleton|
    next if singleton
    mod = nesting.get_module_named(owner_name)
    break if mod
  end
  mod ||= @top_level.get_module_named(owner_name)
  [mod.full_name, path].compact.join('::') if mod
end

# File 'lib/rdoc/parser/ruby.rb', line 203

def scan
  @lines = @content.lines
  result = Prism.parse_lex(@content)
  @program_node, unordered_tokens = result.value
  # Heredoc tokens are not in start_offset order.
  # Need to sort them to use bsearch for finding tokens from location.
  @prism_tokens = unordered_tokens.map(&:first).sort_by { |t| t.location.start_offset }
  @line_nodes = {}
  prepare_line_nodes(@program_node)
  prepare_comments(result.comments)
  return if @top_level.done_documenting

  @first_non_meta_comment_start_line = nil
  if (_line_no, start_line = @unprocessed_comments.first)
    @first_non_meta_comment_start_line = start_line if start_line < @program_node.location.start_line
  end

  @program_node.accept(RDocVisitor.new(self, @top_level, @store))
  process_comments_until(@lines.size + 1)
end

# File 'lib/rdoc/parser/ruby.rb', line 224

def should_document?(code_object) # :nodoc:
  return true unless @track_visibility
  return false if code_object.parent&.document_children == false
  code_object.document_self
end

# File 'lib/rdoc/parser/ruby.rb', line 453

def skip_comments_until(line_no_until)
  while !@unprocessed_comments.empty? && @unprocessed_comments.first[0] <= line_no_until
    @unprocessed_comments.shift
  end
end

# File 'lib/rdoc/parser/ruby.rb', line 503

def syntax_highlighted_tokens(node)
  RDoc::Parser::RubyColorizer.partial_colorize(@content, node, @prism_tokens)
end

# File 'lib/rdoc/parser/ruby.rb', line 850

def warn_invalid_type_signature(type_signature_lines, line_no)
  type_signature_lines.each_with_index do |line, i|
    next if RDoc::RbsHelper.valid_method_type?(line)
    next if RDoc::RbsHelper.valid_type?(line)
    @options.warn "#{@top_level.relative_name}:#{line_no + i}: invalid RBS type signature: #{line.inspect}"
  end
end

# File 'lib/rdoc/parser/ruby.rb', line 170

def with_container(container, singleton: false)
  old_container = @container
  old_visibility = @visibility
  old_singleton = @singleton
  old_in_proc_block = @in_proc_block
  @visibility = :public
  @container = container
  @singleton = singleton
  @in_proc_block = false
  @module_nesting.push([container, singleton])
  yield container
ensure
  @container = old_container
  @visibility = old_visibility
  @singleton = old_singleton
  @in_proc_block = old_in_proc_block
  @module_nesting.pop
end

# File 'lib/rdoc/parser/ruby.rb', line 161

def with_in_proc_block
  in_proc_block = @in_proc_block
  @in_proc_block = true
  yield
  @in_proc_block = in_proc_block
end