class Prism::Location - prism: Ruby Standard Library Documentation

# class 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) click to toggle source

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

    # File prism/parse_result.rb, line 288
    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) click to toggle source

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

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

adjoin(string) click to toggle source

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.

    # File prism/parse_result.rb, line 495
    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) click to toggle source

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

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

cached_end_code_units_offset(cache) click to toggle source

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

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

cached_start_code_units_column(cache) click to toggle source

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

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

cached_start_code_units_offset(cache) click to toggle source

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

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

chop() click to toggle source

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

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

comments() click to toggle source

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

    # File prism/parse_result.rb, line 324
    def comments
      [*@leading_comments, *@trailing_comments]
    end

copy(source: self.source, start_offset: self.start_offset, length: self.length) click to toggle source

Create a new location object with the given options.

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

deconstruct_keys(keys) click to toggle source

Implement the hash pattern matching interface for `Location`.

    # File prism/parse_result.rb, line 466
    def deconstruct_keys(keys)
      { start_offset: start_offset, end_offset: end_offset }
    end

end_character_column() click to toggle source

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

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

end_character_offset() click to toggle source

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

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

end_code_units_column(encoding = Encoding::UTF_16LE) click to toggle source

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

    # File prism/parse_result.rb, line 455
    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) click to toggle source

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

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

end_column() click to toggle source

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

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

end_line() click to toggle source

The line number where this location ends.

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

end_offset() click to toggle source

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

    # File prism/parse_result.rb, line 380
    def end_offset
      start_offset + length
    end

inspect() click to toggle source

Returns a string representation of this location.

    # File prism/parse_result.rb, line 339
    def inspect
      "#<Prism::Location @start_offset=#{@start_offset} @length=#{@length} start_line=#{start_line}>"
    end

join(other) click to toggle source

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.

    # File prism/parse_result.rb, line 485
    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) click to toggle source

Attach a comment to the leading comments of this location.

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

leading_comments() click to toggle source

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

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

pretty_print(q) click to toggle source

Implement the pretty print interface for `Location`.

    # File prism/parse_result.rb, line 471
    def pretty_print(q)
      q.text("(#{start_line},#{start_column})-(#{end_line},#{end_column})")
    end

slice() click to toggle source

The source code that this location represents.

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

slice_lines() click to toggle source

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.

    # File prism/parse_result.rb, line 356
    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() click to toggle source

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

    # File prism/parse_result.rb, line 344
    def source_lines
      source.lines
    end

start_character_column() click to toggle source

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

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

start_character_offset() click to toggle source

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

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

start_code_units_column(encoding = Encoding::UTF_16LE) click to toggle source

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

    # File prism/parse_result.rb, line 431
    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) click to toggle source

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

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

start_column() click to toggle source

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

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

start_line() click to toggle source

The line number where this location starts.

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

start_line_slice() click to toggle source

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

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

trailing_comment(comment) click to toggle source

Attach a comment to the trailing comments of this location.

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

trailing_comments() click to toggle source

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

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