method-pipeline 1.0.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 197ac28d84c9435d6f894925841cd79b2f25510529b1f027b539b6cb181dac17
+  data.tar.gz: 6308de9cb33fac936542ca87904530649c45f791cfc67ebc60a09f357d967e7a
+SHA512:
+  metadata.gz: 82f756e9b6fa5faf26aff5e832a3c50d7305b9a0ad0a398b8fccbe59f7121a9916ac242329b598df064439db0cc6d8f6c5a479e5d8235d7c4ffa0f40813ee631
+  data.tar.gz: b94a698fed672c08d6d939c1bedbd8056b2de306bce1eeda964d67b05a110c76656b23bbe4ef447e3bd90a948a5d3a4dcce47fa5814adcfbb07456f7c45606f3

data/Gemfile

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+source 'https://rubygems.org'
+gemspec
+
+# Development Apps
+group :development do
+  group :type_check do
+    gem 'rbs', '~> 3.1.0', require: false
+    gem 'steep', '~> 1.5.0', require: false
+  end
+  group :documentation do
+    gem 'yard', '~> 0.9.0', require: false
+    gem 'commonmarker', '~> 0.23.0', require: false
+  end
+  group :test do
+    gem 'rake', '~> 13.0.0'
+    gem 'minitest', '~> 5.19.0'
+  end
+end

data/LICENSE.txt

@@ -0,0 +1,35 @@
+Copyright (c) 2023 ParadoxV5
+
+The Universal Permissive License (UPL), Version 1.0
+
+Subject to the condition set forth below, permission is hereby granted to any
+person obtaining a copy of this software, associated documentation and/or data
+(collectively the "Software"), free of charge and under any and all copyright
+rights in the Software, and any and all patent rights owned or freely
+licensable by each licensor hereunder covering either (i) the unmodified
+Software as contributed to or provided by such licensor, or (ii) the Larger
+Works (as defined below), to deal in both
+
+(a) the Software, and
+(b) any piece of software and/or hardware listed in the lrgrwrks.txt file if
+one is included with the Software (each a "Larger Work" to which the Software
+is contributed by such licensors),
+
+without restriction, including without limitation the rights to copy, create
+derivative works of, display, perform, and distribute the Software and make,
+use, sell, offer for sale, import, export, have made, and have sold the
+Software and the Larger Work(s), and to sublicense the foregoing rights on
+either these or other terms.
+
+This license is subject to the following condition:
+The above copyright notice and either this complete permission notice or at
+a minimum a reference to the UPL must be included in all copies or
+substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,148 @@
+The `Pipeline` Refinement module bundles a method duo that builds
+a clean and clever pure-Ruby solution to rightward method piping.
+
+A reminder that Refinement modules are activated with `using` and last only
+for that module/class block or file (if top-level). See: `refinements.rdoc`
+([on docs.ruby-lang.org](https://docs.ruby-lang.org/en/master/syntax/refinements_rdoc.html))
+
+
+## Synopsis Example
+
+Here’s the example from `Kernel#then` straight off the Ruby 3.2 docs:
+```ruby
+require 'open-uri'
+require 'json'
+
+construct_url(arguments).
+  then {|url| URI(url).read }.
+  then {|response| JSON.parse(response) }
+```
+
+With the new Refinement active: (Oh gosh, this looks like a brand-new language!)
+```ruby
+using Pipeline
+
+arguments.then_pipe(
+  `construct_url`,
+  `URI`,
+  :read,
+  JSON.`:parse
+)
+```
+
+
+## Walkthrough Introduction
+
+We traditionally pipe methods leftwards as nesting arguments:
+```ruby
+def parse(string) = …
+do_stuff = ->(a){ … }
+
+# This is even more incomprehensible if omitting round parentheses (poetry mode)
+STDOUT.puts(     # different-scope method
+  do_stuff.call( # Proc
+    parse(       # same-scope method
+      input
+    )
+  )
+)
+```
+
+The trending Rightward Operations improve readability –
+especially for wordy expressions like the above –
+by matching English’s left-to-right writing direction.
+We currently accomplish this with `Object#then` and *light-weight Procs*:
+```ruby
+input
+  .then { parse _1 }
+  .then { do_stuff.call _1 }
+  .then { STDOUT.puts _1 }
+```
+
+We alternatively can deconstruct the corresponding `#to_proc` objects with `&`:
+```ruby
+# heck, these `method` calls can't even go poetry mode
+input
+  .then(&method(:parse))
+  .then(&do_stuff)
+  .then(&STDOUT.method(:puts))
+```
+
+The Refinement module `Pipeline` introduces `Object#then_pipe` to
+eliminate repeating `then(&…)`. It gives a beautiful vibe similar to
+that of the Pipe Operator `|>` in some other languages (namely Elixir).
+```ruby
+using Pipeline
+
+input.then_pipe(
+  method(:parse),
+  do_stuff,
+  STDOUT.method(:puts)
+)
+```
+
+However, unlike Lisp-1 languages like Python or JavaScript,
+Lisp-2s like Ruby face the additional challenge of namespace disambiguation.
+Ruby solves it with the reflection methods `method` & co., but, as seen above,
+their verbosity makes them eyesores inside otherwise elegant syntax.
+Therefore, `Pipeline` further improves the grammar by replacing the `` `…` ``
+syntax (powered by `` Kernel#` ``) with an `alias` of the bulky `Object#method`:
+```ruby
+using Pipeline
+
+input.then_pipe(
+  `parse`,
+  do_stuff,
+  STDOUT.`:puts
+)
+```
+
+
+## Why `` #` ``?
+
+* It is the backend of both `` `…` `` and `%x{…}` syntaxes –
+  ``self.`:meth`` can instead be `%x:meth:` or `` `meth` ``.
+* A Ruby script is not (strictly) a Shell script. User system differences aside,
+  summoning subshells should be the last resort when there are no Ruby/Gem APIs.
+  Dedicating the `` ` `` char to subshells is a waste;
+  e.g., you typically see `$(…)` in bash rather than `` `…` ``.
+  `Pipeline` assigns `` #` `` a new and recurrent purpose; it also `alias`es
+  the original `` Kernel#` `` to `Object#sys` in the event of its preference.
+
+
+## Limitations
+
+* **The new `` #` `` ignores method visibilities (`private` or `protected`).**
+  * This is a Ruby limitation – one can bypass visibilities with
+    `Object#method` and `Method#call` regardless of this Refinement.
+    A security engineer would love reflection APIs that respect visibilities.
+  * The original design for the new `` #` `` was to match `Object#public_method`,
+    but it couldn’t retrieve oneself’s own `private` and `protected` methods.
+* **`#then_pipe` cannot pass additional arguments at each step.**
+  * The current `Object#then`-based solution is as good as it can get –
+    There are no syntactical benefits to avoid a block while calling rightwards.
+    Hey, unlike `#then_pipe`, it welcomes (inner) blocks.
+    ```ruby
+    # a lambda – a Proc with fixed arities, unlike regula-o’ procs (or blocks)
+    do_stuff = ->(a, o, z){ … }
+    
+    # This essentially wraps `do_stuff` in a one-arg block (as in F#).
+    # The `_1` resembles Hack’s special pipe variable `$$`.
+    o.then { do_stuff.(a, _1, z) }
+    # The previous, adapted for `then_pipe`
+    o.then_pipe ->{ do_stuff.(a, _1, z) }
+    # Pure-rightward solution
+    [a, o, b].then { do_stuff.(*_1) }
+    ```
+
+
+## Miniblog: My insights on a Pipeline Operator for Ruby
+
+https://gist.github.com/ParadoxV5/4f563e609decbdac07d40e5f2dead751
+
+
+## License
+
+Copyright (c) 2023 ParadoxV5
+
+Licensed under the [Universal Permissive License v 1.0](https://oss.oracle.com/licenses/upl/)

data/Rakefile

@@ -0,0 +1,8 @@
+require 'minitest/test_task'
+# Create the following tasks:
+# * test          : run tests
+# * test:cmd      : print the testing command
+# * test:isolated : run tests independently to surface order dependencies
+# * test:deps     : (alias of test:isolated)
+# * test:slow     : run tests and reports the slowest 25
+Minitest::TestTask.create

data/Steepfile

@@ -0,0 +1,4 @@
+target :lib do
+  check 'lib'
+  signature 'sig'
+end

data/lib/pipeline.rb

@@ -0,0 +1,54 @@
+# The `Pipeline` Refinement module bundles a method duo that builds
+# a clean and clever pure-Ruby solution to rightward method piping.
+# Check out [the README](index.html) for examples.
+# 
+# Reminder: activate a Refinement module with `using`:
+# ```ruby
+# using Pipeline
+# my_obj.then_pipe(…)
+# ```
+# Refinements are only active for the module/class block or file
+# (if top-level) that’s `using` them. See: `refinements.rdoc`
+# ([on docs.ruby-lang.org](https://docs.ruby-lang.org/en/master/syntax/refinements_rdoc.html))
+# 
+# @!method then_pipe(*procs)
+#   Yield `self` to the first `Proc` (or `#to_proc` object) argument,
+#   then the result to the second argument, and so forth.
+#   ```ruby
+#   construct_url(arguments).then_pipe(
+#     proc {|url| URI(url).read },
+#     JSON.public_method :parse
+#   )
+#   ```
+#   @param procs `Proc` or `#to_proc` objects to call
+#   @return The result of the last call, or `self` if no arguments were given.
+# 
+# @!method sys(command)
+#   Provide a replacement alias for `` Kernel#` ``, the subshell method.
+#   @see #`
+# 
+# @!method `(name)
+#   Alias `Object#method`.
+#   ```ruby
+#   m = 42.` :to_s
+#   m.call #=> "42"
+#   ```
+#   The `` ` `` method is the backend to the `` `…` `` and `%x{…}` syntaxes.
+#   ```ruby
+#   class MyArray < Array
+#     using Pipeline
+#     def fetch_values(*indices)
+#       indices.map(&`[]`)
+#     end
+#   end
+#   a = MyArray.new(['A', 'B', 'C'])
+#   a.fetch_values 1, 3 #=> ["B", nil]
+#   ```
+#   @see #sys
+
+module Pipeline; refine Object do
+  def then_pipe(*procs) = procs.reduce(self) { _1.then(&_2) }
+  
+  alias sys `
+  alias ` method
+end end

data/pipeline.gemspec

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+Gem::Specification.new do |spec|
+  spec.name = 'method-pipeline'
+  spec.summary = 'Pure-Ruby solution to method pipelines'
+  spec.version = '1.0.3'
+  spec.author = 'ParadoxV5'
+  spec.license = 'UPL-1.0'
+  
+
+  github_account = spec.author
+  github = File.join 'https://github.com', github_account, spec.name
+  spec.homepage = github
+  spec.metadata = {
+    'homepage_uri'      => spec.homepage,
+    'source_code_uri'   => github,
+    'changelog_uri'     => File.join(github, 'releases'),
+    'bug_tracker_uri'   => File.join(github, 'issues'),
+    'documentation_uri' => File.join('https://rubydoc.info/gems', spec.name)
+  }
+  
+  spec.files = Dir['**/*']
+  spec.required_ruby_version = '~> 3.2'
+end

data/rbs_collection.yaml

@@ -0,0 +1,7 @@
+path: .gem_rbs_collection
+
+sources:
+- name: ruby/gem_rbs_collection
+  remote: https://github.com/ruby/gem_rbs_collection.git
+  revision: main
+  repo_dir: gems

data/sig/pipeline.rbs

@@ -0,0 +1,13 @@
+module Pipeline
+  VERSION: String
+  
+  interface _Function
+    def to_proc: () -> ^(untyped) -> untyped
+  end
+end
+class Object
+  def then_pipe: (*Pipeline::_Function procs) -> untyped
+  
+  def sys: (String) -> String
+  alias ` method
+end

data/test/pipeline_test.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+require 'minitest/autorun'
+require 'pipeline'
+describe Pipeline do
+  
+  it 'is a module that refines the Object class and only that' do
+    assert_kind_of Module, Pipeline
+    assert_equal [Object], Pipeline.refinements.map(&:refined_class)
+    assert_empty Pipeline.instance_methods
+    assert_empty Pipeline.private_instance_methods
+  end
+  using Pipeline
+  
+  describe '`#method` shorthand' do
+    it 'overrides `backticks` with a public delegate to #method or equivalent' do
+      o = Object.new
+      def o.echo = # do nothing for a phony name
+      assert_equal o.method(:echo), o.`('echo')
+      assert_equal o.method(:__id__), o.`(:__id__) 
+      pass if o.`(:initialize)
+    end
+    
+    it 'renames Object#` to Object#sys' do
+      assert_equal :`, Object.instance_method(:sys).original_name
+      random_string = Kernel.rand.to_s
+      assert_equal random_string, sys("echo #{random_string}").chomp
+    end
+  end
+  
+  it 'defines Object#then_pipe that chain-calls each of the given _ToProc’s  with the receiver as the first arg' do
+    receiver, proc_return = Object.new, Object.new
+    # It is neither required nor forbidden for `#then_pipe` to also
+    # pass their blocks to their _ToProc arg(s) (block-ception Lol)
+    a_proc = proc do|arg|
+      assert_same receiver, arg
+      proc_return
+    end
+    a_proc_like = Object.new
+    a_proc_like.define_singleton_method(:to_proc) { a_proc }
+    assert_same proc_return, receiver.then_pipe(a_proc_like)
+    receiver.then_pipe(a_proc, ->{ assert_same proc_return, _1 })
+  end
+end

metadata

@@ -0,0 +1,57 @@
+--- !ruby/object:Gem::Specification
+name: method-pipeline
+version: !ruby/object:Gem::Version
+  version: 1.0.3
+platform: ruby
+authors:
+- ParadoxV5
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2023-07-26 00:00:00.000000000 Z
+dependencies: []
+description: 
+email: 
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- Steepfile
+- lib/pipeline.rb
+- pipeline.gemspec
+- rbs_collection.yaml
+- sig/pipeline.rbs
+- test/pipeline_test.rb
+homepage: https://github.com/ParadoxV5/method-pipeline
+licenses:
+- UPL-1.0
+metadata:
+  homepage_uri: https://github.com/ParadoxV5/method-pipeline
+  source_code_uri: https://github.com/ParadoxV5/method-pipeline
+  changelog_uri: https://github.com/ParadoxV5/method-pipeline/releases
+  bug_tracker_uri: https://github.com/ParadoxV5/method-pipeline/issues
+  documentation_uri: https://rubydoc.info/gems/method-pipeline
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - "~>"
+    - !ruby/object:Gem::Version
+      version: '3.2'
+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: Pure-Ruby solution to method pipelines
+test_files: []