class Ruby::Prism::Location

This represents a location in the source.

Attributes

length [R]

The length of this location in bytes.

source [R]

A Source object that is used to determine more information from the given offset and length.

start_offset [R]

The byte offset from the beginning of the source where this location starts.

Public Class Methods

new (source, start_offset, length)

Create a new location object with the given source, start byte offset, and byte length.

: (Source source, Integer start_offset, Integer length) -> void

# File lib/ruby/prism/parse_result.rb, line 416
def initialize(source, start_offset, length)
  @source = source
  @start_offset = start_offset
  @length = length

  # These are used to store comments that are associated with this location.
  # They are initialized to `nil` to save on memory when there are no
  # comments to be attached and/or the comment-related APIs are not used.
  @leading_comments = nil
  @trailing_comments = nil
end

Public Instance Methods

== (other)

Returns true if the given other location is equal to this location.

: (untyped other) -> bool

# File lib/ruby/prism/parse_result.rb, line 668
def ==(other)
  Location === other &&
    other.start_offset == start_offset &&
    other.end_offset == end_offset
end

adjoin (string)

Join this location with the first occurrence of the string in the source that occurs after this location on the same line, and return the new location. This will raise an error if the string does not exist.

: (String string) -> Location

# File lib/ruby/prism/parse_result.rb, line 691
def adjoin(string)
  line_suffix = source.slice(end_offset, source.line_end(end_offset) - end_offset)

  line_suffix_index = line_suffix.byteindex(string)
  raise "Could not find #{string}" if line_suffix_index.nil?

  Location.new(source, start_offset, length + line_suffix_index + string.bytesize)
end

cached_end_code_units_column (cache)

The end column in code units using the given cache to fetch or calculate the value.

: (_CodeUnitsCache cache) -> Integer

# File lib/ruby/prism/parse_result.rb, line 647
def cached_end_code_units_column(cache)
  cache[end_offset] - cache[source.line_start(end_offset)]
end

cached_end_code_units_offset (cache)

The end offset from the start of the file in code units using the given cache to fetch or calculate the value.

: (_CodeUnitsCache cache) -> Integer

# File lib/ruby/prism/parse_result.rb, line 561
def cached_end_code_units_offset(cache)
  cache[end_offset]
end

cached_start_code_units_column (cache)

The start column in code units using the given cache to fetch or calculate the value.

: (_CodeUnitsCache cache) -> Integer

# File lib/ruby/prism/parse_result.rb, line 615
def cached_start_code_units_column(cache)
  cache[start_offset] - cache[source.line_start(start_offset)]
end

cached_start_code_units_offset (cache)

The start offset from the start of the file in code units using the given cache to fetch or calculate the value.

: (_CodeUnitsCache cache) -> Integer

# File lib/ruby/prism/parse_result.rb, line 531
def cached_start_code_units_offset(cache)
  cache[start_offset]
end

chop ()

Returns a new location that is the result of chopping off the last byte.

: () -> Location

# File lib/ruby/prism/parse_result.rb, line 476
def chop
  copy(length: length == 0 ? length : length - 1)
end

comments ()

Returns all comments that are associated with this location (both leading and trailing comments).

: () -> Array

# File lib/ruby/prism/parse_result.rb, line 462
def comments
  [*@leading_comments, *@trailing_comments] #: Array[Comment]
end

copy (source: self.source, start_offset: self.start_offset, length: self.length)

Create a new location object with the given options.

: (?source: Source, ?start_offset: Integer, ?length: Integer) -> Location

# File lib/ruby/prism/parse_result.rb, line 469
def copy(source: self.source, start_offset: self.start_offset, length: self.length)
  Location.new(source, start_offset, length)
end

end_character_column ()

The column in characters where this location ends from the start of the line.

: () -> Integer

# File lib/ruby/prism/parse_result.rb, line 631
def end_character_column
  source.character_column(end_offset)
end

end_character_offset ()

The character offset from the beginning of the source where this location ends.

: () -> Integer

# File lib/ruby/prism/parse_result.rb, line 546
def end_character_offset
  source.character_offset(end_offset)
end

end_code_units_column (encoding = Encoding::UTF_16LE)

The column in code units of the given encoding where this location ends from the start of the line.

: (?Encoding encoding) -> Integer

# File lib/ruby/prism/parse_result.rb, line 639
def end_code_units_column(encoding = Encoding::UTF_16LE)
  source.code_units_column(end_offset, encoding)
end

end_code_units_offset (encoding = Encoding::UTF_16LE)

The offset from the start of the file in code units of the given encoding.

: (Encoding encoding) -> Integer

# File lib/ruby/prism/parse_result.rb, line 553
def end_code_units_offset(encoding = Encoding::UTF_16LE)
  source.code_units_offset(end_offset, encoding)
end

end_column ()

The column in bytes where this location ends from the start of the line.

: () -> Integer

# File lib/ruby/prism/parse_result.rb, line 623
def end_column
  source.column(end_offset)
end

end_line ()

The line number where this location ends.

: () -> Integer

# File lib/ruby/prism/parse_result.rb, line 583
def end_line
  source.line(end_offset)
end

end_offset ()

The byte offset from the beginning of the source where this location ends.

: () -> Integer

# File lib/ruby/prism/parse_result.rb, line 538
def end_offset
  start_offset + length
end

join (other)

Returns a new location that stretches from this location to the given other location. Raises an error if this location is not before the other location or if they don’t share the same source.

: (Location other) -> Location

# File lib/ruby/prism/parse_result.rb, line 679
def join(other)
  raise "Incompatible sources" if source != other.source
  raise "Incompatible locations" if start_offset > other.start_offset

  Location.new(source, start_offset, other.end_offset - start_offset)
end

leading_comment (comment)

Attach a comment to the leading comments of this location.

: (Comment comment) -> void

# File lib/ruby/prism/parse_result.rb, line 439
def leading_comment(comment)
  leading_comments << comment
end

leading_comments ()

These are the comments that are associated with this location that exist before the start of this location.

: () -> Array

# File lib/ruby/prism/parse_result.rb, line 432
def leading_comments
  @leading_comments ||= []
end

slice ()

The source code that this location represents.

: () -> String

# File lib/ruby/prism/parse_result.rb, line 497
def slice
  source.slice(start_offset, length)
end

slice_lines ()

The source code that this location represents starting from the beginning of the line that this location starts on to the end of the line that this location ends on.

: () -> String

# File lib/ruby/prism/parse_result.rb, line 506
def slice_lines
  line_start = source.line_start(start_offset)
  line_end = source.line_end(end_offset)
  source.slice(line_start, line_end - line_start)
end

source_lines ()

Returns all of the lines of the source code associated with this location.

: () -> Array

# File lib/ruby/prism/parse_result.rb, line 490
def source_lines
  source.lines
end

start_character_column ()

The column in characters where this location ends from the start of the line.

: () -> Integer

# File lib/ruby/prism/parse_result.rb, line 599
def start_character_column
  source.character_column(start_offset)
end

start_character_offset ()

The character offset from the beginning of the source where this location starts.

: () -> Integer

# File lib/ruby/prism/parse_result.rb, line 516
def start_character_offset
  source.character_offset(start_offset)
end

start_code_units_column (encoding = Encoding::UTF_16LE)

The column in code units of the given encoding where this location starts from the start of the line.

: (?Encoding encoding) -> Integer

# File lib/ruby/prism/parse_result.rb, line 607
def start_code_units_column(encoding = Encoding::UTF_16LE)
  source.code_units_column(start_offset, encoding)
end

start_code_units_offset (encoding = Encoding::UTF_16LE)

The offset from the start of the file in code units of the given encoding.

: (Encoding encoding) -> Integer

# File lib/ruby/prism/parse_result.rb, line 523
def start_code_units_offset(encoding = Encoding::UTF_16LE)
  source.code_units_offset(start_offset, encoding)
end

start_column ()

The column in bytes where this location starts from the start of the line.

: () -> Integer

# File lib/ruby/prism/parse_result.rb, line 591
def start_column
  source.column(start_offset)
end

start_line ()

The line number where this location starts.

: () -> Integer

# File lib/ruby/prism/parse_result.rb, line 568
def start_line
  source.line(start_offset)
end

start_line_slice ()

The content of the line where this location starts before this location.

: () -> String

# File lib/ruby/prism/parse_result.rb, line 575
def start_line_slice
  offset = source.line_start(start_offset)
  source.slice(offset, start_offset - offset)
end

trailing_comment (comment)

Attach a comment to the trailing comments of this location.

: (Comment comment) -> void

# File lib/ruby/prism/parse_result.rb, line 454
def trailing_comment(comment)
  trailing_comments << comment
end

trailing_comments ()

These are the comments that are associated with this location that exist after the end of this location.

: () -> Array

# File lib/ruby/prism/parse_result.rb, line 447
def trailing_comments
  @trailing_comments ||= []
end