Class: Kotoshu::Documents::Location

Inherits:
Object
  • Object
show all
Defined in:
lib/kotoshu/documents/location.rb

Overview

Unified location reference for errors in documents.

Supports both line/column locations (plain text) and node paths (structured formats like Markdown, AsciiDoc).

Examples:

Plain text location

Location.new(line: 5, column: 12)

Node path location

Location.new(node_path: [:paragraph, 3, :text, 2])

Mixed location

Location.new(line: 5, column: 12, node_path: [:paragraph, 3])

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(line: nil, column: nil, node_path: nil, offset: nil) ⇒ Location

Create a new location.

Parameters:

  • line (Integer, nil) (defaults to: nil) —

    Line number (1-indexed)

  • column (Integer, nil) (defaults to: nil) —

    Column number (0-indexed)

  • node_path (Array<Symbol, Integer>, nil) (defaults to: nil) —

    Path to node in AST

  • offset (Integer, nil) (defaults to: nil) —

    Byte offset in content



27
28
29
30
31
32
33
 
# File 'lib/kotoshu/documents/location.rb', line 27

def initialize(line: nil, column: nil, node_path: nil, offset: nil)
  @line = line
  @column = column
  @node_path = node_path&.freeze
  @offset = offset
  freeze
end

Instance Attribute Details

#column ⇒ Object (readonly)

Returns the value of attribute column.



19
20
21
 
# File 'lib/kotoshu/documents/location.rb', line 19

def column
  @column
end

#line ⇒ Object (readonly)

Returns the value of attribute line.



19
20
21
 
# File 'lib/kotoshu/documents/location.rb', line 19

def line
  @line
end

#node_path ⇒ Object (readonly)

Returns the value of attribute node_path.



19
20
21
 
# File 'lib/kotoshu/documents/location.rb', line 19

def node_path
  @node_path
end

#offset ⇒ Object (readonly)

Returns the value of attribute offset.



19
20
21
 
# File 'lib/kotoshu/documents/location.rb', line 19

def offset
  @offset
end

Class Method Details

.for_line(line) ⇒ Location

Create a line-only location.

Parameters:

  • line (Integer) —

    Line number

Returns:



134
135
136
 
# File 'lib/kotoshu/documents/location.rb', line 134

def self.for_line(line)
  new(line: line, column: 0)
end

.for_line_column(line, column) ⇒ Location

Create a line/column location.

Parameters:

  • line (Integer) —

    Line number

  • column (Integer) —

    Column number

Returns:



126
127
128
 
# File 'lib/kotoshu/documents/location.rb', line 126

def self.for_line_column(line, column)
  new(line: line, column: column)
end

.for_text_node(node_path, start_offset:, length:) ⇒ Location

Create a location for a text node.

Parameters:

  • node_path (Array) —

    Path to the text node

  • start_offset (Integer) —

    Starting character offset

  • length (Integer) —

    Length of the text

Returns:



114
115
116
117
118
119
 
# File 'lib/kotoshu/documents/location.rb', line 114

def self.for_text_node(node_path, start_offset:, length:)
  new(
    node_path: node_path,
    offset: start_offset
  )
end

Instance Method Details

#<=>(other) ⇒ Integer

Comparison for sorting (by line, then column).

Parameters:

Returns:

  • (Integer) —

    Comparison result (-1, 0, 1)



53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
 
# File 'lib/kotoshu/documents/location.rb', line 53

def <=>(other)
  return 0 unless other.is_a?(Location)

  if line_column? && other.line_column?
    # Both line/column - sort by line then column
    [@line, @column] <=> [other.line, other.column]
  elsif line_column?
    # We're line/column, other is node path - we come first
    -1
  elsif other.line_column?
    # Other is line/column, we're node path - other comes first
    1
  else
    # Both node paths - compare lexicographically
    @node_path <=> other.node_path
  end
end

#==(other) ⇒ Boolean Also known as: eql?

Check if this equals another location.

Parameters:

  • other (Object) —

    Another object

Returns:

  • (Boolean) —

    True if locations match



75
76
77
78
79
80
81
82
 
# File 'lib/kotoshu/documents/location.rb', line 75

def ==(other)
  return false unless other.is_a?(Location)

  @line == other.line &&
    @column == other.column &&
    @node_path == other.node_path &&
    @offset == other.offset
end

#hash ⇒ Integer

Hash code for hash table usage.

Returns:

  • (Integer) —

    Hash code



88
89
90
 
# File 'lib/kotoshu/documents/location.rb', line 88

def hash
  [@line, @column, @node_path, @offset].hash
end

#line_column? ⇒ Boolean

Check if this is a line/column location.

Returns:

  • (Boolean) —

    True if has line and column



38
39
40
 
# File 'lib/kotoshu/documents/location.rb', line 38

def line_column?
  !@line.nil? && !@column.nil?
end

#node_location? ⇒ Boolean

Check if this is a node path location.

Returns:

  • (Boolean) —

    True if has node path



45
46
47
 
# File 'lib/kotoshu/documents/location.rb', line 45

def node_location?
  !@node_path.nil? && !@node_path.empty?
end

#to_s ⇒ String Also known as: inspect

String representation.

Returns:

  • (String) —

    Human-readable representation



95
96
97
98
99
100
101
102
103
104
105
 
# File 'lib/kotoshu/documents/location.rb', line 95

def to_s
  if line_column?
    "Line #{@line}:#{@column}"
  elsif node_location?
    "Path: #{@node_path.join('.')}"
  elsif @offset
    "Offset #{@offset}"
  else
    "Unknown"
  end
end