augmented 0.2.0 → 0.2.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: e809f083463caa0de7cb0c619078a075a058aaa7
-  data.tar.gz: e61a37488b312e6c24187a476e14d8d2bb142718
+SHA256:
+  metadata.gz: 02a3d4fd8fbc13022569168b89c6fb60b575dea7030a6c36b1457a049c468b62
+  data.tar.gz: bb89fe218a192cb1eb72f9456988a65c08eec651fc6e3f89e62941e9632dac9a
 SHA512:
-  metadata.gz: d3398225a2262317005c77498a625b769fceda255c1565a47e0b8b0d82d3f3023393dfa3d1f07401a40620d45dbee3b2fddc82d3956999d83998a006e1ae3683
-  data.tar.gz: e7552233cc563a5eb1275b69a3a1836aa000e86af58d62a3e717aa28bd670cb357fc22a8d0cc1cdee9d38f8326cdc055b2769b39e9b04c1341f4ada380932b92
+  metadata.gz: c4f04bc92e1bdfbff68e62283bfb16b7f8499297916c208ae62156e84d1358efdf4a94f56cb5d0d0123ea985a7f315126026147b82e338e6fea7d4ddcbff489f
+  data.tar.gz: 99d873ac314d8ff5a8cc7bf6f6fc5a47cfb27080dbf69167c2a6f6f0509175e6f7cd4c6ab23c2a41a7f73cbd8a5b39cda20c473d1448228dd0316013b7659ae9

data/CHANGELOG.md

@@ -0,0 +1,11 @@
+## [Unreleased]
+
+## [0.2.5] - 2021-05-30
+
+- Added `Exception#details`, `Exception#details=`, `Exception#detailed`
+- Added `Exception#chain`
+- Added `Exception#to_h`
+
+## [0.2.3] - 2021-05-29
+
+- Added `String#truncate`, `String#truncate!` and `String#blank?`

data/README.md

@@ -2,7 +2,7 @@
 
 `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/).
+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.
 
 
 ## Installation
@@ -31,10 +31,12 @@ You can load all refinements for just one type:
 ```ruby
 using Augmented::Arrays
 using Augmented::Enumerators
+using Augmented::Exceptions
 using Augmented::Hashes
 using Augmented::Modules
 using Augmented::Objects
 using Augmented::Procs
+using Augmented::Strings
 using Augmented::Symbols
 # etc.
 ```
@@ -60,7 +62,7 @@ Weaves an object between the elements of an array. Like `join` but without flatt
 ```ruby
 using Augmented::Arrays::Tieable
 
-[1, 2, 3].tie :hello
+[1, 2, 3].tie(:hello)
 # [1, :hello, 2, :hello, 3]
 
 [1, 5, 12].tie{ |a, b| a + b }
@@ -72,13 +74,88 @@ using Augmented::Arrays::Tieable
 
 ##### `Enumerator#index_by`
 
-Builds an index of all elements of an enumerator according to the given criterion.
+Builds an index of all elements of an enumerator according to the given criterion. Last element wins.
 
 ```ruby
 using Augmented::Enumerators::Indexing
 
-['a', 'bb', 'ccccc'].to_enum.index_by(&:length)
-# {1=>"a", 2=>"bb", 5=>"ccccc"}
+['a', 'bb', 'c', 'ddddd'].to_enum.index_by(&:length)
+# {1=>"c", 2=>"bb", 5=>"ddddd"}
+```
+
+
+#### `Augmented::Exceptions`
+
+##### `Exception#chain`
+
+Returns an enumerator over the exception's causal chain, starting with the exception itself.
+
+```ruby
+using Augmented::Exceptions::Chain
+
+begin
+  begin
+    begin
+      raise 'first'
+    rescue
+      raise 'second'
+    end
+  rescue
+    raise 'third'
+  end
+rescue => error
+  error.chain.map(&:message)
+end
+# ["third", "second", "first"]
+```
+
+
+##### `Exception#details`, `Exception#details=`, `Exception#detailed`
+
+Attach a hash of details to any exception.
+
+```ruby
+using Augmented::Exceptions::Detailed
+
+exception = RuntimeError.new('oops!').detailed(foo: 10, bar: { baz: 30 })
+exception.details
+# {:foo=>10, :bar=>{:baz=>30}}
+exception.details = { bam: 40 }
+exception.details
+# {:bam=>40}
+```
+
+
+##### `Exception#to_h`
+
+Serializes an exception into a Hash including its backtrace, details and causal chain.
+
+```ruby
+using Augmented::Exceptions::Serializable
+using Augmented::Exceptions::Detailed
+
+begin
+  begin
+    raise RuntimeError.new('first').detailed(foo: 10)
+  rescue
+    raise RuntimeError.new('second').detailed(bar: 20)
+  end
+rescue => error
+  error.to_h
+end
+# {
+#   :class => "RuntimeError",
+#   :message => "second",
+#   :details => { :bar => 20 },
+#   :backtrace => [ ... ],
+#   :cause => {
+#     :class => "RuntimeError",
+#     :message => "first",
+#     :details => { :foo => 10 },
+#     :backtrace => [ ... ],
+#     :cause => nil
+#   }
+# }
 ```
 
 
@@ -149,21 +226,16 @@ tree.transform({ lorem: :upcase, dolor: { sit: triple } })
 Makes it less verbose to create small refinements.
 
 ```ruby
-using Augmented::Hashes::Transformable
+using Augmented::Modules::Refined
 
 class TextPage
   using refined String,
-    as_phrase: -> { self.strip.capitalize.gsub /\.?\z/, '.' },
-    fill:      -> filler { (filler * self.length)[0..length] }
+    to_phrase: -> { self.strip.capitalize.gsub(/\.?\z/, '.') }
 
   # ...
 
   def text
-    @strings.map(&:as_phrase).join ' '
-  end
-
-  def obscured_text
-    text.fill '?'
+    @lines.map(&:to_phrase).join(' ')
   end
 end
 ```
@@ -178,11 +250,11 @@ Allows you to conditionally return an object, allowing you to be more concise in
 ```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.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)
+Person.new.eat(toast.unless(toast.soggy?).else(muffin))
+Person.new.eat(toast.unless(&:soggy?).else(muffin))
 ```
 
 ##### `Object#pick`
@@ -193,13 +265,13 @@ Calls a bunch of methods on an object and collects the results.
 using Augmented::Objects::Pickable
 
 class MyThing
-  def lorem; 'hello'; end
-  def ipsum; 'cruel'; end
-  def dolor; 'world'; end
+  def foo; 'lorem'; end
+  def bar; 'ipsum'; end
+  def baz; 'dolor'; end
 end
 
-MyThing.new.pick :lorem, :dolor
-# {:lorem=>"hello", :dolor=>"world"}
+MyThing.new.pick(:foo, :baz)
+# {:foo=>"lorem", :baz=>"dolor"}
 ```
 
 ##### `Object#tack`
@@ -209,8 +281,8 @@ Appends a bunch of singleton methods to an object.
 ```ruby
 using Augmented::Objects::Tackable
 
-Object.new.tack(id: 11, greet: -> { puts "hello I'm #{id}" }).greet
-# hello I'm 11
+Object.new.tack(name: 'Alice', greet: -> { puts "hello I'm #{name}" }).greet
+# hello I'm Alice
 ```
 
 ##### `Object#tap_if`, `Object#tap_unless`
@@ -269,13 +341,45 @@ Wraps a `Proc` to rescue it from certain exceptions while returning a given valu
 ```ruby
 using Augmented::Procs::Rescuable
 
-integerify = proc{ |x| Integer(x) }.rescues ArgumentError, 42
+integerify = proc{ |x| Integer(x) }.rescues(ArgumentError, 42)
 
-['1', '2', 'abc', '4'].map &integerify
+['1', '2', 'oops!', '4'].map(&integerify)
 # [1, 2, 42, 4]
 ```
 
 
+#### `Augmented::Strings`
+
+##### `String#blank?`
+
+Tests if a string is empty or made of whitespace.
+
+```ruby
+using Augmented::Strings::Blank
+
+''.blank?
+# true
+' '.blank?
+# true
+' hello '.blank?
+# false
+```
+
+
+##### `String#truncate`, `String#truncate!`
+
+Returns a prefix of a string up to a given number of characters.
+
+```ruby
+using Augmented::Strings::Truncatable
+
+'hello world'.truncate(5)
+# "hello"
+[(string = 'hello world'), string.truncate!(5)]
+# ["hello", "hello"]
+```
+
+
 #### `Augmented::Symbols`
 
 ##### `Symbol#with`
@@ -311,8 +415,8 @@ end
 
 users = [ User.new('Marianne'), User.new('Jeremy') ]
 
-users.find &(:name.eq 'Marianne')
-# <User:0x... name='Marianne'>
+users.find(&:name.eq('Marianne'))
+# <User:0x... @name='Marianne'>
 ```
 
 

data/augmented.gemspec

@@ -6,18 +6,24 @@ require 'augmented/version'
 Gem::Specification.new do |spec|
   spec.name          = "augmented"
   spec.version       = Augmented::VERSION
-  spec.authors       = ["bruno"]
-  spec.email         = ["bruno@brunze.com"]
+  spec.authors       = ["brunze"]
   spec.summary       = %q{Useful extra methods for some Ruby core types.}
   spec.description   = %q{Adds a few useful extra methods to some of Ruby's core types, available as refinements.}
   spec.homepage      = "https://github.com/brunze/augmented"
   spec.license       = "MIT"
 
-  spec.files         = `git ls-files -z`.split("\x0")
-  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
-  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
-  spec.require_paths = ["lib"]
+  spec.metadata['homepage_uri']    = spec.homepage
+  spec.metadata['source_code_uri'] = spec.homepage
+  spec.metadata['changelog_uri']   = spec.homepage + '/CHANGELOG.md'
 
-  spec.add_development_dependency "bundler", "~> 1.7"
-  spec.add_development_dependency "rake", "~> 10.0"
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features)/}) }
+  end
+  spec.bindir        = 'bin'
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency "bundler", "~> 2"
+  spec.add_development_dependency "rake", ">= 13.0.3"
 end

data/lib/augmented.rb

@@ -2,18 +2,22 @@ require 'augmented/version'
 
 require 'augmented/arrays'
 require 'augmented/enumerators'
+require 'augmented/exceptions'
 require 'augmented/hashes'
 require 'augmented/modules'
 require 'augmented/objects'
 require 'augmented/procs'
+require 'augmented/strings'
 require 'augmented/symbols'
 
 module Augmented
   include Arrays
   include Enumerators
+  include Exceptions
   include Hashes
   include Modules
   include Objects
   include Procs
+  include Strings
   include Symbols
 end

data/lib/augmented/arrays/tieable.rb

@@ -7,7 +7,7 @@ module Augmented
           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
+          ties = self.each_cons(2).map(&tie_function)
 
           self.zip(ties).flatten(1)[0...-1]
         end

data/lib/augmented/enumerators/indexing.rb

@@ -4,7 +4,9 @@ module Augmented
       refine Enumerator do
 
         def index_by &criterion
-          Hash[ self.map(&criterion).zip(self) ]
+          self.each_with_object({}) do |element, index|
+            index[criterion.(element)] = element
+          end
         end
 
       end

data/lib/augmented/exceptions.rb

@@ -0,0 +1,11 @@
+require 'augmented/exceptions/chain'
+require 'augmented/exceptions/detailed'
+require 'augmented/exceptions/serializable'
+
+module Augmented
+  module Exceptions
+    include Chain
+    include Detailed
+    include Serializable
+  end
+end

data/lib/augmented/exceptions/chain.rb

@@ -0,0 +1,16 @@
+module Augmented
+  module Exceptions
+    module Chain
+      refine Exception do
+
+        def chain
+          Enumerator.new do |yielder|
+            yielder << exception = self
+            yielder << exception while exception = exception.cause
+          end
+        end
+
+      end
+    end
+  end
+end

data/lib/augmented/exceptions/detailed.rb

@@ -0,0 +1,22 @@
+module Augmented
+  module Exceptions
+    module Detailed
+      refine Exception do
+
+        def details
+          @_details ||= {}
+        end
+
+        def details= **details
+          @_details = details
+        end
+
+        def detailed **details
+          self.details = details
+          self
+        end
+
+      end
+    end
+  end
+end

data/lib/augmented/exceptions/serializable.rb

@@ -0,0 +1,25 @@
+module Augmented
+  module Exceptions
+    module Serializable
+      refine Exception do
+        using Chain
+        using Detailed
+
+        def to_h
+          self.chain.map do |exception|
+            {
+              class: exception.class.name,
+              message: exception.message,
+              details: exception.details,
+              backtrace: exception.backtrace || [],
+              cause: nil,
+            }
+          end.reverse.reduce do |cause, exception|
+            exception.merge!(cause: cause)
+          end
+        end
+
+      end
+    end
+  end
+end

data/lib/augmented/objects/pickable.rb

@@ -7,14 +7,14 @@ module Augmented
           ensure_array = -> thing { thing.kind_of?(Array) ? thing : Array[thing] }
 
           if self.respond_to? :each
-            self.map{ |thing| thing.pick *picks }
+            self.map{ |thing| thing.pick(*picks) }
           else
             picks.each_with_object({}) do |pick, result|
 
               if pick.kind_of? Hash
 
                 pick.each do |attribute, nested_picks|
-                  result[attribute] = self.__send__(attribute.to_sym).pick *ensure_array[nested_picks]
+                  result[attribute] = self.__send__(attribute.to_sym).pick(*ensure_array[nested_picks])
                 end
 
               else