123456789_123456789_123456789_123456789_123456789_

Class: Prism::Location

Relationships & Source Files
Inherits: Object
Defined in: lib/prism/parse_result.rb,
prism/extension.c

Overview

This represents a location in the source.

Class Method Summary

Instance Attribute Summary

  • #length readonly

    The length of this location in bytes.

  • #start_offset readonly

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

  • #source readonly protected

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

Instance Method Summary

Constructor Details

.new(source, start_offset, length) ⇒ Location

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

[ GitHub ] 

  


# File 'lib/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


  







Instance Attribute Details



  

    #length   (readonly)
  



  

    
The length of this location in bytes.

  



  [ GitHub ]


  

  


# File 'lib/prism/parse_result.rb', line 407



attr_reader :length #: Integer


  








  

    #source   (readonly, protected)
  



  

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

  



  [ GitHub ]


  

  


# File 'lib/prism/parse_result.rb', line 399



attr_reader :source #: Source


  








  

    #start_offset   (readonly)
  



  

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

  



  [ GitHub ]


  

  


# File 'lib/prism/parse_result.rb', line 404



attr_reader :start_offset #: Integer


  







Instance Method Details



  

    #==(other)  
  



  

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

  



  [ GitHub ]


  

  


# File 'lib/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.

  



  [ GitHub ]


  

  


# File 'lib/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.

  



  [ GitHub ]


  

  


# File 'lib/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.

  



  [ GitHub ]


  

  


# File 'lib/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.

  



  [ GitHub ]


  

  


# File 'lib/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.

  



  [ GitHub ]


  

  


# File 'lib/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.

  



  [ GitHub ]


  

  


# File 'lib/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).

  



  [ GitHub ]


  

  


# File 'lib/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.

  



  [ GitHub ]


  

  


# File 'lib/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


  








  

    #deconstruct_keys(keys)  
  

  

    This method is for internal use only.
  



  

    
Implement the hash pattern matching interface for Location.

  



  [ GitHub ]


  

  


# File 'lib/prism/parse_result.rb', line 654



def deconstruct_keys(keys) # :nodoc:
  { start_offset: start_offset, end_offset: end_offset }
end


  








  

    #end_character_column  
  



  

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

  



  [ GitHub ]


  

  


# File 'lib/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.

  



  [ GitHub ]


  

  


# File 'lib/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.

  



  [ GitHub ]


  

  


# File 'lib/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.

  



  [ GitHub ]


  

  


# File 'lib/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.

  



  [ GitHub ]


  

  


# File 'lib/prism/parse_result.rb', line 623



def end_column
  source.column(end_offset)
end


  








  

    #end_line  
  



  

    
The line number where this location ends.

  



  [ GitHub ]


  

  


# File 'lib/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.

  



  [ GitHub ]


  

  


# File 'lib/prism/parse_result.rb', line 538



def end_offset
  start_offset + length
end


  








  

    #inspect  
  

  

    This method is for internal use only.
  



  

    
Returns a string representation of this location.

  



  [ GitHub ]


  

  


# File 'lib/prism/parse_result.rb', line 483



def inspect # :nodoc:
  "#<Prism::Location @start_offset=#{@start_offset} @length=#{@length} start_line=#{start_line}>"
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.

  



  [ GitHub ]


  

  


# File 'lib/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.

  



  [ GitHub ]


  

  


# File 'lib/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.

  



  [ GitHub ]


  

  


# File 'lib/prism/parse_result.rb', line 432



def leading_comments
  @leading_comments ||= []
end


  








  

    #pretty_print(q)  
  

  

    This method is for internal use only.
  



  

    
Implement the pretty print interface for Location.

  



  [ GitHub ]


  

  


# File 'lib/prism/parse_result.rb', line 661



def pretty_print(q) # :nodoc:
  q.text("(#{start_line},#{start_column})-(#{end_line},#{end_column})")
end


  








  

    #slice  
  



  

    
The source code that this location represents.

  



  [ GitHub ]


  

  


# File 'lib/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.

  



  [ GitHub ]


  

  


# File 'lib/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.

  



  [ GitHub ]


  

  


# File 'lib/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.

  



  [ GitHub ]


  

  


# File 'lib/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.

  



  [ GitHub ]


  

  


# File 'lib/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.

  



  [ GitHub ]


  

  


# File 'lib/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.

  



  [ GitHub ]


  

  


# File 'lib/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.

  



  [ GitHub ]


  

  


# File 'lib/prism/parse_result.rb', line 591



def start_column
  source.column(start_offset)
end


  








  

    #start_line  
  



  

    
The line number where this location starts.

  



  [ GitHub ]


  

  


# File 'lib/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.

  



  [ GitHub ]


  

  


# File 'lib/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.

  



  [ GitHub ]


  

  


# File 'lib/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.

  



  [ GitHub ]


  

  


# File 'lib/prism/parse_result.rb', line 447



def trailing_comments
  @trailing_comments ||= []
end