Module: Ibex::IR::Serialize

Defined in:
lib/ibex/ir/serialize.rb

Overview

Stable JSON serialization for versioned pipeline IR. rubocop:disable Metrics/ModuleLength -- explicit versioned fields keep serialization changes auditable.

Class Method Summary collapse

Class Method Details

.dump(value) ⇒ Object 



39
40
41
 
# File 'lib/ibex/ir/serialize.rb', line 39

def dump(value)
  "#{JSON.pretty_generate(value.to_h)}\n"
end

.load(source) ⇒ Object 



45
46
47
48
49
50
51
52
53
54
55
56
57
 
# File 'lib/ibex/ir/serialize.rb', line 45

def load(source)
  data = JSON.parse(source)
  type = data.fetch("ibex_ir") { raise Ibex::Error, "(ir):1:1: missing ibex_ir discriminator" }
  return load_lexer(data) if type == "lexer"

  validate_version(data)
  return load_grammar(data) if type == "grammar"
  return load_automaton(data) if type == "automaton"

  raise Ibex::Error, "(ir):1:1: unsupported IR type #{type.inspect}"
rescue JSON::ParserError => e
  raise Ibex::Error, "(ir):1:1: invalid JSON: #{e.message}"
end

.load_automaton(data) ⇒ Object 



107
108
109
110
111
112
113
 
# File 'lib/ibex/ir/serialize.rb', line 107

def load_automaton(data)
  grammar = load_grammar(data.fetch("grammar"))
  states = data.fetch("states").map { |state| load_state(state, grammar) }
  Automaton.new(grammar: grammar, states: states, conflict_summary: symbolize(data.fetch("conflict_summary")),
                algorithm: data.fetch("algorithm"), grammar_digest: data.fetch("grammar_digest"),
                schema_version: data.fetch("schema_version"), entry_states: data["entry_states"])
end

.load_grammar(data) ⇒ Object 



73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
 
# File 'lib/ibex/ir/serialize.rb', line 73

def load_grammar(data) # rubocop:disable Metrics/AbcSize -- explicit fields preserve the public IR contract.
  empty_chunks = {} #: Hash[String, untyped]
  empty_parameters = [] #: Array[untyped]
  empty_printers = [] #: Array[untyped]
  empty_tests = [] #: Array[untyped]
  empty_recovery = { "sync_tokens" => [], "on_error_reduce" => [] } #: Hash[String, untyped]
  schema_version = data.fetch("schema_version")
  symbols = data.fetch("symbols").map do |symbol|
    GrammarSymbol.new(id: symbol.fetch("id"), name: symbol.fetch("name"), kind: symbol.fetch("kind"),
                      reserved: symbol.fetch("reserved"), precedence: symbolize(symbol["prec"]),
                      location: symbolize(symbol["loc"]),
                      display_name: load_symbol_metadata(symbol, "display_name"),
                      semantic_type: load_symbol_metadata(symbol, "semantic_type"),
                      documentation: symbol["doc"])
  end
  productions = data.fetch("productions").map { |production| load_production(production, schema_version) }
  Grammar.new(class_name: data.fetch("class_name"), superclass: data["superclass"], start: data.fetch("start"),
              expect: data.fetch("expect"), options: symbolize(data.fetch("options")), symbols: symbols,
              mode: (data["mode"] || "default").to_sym,
              starts: data["starts"],
              expect_rr: data["expect_rr"],
              parser_parameters: symbolize(data.fetch("params", empty_parameters)),
              value_printers: symbolize(data.fetch("printers", empty_printers)),
              grammar_tests: load_grammar_tests(data.fetch("tests", empty_tests)),
              lexer: data["lexer"] && load_lexer(data.fetch("lexer")),
              recovery: symbolize(data.fetch("recovery", empty_recovery)),
              productions: productions, user_code: data.fetch("user_code"),
              conversions: data.fetch("conversions"), warnings: symbolize(data.fetch("warnings")),
              user_code_chunks: load_user_code_chunks(data.fetch("user_code_chunks", empty_chunks)),
              schema_version: schema_version, source_provenance: symbolize(data["source_provenance"]),
              migration: symbolize(data["migration"]))
end

.load_grammar_tests(tests) ⇒ Object 



221
222
223
 
# File 'lib/ibex/ir/serialize.rb', line 221

def load_grammar_tests(tests)
  symbolize(tests).map { |test| test.merge(expectation: test.fetch(:expectation).to_sym) }
end

.load_lexer(data) ⇒ Object 



116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
 
# File 'lib/ibex/ir/serialize.rb', line 116

def load_lexer(data)
  version = data.fetch("schema_version")
  unless SUPPORTED_LEXER_SCHEMA_VERSIONS.include?(version)
    expected = SUPPORTED_LEXER_SCHEMA_VERSIONS.join(", ")
    raise Ibex::Error,
          "(ir):1:1: unsupported lexer schema_version #{version.inspect}; expected one of #{expected}"
  end
  rules = data.fetch("rules").map do |rule|
    LexerRule.new(
      id: rule.fetch("id"), state: rule.fetch("state"), kind: rule.fetch("kind").to_sym,
      token: rule["token"], pattern: rule.fetch("pattern"), pattern_kind: rule.fetch("pattern_kind").to_sym,
      options: rule.fetch("options"), action: rule["action"], location: symbolize(rule.fetch("loc"))
    )
  end
  Lexer.new(
    states: data.fetch("states"), rules: rules, warnings: symbolize(data.fetch("warnings")),
    schema_version: version, source_provenance: symbolize(data["source_provenance"])
  )
end

.load_production(production, schema_version) ⇒ Object 



167
168
169
170
171
172
173
174
175
176
177
178
179
180
 
# File 'lib/ibex/ir/serialize.rb', line 167

def load_production(production, schema_version)
  action_data = production["action"]
  action = if action_data
             Action.new(code: action_data.fetch("code"), location: symbolize(action_data["loc"]),
                        named_refs: symbolize(action_data.fetch("named_refs")),
                        context_length: action_data.fetch("context_length"),
                        composition: symbolize(action_data["composition"]))
           end
  Production.new(id: production.fetch("id"), lhs: production.fetch("lhs"), rhs: production.fetch("rhs"),
                 action: action, precedence_override: production["prec_override"],
                 origin: symbolize(production.fetch("origin")), documentation: production["doc"],
                 expansion: schema_version >= 2 ? symbolize(production["expansion"]) : nil,
                 node: schema_version >= 2 ? symbolize(production["node"]) : nil)
end

.load_state(state, grammar) ⇒ Object 



137
138
139
140
141
142
143
144
145
146
147
148
 
# File 'lib/ibex/ir/serialize.rb', line 137

def load_state(state, grammar)
  items = state.fetch("items").map do |item|
    lookaheads = item.fetch("lookaheads").map { |name| grammar.symbol(name).id }
    AutomatonItem.new(production: item.fetch("production"), dot: item.fetch("dot"), lookaheads: lookaheads)
  end
  AutomatonState.new(id: state.fetch("id"), items: items,
                     transitions: symbol_keyed(state.fetch("transitions"), grammar),
                     actions: symbol_keyed(state.fetch("actions"), grammar, actions: true),
                     gotos: symbol_keyed(state.fetch("gotos"), grammar),
                     default_action: normalize_action(state["default_action"]),
                     conflicts: symbolize(state.fetch("conflicts")))
end

.load_symbol_metadata(symbol, field) ⇒ Object

Raises:



193
194
195
196
197
198
199
200
201
202
203
204
205
 
# File 'lib/ibex/ir/serialize.rb', line 193

def load_symbol_metadata(symbol, field)
  value = symbol[field]
  return nil if value.nil?

  position = symbol_source_position(symbol)
  raise Ibex::Error, "#{position}: #{field} must be a String or null" unless value.is_a?(String)
  raise Ibex::Error, "#{position}: #{field} must not be empty" if value.strip.empty?
  raise Ibex::Error, "#{position}: #{field} must be a single line" if value.match?(/[\r\n]/)
  raise Ibex::Error, "#{position}: #{field} must not contain control characters" if
    value.match?(/[[:cntrl:]]/)

  value
end

.load_user_code_chunks(chunks) ⇒ Object 



183
184
185
186
187
188
189
190
 
# File 'lib/ibex/ir/serialize.rb', line 183

def load_user_code_chunks(chunks)
  chunks.to_h do |name, values|
    loaded = values.map do |value|
      UserCodeChunk.new(code: value.fetch("code"), location: symbolize(value.fetch("loc")))
    end
    [name, loaded]
  end
end

.normalize_action(value) ⇒ Object 



158
159
160
161
162
163
164
 
# File 'lib/ibex/ir/serialize.rb', line 158

def normalize_action(value)
  return nil unless value

  action = symbolize(value)
  action[:type] = action[:type].to_sym
  action
end

.symbol_keyed(values, grammar, actions: false) ⇒ Object 



151
152
153
154
155
 
# File 'lib/ibex/ir/serialize.rb', line 151

def symbol_keyed(values, grammar, actions: false)
  values.to_h do |name, value|
    [grammar.symbol(name).id, actions ? normalize_action(value) : value]
  end
end

.symbol_source_position(symbol) ⇒ Object 



208
209
210
211
212
213
214
215
216
217
218
 
# File 'lib/ibex/ir/serialize.rb', line 208

def symbol_source_position(symbol)
  location = symbol["loc"]
  return "(ir):1:1" unless location.is_a?(Hash)

  file = location["file"]
  line = location["line"]
  column = location["column"]
  return "(ir):1:1" unless file.is_a?(String) && line.is_a?(Integer) && column.is_a?(Integer)

  "#{file}:#{line}:#{column}"
end

.symbolize(value) ⇒ Object 



226
227
228
229
230
231
232
 
# File 'lib/ibex/ir/serialize.rb', line 226

def symbolize(value)
  case value
  when Array then value.map { |item| symbolize(item) }
  when Hash then value.to_h { |key, item| [key.to_sym, symbolize(item)] }
  else value
  end
end

.validate_version(data) ⇒ Object

Raises:



64
65
66
67
68
69
70
 
# File 'lib/ibex/ir/serialize.rb', line 64

def validate_version(data)
  version = data["schema_version"]
  return if SUPPORTED_SCHEMA_VERSIONS.include?(version)

  expected = SUPPORTED_SCHEMA_VERSIONS.join(", ")
  raise Ibex::Error, "(ir):1:1: unsupported schema_version #{version.inspect}; expected one of #{expected}"
end