Exception: RSTError

Inherits:
StandardError
  • Object
show all
Defined in:
lib/rsyntaxtree.rb

Overview

A parse or generation failure. message is the human-readable text the CLI and the web UI display and must stay stable; the structured attributes ride alongside for machine callers (--validate, an MCP server, a repair loop). code is a Symbol; label/position locate the failure inside the offending label when one is known; hint is a one-line fix; and retryable tells a caller whether applying the hint could plausibly fix the input (false means retrying would be guessing).

Constant Summary collapse

CODES =

Every code an error from this library can carry. Consumers dispatch on these — a translation keyed by code, a harness counting what kinds of mistake occur — and both need to know the whole set, not only the codes they have happened to see: a kind of mistake nobody made is not the same as a kind that cannot happen. Until this list existed the set was only discoverable by reading five files and a repair table.

Written out rather than computed, because it is a contract and a contract should be readable at a glance and visible in a diff. A test keeps it honest by finding the codes the library actually raises and comparing.

The list grows and does not churn: a code once published is not renamed or removed, so a consumer keyed by code — a translation table, a tally of what kinds of mistake a writer makes — only ever has entries to add.

Eight are named by the repair table, which diagnoses a label by rewriting it and asking the parser whether the rewrite reads: angle_brackets, bare_hyphen, incomplete_path, invalid_color, rule_name_without_derivation, stray_triangle, unclosed_markup, unclosed_matrix. invalid_markup is where a label lands whose mistake no single rewrite fits, which in practice means more than one. unknown_color and label_split are mistakes inside a label too, found before the repair table is reached.

%i[
  angle_brackets
  bare_hyphen
  empty_brackets
  empty_input
  incomplete_path
  internal_error
  invalid_color
  invalid_markup
  invalid_option
  label_split
  path_multiple_ends
  path_single_end
  result_too_big
  rule_name_without_derivation
  stray_triangle
  unbalanced_brackets
  unclosed_markup
  unclosed_matrix
  unknown_color
].freeze
REFERENCE =

Where the notation is written down. A hint repairs the mistake in front of it and says nothing about the rest, which is enough for a reader who knows the notation and not enough for one who was guessing at it. Given once, at the top, rather than repeated on every error.

"rsyntaxtree --notation, or https://yohasebe.github.io/rsyntaxtree/llms-full.txt"

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(msg = "Error: something unexpected occurred", code: :invalid, label: nil, position: nil, hint: nil, retryable: false) ⇒ RSTError

Returns a new instance of RSTError.



124
125
126
127
128
129
130
131
132
133
134
 
# File 'lib/rsyntaxtree.rb', line 124

def initialize(msg = "Error: something unexpected occurred", code: :invalid, label: nil, position: nil, hint: nil, retryable: false)
  # Non-destructive: every file here carries frozen_string_literal, so
  # mutating the message in place turned a raise with a plain literal into
  # a FrozenError from inside the error class itself.
  @code = code
  @label = label
  @position = position
  @hint = hint
  @retryable = retryable
  super(msg.gsub(WHITESPACE_BLOCK, "<>"))
end

Instance Attribute Details

#code ⇒ Object (readonly)

Returns the value of attribute code.



122
123
124
 
# File 'lib/rsyntaxtree.rb', line 122

def code
  @code
end

#hint ⇒ Object (readonly)

Returns the value of attribute hint.



122
123
124
 
# File 'lib/rsyntaxtree.rb', line 122

def hint
  @hint
end

#label ⇒ Object (readonly)

Returns the value of attribute label.



122
123
124
 
# File 'lib/rsyntaxtree.rb', line 122

def label
  @label
end

#position ⇒ Object (readonly)

Returns the value of attribute position.



122
123
124
 
# File 'lib/rsyntaxtree.rb', line 122

def position
  @position
end

#retryable ⇒ Object (readonly)

Returns the value of attribute retryable.



122
123
124
 
# File 'lib/rsyntaxtree.rb', line 122

def retryable
  @retryable
end

Instance Method Details

#error_entry ⇒ Object

One error as the hash the JSON diagnosis carries; to_h wraps a single one and diagnose collects many.



188
189
190
191
192
193
194
195
 
# File 'lib/rsyntaxtree.rb', line 188

def error_entry
  { "code" => code.to_s,
    "message" => message,
    "label" => label,
    "position" => position,
    "hint" => hint,
    "retryable" => retryable }.compact
end

#to_h ⇒ Object 



197
198
199
200
201
 
# File 'lib/rsyntaxtree.rb', line 197

def to_h
  { "ok" => false,
    "errors" => [error_entry],
    "reference" => REFERENCE }
end