pied_piper 0.1.3 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 89ea6a51147ba81496b97d9693cfe8f8e241b367b82a02fbd263168804c1537c
-  data.tar.gz: 8f83601c922d1722fd13ba86174c9c84c99aded9b561c97f3652d5e4cfd2f46e
+  metadata.gz: d579aeffae1f032f9ee5e820ddbbaa907cdf9126aa053dbbd97d7d31e38cc24b
+  data.tar.gz: ca5279f4ddbf50304fa72029a5f3d871beb79f2e90b16f67da14d6bc19a723e4
 SHA512:
-  metadata.gz: 138e540a64d9660f99c9bdde4a411f9bfec58308f174eebf6f4a7be105e01265ae13c64f973ec9a9523f7f52fdee5800a39e14d9f5990f665e858631b4b918f4
-  data.tar.gz: cfad21cda12073d7aa3f69b8a8a937b7838e3e7e6a5eb447b1345d06f2cb6b188ebce313049ecad7783f98787e0eb89bf13ed9173c8fb7b58d9cca23854e2c8a
+  metadata.gz: 0c210a151538ab94ef386fd7fa463007545b4a2329b67e59c717c5b2055b9abb854ea661034b6190db1f5965b2d63d238bd783377ba7cc641425df704986de5b
+  data.tar.gz: 9a98bd3b029ff085f5d96cc7c1ffa1a915b3e64ec1a3b9d51069597d1c18dd2180a0e7f31049e2faa58129b6ca2602d9b8bb76d854d34ad925eccbf7f6c93f23

data/Gemfile.lock

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

data/README.md

@@ -6,13 +6,15 @@ The inspiration for this gem were `|>` pipes and functional programming in [Elix
 
 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.
+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), a guy who played pipe and hypnotized and lured all children out of town with his music and they were never be seen again.
+
+Another thing worth seeing, regarding "Pied Piper" and coding, is [Silicon Valley - Company Name](https://www.youtube.com/watch?v=QJ70b-WRHlU). It's hilarious :-D ( Thanks, Michael! )
 
 Despite the word "pipe" there's also another common thing between the fairy tale and pipes in this gem:
 
 There's a "piper" object who lures "children" (other objects) away ( through pipes ) until they never be seen again ( are transformed into other objects ).  :-)
 
-If you never worked with pipes, this little analogy may help to understand what's happening.
+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... :-)
 
@@ -58,7 +60,7 @@ Our initial object (e.g: `"rats and kids"`), is passed around through each pipe
 
 ### Symbol/String Pipes
 
-1. A Symbol or String, this calls a method on the piped object with the same name:
+The easiest way to create a pipe is using symbols or strings.  This will call the method with the same name as the Symbol/String on the wrapped object:
 
 ```ruby
 p = piper("rats and kids")
@@ -67,7 +69,11 @@ p | :upcase | p.end
 # => "RATS AND KIDS"
 ```
 
-Pipes can be chained:
+More about `p.end` below.
+
+### Chaining Pipes
+
+Pipes can be chained of course:
 
 ```ruby
 p = piper("rats and kids")
@@ -78,11 +84,13 @@ p | :upcase | :reverse | p.end
 
 ### Ending Pipes
 
-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.
+Note: Since "piping" is not a native Ruby syntax feature, rather than a method call in disguise (e.g: `"foo".|(: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"`).
+Everytime you transformed an object through a pipe 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`.
+This way, we can build pipe-chains of arbitrary length, but at the end of each pipe-chain, the piped object has to be "unwrapped" again by some kind of "terminator" object.
+
+This happens by "terminating" the pipe-chain with the `.end` method, which is defined on every piped object, or by just writing `PiedPiper::EndOfPipe` or if you have required `pied_piper/kernel` you can just write `p_end`.
 
 ```ruby
 p = piper("rats and kids")
@@ -99,13 +107,46 @@ p | :upcase | p_end # when PiedPiper::Kernel was required
 
 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.
+I decided against that, since I only wanted to add pipe functionality and not alter existing Ruby 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".
+### Ruby and its Kernel module
+
+If you want to add pipe functionality everywhere, we already talked about how to implement it above by requiring `pied_piper/kernel".
+
+This will provide pipe functionality on every object which has `Object` in one of its superclasses ( thus practically every object in Ruby besides `BasicObject` ) with the least amount of monkey-patching/side-effects, since we only add one Kernel method named `piper` and don't alter existing behaviour.
+
+In case you didn't know:
+
+`Object` includes `Kernel` as a module.
+
+Methods who are intended to be globally available, like `puts` and `gets`, and who aren't intended to be available with an explicit receiver like `"foo".puts` are defined as private instance methods on `Kernel`.
+
+Private instance methods can only be called with an implicit receiver (implicit self) in Ruby.
+
+That's why things like this work, because were always "inside" an object:
+
+```ruby
+puts self
+# main
+# nil
+
+# implicit receiver for puts
+puts "foo"
+```
+
+but this doesn't:
+
+```ruby
+# explicit receiver for puts
+self.puts "foo"
+# => NoMethodError: private method `puts' called for main:Object
+```
+
+So if you want to provide functionality that's available everywhere like `puts` the usual approach is to define a private instance method on Kernel.
 
-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.
+That's what has been done with the `piper` and `p_end` method :-)
 
 ### Array Pipes
 

data/lib/pied_piper/kernel.rb

@@ -2,6 +2,8 @@ require 'pied_piper'
 
 module PiedPiper::Kernel
   ::Kernel.class_eval do
+    private
+
     def piper(obj)
       PiedPiper.new(obj)
     end

data/lib/pied_piper/version.rb

@@ -1,3 +1,3 @@
 class PiedPiper
-  VERSION = '0.1.3'.freeze
+  VERSION = '0.1.4'.freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pied_piper
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.4
 platform: ruby
 authors:
 - Christoph Weegen