augmented 0.2.2 → 0.2.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d8cd8a8566eb16186e26909a2c32597cb2cf8d0e12e2f6785a55fa2cc43992ab
-  data.tar.gz: b19a9fd510664c6dc52e99b98ebf0faa5bc70c8c061143b7c4e57addb84f261f
+  metadata.gz: 6d65d68527ff708f00861bd8c107acfde5f7ce813ab5a3f6b88a8d9c12a331ad
+  data.tar.gz: 2d1c9fe2af451feb5c9eda30aee3514304e4ba62e0baf0d38475a3093389a4d4
 SHA512:
-  metadata.gz: de5a4fde6a7325acd6d90008bd4f7895da85a87b71691d4c7cc5cbb81b798576f46b34621cbd9f0857c6ae087ab7e684855d839b97885ad7f127118a00e92f88
-  data.tar.gz: f6185c773e2af7676f35e07d0732305bfc7c5882109a0248db835c77ebd41c361ee8946cc66dcdced3b3087fcfc14b8c6953299eea677e8b08019f70983323cd
+  metadata.gz: 907238de8dda6ab6a1403a43ea31bdc3c7a7315d3c951a62434da1bc91ff932df1111e141ffdef65fd12d7d447c67151d3745e823ba2bbdceeff246f0bea57cf
+  data.tar.gz: 8ab148a0c46b387f722041efd2a73aeff7c02e3e939ff1e1edf92c013ab935a08b5c8928bc4becf238f56307e0e7b6099d04b9be64408ba18ed25297577ed21c

data/CHANGELOG.md

@@ -0,0 +1,20 @@
+## [Unreleased]
+
+## [0.2.7] - 2021-06-26
+
+- Added `String#squish` and `String#squish!`.
+- Added `Object#in?`.
+
+## [0.2.6] - 2021-06-23
+
+- Fixed `String#blank?` not working on Ruby 2.3.
+
+## [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

@@ -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,26 @@ 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#in?`
+
+Tests if the object is included in a collection (collection must respond to `included?`).
+
+```ruby
+using Augmented::Objects::In
+
+2.in?([1, 2, 3])
+# true
+5.in?(0..2)
+# false
+'B'.in?('ABC')
+# true
 ```
 
 ##### `Object#pick`
@@ -193,13 +280,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 +296,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 +356,60 @@ 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#squish`, `String#squish!`
+
+Replaces runs of whitespace with a single space except at the edges of the string. Can be given a custom pattern and replacement.
+
+```ruby
+using Augmented::Strings::Squish
+
+' hello   world '.squish!
+# "hello world"
+
+'---what-a-nice--kebab-'.squish(/\W+/, '_')
+# "what_a_nice_kebab"
+```
+
+
+##### `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 +445,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", "~> 2.1"
-  spec.add_development_dependency "rake", ">= 12.3.3"
+  # 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/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