Class Parser::Source::Comment::Associator
In: lib/parser/source/comment/associator.rb
Parent: Object

A processor which associates AST nodes with comments based on their location in source code. It may be used, for example, to implement rdoc-style processing.

@example 

  require 'parser/current'

  ast, comments = Parser::CurrentRuby.parse_with_comments(<<-CODE)
  # Class stuff
  class Foo
    # Attr stuff
    # @see bar
    attr_accessor :foo
  end
  CODE

  p Parser::Source::Comment.associate(ast, comments)
  # => {
  #   (class (const nil :Foo) ...) =>
  #     [#<Parser::Source::Comment (string):1:1 "# Class stuff">],
  #   (send nil :attr_accessor (sym :foo)) =>
  #     [#<Parser::Source::Comment (string):3:3 "# Attr stuff">,
  #      #<Parser::Source::Comment (string):4:3 "# @see bar">]
  # }

@see {associate}

@!attribute skip_directives 

 Skip file processing directives disguised as comments.
 Namely:

   * Shebang line,
   * Magic encoding comment.

 @return [Boolean]

@api public

Methods

associate   associate_locations   new  

Constants

MAGIC_COMMENT_RE = /^#\s*(-\*-|)\s*(frozen_string_literal|warn_indent|warn_past_scope):.*\1$/

Attributes

skip_directives  [RW] 

Public Class methods

Public Instance methods

associate()

Compute a mapping between AST nodes and comments. Comment is associated with the node, if it is one of the following types:

  • preceding comment, it ends before the node start
  • sparse comment, it is located inside the node, after all child nodes
  • decorating comment, it starts at the same line, where the node ends

This rule is unambiguous and produces the result one could reasonably expect; for example, this code 

    # foo
    hoge # bar
      + fuga

will result in the following association: 

    {
      (send (lvar :hoge) :+ (lvar :fuga)) =>
        [#<Parser::Source::Comment (string):2:1 "# foo">],
      (lvar :fuga) =>
        [#<Parser::Source::Comment (string):3:8 "# bar">]
    }

Note that comments after the end of the end of a passed tree range are ignored (except root decorating comment).

Note that {associate} produces unexpected result for nodes which are equal but have distinct locations; comments for these nodes are merged.

@return [Hash(Parser::AST::Node, Array(Parser::Source::Comment))] @deprecated Use {associate_locations}.

associate_locations()

Same as {associate}, but uses `node.loc` instead of `node` as the hash key, thus producing an unambiguous result even in presence of equal nodes.

@return [Hash(Parser::Source::Map, Array(Parser::Source::Comment))]

[Validate]