refract 1.0.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 (40) 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 +101 -7
  5. data/lib/refract/formatter.rb +436 -170
  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 +5 -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/symbol_node.rb +3 -2
  36. data/lib/refract/nodes/true_node.rb +1 -0
  37. data/lib/refract/version.rb +1 -1
  38. data/lib/refract/visitor.rb +3 -1
  39. data/lib/refract.rb +27 -0
  40. metadata +2 -2
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 8b42e2ba437813613a9e793d44876702acdf9c730426f890f5696c65dc930591
4
- data.tar.gz: f920d8b6cba89d57710d8175f0b977445128c66e4936d0e6a0092f8d2338d292
3
+ metadata.gz: f20a543e6810566dd44ca44ea79741e133d15697452b7ff82bf957a04d4a45a4
4
+ data.tar.gz: d7564beebb4e7a667f964a5b26f3f1cdca6085da502b9c676079d0c91a9b36c6
5
5
  SHA512:
6
- metadata.gz: 814f27c216c27736cb7caf003770855996af84c326637ce8f2edc7087d506e9a4228b7707f2824f852f0e1d333e948514efa6c60b130f4ca55b60aa67a923f04
7
- data.tar.gz: d029a121d9ce0bdabe5a809de3e47d687f807b9978b815cf6138fd2fc73f221b76888d35094e96e05e2d691fd38546862831d008096b9a3677a237ffd77e7522
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
 
@@ -163,6 +164,9 @@ module Refract
163
164
  name: node.name,
164
165
  arguments: visit(node.arguments),
165
166
  block: visit(node.block),
167
+ safe_navigation: node.safe_navigation?,
168
+ variable_call: node.variable_call?,
169
+ attribute_write: node.attribute_write?,
166
170
  )
167
171
  end
168
172
 
@@ -173,6 +177,7 @@ module Refract
173
177
  read_name: node.read_name,
174
178
  binary_operator: node.binary_operator,
175
179
  value: visit(node.value),
180
+ safe_navigation: node.safe_navigation?,
176
181
  )
177
182
  end
178
183
 
@@ -182,6 +187,7 @@ module Refract
182
187
  receiver: visit(node.receiver),
183
188
  read_name: node.read_name,
184
189
  value: visit(node.value),
190
+ safe_navigation: node.safe_navigation?,
185
191
  )
186
192
  end
187
193
 
@@ -416,6 +422,20 @@ module Refract
416
422
  )
417
423
  end
418
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
+
419
439
  visit Prism::FalseNode do |node|
420
440
  FalseNode.new(
421
441
  prism_node: node,
@@ -533,6 +553,7 @@ module Refract
533
553
  visit Prism::HashPatternNode do |node|
534
554
  HashPatternNode.new(
535
555
  prism_node: node,
556
+ constant: visit(node.constant),
536
557
  elements: node.elements&.map { |n| visit(n) },
537
558
  rest: visit(node.rest),
538
559
  )
@@ -678,6 +699,7 @@ module Refract
678
699
  multi_line: node.multi_line?,
679
700
  extended: node.extended?,
680
701
  once: node.once?,
702
+ encoding: regexp_encoding(node),
681
703
  )
682
704
  end
683
705
 
@@ -689,6 +711,7 @@ module Refract
689
711
  multi_line: node.multi_line?,
690
712
  extended: node.extended?,
691
713
  once: node.once?,
714
+ encoding: regexp_encoding(node),
692
715
  )
693
716
  end
694
717
 
@@ -805,6 +828,7 @@ module Refract
805
828
  multi_line: node.multi_line?,
806
829
  extended: node.extended?,
807
830
  once: node.once?,
831
+ encoding: regexp_encoding(node),
808
832
  )
809
833
  end
810
834
 
@@ -832,10 +856,13 @@ module Refract
832
856
  )
833
857
  end
834
858
 
835
- visit Prism::MissingNode do |node|
836
- MissingNode.new(
837
- prism_node: node,
838
- )
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
839
866
  end
840
867
 
841
868
  visit Prism::ModuleNode do |node|
@@ -974,6 +1001,8 @@ module Refract
974
1001
  ProgramNode.new(
975
1002
  prism_node: node,
976
1003
  statements: visit(node.statements),
1004
+ frozen_string_literal: frozen_string_literal(node),
1005
+ encoding: node.slice.encoding,
977
1006
  )
978
1007
  end
979
1008
 
@@ -1008,6 +1037,7 @@ module Refract
1008
1037
  multi_line: node.multi_line?,
1009
1038
  extended: node.extended?,
1010
1039
  once: node.once?,
1040
+ encoding: regexp_encoding(node),
1011
1041
  )
1012
1042
  end
1013
1043
 
@@ -1073,6 +1103,7 @@ module Refract
1073
1103
  ShareableConstantNode.new(
1074
1104
  prism_node: node,
1075
1105
  write: visit(node.write),
1106
+ value: shareable_constant_value(node),
1076
1107
  )
1077
1108
  end
1078
1109
 
@@ -1119,7 +1150,7 @@ module Refract
1119
1150
  visit Prism::StringNode do |node|
1120
1151
  StringNode.new(
1121
1152
  prism_node: node,
1122
- unescaped: node.unescaped,
1153
+ unescaped: unescaped(node),
1123
1154
  )
1124
1155
  end
1125
1156
 
@@ -1134,7 +1165,8 @@ module Refract
1134
1165
  visit Prism::SymbolNode do |node|
1135
1166
  SymbolNode.new(
1136
1167
  prism_node: node,
1137
- unescaped: node.unescaped,
1168
+ unescaped: unescaped(node),
1169
+ quoted: node.opening_loc && node.closing_loc,
1138
1170
  )
1139
1171
  end
1140
1172
 
@@ -1190,7 +1222,7 @@ module Refract
1190
1222
  visit Prism::XStringNode do |node|
1191
1223
  XStringNode.new(
1192
1224
  prism_node: node,
1193
- unescaped: node.unescaped,
1225
+ unescaped: unescaped(node),
1194
1226
  )
1195
1227
  end
1196
1228
 
@@ -1200,5 +1232,67 @@ module Refract
1200
1232
  arguments: visit(node.arguments),
1201
1233
  )
1202
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
1203
1297
  end
1204
1298
  end