pipe_operator 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fc08d5b15937d1418ca864e631eb9f0a6a3fafd04e2c1f7496fbdd925531eec7
+  data.tar.gz: 340f185be7fe2f803a0d61603f1b1c89c641f6dfbf21ba691e1c3e48c3c5bdce
+SHA512:
+  metadata.gz: 4b2e3096c092d839dde50eadbc196cef82745371c99cb313f845587b0c4908ab6225a261309984d2cdef927605f44308026adf57a7c02970721d84c0e240d958
+  data.tar.gz: a873ca59f03c6e50630c9d8b91f5494a5b7bfb06b558b21c574c716065f63fb381d155b66c106c4d12de237fbb8b1506bb40fd2e459f130a278ceea26ee0daa5

data/.gitignore

@@ -0,0 +1,4 @@
+coverage
+doc
+pkg
+rdoc

data/.rspec

@@ -0,0 +1,3 @@
+--color
+--format progress
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,116 @@
+AllCops:
+  DisplayCopNames: true
+  TargetRubyVersion: 2.5
+  Exclude:
+    - "Rakefile"
+    - "tmp/**/*"
+
+Gemspec/RequiredRubyVersion:
+  Enabled: false
+
+Layout/AlignHash:
+  Exclude:
+    - "spec/**/*"
+
+Layout/EmptyLineAfterGuardClause:
+  Enabled: false
+
+Layout/SpaceBeforeBlockBraces:
+  Exclude:
+    - "spec/**/*"
+
+Layout/SpaceInsideBlockBraces:
+  Exclude:
+    - "spec/**/*"
+
+Metrics/AbcSize:
+  Enabled: false
+
+Metrics/BlockLength:
+  Enabled: false
+
+Metrics/CyclomaticComplexity:
+  Enabled: false
+
+Metrics/LineLength:
+  Enabled: false
+
+Metrics/MethodLength:
+  Enabled: false
+
+Metrics/PerceivedComplexity:
+  Exclude:
+    - "lib/pipe_operator/proxy.rb"
+    - "lib/pipe_operator/proxy_resolver.rb"
+
+Naming/MemoizedInstanceVariableName:
+  Exclude:
+    - "lib/pipe_operator/closure.rb"
+
+Naming/UncommunicativeMethodParamName:
+  Enabled: false
+
+Style/BlockDelimiters:
+  Exclude:
+    - "spec/**/*"
+
+Style/CaseEquality:
+  Enabled: false
+
+Style/Documentation:
+  Enabled: false
+
+Style/DoubleNegation:
+  Enabled: false
+
+Style/FormatString:
+  Enabled: false
+
+Style/FormatStringToken:
+  Enabled: false
+
+Style/FrozenStringLiteralComment:
+  Enabled: false
+
+Style/GuardClause:
+  Enabled: false
+
+Style/LambdaCall:
+  Exclude:
+    - "spec/**/*"
+
+Style/MethodMissingSuper:
+  Exclude:
+    - "lib/pipe_operator/closure.rb"
+    - "lib/pipe_operator/pipe.rb"
+
+Style/RedundantBegin:
+  Exclude:
+    - "lib/pipe_operator/proxy_resolver.rb"
+
+Style/RescueModifier:
+  Exclude:
+    - "lib/pipe_operator/proxy_resolver.rb"
+
+Style/MissingRespondToMissing:
+  Exclude:
+    - "lib/pipe_operator/closure.rb"
+    - "lib/pipe_operator/pipe.rb"
+
+Style/Semicolon:
+  Exclude:
+    - "spec/**/*"
+
+Style/SingleLineMethods:
+  Exclude:
+    - "spec/**/*"
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/TrailingCommaInHashLiteral:
+  Exclude:
+    - "spec/**/*"
+
+Style/WordArray:
+  Enabled: false

data/Gemfile

@@ -0,0 +1,12 @@
+source "https://www.rubygems.org"
+
+gemspec
+
+gem "codeclimate-test-reporter"
+gem "fasterer"
+gem "pry"
+gem "pry-byebug"
+gem "rake"
+gem "rdoc"
+gem "rspec"
+gem "rubocop"

data/Gemfile.lock

@@ -0,0 +1,83 @@
+PATH
+  remote: .
+  specs:
+    pipe_operator (0.0.1)
+
+GEM
+  remote: https://www.rubygems.org/
+  specs:
+    ast (2.4.0)
+    byebug (10.0.2)
+    codeclimate-test-reporter (1.0.9)
+      simplecov (<= 0.13)
+    coderay (1.1.2)
+    colorize (0.8.1)
+    diff-lcs (1.3)
+    docile (1.1.5)
+    fasterer (0.4.1)
+      colorize (~> 0.7)
+      ruby_parser (~> 3.11.0)
+    jaro_winkler (1.5.1)
+    json (2.1.0)
+    method_source (0.9.2)
+    parallel (1.12.1)
+    parser (2.5.3.0)
+      ast (~> 2.4.0)
+    powerpack (0.1.2)
+    pry (0.12.2)
+      coderay (~> 1.1.0)
+      method_source (~> 0.9.0)
+    pry-byebug (3.6.0)
+      byebug (~> 10.0)
+      pry (~> 0.10)
+    rainbow (3.0.0)
+    rake (12.3.1)
+    rdoc (6.0.4)
+    rspec (3.8.0)
+      rspec-core (~> 3.8.0)
+      rspec-expectations (~> 3.8.0)
+      rspec-mocks (~> 3.8.0)
+    rspec-core (3.8.0)
+      rspec-support (~> 3.8.0)
+    rspec-expectations (3.8.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.8.0)
+    rspec-mocks (3.8.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.8.0)
+    rspec-support (3.8.0)
+    rubocop (0.60.0)
+      jaro_winkler (~> 1.5.1)
+      parallel (~> 1.10)
+      parser (>= 2.5, != 2.5.1.1)
+      powerpack (~> 0.1)
+      rainbow (>= 2.2.2, < 4.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (~> 1.4.0)
+    ruby-progressbar (1.10.0)
+    ruby_parser (3.11.0)
+      sexp_processor (~> 4.9)
+    sexp_processor (4.11.0)
+    simplecov (0.13.0)
+      docile (~> 1.1.0)
+      json (>= 1.8, < 3)
+      simplecov-html (~> 0.10.0)
+    simplecov-html (0.10.2)
+    unicode-display_width (1.4.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  codeclimate-test-reporter
+  fasterer
+  pipe_operator!
+  pry
+  pry-byebug
+  rake
+  rdoc
+  rspec
+  rubocop
+
+BUNDLED WITH
+   1.17.1

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2018 LendingHome - engineering@lendinghome.com
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall 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,384 @@
+# ![LendingHome](https://avatars0.githubusercontent.com/u/5448482?s=24&v=4) pipe_operator
+
+> Elixir/Unix style pipe operations in Ruby - **PROOF OF CONCEPT**
+
+```ruby
+-9.pipe { abs | Math.sqrt | to_i } #=> 3
+```
+
+```ruby
+[9, 64].map(&Math.|.sqrt.to_i) #=> [3, 8]
+```
+
+```ruby
+"https://api.github.com/repos/ruby/ruby".| do
+  URI.parse
+  Net::HTTP.get
+  JSON.parse.fetch("stargazers_count")
+  yield_self { |n| "Ruby has #{n} stars" }
+  Kernel.puts
+end
+#=> Ruby has 15115 stars
+```
+
+## Why?
+
+There's been some recent activity related to `Method` and `Proc` composition in Ruby:
+
+* [#6284 - Add composition for procs](https://bugs.ruby-lang.org/issues/6284)
+* [#13581 - Syntax sugar for method reference](https://bugs.ruby-lang.org/issues/13581)
+* [#12125 - Shorthand operator for Object#method](https://bugs.ruby-lang.org/issues/12125)
+
+This gem was created to **propose an alternative syntax** for this kind of behavior.
+
+## Concept
+
+The general idea is to **pass the result of one expression as an argument to another expression** - similar to [Unix pipelines](https://en.wikipedia.org/wiki/Pipeline_(Unix)):
+
+```ruby
+echo "testing" | sed "s/ing//" | rev
+#=> tset
+```
+
+The [Elixir pipe operator documentation](https://elixirschool.com/en/lessons/basics/pipe-operator/) has some other examples but basically it allows expressions like:
+
+```ruby
+JSON.parse(Net::HTTP.get(URI.parse(url)))
+```
+
+To be **inversed** and rewritten as **left to right** or **top to bottom** which is more **natural to read** in English:
+
+```ruby
+# left to right
+url.pipe { URI.parse | Net::HTTP.get | JSON.parse }
+
+# or top to bottom for clarity
+url.pipe do
+  URI.parse
+  Net::HTTP.get
+  JSON.parse
+end
+```
+
+The differences become a bit **clearer when other arguments are involved**:
+
+```ruby
+loans = Loan.preapproved.submitted(Date.current).where(broker: Current.user)
+data = loans.map { |loan| LoanPresenter.new(loan).as_json }
+json = JSON.pretty_generate(data, allow_nan: false)
+```
+
+Using pipes **removes the verbosity of maps and temporary variables**:
+
+```ruby
+json = Loan.pipe do
+  preapproved
+  submitted(Date.current)
+  where(broker: Current.user)
+  map(&LoanPresenter.new.as_json)
+  JSON.pretty_generate(allow_nan: false)
+end
+```
+
+While the ability to perform a job correctly and efficiently is certainly important - the **true beauty of a program lies in its clarity and conciseness**:
+
+```ruby
+"https://api.github.com/repos/ruby/ruby".| do
+  URI.parse
+  Net::HTTP.get
+  JSON.parse.fetch("stargazers_count")
+  yield_self { |n| "Ruby has #{n} stars" }
+  Kernel.puts
+end
+#=> Ruby has 15115 stars
+```
+
+There's nothing really special here - it's just a **block of expressions like any other Ruby DSL** and the pipe `|` operator has been [around for decades](https://en.wikipedia.org/wiki/Pipeline_(Unix))!
+
+```ruby
+# we can already do this
+objects.map(&Marshal.method(:dump))
+
+# but this is more concise
+objects.map(&Marshal.|.dump)
+```
+
+The **simplicity and elegance of Ruby** is one of the many reasons that people fall in love with the language!
+
+```ruby
+Ruby.is.so(:simple, &elegant).that(you can) do
+  pretty_much ANYTHING if it.compiles!
+end
+```
+
+This concept of **pipes could be a great fit** like it has been for many other languages:
+
+* [Caml composition operators](http://caml.inria.fr/pub/docs/manual-ocaml/libref/Pervasives.html#1_Compositionoperators)
+* [Closure threading macros](https://clojure.org/guides/threading_macros)
+* [Elixir pipe operator](https://elixirschool.com/en/lessons/basics/pipe-operator/)
+* [Elm operators](https://elm-lang.org/docs/syntax#operators)
+* [F# function composition and pipelining](https://docs.microsoft.com/en-us/dotnet/fsharp/language-reference/functions/index#function-composition-and-pipelining)
+* [Hack pipe operator](https://docs.hhvm.com/hack/operators/pipe-operator)
+* [Haskell pipes](http://hackage.haskell.org/package/pipes-4.3.9/docs/Pipes-Tutorial.html)
+* [JavaScript pipeline operator proposals](https://github.com/tc39/proposal-pipeline-operator/wiki)
+* [LiveScript piping](http://livescript.net/#piping)
+* [Unix pipelines](https://en.wikipedia.org/wiki/Pipeline_(Unix))
+
+## Usage
+
+**WARNING - EXPERIMENTAL PROOF OF CONCEPT**
+
+This has only been **tested in isolation with RSpec**!
+
+```ruby
+# First `gem install pipe_operator`
+require "pipe_operator"
+
+# Then use PipeOperator as a refinement
+using ::PipeOperator
+
+# Or include PipeOperator in classes/modules
+class AnyClass
+  include ::PipeOperator
+end
+
+# Or monkey patch PipeOperator into ALL objects
+require "pipe_operator/autoload"
+```
+
+## Implementation
+
+The [PipeOperator](https://github.com/lendinghome/pipe_operator/blob/master/lib/pipe_operator.rb) module has a method named `__pipe__` which is aliased as `pipe` for convenience and `|` for syntactic sugar:
+
+```ruby
+def __pipe__(*args, &block)
+  Pipe.new(self, *args, &block)
+end
+
+alias | __pipe__
+alias pipe __pipe__
+```
+
+When no arguments are passed to `__pipe__` then a [PipeOperator::Pipe](https://github.com/lendinghome/pipe_operator/blob/master/lib/pipe_operator/pipe.rb) object is returned:
+
+```ruby
+Math.| #=> #<PipeOperator::Pipe:Math>
+```
+
+Any methods invoked on this object returns a [PipeOperator::Closure](https://github.com/lendinghome/pipe_operator/blob/master/lib/pipe_operator/closure.rb) which **calls the method on the object later**:
+
+```ruby
+sqrt = Math.|.sqrt       #=> #<PipeOperator::Closure:0x00007fc1172ed558@pipe_operator/closure.rb:18>
+sqrt.call(16)            #=> 4.0
+
+missing = Math.|.missing #=> #<PipeOperator::Closure:0x00007fc11726f0e0@pipe_operator/closure.rb:18>
+missing.call             #=> NoMethodError: undefined method 'missing' for Math:Module
+
+Math.method(:missing)    #=> NameError: undefined method 'missing' for class '#<Class:Math>'
+```
+
+When `__pipe__` is called **with arguments but without a block** then it behaves similar to `__send__`:
+
+```ruby
+sqrt = Math | :sqrt #=> #<PipeOperator::Closure:0x00007fe52e0cdf80@pipe_operator/closure.rb:18>
+sqrt.call(16)       #=> 4.0
+
+sqrt = Math.pipe(:sqrt, 16) #=> #<PipeOperator::Closure:0x00007fe52fa18fd0@pipe_operator/closure.rb:18>
+sqrt.call                   #=> 4.0
+sqrt.call(16)               #=> ArgumentError: wrong number of arguments (given 2, expected 1)
+```
+
+These [PipeOperator::Closure](https://github.com/lendinghome/pipe_operator/blob/master/lib/pipe_operator/closure.rb) objects can be [bound as block arguments](https://github.com/lendinghome/pipe_operator/blob/master/lib/pipe_operator/proxy.rb#L10-L13) just like any other [Proc](https://ruby-doc.org/core-2.5.3/Proc.html):
+
+```ruby
+[16, 256].map(&Math.|.sqrt) #=> [4.0, 16.0]
+```
+
+Simple **closure composition is supported** via [method chaining](https://github.com/lendinghome/pipe_operator/blob/master/lib/pipe_operator/closure.rb#L56):
+
+```ruby
+[16, 256].map(&Math.|.sqrt.to_i.to_s) #=> ["4", "16"]
+```
+
+The **block** form of `__pipe__` behaves **similar to instance_exec** but can also [call methods on other objects](https://github.com/lendinghome/pipe_operator/blob/master/lib/pipe_operator/pipe.rb#L81):
+
+```ruby
+"abc".pipe { reverse }        #=> "cba"
+"abc".pipe { reverse.upcase } #=> "CBA"
+
+"abc".pipe { Marshal.dump }                   #=> "\x04\bI\"\babc\x06:\x06ET"
+"abc".pipe { Marshal.dump | Base64.encode64 } #=> "BAhJIghhYmMGOgZFVA==\n"
+```
+
+Outside the context of a `__pipe__` block things behave like normal:
+
+```ruby
+Math.sqrt     #=> ArgumentError: wrong number of arguments (given 0, expected 1)
+Math.sqrt(16) #=> 4.0
+```
+
+But within a `__pipe__` block the `Math.sqrt` expression returns a [PipeOperator::Closure](https://github.com/lendinghome/pipe_operator/blob/master/lib/pipe_operator/closure.rb) instead:
+
+```ruby
+16.pipe { Math.sqrt }     #=> 4.0
+16.pipe { Math.sqrt(16) } #=> ArgumentError: wrong number of arguments (given 2, expected 1)
+```
+
+The **piped object is passed as the first argument by default** but can be customized by specifying `self`:
+
+```ruby
+class String
+  def self.join(*args, with: "")
+    args.map(&:to_s).join(with)
+  end
+end
+
+"test".pipe { String.join("123", with: "-") }       #=> "test-123"
+
+"test".pipe { String.join("123", self, with: "-") } #=> "123-test"
+```
+
+Instance methods like `reverse` below [do not receive the piped object](https://github.com/lendinghome/pipe_operator/blob/master/lib/pipe_operator/pipe.rb#L79) as [an argument](https://github.com/lendinghome/pipe_operator/blob/master/lib/pipe_operator/closure.rb#L47) since it's available as `self`:
+
+```ruby
+Base64.encode64(Marshal.dump("abc").reverse)            #=> "VEUGOgZjYmEIIkkIBA==\n"
+
+"abc".pipe { Marshal.dump | reverse | Base64.encode64 } #=> "VEUGOgZjYmEIIkkIBA==\n"
+```
+
+Pipes also support **multi-line blocks for clarity**:
+
+```ruby
+"abc".pipe do
+  Marshal.dump
+  reverse
+  Base64.encode64
+end
+```
+
+Notice the pipe `|` operator wasn't used to **separate expressions** - it's actually always optional:
+
+```ruby
+# this example from above
+"abc".pipe { Marshal.dump | reverse | Base64.encode64 }
+
+# could also be written as
+"abc".pipe { Marshal.dump; reverse; Base64.encode64 }
+```
+
+The closures created by these **pipe expressions are evaluated via reduce**:
+
+```ruby
+pipeline = [
+  -> object { Marshal.dump(object) },
+  -> object { object.reverse },
+  -> object { Base64.encode64(object) },
+]
+
+pipeline.reduce("abc") do |object, pipe|
+  pipe.call(object)
+end
+```
+
+[Intercepting methods](https://github.com/lendinghome/pipe_operator/blob/master/lib/pipe_operator/proxy.rb#L19-L25) within pipes requires [prepending](https://github.com/lendinghome/pipe_operator/blob/master/lib/pipe_operator/pipe.rb#L38) a [PipeOperator::Proxy](https://github.com/lendinghome/pipe_operator/blob/master/lib/pipe_operator/proxy.rb) module infront of `::Object` and all [nested constants](https://github.com/lendinghome/pipe_operator/blob/master/lib/pipe_operator/proxy_resolver.rb#L46):
+
+```ruby
+define_method(method) do |*args, &block|
+  if Pipe.open
+    Pipe.new(self).__send__(method, *args, &block)
+  else
+    super(*args, &block)
+  end
+end
+```
+
+These proxy modules are prepended everywhere! It's certainly something that **could be way more efficient as a core part of Ruby**.
+
+## Bugs
+
+This test case doesn't work yet - seems like the [object is not proxied](https://github.com/lendinghome/pipe_operator/blob/master/lib/pipe_operator/pipe.rb#L39) for some reason:
+
+```ruby
+class Markdown
+  def format(string)
+    string.upcase
+  end
+end
+
+"test".pipe(Markdown.new, &:format) # expected "TEST"
+#=> ArgumentError: wrong number of arguments (given 0, expected 1)
+```
+
+## Caveats
+
+* `PIPE_OPERATOR_AUTOLOAD`
+    * Constants flagged for autoload are NOT proxied by default (for performance)
+    * Set `ENV["PIPE_OPERATOR_AUTOLOAD"] = 1` to enable this behavior
+* `PIPE_OPERATOR_FROZEN`
+    * Objects flagged as frozen are NOT proxied by default
+    * Set `ENV["PIPE_OPERATOR_FROZEN"] = 1` to enable this behavior (via [Fiddle](http://ruby-doc.org/stdlib-2.5.3/libdoc/fiddle/rdoc/Fiddle.html))
+* `PIPE_OPERATOR_REBIND`
+    * `Object` and its recursively nested `constants` are only proxied ONCE by default (for performance)
+    * Constants defined after `__pipe__` is called for the first time are NOT proxied
+    * Set `ENV["PIPE_OPERATOR_REBIND"] = 1` to enable this behavior
+* `PIPE_OPERATOR_RESERVED`
+    * The following methods are reserved on `PipeOperator::Closure` objects:
+        * `==`
+        * `[]`
+        * `__chain__`
+        * `__send__`
+        * `__shift__`
+        * `call`
+        * `class`
+        * `kind_of?`
+    * The following methods are reserved on `PipeOperator::Pipe` objects:
+        * `!`
+        * `!=`
+        * `==`
+        * `__call__`
+        * `__id__`
+        * `__pop__`
+        * `__push__`
+        * `__send__`
+        * `instance_exec`
+        * `method_missing`
+        * `|`
+    * These methods can be piped via `send` as a workaround:
+        * `9.pipe { Math.sqrt.to_s.send(:[], 0) }`
+        * `example.pipe { send(:__call__, 1, 2, 3) }`
+        * `example.pipe { send(:instance_exec) { } }`
+
+## Testing
+
+```bash
+bundle exec rspec
+```
+
+## Inspiration
+
+* https://github.com/hopsoft/pipe_envy
+* https://github.com/akitaonrails/chainable_methods
+* https://github.com/kek/pipelining
+* https://github.com/k-motoyan/shelike-pipe
+* https://github.com/nwtgck/ruby_pipe_chain
+* https://github.com/teamsnap/pipe-ruby
+* https://github.com/danielpclark/elixirize
+* https://github.com/tiagopog/piped_ruby
+* https://github.com/jicksta/methodphitamine
+* https://github.com/jicksta/superators
+
+## Contributing
+
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so we don't break it in a future version unintentionally.
+* Commit, do not mess with the version or history.
+* Open a pull request. Bonus points for topic branches.
+
+## Authors
+
+* [Sean Huber](https://github.com/shuber)
+
+## License
+
+[MIT](https://github.com/lendinghome/pipe_operator/blob/master/LICENSE) - Copyright © 2018 LendingHome