rephrase 0.1 → 0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 35b9da1b746b755618ad23cc57fa70559f35064277b61965278544333d678f1d
-  data.tar.gz: 0467c2c8bc54226c445ed39cedb4a16ca85a945c326bd3bae26abf049f5622b2
+  metadata.gz: 50dd6a940c19895850f10694544b163b9362ab853242972760a885f555750a54
+  data.tar.gz: 0d41895ceb222d573384ae073bc183d0eaf5ee3d3429acc5f59f894af4af628f
 SHA512:
-  metadata.gz: '0912d93aac2a5fdbdf6c69490947530b6147f2fb55eff205c3839fdc1ad48dd6adddf35d2db868cef4da109b82fdae5b74a489f93d73d6dfed3a65ee8cd8d381'
-  data.tar.gz: aa45eefab2311a46c513af8f161345065cb08e2efdd56f7cbfc20e75c56bccf9b1907a90ba4a97e43976fc00efac096387b272895e68a49d212694e1ed7b9f92
+  metadata.gz: '0513931ee88c085b5026f71e9e5f427664a745ba93fa94e0d20422d7b690dec9bce8142fc8129ebd59379c0f3ee7f425d898a671011762c2c373c8266ea47a83'
+  data.tar.gz: 42757fb4d2ca4cad5feff6b19a42350662875864e8c262bced0dd6dcb73c1ed12d20630884ee09e9351a3411ca438360b76909e2a927467561c25e911415f50d

data/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 0.2 2011-11-16
+
+- Rename `#to_ruby` to `#to_source`
+- Add documentation
+
 ## 0.1 2021-11-16
 
 - First working version

data/README.md

@@ -3,3 +3,43 @@
 [![Gem Version](https://badge.fury.io/rb/rephrase.svg)](http://rubygems.org/gems/rephrase)
 [![Modulation Test](https://github.com/digital-fabric/rephrase/workflows/Tests/badge.svg)](https://github.com/digital-fabric/rephrase/actions?query=workflow%3ATests)
 [![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/digital-fabric/rephrase/blob/master/LICENSE)
+
+## Summary
+
+Rephrase converts Ruby procs or methods to source code, allowing you to
+reformat, reinterpret or otherwise manipulate the generated source code.
+Possible uses include:
+
+- Generating code from DSL blocks.
+- Inlining loops.
+- Macro exansion.
+- World domination (???)
+
+## How does it do it?
+
+Rephrase uses the `RubyVM::AbstractSyntaxTree` API to get the AST of a proc or
+method. This allows you to manipulate code at runtime, and to be able to access
+its binding.
+
+## How to use it
+
+Use `Rephrase.to_source` to get the unmodified source code of a proc or method,
+e.g.:
+
+```ruby
+require 'rephrase'
+
+example = proc { 2 + 2 }
+Rephrase.to_source(example) #=> "proc do\n2 + 2\nend"
+```
+
+## How to rephrase code
+
+Further documentation is forthcoming...
+
+## Limitations
+
+- Works only on MRI.
+- Ruby 2.7 or newer.
+- Generated source code will not be formatted identically to the source
+  (indentation, line breaks etc.)

data/lib/rephrase/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class Rephrase
-  VERSION = '0.1'
+  VERSION = '0.2'
 end

data/lib/rephrase.rb

@@ -4,35 +4,76 @@
 # for use in Pry, see https://dev.to/okinawarb/using-rubyvm-abstractsyntaxtree-of-in-pry-4cm3
 
 class Rephrase
+  # Class for faking a node
   class FakeNode
+    # Constructs a FakeNode with type `:LIST_EMBEDDED`
+    # @param children [Array] child nodes
     def self.list(children)
       new(:LIST_EMBEDDED, children)
     end
 
+    # Constructs a FakeNode with type `:ITER_SCOPE`
+    # @param children [Array] child nodes
     def self.iter_scope(children)
       new(:ITER_SCOPE, children)
     end
 
     attr_reader :type, :children
     
+    # Initializes a FakeNode
+    # @param type [Symbol] node type
+    # @param children [Array] child nodes
     def initialize(type, children)
       @type = type
       @children = children
     end
   end
+  
+  # Converts a :block or method to its source code
+  # @param code [Proc, BoundMethod, UnboundMethod] proc or method
+  # @return [String] converted source code
+  def self.to_source(code)
+    ast = RubyVM::AbstractSyntaxTree.of(code)
+    new.convert({}, ast)
+  end
+
+  # Pretty-prints an AST
+  # @param node [RubyVM::AbstractSyntaxTree::Node] AST node
+  def self.pp_ast(node, level = 0)
+    case node
+    when RubyVM::AbstractSyntaxTree::Node
+      puts "#{'  ' * level}#{node.type.inspect} (#{node.first_lineno})"
+      node.children.each { |c| pp_ast(c, level + 1) }
+    when Array
+      puts "#{'  ' * level}["
+      node.each { |c| pp_ast(c, level + 1) }
+      puts "#{'  ' * level}]"
+    else
+      puts "#{'  ' * level}#{node.inspect}"
+      return
+    end
+  end
 
+  # Converts an AST node to a string containing its source code
+  # @param ctx [Hash] context object
+  # @param node [RubyVM::AbstractSyntaxTree::Node] AST node
+  # @return [String] source code
   def convert(ctx, node)
     ctx[:buffer] ||= +''
     ctx[:indent] ||= 0
     method_name = :"on_#{node.type.downcase}"
-    if respond_to?(method_name)
-      send(method_name, ctx, node)
-      ctx[:buffer]
-    else
+
+    if !respond_to?(method_name)
       raise "Could not convert #{node.type} node to ruby"
     end
+
+    send(method_name, ctx, node)
+    ctx[:buffer]
   end
 
+  # Converts a :SCOPE AST node
+  # @param ctx [Hash] context object
+  # @param node [RubyVM::AbstractSyntaxTree::Node] AST node
   def on_scope(ctx, node)
     body = node.children.last
     # if body.type != :BLOCK
@@ -41,6 +82,9 @@ class Rephrase
     emit(ctx, "proc do", [body], "end")
   end
 
+  # Converts a :BLOCK AST node
+  # @param ctx [Hash] context object
+  # @param node [RubyVM::AbstractSyntaxTree::Node] AST node
   def on_block(ctx, node)
     last_idx = node.children.size - 1
     node.children.each_with_index do |c, idx|
@@ -49,12 +93,18 @@ class Rephrase
     end
   end
 
+  # Converts a :ITER AST node
+  # @param ctx [Hash] context object
+  # @param node [RubyVM::AbstractSyntaxTree::Node] AST node
   def on_iter(ctx, node)
     call, scope = node.children
     emit(ctx, call)
     emit(ctx, FakeNode.iter_scope(scope.children))
   end
 
+  # Converts a :ITER_SCOPE AST (fake) node
+  # @param ctx [Hash] context object
+  # @param node [Rephrase::FakeNode] AST node
   def on_iter_scope(ctx, node)
     args, arg_spec, body = node.children
     emit(ctx, " do")
@@ -64,15 +114,24 @@ class Rephrase
     emit(ctx, "\nend")
   end
 
+  # Converts a :CONST AST node
+  # @param ctx [Hash] context object
+  # @param node [RubyVM::AbstractSyntaxTree::Node] AST node
   def on_const(ctx, node)
     emit(ctx, node.children.first.to_s)
   end
 
+  # Converts a :COLON2 AST node
+  # @param ctx [Hash] context object
+  # @param node [RubyVM::AbstractSyntaxTree::Node] AST node
   def on_colon2(ctx, node)
     left, right = node.children
     emit(ctx, left, "::", right.to_s)
   end
 
+  # Converts a :CALL AST node
+  # @param ctx [Hash] context object
+  # @param node [RubyVM::AbstractSyntaxTree::Node] AST node
   def on_call(ctx, node)
     receiver, method, args = node.children
     args = args && FakeNode.list(args.children)
@@ -88,16 +147,25 @@ class Rephrase
     end
   end
 
+  # Converts a :FCALL AST node
+  # @param ctx [Hash] context object
+  # @param node [RubyVM::AbstractSyntaxTree::Node] AST node
   def on_fcall(ctx, node)
     method, args = node.children
     args = args && FakeNode.list(args.children)
     emit(ctx, "#{method}(", args, ")")
   end
 
+  # Converts a :VCALL AST node
+  # @param ctx [Hash] context object
+  # @param node [RubyVM::AbstractSyntaxTree::Node] AST node
   def on_vcall(ctx, node)
     emit(ctx, node.children.first.to_s, "()")
   end
 
+  # Converts a :OPCALL AST node
+  # @param ctx [Hash] context object
+  # @param node [RubyVM::AbstractSyntaxTree::Node] AST node
   def on_opcall(ctx, node)
     left, op, right = node.children
     if op == :!
@@ -107,16 +175,25 @@ class Rephrase
     end
   end
 
+  # Converts a :DASGN_CURR AST node
+  # @param ctx [Hash] context object
+  # @param node [RubyVM::AbstractSyntaxTree::Node] AST node
   def on_dasgn_curr(ctx, node)
     left, right = node.children
     emit(ctx, left.to_s, " = ", right)
   end
 
+  # Converts a :IASGN AST node
+  # @param ctx [Hash] context object
+  # @param node [RubyVM::AbstractSyntaxTree::Node] AST node
   def on_iasgn(ctx, node)
     left, right = node.children
     emit(ctx, left.to_s, " = ", right)
   end
 
+  # Converts a :IF AST node
+  # @param ctx [Hash] context object
+  # @param node [RubyVM::AbstractSyntaxTree::Node] AST node
   def on_if(ctx, node)
     cond, branch1, branch2 = node.children
     if branch2
@@ -126,6 +203,9 @@ class Rephrase
     end
   end
 
+  # Converts a :UNLESS AST node
+  # @param ctx [Hash] context object
+  # @param node [RubyVM::AbstractSyntaxTree::Node] AST node
   def on_unless(ctx, node)
     cond, branch1, branch2 = node.children
     if branch2
@@ -135,39 +215,66 @@ class Rephrase
     end
   end
 
+  # Converts a :WHILE AST node
+  # @param ctx [Hash] context object
+  # @param node [RubyVM::AbstractSyntaxTree::Node] AST node
   def on_while(ctx, node)
     cond, body = node.children
     emit(ctx, "while ", cond, "\n", body, "\nend")
   end
 
+  # Converts a :LIT AST node
+  # @param ctx [Hash] context object
+  # @param node [RubyVM::AbstractSyntaxTree::Node] AST node
   def on_lit(ctx, node)
     emit(ctx, node.children.first.inspect)
   end
 
+  # Converts a :NIL AST node
+  # @param ctx [Hash] context object
+  # @param node [RubyVM::AbstractSyntaxTree::Node] AST node
   def on_nil(ctx, node)
     emit(ctx, "nil")
   end
 
+  # Converts a :TRUE AST node
+  # @param ctx [Hash] context object
+  # @param node [RubyVM::AbstractSyntaxTree::Node] AST node
   def on_true(ctx, node)
     emit(ctx, "true")
   end
 
+  # Converts a :FALSE AST node
+  # @param ctx [Hash] context object
+  # @param node [RubyVM::AbstractSyntaxTree::Node] AST node
   def on_false(ctx, node)
     emit(ctx, "false")
   end
 
+  # Converts a :DVAR AST node
+  # @param ctx [Hash] context object
+  # @param node [RubyVM::AbstractSyntaxTree::Node] AST node
   def on_dvar(ctx, node)
     emit(ctx, node.children.first.to_s)
   end
 
+  # Converts a :IVAR AST node
+  # @param ctx [Hash] context object
+  # @param node [RubyVM::AbstractSyntaxTree::Node] AST node
   def on_ivar(ctx, node)
     emit(ctx, node.children.first.to_s)
   end
 
+  # Converts a :STR AST node
+  # @param ctx [Hash] context object
+  # @param node [RubyVM::AbstractSyntaxTree::Node] AST node
   def on_str(ctx, node)
     emit(ctx, node.children.first.inspect)
   end
 
+  # Converts a :DSTR AST node
+  # @param ctx [Hash] context object
+  # @param node [RubyVM::AbstractSyntaxTree::Node] AST node
   def on_dstr(ctx, node)
     prefix, evstr1, rest = node.children
     emit(ctx, "\"", prefix.inspect[1..-2], evstr1)
@@ -186,20 +293,32 @@ class Rephrase
     emit(ctx, "\"")
   end
 
+  # Converts a :EVSTR AST node
+  # @param ctx [Hash] context object
+  # @param node [RubyVM::AbstractSyntaxTree::Node] AST node
   def on_evstr(ctx, node)
     emit(ctx, "\#{", node.children.first, "}")
   end
 
+  # Converts a :AND AST node
+  # @param ctx [Hash] context object
+  # @param node [RubyVM::AbstractSyntaxTree::Node] AST node
   def on_and(ctx, node)
     left, right = node.children
     emit(ctx, left, " && ", right)
   end
 
+  # Converts a :OR AST node
+  # @param ctx [Hash] context object
+  # @param node [RubyVM::AbstractSyntaxTree::Node] AST node
   def on_or(ctx, node)
     left, right = node.children
     emit(ctx, left, " || ", right)
   end
 
+  # Converts a :LIST AST node
+  # @param ctx [Hash] context object
+  # @param node [RubyVM::AbstractSyntaxTree::Node] AST node
   def on_list(ctx, node)
     items = node.children[0..-2]
     last_idx = items.size - 1
@@ -211,6 +330,9 @@ class Rephrase
     emit(ctx, "]")
   end
 
+  # Converts a :LIST_EMBEDDED AST (fake) node
+  # @param ctx [Hash] context object
+  # @param node [Rephrase::FakeNode] AST node
   def on_list_embedded(ctx, node)
     items = node.children.compact
     last_idx = items.size - 1
@@ -220,6 +342,9 @@ class Rephrase
     end
   end
 
+  # Converts a :HASH AST node
+  # @param ctx [Hash] context object
+  # @param node [RubyVM::AbstractSyntaxTree::Node] AST node
   def on_hash(ctx, node)
     list = node.children.first
     idx = 0
@@ -235,6 +360,9 @@ class Rephrase
     emit(ctx, "}")
   end
 
+  # Converts a :ATTRASGN AST node
+  # @param ctx [Hash] context object
+  # @param node [RubyVM::AbstractSyntaxTree::Node] AST node
   def on_attrasgn(ctx, node)
     left, op, args = node.children
     emit(ctx, left)
@@ -249,12 +377,18 @@ class Rephrase
     end
   end
 
+  # Converts a :RESCUE AST node
+  # @param ctx [Hash] context object
+  # @param node [RubyVM::AbstractSyntaxTree::Node] AST node
   def on_rescue(ctx, node)
     code, rescue_body = node.children
     emit(ctx, code)
     emit(ctx, " rescue ", rescue_body.children[1])
   end
 
+  # Emits code into the context buffer
+  # @param ctx [Hash] context object
+  # @param entries [Array<String, Symbol>] code entries
   def emit(ctx, *entries)
     entries.each do |e|
       case e

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rephrase
 version: !ruby/object:Gem::Version
-  version: '0.1'
+  version: '0.2'
 platform: ruby
 authors:
 - Sharon Rosner