augmented 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c45e4c37723b2e38793bb1476b7be8e8662b8c4a
-  data.tar.gz: c988abdf0493e83cb1b8406af472649fe6f10d00
+  metadata.gz: e809f083463caa0de7cb0c619078a075a058aaa7
+  data.tar.gz: e61a37488b312e6c24187a476e14d8d2bb142718
 SHA512:
-  metadata.gz: 9e87a5bf8e30edfc41f7364f6b5851bccbbe15cbe1d908d4ad7471793ea4129dfb254ae3963257fc0f61c378e6c96be43be480d8d735864e3923f9c28a43e155
-  data.tar.gz: 19b0e83ca99b904f0f69614966649e7e26c70210ca6da3862a21ded599e4e934d249b4d08c36e9c3ec71d3d785d6e3861abf5ca72b3ad5accb4368ca9eb3085c
+  metadata.gz: d3398225a2262317005c77498a625b769fceda255c1565a47e0b8b0d82d3f3023393dfa3d1f07401a40620d45dbee3b2fddc82d3956999d83998a006e1ae3683
+  data.tar.gz: e7552233cc563a5eb1275b69a3a1836aa000e86af58d62a3e717aa28bd670cb357fc22a8d0cc1cdee9d38f8326cdc055b2769b39e9b04c1341f4ada380932b92

data/README.md

@@ -1,9 +1,10 @@
 # Augmented
 
-`Augmented` is a library with some core-type utility methods that I frequently find myself copying across projects. It uses refinements instead of class modification for maximum control and an easy sleep at night. 
+`Augmented` is a library with some core-type utility methods that I frequently find myself copying across projects. It uses refinements instead of class modification for maximum control and an easy sleep at night.
 
 Many of the methods in `Augmented` facilitate a more functional style of programming and cover a few tiny gaps in Ruby's solid functional support. See more thoughts on this [blog post](http://blog.brunze.com/2015/using-ruby-refinements-fun-flow/).
 
+
 ## Installation
 
 In your Gemfile:
@@ -16,6 +17,7 @@ Or:
 
     $ gem install augmented
 
+
 ## Usage
 
 You have 3 ways of loading the refinements. You can load all of them at once:
@@ -27,11 +29,14 @@ using Augmented
 You can load all refinements for just one type:
 
 ```ruby
+using Augmented::Arrays
 using Augmented::Enumerators
 using Augmented::Hashes
+using Augmented::Modules
 using Augmented::Objects
 using Augmented::Procs
 using Augmented::Symbols
+# etc.
 ```
 
 Or you can load just the methods you need:
@@ -43,8 +48,28 @@ using Augmented::Symbols::Arguable
 # etc.
 ```
 
+
 ## Quick Examples
 
+#### `Augmented::Arrays`
+
+##### `Array#tie`
+
+Weaves an object between the elements of an array. Like `join` but without flattening the array into a string.
+
+```ruby
+using Augmented::Arrays::Tieable
+
+[1, 2, 3].tie :hello
+# [1, :hello, 2, :hello, 3]
+
+[1, 5, 12].tie{ |a, b| a + b }
+# [1, 6, 5, 17, 12]
+```
+
+
+#### `Augmented::Enumerators`
+
 ##### `Enumerator#index_by`
 
 Builds an index of all elements of an enumerator according to the given criterion.
@@ -56,6 +81,9 @@ using Augmented::Enumerators::Indexing
 # {1=>"a", 2=>"bb", 5=>"ccccc"}
 ```
 
+
+#### `Augmented::Hashes`
+
 ##### `Hash#map_values`
 
 Returns a new hash with the same keys but transformed values.
@@ -87,16 +115,16 @@ using Augmented::Hashes::Polymorphable
 
 class Sheep
   def initialize attributes
-    @sound = attributes[:sound]
+    @speak = attributes[:speak]
   end
 
   def speak
-    puts @sound
+    puts @speak
   end
 end
 
-{ type: 'Sheep', sound: 'meeehh' }.polymorph.speak
-# meeehh
+{ type: 'Sheep', speak: 'baaaah' }.polymorph.speak
+# baaaah
 ```
 
 ##### `Hash#transform`, `Hash#transform!`
@@ -113,15 +141,48 @@ tree.transform({ lorem: :upcase, dolor: { sit: triple } })
 # {:lorem=>"IPSUM", :dolor=>[{:sit=>30}, {:sit=>60}]}
 ```
 
-##### `Object#if`, `Object#else`
 
-Allows you to conditionally return an object, increasing readability in some situations.
+#### `Augmented::Modules`
+
+##### `Module#refined`
+
+Makes it less verbose to create small refinements.
+
+```ruby
+using Augmented::Hashes::Transformable
+
+class TextPage
+  using refined String,
+    as_phrase: -> { self.strip.capitalize.gsub /\.?\z/, '.' },
+    fill:      -> filler { (filler * self.length)[0..length] }
+
+  # ...
+
+  def text
+    @strings.map(&:as_phrase).join ' '
+  end
+
+  def obscured_text
+    text.fill '?'
+  end
+end
+```
+
+
+#### `Augmented::Objects`
+
+##### `Object#if`, `Object#unless`, `Object#else`
+
+Allows you to conditionally return an object, allowing you to be more concise in some situations.
 
 ```ruby
 using Augmented::Objects::Iffy
 
 Person.new.eat toast.if(toast.buttered?).else(muffin)
 Person.new.eat toast.if(&:buttered?).else(muffin)
+
+Person.new.eat toast.unless(toast.soggy?).else(muffin)
+Person.new.eat toast.unless(&:soggy?).else(muffin)
 ```
 
 ##### `Object#pick`
@@ -163,9 +224,9 @@ toast.tap_if(toast.warm?){ |toast| toast.butter }.eat
 toast.tap_if(:warm?.to_proc){ |toast| toast.butter }.eat
 ```
 
-##### `Object#thru`
+##### `Object#thru`, `Object#thru_if`, `Object#thru_unless`
 
-Applies a function to an object and returns the result.
+Applies a function to an object and returns the result. `Object#thru_if` and `Object#thru_unless` do so depending on the condition supplied (if the condition fails, the object is returned untouched).
 
 ```ruby
 using Augmented::Objects::Thru
@@ -173,9 +234,19 @@ using Augmented::Objects::Thru
 filter_words = -> s { s.gsub(/bad/, '').squeeze(' ').strip }
 
 'BAD WORDS, BAD WORDS'.downcase.thru(&filter_words).capitalize
-# Words, words
+# "Words, words"
+
+config.censor = true
+'BAD WORDS, BAD WORDS'.downcase.thru_if(config.censor?, &filter_words).capitalize
+# "Words, words"
+
+''.downcase.thru_unless(:empty?.to_proc, &filter_words).capitalize
+# ""
 ```
 
+
+#### `Augmented::Procs`
+
 ##### `Proc#|`
 
 Chains several procs together so they execute from left to right.
@@ -191,6 +262,22 @@ add_twenty = -> i { i + 20 }
 # 29
 ```
 
+##### `Proc#rescues`
+
+Wraps a `Proc` to rescue it from certain exceptions while returning a given value.
+
+```ruby
+using Augmented::Procs::Rescuable
+
+integerify = proc{ |x| Integer(x) }.rescues ArgumentError, 42
+
+['1', '2', 'abc', '4'].map &integerify
+# [1, 2, 42, 4]
+```
+
+
+#### `Augmented::Symbols`
+
 ##### `Symbol#with`
 
 Like [`Symbol#to_proc`](http://ruby-doc.org/core-2.3.0/Symbol.html#method-i-to_proc) but allows you to pass some arguments along.
@@ -228,6 +315,7 @@ users.find &(:name.eq 'Marianne')
 # <User:0x... name='Marianne'>
 ```
 
+
 ## Contributing
 
 Do you have a method you would like to see added to this library? Perhaps something you keep copying from project to project but always found too small to bother with a gem? Feel free to submit a ticket/pull request with your idea.

data/lib/augmented/arrays/tieable.rb

@@ -0,0 +1,18 @@
+module Augmented
+  module Arrays
+    module Tieable
+      refine Array do
+
+        def tie object = nil, &block
+          raise ArgumentError, 'you must provide a non-nil tie object or block' if object.nil? && !block_given?
+
+          tie_function = block_given? ? block : proc{ object }
+          ties = self.each_cons(2).map &tie_function
+
+          self.zip(ties).flatten(1)[0...-1]
+        end
+
+      end
+    end
+  end
+end

data/lib/augmented/arrays.rb

@@ -0,0 +1,7 @@
+require 'augmented/arrays/tieable'
+
+module Augmented
+  module Arrays
+    include Tieable
+  end
+end

data/lib/augmented/modules/refined.rb

@@ -0,0 +1,19 @@
+module Augmented
+  module Modules
+    module Refined
+      refine Module do
+
+        def refined klass, **hash_of_procs
+          Module.new do
+            refine klass do
+              hash_of_procs.each_pair do |name, proc|
+                define_method name, proc
+              end
+            end
+          end
+        end
+
+      end
+    end
+  end
+end

data/lib/augmented/modules.rb

@@ -0,0 +1,7 @@
+require 'augmented/modules/refined'
+
+module Augmented
+  module Modules
+    include Refined
+  end
+end

data/lib/augmented/objects/iffy.rb

@@ -7,6 +7,10 @@ module Augmented
           self if (block_given? ? yield(self) : condition)
         end
 
+        def unless condition = self
+          self unless (block_given? ? yield(self) : condition)
+        end
+
         def else *_
           self
         end

data/lib/augmented/objects/thru.rb

@@ -8,6 +8,16 @@ module Augmented
           (function || :itself.to_proc).call self
         end
 
+        def thru_if condition, &function
+          apply_function = condition.respond_to?(:call) ? condition.call(self) : condition
+          apply_function ? self.thru(&function) : self
+        end
+
+        def thru_unless condition, &function
+          skip_function = condition.respond_to?(:call) ? condition.call(self) : condition
+          skip_function ? self : self.thru(&function)
+        end
+
       end
     end
   end

data/lib/augmented/procs/rescuable.rb

@@ -0,0 +1,25 @@
+module Augmented
+  module Procs
+    module Rescuable
+      refine Proc do
+
+        NOT_PROVIDED = Object.new
+
+        def rescues exception_class, return_value = NOT_PROVIDED, &block
+          raise ArgumentError, 'must provide a return value or block' if return_value == NOT_PROVIDED && !block_given?
+
+          original = self
+
+          Proc.new do |*args|
+            begin
+              original.call *args
+            rescue exception_class => exception
+              block ? block.call(exception) : return_value
+            end
+          end
+        end
+
+      end
+    end
+  end
+end

data/lib/augmented/procs.rb

@@ -1,7 +1,9 @@
 require 'augmented/procs/chainable'
+require 'augmented/procs/rescuable'
 
 module Augmented
   module Procs
     include Chainable
+    include Recuable
   end
 end

data/lib/augmented/version.rb

@@ -1,3 +1,3 @@
 module Augmented
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/augmented.rb

@@ -1,14 +1,18 @@
 require 'augmented/version'
 
+require 'augmented/arrays'
 require 'augmented/enumerators'
 require 'augmented/hashes'
+require 'augmented/modules'
 require 'augmented/objects'
 require 'augmented/procs'
 require 'augmented/symbols'
 
 module Augmented
+  include Arrays
   include Enumerators
   include Hashes
+  include Modules
   include Objects
   include Procs
   include Symbols

data/test/augmented/arrays/tieable_test.rb

@@ -0,0 +1,66 @@
+require 'minitest/autorun'
+require 'augmented/arrays/tieable'
+
+describe Augmented::Arrays::Tieable do
+  using Augmented::Arrays::Tieable
+
+  describe '#tie' do
+
+    describe 'when supplied with an object' do
+
+      it 'returns an array interweaved with the specified object' do
+        object = Object.new
+        weaved = %w(a b c).tie object
+
+        weaved.must_equal ['a', object, 'b', object, 'c']
+      end
+
+      it 'returns an empty array if the original array is empty' do
+        [].tie(1).must_equal []
+      end
+
+      it 'returns the original array if it has only one element' do
+        [42].tie(1).must_equal [42]
+      end
+
+    end
+
+    describe 'when supplied with a block' do
+
+      it 'returns an array interweaved with the result of invoking the block' do
+        values = [10 ,20].each
+        weaved = %w(a b c).tie{ values.next }
+
+        weaved.must_equal ['a', 10, 'b', 20, 'c']
+      end
+
+      it 'passes both neighbour values as arguments to the supplied block' do
+        weaved = [1, 5, 12].tie{ |a, b| a + b }
+
+        weaved.must_equal [1, 6, 5, 17, 12]
+      end
+
+      it 'will weave nils if the block does not return anything else' do
+        weaved = [1, 2, 3].tie{}
+
+        weaved.must_equal [1, nil, 2, nil, 3]
+      end
+
+      it 'returns an empty array if the original arrays is empty' do
+        [].tie{ 1 }.must_equal []
+      end
+
+      it 'returns the original array if it has only one element' do
+        [42].tie{ 1 }.must_equal [42]
+      end
+
+    end
+
+    it 'raises an ArgumentError if not passed a non-nil object or block' do
+      proc{ [].tie }.must_raise ArgumentError
+      proc{ [].tie nil }.must_raise ArgumentError
+    end
+
+  end
+
+end

data/test/augmented/modules/refined_test.rb

@@ -0,0 +1,27 @@
+require 'minitest/autorun'
+require 'augmented/modules/refined'
+
+describe Augmented::Modules::Refined do
+  using Augmented::Modules::Refined
+
+  describe '#refined' do
+
+    before do
+      class TesterClass
+        using refined String,
+          as_phrase: -> { self.capitalize.gsub /\.?\z/, '.' },
+          fill:      -> filler { (filler * self.length)[0..length] }
+
+        def do_test
+          'hello world'.as_phrase.must_equal 'Hello world.'
+          'hello world'.fill('!').must_equal '!!!!!!!!!!!'
+        end
+      end
+    end
+
+    it 'creates a refinement module on the fly for the given class, with the procs supplied' do
+      TesterClass.new.do_test
+    end
+
+  end
+end

data/test/augmented/objects/iffy_test.rb

@@ -26,6 +26,28 @@ describe Augmented::Objects::Iffy do
 
   end
 
+  describe '#unless' do
+
+    it 'returns the object if the condition evaluates to falsy' do
+      subject = 'abc'
+      condition = -> subj { subj.length == 0 }
+
+      subject.unless(false).must_be_same_as subject
+      subject.unless(nil).must_be_same_as subject
+      subject.unless(&condition).must_be_same_as subject
+    end
+
+    it 'returns nil if the condition evaluates to truish' do
+      subject = 'abc'
+      condition = -> subj { subj.length == 3 }
+
+      subject.unless(true).must_be_same_as nil
+      subject.unless(Object.new).must_be_same_as nil
+      subject.unless(&condition).must_be_same_as nil
+    end
+
+  end
+
   describe '#else' do
 
     it 'returns the alternative if the object is falsy' do

data/test/augmented/objects/thru_test.rb

@@ -19,4 +19,80 @@ describe Augmented::Objects::Thru do
 
   end
 
+  describe '#thru_if' do
+
+    it 'applies the given function to the object if the condition is truish' do
+      plus_10 = -> i { i + 10 }
+
+      5.thru_if(true, &plus_10).must_equal 15
+      5.thru_if(Object.new, &plus_10).must_equal 15
+    end
+
+    it 'applies the given function to the object if the condition evaluates to truish' do
+      plus_10 = -> i { i + 10 }
+
+      condition_1 = -> i { i == 5 }
+      condition_2 = -> i { i.to_s }
+
+      5.thru_if(condition_1, &plus_10).must_equal 15
+      5.thru_if(condition_2, &plus_10).must_equal 15
+    end
+
+    it 'returns the object without applying the function if the condition is falsy' do
+      plus_10 = -> i { i + 10 }
+
+      5.thru_if(false, &plus_10).must_equal 5
+      5.thru_if(nil,   &plus_10).must_equal 5
+    end
+
+    it 'returns the object without applying the function if the condition evaluates to falsy' do
+      plus_10 = -> i { i + 10 }
+
+      condition_1 = -> i { i == 10 }
+      condition_2 = -> i { nil }
+
+      5.thru_if(condition_1, &plus_10).must_equal 5
+      5.thru_if(condition_2, &plus_10).must_equal 5
+    end
+
+  end
+
+  describe '#thru_unless' do
+
+    it 'applies the given function to the object if the condition is falsy' do
+      plus_10 = -> i { i + 10 }
+
+      5.thru_unless(false, &plus_10).must_equal 15
+      5.thru_unless(nil,   &plus_10).must_equal 15
+    end
+
+    it 'applies the given function to the object if the condition evaluates to falsy' do
+      plus_10 = -> i { i + 10 }
+
+      condition_1 = -> i { i == 10 }
+      condition_2 = -> i { nil }
+
+      5.thru_unless(condition_1, &plus_10).must_equal 15
+      5.thru_unless(condition_2, &plus_10).must_equal 15
+    end
+
+    it 'returns the object without applying the function if the condition is truish' do
+      plus_10 = -> i { i + 10 }
+
+      5.thru_unless(true, &plus_10).must_equal 5
+      5.thru_unless(Object.new, &plus_10).must_equal 5
+    end
+
+    it 'returns the object without applying the function if the condition evaluates to truish' do
+      plus_10 = -> i { i + 10 }
+
+      condition_1 = -> i { i == 5 }
+      condition_2 = -> i { i.to_s }
+
+      5.thru_unless(condition_1, &plus_10).must_equal 5
+      5.thru_unless(condition_2, &plus_10).must_equal 5
+    end
+
+  end
+
 end

data/test/augmented/procs/rescuable_test.rb

@@ -0,0 +1,38 @@
+require 'minitest/autorun'
+require 'augmented/procs/rescuable'
+
+describe Augmented::Procs::Rescuable do
+  using Augmented::Procs::Rescuable
+
+  describe '#rescues' do
+
+    it 'returns a proc which returns a provided value if the expected exception is raised' do
+      specific_exception_class = Class.new RuntimeError
+
+      unsafe_proc = -> { raise specific_exception_class }
+      rescued_proc = unsafe_proc.rescues specific_exception_class, 42
+
+      rescued_proc.call.must_equal 42
+    end
+
+    it 'returns a proc which returns the result of the provided block if the expected exception is raised' do
+      specific_exception_class = Class.new RuntimeError
+
+      unsafe_proc = -> { raise specific_exception_class }
+      rescued_proc = unsafe_proc.rescues(specific_exception_class){ |exception| exception }
+
+      rescued_proc.call.must_be_instance_of specific_exception_class
+    end
+
+    it 'returns a proc which lets exceptions other than the expected one to be raised' do
+      specific_exception_class = Class.new RuntimeError
+
+      unsafe_proc = -> { raise RuntimeError }
+      rescued_proc = unsafe_proc.rescues specific_exception_class, 42
+
+      rescued_proc.must_raise RuntimeError
+    end
+
+  end
+
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: augmented
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - bruno
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-03-05 00:00:00.000000000 Z
+date: 2016-11-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -53,12 +53,16 @@ files:
 - Rakefile
 - augmented.gemspec
 - lib/augmented.rb
+- lib/augmented/arrays.rb
+- lib/augmented/arrays/tieable.rb
 - lib/augmented/enumerators.rb
 - lib/augmented/enumerators/indexing.rb
 - lib/augmented/hashes.rb
 - lib/augmented/hashes/mappable.rb
 - lib/augmented/hashes/polymorphable.rb
 - lib/augmented/hashes/transformable.rb
+- lib/augmented/modules.rb
+- lib/augmented/modules/refined.rb
 - lib/augmented/objects.rb
 - lib/augmented/objects/iffy.rb
 - lib/augmented/objects/pickable.rb
@@ -67,20 +71,24 @@ files:
 - lib/augmented/objects/thru.rb
 - lib/augmented/procs.rb
 - lib/augmented/procs/chainable.rb
+- lib/augmented/procs/rescuable.rb
 - lib/augmented/symbols.rb
 - lib/augmented/symbols/arguable.rb
 - lib/augmented/symbols/comparing.rb
 - lib/augmented/version.rb
+- test/augmented/arrays/tieable_test.rb
 - test/augmented/enumerators/indexing_test.rb
 - test/augmented/hashes/mappable_test.rb
 - test/augmented/hashes/polymorphable_test.rb
 - test/augmented/hashes/transformable_test.rb
+- test/augmented/modules/refined_test.rb
 - test/augmented/objects/iffy_test.rb
 - test/augmented/objects/pickable_test.rb
 - test/augmented/objects/tackable_test.rb
 - test/augmented/objects/tappable_test.rb
 - test/augmented/objects/thru_test.rb
 - test/augmented/procs/chainable_test.rb
+- test/augmented/procs/rescuable_test.rb
 - test/augmented/symbols/arguable_test.rb
 - test/augmented/symbols/comparing_test.rb
 homepage: https://github.com/brunze/augmented
@@ -103,20 +111,23 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.5
+rubygems_version: 2.5.1
 signing_key: 
 specification_version: 4
 summary: Useful extra methods for some Ruby core types.
 test_files:
+- test/augmented/arrays/tieable_test.rb
 - test/augmented/enumerators/indexing_test.rb
 - test/augmented/hashes/mappable_test.rb
 - test/augmented/hashes/polymorphable_test.rb
 - test/augmented/hashes/transformable_test.rb
+- test/augmented/modules/refined_test.rb
 - test/augmented/objects/iffy_test.rb
 - test/augmented/objects/pickable_test.rb
 - test/augmented/objects/tackable_test.rb
 - test/augmented/objects/tappable_test.rb
 - test/augmented/objects/thru_test.rb
 - test/augmented/procs/chainable_test.rb
+- test/augmented/procs/rescuable_test.rb
 - test/augmented/symbols/arguable_test.rb
 - test/augmented/symbols/comparing_test.rb