refract 1.1.0 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (39) hide show
  1. checksums.yaml +4 -4
  2. data/README.md +15 -0
  3. data/lib/refract/basic_visitor.rb +3 -3
  4. data/lib/refract/converter.rb +99 -7
  5. data/lib/refract/formatter.rb +401 -168
  6. data/lib/refract/mutation_visitor.rb +17 -1
  7. data/lib/refract/nodes/alias_global_variable_node.rb +1 -1
  8. data/lib/refract/nodes/call_and_write_node.rb +3 -2
  9. data/lib/refract/nodes/call_node.rb +4 -2
  10. data/lib/refract/nodes/call_operator_write_node.rb +3 -2
  11. data/lib/refract/nodes/call_or_write_node.rb +3 -2
  12. data/lib/refract/nodes/false_node.rb +1 -0
  13. data/lib/refract/nodes/forwarding_arguments_node.rb +1 -0
  14. data/lib/refract/nodes/forwarding_parameter_node.rb +1 -0
  15. data/lib/refract/nodes/hash_pattern_node.rb +3 -2
  16. data/lib/refract/nodes/implicit_rest_node.rb +1 -0
  17. data/lib/refract/nodes/interpolated_match_last_line_node.rb +3 -2
  18. data/lib/refract/nodes/interpolated_regular_expression_node.rb +3 -2
  19. data/lib/refract/nodes/it_local_variable_read_node.rb +1 -0
  20. data/lib/refract/nodes/it_parameters_node.rb +1 -0
  21. data/lib/refract/nodes/match_last_line_node.rb +3 -2
  22. data/lib/refract/nodes/missing_node.rb +1 -0
  23. data/lib/refract/nodes/nil_node.rb +1 -0
  24. data/lib/refract/nodes/no_keywords_parameter_node.rb +1 -0
  25. data/lib/refract/nodes/numbered_parameters_node.rb +1 -0
  26. data/lib/refract/nodes/program_node.rb +4 -2
  27. data/lib/refract/nodes/redo_node.rb +1 -0
  28. data/lib/refract/nodes/regular_expression_node.rb +3 -2
  29. data/lib/refract/nodes/retry_node.rb +1 -0
  30. data/lib/refract/nodes/self_node.rb +1 -0
  31. data/lib/refract/nodes/shareable_constant_node.rb +3 -2
  32. data/lib/refract/nodes/source_encoding_node.rb +1 -0
  33. data/lib/refract/nodes/source_file_node.rb +1 -0
  34. data/lib/refract/nodes/source_line_node.rb +1 -0
  35. data/lib/refract/nodes/true_node.rb +1 -0
  36. data/lib/refract/version.rb +1 -1
  37. data/lib/refract/visitor.rb +3 -1
  38. data/lib/refract.rb +27 -0
  39. metadata +2 -2
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: b6108db4a82b8d13ee9e82726fb9a546e9ca2307ebf798f9dc46c7088a4954b3
4
- data.tar.gz: 8a1568765775444eef901017163818dd90e724da75f75c418ebc838f6f05cb73
3
+ metadata.gz: f20a543e6810566dd44ca44ea79741e133d15697452b7ff82bf957a04d4a45a4
4
+ data.tar.gz: d7564beebb4e7a667f964a5b26f3f1cdca6085da502b9c676079d0c91a9b36c6
5
5
  SHA512:
6
- metadata.gz: 616aa31f777bee9127836f599337e4d23b7e1e28ec3b5089c979cc48d901b8e16d26e09390f6c716885464ad88125875288d4e5667ba3b0e5f1c1b164b7cfc69
7
- data.tar.gz: bc620ad21498d5c4351c145047a5b29aa6ff73537809529594bb9c163c088f36f47de7590cf4fe1f2cdd5c04594a2d276bd439d9da19440771af108158ac1ab3
6
+ metadata.gz: 547d939d2e64a9d277bba3c6af1436e930583f849a92db93fb1c0323b9dc3ecfe7d5994135ee2fcfb0731f35b4da9045de31f90e0a57b4f9abe54be6a56d4f7e
7
+ data.tar.gz: dd5e6d181ce081fb700c3830093828ca7d254c6d71f6294c3e0f4442f2d6a1f9a1a29e75599509b93c194b53e4e3d6120570322e9c38191d59b7182d7dc0521d
data/README.md CHANGED
@@ -5,3 +5,18 @@ Refract lets you re-write Ruby at the AST level.
5
5
  1. The `Converter` walks a concrete Prism syntax tree and produces an abstract Refract tree.
6
6
  2. The `MutationVisitor` walks the Refract tree, allowing you to mutate existing nodes and insert new nodes.
7
7
  3. Finally, the `Formatter` walks the Refract tree producing valid Ruby code.
8
+
9
+ ## What the round trip preserves
10
+
11
+ Converting and formatting preserves the meaning of the code, not its layout. Comments, heredocs, `%w[]` and other literal syntaxes, and optional parentheses are normalised.
12
+
13
+ When formatting a `ProgramNode`, the `frozen_string_literal` and `encoding` magic comments are re-emitted. `shareable_constant_value` is re-emitted around each statement containing a constant write it applies to. These are not re-emitted when formatting a smaller node, so formatted fragments take on the settings of the file they are evaluated in.
14
+
15
+ `__LINE__` is formatted as the line number it had in the original source.
16
+
17
+ Not preserved:
18
+
19
+ - `__END__` and the data after it, so `DATA` is not defined.
20
+ - The encoding of string literals containing raw non-ASCII bytes in an `# encoding: ASCII-8BIT` file, because Prism reports such files as UTF-8.
21
+
22
+ Run `CORPUS=1 bundle exec qt test/corpus.test.rb` to round trip every Ruby file in the standard library and installed gems.
@@ -18,9 +18,9 @@ module Refract
18
18
  return unless node
19
19
 
20
20
  @stack.push(node)
21
- around_visit(node) do |n|
22
- n.accept(self).tap { @stack.pop }
23
- end
21
+ around_visit(node) { |n| n.accept(self) }
22
+ ensure
23
+ @stack.pop if node
24
24
  end
25
25
 
26
26
  def visit_each(nodes)
@@ -153,6 +153,7 @@ module Refract
153
153
  receiver: visit(node.receiver),
154
154
  read_name: node.read_name,
155
155
  value: visit(node.value),
156
+ safe_navigation: node.safe_navigation?,
156
157
  )
157
158
  end
158
159
 
@@ -164,6 +165,8 @@ module Refract
164
165
  arguments: visit(node.arguments),
165
166
  block: visit(node.block),
166
167
  safe_navigation: node.safe_navigation?,
168
+ variable_call: node.variable_call?,
169
+ attribute_write: node.attribute_write?,
167
170
  )
168
171
  end
169
172
 
@@ -174,6 +177,7 @@ module Refract
174
177
  read_name: node.read_name,
175
178
  binary_operator: node.binary_operator,
176
179
  value: visit(node.value),
180
+ safe_navigation: node.safe_navigation?,
177
181
  )
178
182
  end
179
183
 
@@ -183,6 +187,7 @@ module Refract
183
187
  receiver: visit(node.receiver),
184
188
  read_name: node.read_name,
185
189
  value: visit(node.value),
190
+ safe_navigation: node.safe_navigation?,
186
191
  )
187
192
  end
188
193
 
@@ -417,6 +422,20 @@ module Refract
417
422
  )
418
423
  end
419
424
 
425
+ # Prism represents a syntax error as MissingNode up to prism 1.9 and as
426
+ # ErrorRecoveryNode after it (ruby/ruby@708656c7, the prism ruby-head
427
+ # bundles). ErrorRecoveryNode adds an optional `unexpected` child, the stray
428
+ # node found in place of the missing one; like Prism's own translators we
429
+ # keep the node a leaf, since source with a syntax error can't be emitted
430
+ # either way. The original stays reachable through `prism_node`.
431
+ if Prism.const_defined?(:ErrorRecoveryNode)
432
+ visit Prism::ErrorRecoveryNode do |node|
433
+ MissingNode.new(
434
+ prism_node: node,
435
+ )
436
+ end
437
+ end
438
+
420
439
  visit Prism::FalseNode do |node|
421
440
  FalseNode.new(
422
441
  prism_node: node,
@@ -534,6 +553,7 @@ module Refract
534
553
  visit Prism::HashPatternNode do |node|
535
554
  HashPatternNode.new(
536
555
  prism_node: node,
556
+ constant: visit(node.constant),
537
557
  elements: node.elements&.map { |n| visit(n) },
538
558
  rest: visit(node.rest),
539
559
  )
@@ -679,6 +699,7 @@ module Refract
679
699
  multi_line: node.multi_line?,
680
700
  extended: node.extended?,
681
701
  once: node.once?,
702
+ encoding: regexp_encoding(node),
682
703
  )
683
704
  end
684
705
 
@@ -690,6 +711,7 @@ module Refract
690
711
  multi_line: node.multi_line?,
691
712
  extended: node.extended?,
692
713
  once: node.once?,
714
+ encoding: regexp_encoding(node),
693
715
  )
694
716
  end
695
717
 
@@ -806,6 +828,7 @@ module Refract
806
828
  multi_line: node.multi_line?,
807
829
  extended: node.extended?,
808
830
  once: node.once?,
831
+ encoding: regexp_encoding(node),
809
832
  )
810
833
  end
811
834
 
@@ -833,10 +856,13 @@ module Refract
833
856
  )
834
857
  end
835
858
 
836
- visit Prism::MissingNode do |node|
837
- MissingNode.new(
838
- prism_node: node,
839
- )
859
+ # Prism <= 1.9 has MissingNode; later prism replaces it with ErrorRecoveryNode (above).
860
+ if Prism.const_defined?(:MissingNode)
861
+ visit Prism::MissingNode do |node|
862
+ MissingNode.new(
863
+ prism_node: node,
864
+ )
865
+ end
840
866
  end
841
867
 
842
868
  visit Prism::ModuleNode do |node|
@@ -975,6 +1001,8 @@ module Refract
975
1001
  ProgramNode.new(
976
1002
  prism_node: node,
977
1003
  statements: visit(node.statements),
1004
+ frozen_string_literal: frozen_string_literal(node),
1005
+ encoding: node.slice.encoding,
978
1006
  )
979
1007
  end
980
1008
 
@@ -1009,6 +1037,7 @@ module Refract
1009
1037
  multi_line: node.multi_line?,
1010
1038
  extended: node.extended?,
1011
1039
  once: node.once?,
1040
+ encoding: regexp_encoding(node),
1012
1041
  )
1013
1042
  end
1014
1043
 
@@ -1074,6 +1103,7 @@ module Refract
1074
1103
  ShareableConstantNode.new(
1075
1104
  prism_node: node,
1076
1105
  write: visit(node.write),
1106
+ value: shareable_constant_value(node),
1077
1107
  )
1078
1108
  end
1079
1109
 
@@ -1120,7 +1150,7 @@ module Refract
1120
1150
  visit Prism::StringNode do |node|
1121
1151
  StringNode.new(
1122
1152
  prism_node: node,
1123
- unescaped: node.unescaped,
1153
+ unescaped: unescaped(node),
1124
1154
  )
1125
1155
  end
1126
1156
 
@@ -1135,7 +1165,7 @@ module Refract
1135
1165
  visit Prism::SymbolNode do |node|
1136
1166
  SymbolNode.new(
1137
1167
  prism_node: node,
1138
- unescaped: node.unescaped,
1168
+ unescaped: unescaped(node),
1139
1169
  quoted: node.opening_loc && node.closing_loc,
1140
1170
  )
1141
1171
  end
@@ -1192,7 +1222,7 @@ module Refract
1192
1222
  visit Prism::XStringNode do |node|
1193
1223
  XStringNode.new(
1194
1224
  prism_node: node,
1195
- unescaped: node.unescaped,
1225
+ unescaped: unescaped(node),
1196
1226
  )
1197
1227
  end
1198
1228
 
@@ -1202,5 +1232,67 @@ module Refract
1202
1232
  arguments: visit(node.arguments),
1203
1233
  )
1204
1234
  end
1235
+
1236
+ # Prism records the `frozen_string_literal` magic comment on each string
1237
+ # literal. Interpolated parts, hash keys, `when` conditions and lone
1238
+ # strings in `#{}` are always marked frozen, so they are skipped, and
1239
+ # interpolated strings can be marked mutable regardless of the comment.
1240
+ private def frozen_string_literal(node)
1241
+ queue = [node]
1242
+
1243
+ while (current = queue.shift)
1244
+ case current
1245
+ when Prism::StringNode, Prism::SourceFileNode
1246
+ return true if current.frozen?
1247
+ return false if current.mutable?
1248
+ when Prism::InterpolatedStringNode
1249
+ return true if current.frozen?
1250
+ end
1251
+
1252
+ case current
1253
+ when Prism::InterpolatedStringNode, Prism::InterpolatedSymbolNode, Prism::InterpolatedXStringNode,
1254
+ Prism::InterpolatedRegularExpressionNode, Prism::InterpolatedMatchLastLineNode
1255
+
1256
+ queue.concat(current.parts.grep_v(Prism::StringNode))
1257
+ when Prism::AssocNode
1258
+ queue << current.key unless Prism::StringNode === current.key
1259
+ queue << current.value if current.value
1260
+ when Prism::WhenNode
1261
+ queue.concat(current.conditions.grep_v(Prism::StringNode))
1262
+ queue << current.statements if current.statements
1263
+ when Prism::EmbeddedStatementsNode
1264
+ queue << current.statements unless current.statements&.body in [Prism::StringNode] | nil
1265
+ else
1266
+ queue.concat(current.compact_child_nodes)
1267
+ end
1268
+ end
1269
+ end
1270
+
1271
+ private def shareable_constant_value(node)
1272
+ if node.literal? then :literal
1273
+ elsif node.experimental_everything? then :experimental_everything
1274
+ elsif node.experimental_copy? then :experimental_copy
1275
+ end
1276
+ end
1277
+
1278
+ # Prism returns content in the source encoding and flags escapes that
1279
+ # force a different one, e.g. `"é"` in a US-ASCII file is UTF-8.
1280
+ private def unescaped(node)
1281
+ if node.forced_utf8_encoding?
1282
+ node.unescaped.dup.force_encoding(Encoding::UTF_8)
1283
+ elsif node.forced_binary_encoding?
1284
+ node.unescaped.b
1285
+ else
1286
+ node.unescaped
1287
+ end
1288
+ end
1289
+
1290
+ private def regexp_encoding(node)
1291
+ if node.ascii_8bit? then :ascii_8bit
1292
+ elsif node.euc_jp? then :euc_jp
1293
+ elsif node.windows_31j? then :windows_31j
1294
+ elsif node.utf_8? then :utf_8
1295
+ end
1296
+ end
1205
1297
  end
1206
1298
  end