not_a_pipe 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7bce76fdfb113226a7d9df588a1b8f74cef8be5bac312cec5c0207645e3ff9a1
+  data.tar.gz: 2814f87bc83c48f10e035b9a372706834aa4480278bd1ec31efe1987bfa2759b
+SHA512:
+  metadata.gz: 909b726c84f8f5711f515a28522e81f842e8d5bf38c2d1e402a015109c8170b013766ea71d725c2b1eff183e250123042fc78ef97d717007b548fca01fc6e8e8
+  data.tar.gz: 5ad91cdb551c346c6929e3ebc36b45d7b6e4e87c349b18ad14dba135d8a885f6bba63dfe10c84a63c00f4364a7e3d567c34204f7b6ae4d270ecf8b268b93cb40

data/README.md

@@ -0,0 +1,88 @@
+<p align="center">
+  <a href="https://en.wikipedia.org/wiki/The_Treachery_of_Images"><img src="https://github.com/zverok/not_a_pipe/blob/main/img/une_pipe.jpg?raw=true"/></a>
+</p>
+
+# This is not a pipe
+
+This is an experimental/demo Ruby implementation of Elixir-style pipes. It allows to write code like this:
+
+```ruby
+require 'not_a_pipe'
+
+extend NotAPipe
+
+pipe def repos(username)
+  username >>
+    "https://api.github.com/users/#{_}/repos" >>
+    URI.open >>
+    _.read >>
+    JSON.parse(symbolize_names: true) >>
+    _.map { _1.dig(:full_name) }.first(10) >>
+    pp
+end
+```
+
+Basically:
+* `not_a_pipe` is a decorator to mark methods inside which `>>` works as “pipe operator”;
+* every step can reference `_` which would be a result of the previous step;
+* but it also can omit the reference and just specify a method to call; the result of the previous step would be substituted as the _first argument_ of the method.
+
+`not_a_pipe` works by _rewriting the AST_ and reevaluating the (rewritten) method code at the definition time and has no runtime penalty; thus achieving something akin to macros.
+
+**It is not intended to use in production codebase**, but rather as an approach investigation/demonstration.
+
+Inspired by a [Python’s library](https://github.com/Jordan-Kowal/pipe-operator?tab=readme-ov-file#-elixir-like-implementation) that uses the similar approach, and a [recent discussion](https://bugs.ruby-lang.org/issues/20770#note-34) in Ruby’s bug-tracker.
+
+See also an [explanatory blog-post](https://zverok.space/blog/2024-11-16-elixir-pipes.html).
+
+## Usage
+
+Don’t. Really. The code is really naive, tested only for simple cases, and is not intended as a library that will be relied upon. It is an experiment.
+
+But if you want to play, you can install it as a gem:
+
+```bash
+gem install not_a_pipe
+```
+
+...and then follow the example above.
+
+## Benchmarks
+
+See `benchmark.rb`. Compared versions are:
+* “naive” Ruby code which puts values into intermediate variables;
+* `.then`-based Ruby version that chains everything in one statement;
+* `not_a_pipe` version
+* [pipe_envy](https://github.com/hopsoft/pipe_envy)-based solution, which is pretty simple (allows to join callable objects with `>>`)
+* [pipe_operator](https://github.com/LendingHome/pipe_operator)-based solution, which is impressively witty looking but requires an extensive implementation with “proxy objects”
+
+```
+ruby 3.3.0 (2023-12-25 revision 5124f9ac75) [x86_64-linux]
+Warming up --------------------------------------
+               naive     3.000 i/100ms
+               .then     3.000 i/100ms
+          not_a_pipe     4.000 i/100ms
+       pipe_operator     1.000 i/100ms
+           pipe_envy     1.000 i/100ms
+Calculating -------------------------------------
+               naive     18.488 (± 5.4%) i/s   (54.09 ms/i) -     93.000 in   5.067112s
+               .then     15.622 (± 6.4%) i/s   (64.01 ms/i) -     78.000 in   5.019804s
+          not_a_pipe     18.140 (± 5.5%) i/s   (55.13 ms/i) -     92.000 in   5.083882s
+       pipe_operator      1.520 (± 0.0%) i/s  (657.81 ms/i) -      8.000 in   5.266537s
+           pipe_envy      7.296 (±13.7%) i/s  (137.06 ms/i) -     37.000 in   5.098091s
+
+Comparison:
+               naive:       18.5 i/s
+          not_a_pipe:       18.1 i/s - same-ish: difference falls within error
+               .then:       15.6 i/s - 1.18x  slower
+           pipe_envy:        7.3 i/s - 2.53x  slower
+       pipe_operator:        1.5 i/s - 12.16x  slower
+```
+
+Note that `not_a_pipe` is the _fastest_ version, on par only with “naive” verbose Ruby code with intermediate variables, and without `.then`-chaining (truth be told, on various runs `.then`-based version is frequently “sam-ish”). The rewrite-on-load approach is a rare way to introduce a DSL without _any_ performance penalty.
+
+## Credits
+
+* Implementation: [Victor Shepelev aka zverok](https://zverok.space)
+* The syntax is proposed by Alexandre Magro [on Ruby bug-tracker](https://bugs.ruby-lang.org/issues/20770#note-34)
+* The AST-rewriting approach is inspired by Python’s [pipe_operator](https://github.com/Jordan-Kowal/pipe-operator) library

data/lib/not_a_pipe.rb

@@ -0,0 +1,94 @@
+require 'parser/current'
+require 'unparser'
+require 'method_source'
+
+module NotAPipe
+  # Usage:
+  #
+  #   pipe def my_method
+  #      value >> Some.method >> _.some_call >> [_, anything]
+  #   end
+  #
+  # Will rewrite and reevaluate method code, replacing it with code like:
+  #
+  #   def my_method
+  #      _ = value
+  #      _ = Some.method(_)
+  #      _ = _.some_call
+  #      _ = [_, anything]
+  #   end
+  def pipe(name)
+    meth = is_a?(Module) ? instance_method(name) : method(name)
+    # Replacement is because method_source will read `pipe def foo; ...` from source including
+    # pipe decorator.
+    src = meth.source.sub(/\bpipe\s*?/, '')
+    src = NotAPipe.rewrite(src)
+
+    if is_a?(Module)
+      module_eval src
+    else
+      instance_eval src
+    end
+  end
+
+  class << self
+    def rewrite(code)
+      node = Unparser.parse(code)
+      node = rewrite_node(node)
+      # Without predefined `_` local var, parser will consider it a method. Forcibly replace all `_()` with `_`
+      Unparser.unparse(node).gsub(/\b_\(\)/, '_')
+    end
+
+    private
+
+    def rewrite_node(node)
+      case node
+      in [:send, left, :>>, right]
+        # foo >> bar >> baz is parsed as:
+        #   left = foo >> bar
+        #   right = baz
+        # `flatten_pipes` will make them into
+        #   [foo, bar, baz]
+        # `rewrite_step` will substitute `Some.method(some, args)` with `Some.method(_, some, args)`, unless
+        # `_` is already a part of the expression
+        steps = [*flatten_pipes(left), right].then { |first, *rest| [first, *rest.map { rewrite_step(_1) }] }
+        # Now turn every foo, bar, baz into `_ = foo`, `_ = bar`, `_ = baz`
+        s(:begin, *steps.map { s(:lvasgn, :_, _1) })
+      in Parser::AST::Node
+        s(node.type, *node.children.map { rewrite_node(_1) })
+      else
+        node
+      end
+    end
+
+    def flatten_pipes(node)
+      case node
+      in [:send, left, :>>, right]
+        [*flatten_pipes(left), right]
+      else
+        [node]
+      end
+    end
+
+    def rewrite_step(node)
+      # This check is probably too naive, but this is a demo anyway.
+      # Basically, if the step of a "pipe" includes _any_ usage of a standalone `_`, we consider
+      # it doesn't need any rewriting.
+      return node if node.loc.expression.source.match?(/\b_\b/)
+
+      # Otherwise, we rewrite it
+      case node
+      in [:send, receiver, sym, *args]
+        # ...by changing every `foo` to `foo(_)`, any `bar(1, 2, 3)` to `bar(_, 1, 2, 3)` etc
+        s(:send, receiver, sym, s(:lvar, :_), *args)
+      else
+        # ...and that's it so far!
+        raise ArgumentError, "Unrewriteable step: #{node}"
+      end
+    end
+
+    def s(type, *children)
+      Parser::AST::Node.new(type, children)
+    end
+  end
+end

metadata

@@ -0,0 +1,114 @@
+--- !ruby/object:Gem::Specification
+name: not_a_pipe
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Victor Shepelev
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2024-11-16 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: parser
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: unparser
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: method_source
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rubygems-tasks
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: "    Experimental/demo library. Not to be used in production.\n"
+email: zverok.offline@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/not_a_pipe.rb
+homepage: https://github.com/zverok/not_a_pipe
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key: 
+specification_version: 4
+summary: Elixir-style pipes in Ruby (yes, again)
+test_files: []