pied_piper 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 87334c647e9be342839edbef72429d045ed689e4d4279493829e157de81df18a
-  data.tar.gz: 39a736f7f6c659f22ee63e5742e6109ddbec69d4c1550ea7a862e52fac9cb646
+  metadata.gz: c1caeb762311438ceb233ae23503f78187a8c832d334f3d82ce9937401c9e476
+  data.tar.gz: 4b59343cd11ed7aa09799fb7b60064a6a4ee017f4d604d647fcde098e73bbec1
 SHA512:
-  metadata.gz: 86ae9191ce94fe5ca8699a43818b6ad640fd5e164208242d51b527e5449247b5b91cc2401530d85d444ed34323ef9203ae6146c596c36bc9b56c77de6d50b3d4
-  data.tar.gz: 5721440aa08e28016e20985f009135f3388cc6d944aab30cba66bd44ebc0c7c66f3c749f64cec0692ade4d5c3712009fe162b01b291753ba62763d23035c9caa
+  metadata.gz: fd9a93c163394ff8843b3026772c597db9a8f088806e38d7d9f550126cfcf648ec3ece2fd4d4cb30705155b9004f3be667c6244ee448b8a8567c128ea511ce72
+  data.tar.gz: ffa15ea30fc2fbb48c36e5921c4217fd4978a58848cf963ce6ab46d5ae9716b27cc4b477ae0996c12178fda757c418dbc1c238ad300d817f378ca1599e82f4bf

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    pied_piper (0.1.1)
+    pied_piper (0.1.2)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -1,10 +1,12 @@
-# PiedPiper - Don't let him lure you away...
+# PiedPiper
 
 This gem provides "Unix-like" pipe functionality in Ruby.
 
-Another inspiration for this gem were `|>` pipes and functional programming in [Elixir](https://elixir-lang.org).
+The inspiration for this gem were `|>` pipes and functional programming in [Elixir](https://elixir-lang.org).
 
-If you want to read about the inspiration for the name `PiedPiper`, it's an old german [fairy tale](https://en.wikipedia.org/wiki/Pied_Piper_of_Hamelin), of a guy who played pipe and hypnotized and lured all children out of town with his music and they were never be seen again.
+After trying to introduce the same `|>` pipe operator in Ruby, which I found out isn't possible due to syntactic reasons ( without hacking the underlying C code ), I settled for another well-known pipe operator, the `|` Unix pipe operator.
+
+If you want to read about the inspiration for the name `PiedPiper`, it's an old german fairy tale, the [Pied Piper of Hamelin](https://en.wikipedia.org/wiki/Pied_Piper_of_Hamelin), of a guy who played pipe and hypnotized and lured all children out of town with his music and they were never be seen again.
 
 Despite the word "pipe" there's also another common thing between the fairy tale and pipes in this gem:
 
@@ -12,7 +14,7 @@ There's a "piper" object who lures "children" (other objects) away ( through pip
 
 If you never worked with pipes, this little analogy may help to understand what's happening.
 
-Have fun with PiedPiper and don't let him lure you away :-)
+Have fun with PiedPiper and don't let him lure you away... :-)
 
 ## Installation
 
@@ -37,56 +39,80 @@ First you have to initialize a piper object with another object of your choice:
 ```ruby
 require "pied_piper"
 
-piper = PiedPiper.new("rats and children")
+p = PiedPiper.new("rats and kids")
 ```
 
 A shortcut to get a piper object anywhere you want, is shown in the following example. Only use this if your name is "Chuck Norris of Hamelin", since it "roundhouse pipes" (monkey-patches) Ruby's `Kernel` module :-D
 
+Note: It only adds the `piper` method to `Kernel` which isn't defined anywhere else and doesn't change existing Ruby behaviour, so using it doesn't actually make you this badass ;-)
+
 ```ruby
 require 'pied_piper/kernel'
 
-piper = pipe("rats and children")
+p = piper("rats and kids")
 ```
 
 Once you have a piper object you can pipe it "Unix-style".
 
-Our initial object (e.g: `"rats and children"`), is passed around through each pipe from left to right and transformed by one of the following objects:
+Our initial object (e.g: `"rats and kids"`), is passed around through each pipe from left to right and transformed by one of the following objects:
 
 ### Symbol/String Pipes
 
 1. A Symbol or String, this calls a method on the piped object with the same name:
 
 ```ruby
-p = pipe("rats and children")
+p = piper("rats and kids")
+
 p | :upcase | p.end
-# => "RATS AND CHILDREN"
+# => "RATS AND KIDS"
 ```
 
-Note: Since "piping" is not a native Ruby syntax feature, rather than a method call in disguise (e.g: `p.|(:upcase)`), the underlying `PiedPiper` class, which wraps the initial object (e.g: `"foo"`) and on which the pipe method is called, is just a wrapper for the initial object which handles piping logic.
+Pipes can be chained:
+
+```ruby
+p = piper("rats and kids")
+
+p | :upcase | :reverse | p.end
+# => "SDIK DNA STAR"
+```
 
-Everytime you "pipe" you create a new object of class `PiedPiper`, which wraps the mutated inital object again (e.g: from `"foo"` to `"FOO"`).
+### Ending Pipes
 
-At the end of each pipe-chain, the piped object has to be "unwrapped" again by ending the pipe-chain with the `.end` method on the pipe object or by just writing `PiedPiper::EndOfPipe` or if you have required `pied_piper/kernel` you can just write `pipe_end`.
+Note: Since "piping" is not a native Ruby syntax feature, rather than a method call in disguise (e.g: `p.|(:upcase)`), the underlying `PiedPiper` class, which wraps the initial object (e.g: `"foo"`) and on which the pipe functionality is called, is just a wrapper for the initial object which handles piping logic.
+
+Everytime you finished a pipe transformation you create a new object of class `PiedPiper`, which wraps the mutated inital object again (e.g: from `"foo"` to `"FOO"`).
+
+We can build pipe-chains this way, but at the end of each pipe-chain, the piped object has to be "unwrapped" again by ending the pipe-chain with the `.end` method on the pipe object or by just writing `PiedPiper::EndOfPipe` or if you have required `pied_piper/kernel` you can just write `p_end`.
 
 ```ruby
-p = pipe("rats and children")
+p = piper("rats and kids")
 
 p | :upcase | p.end
-# => "RATS AND CHILDREN"
+# => "RATS AND KIDS"
 
 p | :upcase | PiedPiper::EndOfPipe
-# => "RATS AND CHILDREN"
+# => "RATS AND KIDS"
 
-p | :upcase | pipe_end # when PiedPiper::Kernel was required
-# => "RATS AND CHILDREN"
+p | :upcase | p_end # when PiedPiper::Kernel was required
+# => "RATS AND KIDS"
 ```
 
+It would be possible to avoid writing `p.end` at the end of the chain, by implementing the gem in another way, but that would have included to monkey-patch existing Ruby classes, since the `|` method is already implemented by some of them.
+
+I decided against that, since I only wanted to add pipe functionality and not alter existing behaviour in any way.
+
+Thus the `PiedPiper` class was born.
+
+If you want to add pipe functionality everywhere, we already talked about how to implement it above under "Usage".
+
+This will make you use pipe functionality everywhere with the least amount of side-effects, since it only adds and doesn't alter existing behaviour.
+
 ### Array Pipes
 
 An Array, whose first element (Symbol/String) again acts as a method call on the piped object and additonal elements which act as parameters to the method call.
 
 ```ruby
-p = pipe("Pied Piper")
+p = piper("Pied Piper")
 
 concat = [:concat, " of", " Hamelin"]
 
@@ -97,39 +123,39 @@ p | concat  | p.end
 ### Proc Object Pipes
 
 An Object of `Proc` class which takes exactly one parameter:
-- `Proc.new { |child| ... }`
-- `proc { |child| ... }`
-- `lambda { |child| ... }`
-- `->(child) { ... }`
+- `Proc.new { |kid| ... }`
+- `proc { |kid| ... }`
+- `lambda { |kid| ... }`
+- `->(kid) { ... }`
 
 ```ruby
-p = pipe("Hypnotized child")
+p = piper("Hypnotized kid")
 
-no_happy_end = ->(child) { child + " was never seen again" }
+no_happy_end = ->(kid) { kid + " was never seen again..." }
 
 p | no_happy_end | p.end
-# => "Hypnotized child was never seen again"
+# => "Hypnotized kid was never seen again..."
 ```
 
-### Method Object Pipe
+### Method Object Pipes
 
 An object of the `Method` class, where the piped object will be used as the first parameter. You can pass an Array if you need additional parameters:
 
 ```ruby
 class PiedPiperOfHamelin
-  def self.plays_song_on_pipe(audience = "Children", effect = "slightly")
-    puts "#{audience} feel already #{effect + " "}hypnotized!"
+  def self.plays_song_on_pipe(audience = "Kids", effect = "slightly")
+    puts "#{audience} already feel #{effect + " "}hypnotized!"
   end
 end
 
-p = pipe("You")
+p = piper("You")
 hypnotize = PiedPiperOfHamelin.method(:plays_song_on_pipe)
 
 p | hypnotize | p.end
-# => "You feel already slightly hypnotized!"
+# => "You already feel slightly hypnotized!"
 
 p | [hypnotize, "VERY"] | p.end
-# => "You feel already VERY hypnotized!"
+# => "You already feel VERY hypnotized!"
 ```
 
 ### Combining Pipes
@@ -137,26 +163,48 @@ p | [hypnotize, "VERY"] | p.end
 Once you know the basic building blocks, you can combine them and build your own pipes of arbitrary length:
 
 ```ruby
-piper = pipe('You')
+p = piper('You')
 lures = [:+, " feel"]
 you = ->(str) { str + " hypnotized!" }
 away = :upcase
 
-piper | lures | you | away | h.end
+p | lures | you | away | piper.end
 # => "YOU FEEL HYPNOTIZED!"
 ```
 
 ### Multiline Pipes
 
-Sadly Ruby's syntax doesn't allow for totally nice multiline pipes ( at least not in a way I already found out ). Thus multiline pipes have to be written like this ( since they're actually just inline syntactic sugar for methods like `obj.|(arg)` under the hood:
+Sadly Ruby's syntax doesn't allow for totally nice multiline pipes ( at least not in a way I already found out ). Thus multiline pipes have to be written with a twist ( since they're actually just inline syntactic sugar for methods like `obj.|(arg)` under the hood:
+
+#### With Backslashes:
+
+In order to tell Ruby that our (inline) expression hasn't ended yet, when writing it over multiple lines, we can put a backslash at the end of a line to avoid syntax errors:
+
+```ruby
+p = piper('You')
+lures = [:+, " feel"]
+you = ->(str) { str + " hypnotized!" }
+away = :upcase
+
+p \
+  | lures \
+  | you \
+  | away \
+  | h.end
+# => "YOU FEEL HYPNOTIZED!"
+```
+
+#### As explicit method calls:
+
+As we already noticed that pipes `|` are simply method calls in disguise, we can explicitly call them on subsequent lines, which is valid Ruby syntax:
 
 ```ruby
-piper = pipe('You')
+p = piper('You')
 lures = [:+, " feel"]
 you = ->(str) { str + " hypnotized!" }
 away = :upcase
 
-piper
+p
   .|(lures)
   .|(you)
   .|(away).
@@ -164,6 +212,60 @@ piper
 # => "YOU FEEL HYPNOTIZED!"
 ```
 
+### What kind of advantages can pipes offer?
+
+Actually we can do nothing else with pipes then we can also do with regular Ruby syntax ( since it only builds on already existing Ruby functionality and is not a totally new language feature ).
+
+But piping objects can make some operations more clear/readable because we go from left to right in a linear fashion, instead from inside to outside like in regular function calls.
+
+This offers advantages when for example working in "functional style" instead of using methods:
+
+```ruby
+class Foo
+  def self.one
+    -> {|x| ... }
+  end
+end
+
+class Bar
+  def self.two
+    -> {|x| ... }
+  end
+end
+
+class Baz
+  def self.three
+    -> {|x| ... }
+  end
+end
+
+# This
+
+Baz.three.call(Bar.two.call(Foo.one.call(x)))
+
+# becomes this
+
+piper(x) | Foo.one | Bar.two | Baz.three | p_end
+
+# or
+
+piper(x) \
+  | Foo.one \
+  | Bar.two \
+  | Baz.three \
+  | p_end
+```
+
+I guess you won't use these kind of functional programming in Ruby too often, since Ruby follows another philosophy.
+
+PiedPiper is more a kind of experiment how Ruby can be modified to resemble concepts used in other programming languages like for example [Elixir](https://elixir-lang.org).
+
+As far as I can judge Ruby does quite a good job, the flexible language constructs that Ruby has to offer, makes it one of the nicest programming languages to work with. :-)
+
+What other kind of good use cases for pipes can you come up with?
+
+If you know some ( or missing features ), feel free to open up a pull request, so we can augment code/documentation :-)
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/lib/pied_piper/kernel.rb

@@ -1,10 +1,10 @@
 module PiedPiper::Kernel
   ::Kernel.class_eval do
-    def pipe(obj = nil)
+    def piper(obj)
       PiedPiper.new(obj)
     end
 
-    def pipe_end
+    def p_end
       PiedPiper::EndOfPipe
     end
   end

data/lib/pied_piper/version.rb

@@ -1,3 +1,3 @@
 class PiedPiper
-  VERSION = '0.1.1'.freeze
+  VERSION = '0.1.2'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pied_piper
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Christoph Weegen
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-04-10 00:00:00.000000000 Z
+date: 2019-04-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler