sirop 0.1 → 0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: edde04771185a121f37a4a2df66569803c6f5b18d2a6739923c2a58cedacfc24
-  data.tar.gz: 364af589b7a6ca122f32447c23dc281b296e6ade1b9f280dca3e6e51b50d456b
+  metadata.gz: 1641ee60187094fe9dcdeebefbfc5283c0d2ea535aa161b17f7bf6f720d63854
+  data.tar.gz: c9abaef1a8b7116760f92e143bcb2e58fbc4424fe3d4afe110bc10bf552852cf
 SHA512:
-  metadata.gz: 6bb9fc18cefdbe071ba2b1d7f54fd0aa8111f97ffde49c362b4314e92d300e33075711a956384c15ee7880dab8bc85524d63de3ef5625278aa35917fce983066
-  data.tar.gz: e35e58fc9ba7d223d68298a3a25c8cb30596a1f548e314298de10730b6ea49456486fff541bee1cca5df3f3b092cd59e98fe3e9634a92be75f1d5b4bf5532c6e
+  metadata.gz: 3900ece58c932df6181676abb597fa6deedfbd8801e28f4993cc36cce7584a188e88b73e6ef2b0fea33b5dbc8a8d284949159973cb108e149dd0d9b3ea5dd762
+  data.tar.gz: 7f848b0e842792a33e3fc7c9b7d6cf72e924040307e2db5ccb0cff16af1e947e7053ee81e54ab688c131532b66432dc1283651ceeef5820ded58c3b8447d193a

data/CHANGELOG.md

@@ -1,3 +1,11 @@
+# 2024-02-27 0.2
+
+- Update README
+- Remove support for Ruby < 3.2
+- Implement general purpose Finder for finding nodes
+- Implement DSL compiler (for tests)
+- Implement Sirop.to_source
+
 # 2024-02-20 0.1
 
 - Find node for a given `Proc` object

data/README.md

@@ -1,4 +1,113 @@
 # Sirop
 
-Sirop is a Ruby code rewriter. More information coming soon...
+Sirop is a Ruby gem for manipulating Ruby source code. Sirop is very young, so
+the following information might be incomplete, out of date, or simply wrong!
 
+## Use Cases
+
+Some of the use cases addressed by Sirop are:
+
+- Compile DSLs into optimized Ruby code. This is especially interesting for HTML
+  templating DSLs in libraries like Phlex, Papercraft etc.
+  [Example](https://github.com/digital-fabric/sirop/blob/main/test/dsl_compiler.rb)
+- Get the source of a given block or method.
+- Rewrite parts of Ruby code, for implementing Ruby macros (and why not?).
+
+## Limitations
+
+- Sirop supports Ruby 3.2 or newer.
+- Sirop can be used only on blocks and methods defined in a file, so cannot
+  really be used on dynamically `eval`'d Ruby code, or in an IRB/Pry session.
+
+## Getting the AST/source of a Ruby proc or method
+
+To get the AST of a proc or a method, use `Sirop.to_ast`:
+
+```ruby
+# for a proc
+mul = ->(x, y) { x * y }
+Sirop.to_ast(mul) #=> ...
+
+# for a method
+def foo; :bar; end
+Sirop.to_ast(method(:foo)) #=> ...
+```
+
+To get the source of a proc or a method, use `Sirop.to_source`:
+
+```ruby
+mul = ->(x, y) { x * y }
+Sirop.to_source(mul) #=> "->(x, y) { x * y }"
+
+def foo; :bar; end
+Sirop.to_source(method(:foo)) #=> "def foo; :bar; end"
+```
+
+## Rewriting Ruby code
+
+You can consult the [DSL compiler
+example](https://github.com/digital-fabric/sirop/blob/main/test/dsl_compiler.rb). This example intercepts method calls by defining a `visit_call_node` method:
+
+```ruby
+# Annotated with some explanations
+def visit_call_node(node)
+  # don't rewrite if the call has a receiver
+  return super if node.receiver
+
+  # set HTML location start
+  @html_location_start ||= node.location
+  # get method arguments...
+  inner_text, attrs = tag_args(node)
+  # and block
+  block = node.block
+
+  # emit HTML tag according to given arguments
+  if inner_text
+    emit_tag_open(node, attrs)
+    emit_tag_inner_text(inner_text)
+    emit_tag_close(node)
+  elsif block
+    emit_tag_open(node, attrs)
+    visit(block.body)
+    emit_tag_close(node)
+  else
+    emit_tag_open_close(node, attrs)
+  end
+  # set HTML location end
+  @html_location_end = node.location
+end
+```
+
+## Future directions
+
+- Implement a macro expander with support for `quote`/`unquote`:
+
+  ```ruby
+  trace_macro = Sirop.macro do |ast|
+    source = Sirop.to_source(ast)
+    quote do
+      result = unquote(ast)
+      puts "The result of #{source} is: #{result}"
+      result
+    end
+  end
+
+  def add(x, y)
+    trace(x + y)
+  end
+
+  Sirop.expand_macros(method(:add), trace: trace_macro)
+  ```
+
+- Implement a DSL compiler with hooks for easier usage in DSL libraries.
+
+## Contributing
+
+We gladly welcome contributions from anyone! Some areas that need work currently
+are:
+
+- Documentation
+- More test cases for Ruby syntax in the Sirop tests. Look here:
+  https://github.com/digital-fabric/sirop/tree/main/test/fixtures
+
+Please feel free to contribute PR's and issues

data/lib/sirop/finder.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require 'prism'
+
+module Sirop
+  class Finder < Prism::BasicVisitor
+    def self.find(*, &)
+      finder = self.new
+      finder.find(*, &)
+    end
+
+    def find(root, key, &)
+      instance_exec(&)
+      @key = key
+      catch(key) do
+        visit(root)
+        nil
+      end
+    end
+
+    def found!(node)
+      throw(@key, node)
+    end
+
+    def method_missing(sym, node, *args)
+      visit_child_nodes(node)
+    end
+  end
+end

data/lib/sirop/prism_ext.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require 'prism'
+
+class Prism::BasicVisitor
+  def on(type, &)
+    singleton_class.define_method(:"visit_#{type}_node", &)
+    self
+  end
+end

data/lib/sirop/sourcifier.rb

@@ -0,0 +1,290 @@
+# frozen_string_literal: true
+
+require 'prism'
+
+module Sirop
+  # 
+  class Sourcifier < Prism::BasicVisitor
+    attr_reader :buffer
+
+    def initialize
+      @buffer = +''
+    end
+  
+    def to_source(node)
+      @buffer.clear
+      visit(node)
+      @buffer
+    end
+  
+    def loc_start(loc)
+      [loc.start_line, loc.start_column]
+    end
+  
+    def loc_end(loc)
+      [loc.end_line, loc.end_column]
+    end
+
+    def emit(str)
+      @buffer << str
+    end
+
+    def adjust_whitespace(loc)
+      if @last_loc_start
+        if @last_loc_end.first != loc.start_line
+          @buffer << "\n" * (loc.start_line - @last_loc_end.first)
+          @buffer << ' ' * loc.start_column
+        else
+          ofs = loc.start_column - @last_loc_end.last
+          if ofs > 0
+            @buffer << ' ' * ofs
+          end
+        end
+      else
+        # empty buffer
+        @buffer << ' ' * loc.start_column
+      end
+      @last_loc = loc
+      @last_loc_start = loc_start(loc)
+      @last_loc_end = loc_end(loc)
+    end
+
+    def emit_code(loc, semicolon: false)
+      return if !loc
+
+      emit_semicolon(loc) if semicolon
+      return visit(loc) if loc.is_a?(Prism::Node)
+
+      adjust_whitespace(loc)
+      emit(loc.slice)
+    end
+  
+    def emit_verbatim(node)
+      emit_code(node.location)
+    end
+
+    def emit_str(str)
+      emit(str)
+      @last_loc_end[1] += str.size
+    end
+  
+    def emit_comma
+      emit_str(',')
+    end
+
+    def emit_semicolon(loc)
+      loc = loc.location if loc.is_a?(Prism::Node)
+      emit_str(';') if loc.start_line == @last_loc.end_line
+    end
+
+    def method_missing(sym, node, *args)
+      puts '!' * 40
+      p node
+      raise NotImplementedError, "Don't know how to handle #{sym}"
+      visit_child_nodes(node)
+    end
+
+    VISIT_PLANS = {
+      and:                    [:left, :operator_loc, :right],
+      assoc:                  :visit_child_nodes,
+      assoc_splat:            [:operator_loc, :value],
+      block:                  [:opening_loc, :parameters, :body, :closing_loc],
+      block_argument:         [:operator_loc, :expression],
+      block_parameter:        [:operator_loc, :name_loc],
+      block_parameters:       [:opening_loc, :parameters, :closing_loc],
+      break:                  [:keyword_loc, :arguments],
+      constant_path:          [:parent, :delimiter_loc, :child],
+      constant_read:          :emit_verbatim,
+      else:                   [:else_keyword_loc, :statements],
+      embedded_statements:    [:opening_loc, :statements, :closing_loc],
+      false:                  :emit_verbatim,
+      integer:                :emit_verbatim,
+      keyword_rest_parameter: [:operator_loc, :name_loc],
+      lambda:                 [:operator_loc, :parameters, :opening_loc, :body,
+                               :closing_loc],
+      local_variable_read:    :emit_verbatim,
+      local_variable_write:   [:name_loc, :operator_loc, :value],
+      next:                   [:keyword_loc, :arguments],
+      nil:                    :emit_verbatim,
+      optional_parameter:     [:name_loc, :operator_loc, :value],
+      or:                     [:left, :operator_loc, :right],
+      parentheses:            [:opening_loc, :body, :closing_loc],
+      required_parameter:     :emit_verbatim,
+      rest_parameter:         [:operator_loc, :name_loc],
+      splat:                  [:operator_loc, :expression],
+      statements:             :visit_child_nodes,
+      string:                 :emit_verbatim,
+      symbol:                 :emit_verbatim,
+      true:                   :emit_verbatim,
+      yield:                  [:keyword_loc, :lparen_loc, :arguments, :rparen_loc],
+    }
+
+    VISIT_PLANS.each do |key, plan|
+      sym = :"visit_#{key}_node"
+      define_method(sym) { |n| visit_plan(plan, n) }
+    end
+  
+    def visit_plan(plan, node)
+      return send(plan, node) if plan.is_a?(Symbol)
+
+      insert_semicolon = false
+      plan.each_with_index do |sym, idx|
+        if sym == :semicolon
+          insert_semicolon = true
+          next
+        end
+
+        obj = node.send(sym)
+        emit_code(obj, semicolon: insert_semicolon)
+        insert_semicolon = false
+      end
+    end
+
+    def visit_comma_separated_nodes(list, comma = false)
+      if list
+        list.each_with_index do |child, idx|
+          emit_comma if comma
+          emit_code(child)
+          comma = true
+        end
+      end
+      comma
+    end
+
+    def visit_parameters_node(node)
+      comma = visit_comma_separated_nodes(node.requireds)
+      comma = visit_comma_separated_nodes(node.optionals, comma)
+      comma = visit_comma_separated_nodes(node.posts, comma)
+      if node.rest
+        emit_comma if comma
+        comma = true
+        emit_code(node.rest)
+      end
+      if node.keyword_rest
+        emit_comma if comma
+        comma = true
+        emit_code(node.keyword_rest)
+      end
+      if node.block
+        emit_comma if comma
+        comma = true
+        emit_code(node.block)
+      end
+    end
+
+    def visit_arguments_node(node)
+      visit_comma_separated_nodes(node.arguments)
+    end
+  
+    def visit_keyword_hash_node(node)
+      visit_comma_separated_nodes(node.elements)
+    end
+
+    def visit_if_node(node)
+      if !node.if_keyword_loc
+        return visit_if_node_ternary(node)
+      elsif !node.end_keyword_loc
+        return visit_if_node_guard(node)
+      end
+
+      emit_code(node.if_keyword_loc)
+      emit_code(node.predicate)
+      emit_code(node.then_keyword_loc)
+      emit_code(node.statements)
+      emit_code(node.consequent) if node.consequent
+      emit_code(node.end_keyword_loc) if node.if_keyword_loc.slice == 'if'
+    end
+
+    def visit_if_node_ternary(node)
+      emit_code(node.predicate)
+      emit_code(node.then_keyword_loc)
+      emit_code(node.statements)
+      emit_code(node.consequent)
+    end
+
+    def visit_if_node_guard(node)
+      emit_code(node.statements)        
+      emit_code(node.if_keyword_loc)
+      emit_code(node.predicate)
+    end
+
+    def visit_case_node(node)
+      emit_code(node.case_keyword_loc)
+      emit_code(node.predicate)
+      node.conditions.each { |c| emit_code(c) }
+      emit_code(node.consequent)
+      emit_code(node.end_keyword_loc)
+    end
+
+    def visit_when_node(node)
+      emit_code(node.keyword_loc)
+      visit_comma_separated_nodes(node.conditions)
+      emit_code(node.statements)
+    end
+
+    def visit_interpolated_symbol_node(node)
+      emit_code(node.opening_loc)
+      node.parts.each { |p| emit_code(p) }
+      emit_code(node.closing_loc)
+    end
+    alias_method :visit_interpolated_string_node, :visit_interpolated_symbol_node
+
+    def visit_def_node(node)
+      emit_code(node.def_keyword_loc)
+      emit_code(node.name_loc)
+      last_loc = node.name_loc
+
+      if node.parameters
+        emit_str('(')
+        emit_code(node.parameters)
+        emit_str(')')
+        last_loc = node.parameters.location
+      end
+
+      emit_code(node.body, semicolon: true)
+      emit_code(node.end_keyword_loc, semicolon: true)
+    end
+
+    def visit_call_node(node)
+      if node.receiver && !node.call_operator_loc && !node.arguments
+        return visit_call_node_unary_op(node)
+      end
+
+      block = node.block
+
+      emit_code(node.receiver)
+      emit_code(node.call_operator_loc)
+      emit_code(node.message_loc)
+      emit_code(node.opening_loc)
+      emit_code(node.arguments)
+      
+      if block.is_a?(Prism::BlockArgumentNode)
+        emit_comma if node.arguments&.arguments.size > 0
+        emit_code(block)
+        block = nil
+      end
+      emit_code(node.closing_loc)
+      emit_code(block)
+    end
+
+    def visit_call_node_unary_op(node)
+      emit_code(node.message_loc)
+      emit_code(node.receiver)
+    end
+
+    def visit_while_node(node)
+      return visit_while_node_guard(node) if !node.closing_loc
+
+      emit_code(node.keyword_loc)
+      emit_code(node.predicate)
+      emit_code(node.statements, semicolon: true)
+      emit_code(node.closing_loc, semicolon: true)
+    end
+
+    def visit_while_node_guard(node)
+      emit_code(node.statements)
+      emit_code(node.keyword_loc)
+      emit_code(node.predicate)
+    end
+  end
+end

data/lib/sirop/version.rb

@@ -1,4 +1,4 @@
 module Sirop
   # Sirop version
-  VERSION = '0.1'
+  VERSION = '0.2'
 end

data/lib/sirop.rb

@@ -1,27 +1,61 @@
 # frozen_string_literal: true
 
 require 'prism'
-require 'sirop/block_finder'
+require 'sirop/prism_ext'
+require 'sirop/finder'
+require 'sirop/sourcifier'
 
 module Sirop
   class << self
-    def find(obj)
+    def to_ast(obj)
       case obj
       when Proc
-        find_proc(obj)
+        proc_ast(obj)
+      when UnboundMethod, Method
+        method_ast(obj)
       else
         raise ArgumentError, "Invalid object type"
       end
     end
 
-    def find_proc(proc)
+    def to_source(obj)
+      obj = to_ast(obj) if !obj.is_a?(Prism::Node)
+      Sourcifier.new.to_source(obj)
+    end
+
+    private
+
+    def proc_ast(proc)
       fn, lineno = proc.source_location  
       pr = Prism.parse(IO.read(fn), filepath: fn)
       program = pr.value
-    
-      finder = Sirop::BlockFinder.new(proc, lineno)
-      finder.find(program)
+
+      Finder.find(program, proc) do
+        on(:lambda) do |node|
+          found!(node) if node.location.start_line == lineno
+          super(node)
+        end
+        on(:call) do |node|
+          case node.name
+          when :proc, :lambda
+            found!(node) if node.block && node.block.location.start_line == lineno
+          end
+          super(node)
+        end
+      end
+    end
+
+    def method_ast(method)
+      fn, lineno = method.source_location
+      pr = Prism.parse(IO.read(fn), filepath: fn)
+      program = pr.value
+
+      Finder.find(program, method) do
+        on(:def) do |node|
+          found!(node) if node.name == method.name && node.location.start_line == lineno
+          super(node)
+        end
+      end
     end
-  
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sirop
 version: !ruby/object:Gem::Version
-  version: '0.1'
+  version: '0.2'
 platform: ruby
 authors:
 - Sharon Rosner
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-02-20 00:00:00.000000000 Z
+date: 2024-02-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: prism
@@ -48,15 +48,16 @@ files:
 - CHANGELOG.md
 - README.md
 - lib/sirop.rb
-- lib/sirop/block_finder.rb
+- lib/sirop/finder.rb
+- lib/sirop/prism_ext.rb
+- lib/sirop/sourcifier.rb
 - lib/sirop/version.rb
 homepage: http://github.com/digital-fabric/sirop
 licenses:
 - MIT
 metadata:
-  source_code_uri: https://github.com/digital-fabric/sirop
-  documentation_uri: https://www.rubydoc.info/gems/sirop
   homepage_uri: https://github.com/digital-fabric/sirop
+  documentation_uri: https://www.rubydoc.info/gems/sirop
   changelog_uri: https://github.com/digital-fabric/sirop/blob/main/CHANGELOG.md
 post_install_message:
 rdoc_options:
@@ -70,7 +71,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.0'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="

data/lib/sirop/block_finder.rb

@@ -1,42 +0,0 @@
-# frozen_string_literal: true
-
-module Sirop
-  class BlockFinder < Prism::BasicVisitor
-    attr_accessor :block_node
-  
-    def initialize(proc, lineno)
-      @proc = proc
-      @lineno = lineno
-    end
-
-    def find(program)
-      # p program
-      # puts
-      catch(@proc) {
-        visit(program)
-        nil
-      }  
-    end
-  
-    def visit_lambda_node(node)
-      if node.location.start_line == @lineno
-        throw @proc, node
-      else
-        visit_child_nodes(node)
-      end
-    end
-
-    def visit_call_node(node)
-      case node.name
-      when :proc, :lambda
-        if node.block && node.block.location.start_line == @lineno
-          throw @proc, node
-        end
-      end
-    end
-
-    def method_missing(sym, node, *args)
-      visit_child_nodes(node)
-    end
-  end  
-end