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.
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
In your Gemfile:
gem 'augmented'Or:
$ gem install augmented
Usage
You have 3 ways of loading the refinements. You can load all of them at once:
using AugmentedYou can load all refinements for just one type:
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.Or you can load just the methods you need:
using Augmented::Objects::Pickable
using Augmented::Procs::Chainable
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.
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. Last element wins.
using Augmented::Enumerators::Indexing
['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.
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.
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.
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
# }
# }Augmented::Hashes
Hash#map_values
Returns a new hash with the same keys but transformed values.
using Augmented::Hashes::Mappable
{ aa: 11, bb: 22 }.map_values{ |i| i * 3 }
# {:aa=>33, :bb=>66}Hash#map_keys
Returns a new hash with the same values but transformed keys.
using Augmented::Hashes::Mappable
{ aa: 11, bb: 22 }.map_keys{ |k| k.to_s[0] }
# {"a"=>11, "b"=>22}Hash#polymorph
Creates an object from a Hash.
using Augmented::Hashes::Polymorphable
class Sheep
def initialize attributes
@speak = attributes[:speak]
end
def speak
puts @speak
end
end
{ type: 'Sheep', speak: 'baaaah' }.polymorph.speak
# baaaah
Hash#transform, Hash#transform!
Recursively applies functions to a tree of hashes.
using Augmented::Hashes::Transformable
tree = { lorem: 'ipsum', dolor: [ { sit: 10}, { sit: 20 } ] }
triple = -> i { i * 3 }
tree.transform({ lorem: :upcase, dolor: { sit: triple } })
# {:lorem=>"IPSUM", :dolor=>[{:sit=>30}, {:sit=>60}]}Augmented::Modules
Module#refined
Makes it less verbose to create small refinements.
using Augmented::Modules::Refined
class TextPage
using refined String,
to_phrase: -> { self.strip.capitalize.gsub(/\.?\z/, '.') }
# ...
def text
@lines.map(&:to_phrase).join(' ')
end
endAugmented::Objects
Object#if, Object#unless, Object#else
Allows you to conditionally return an object, allowing you to be more concise in some situations.
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#in?
Tests if the object is included in a collection (collection must respond to included?).
using Augmented::Objects::In
2.in?([1, 2, 3])
# true
5.in?(0..2)
# false
'B'.in?('ABC')
# trueObject#pick
Calls a bunch of methods on an object and collects the results.
using Augmented::Objects::Pickable
class MyThing
def foo; 'lorem'; end
def bar; 'ipsum'; end
def baz; 'dolor'; end
end
MyThing.new.pick(:foo, :baz)
# {:foo=>"lorem", :baz=>"dolor"}Object#tack
Appends a bunch of singleton methods to an object.
using Augmented::Objects::Tackable
Object.new.tack(name: 'Alice', greet: -> { puts "hello I'm #{name}" }).greet
# hello I'm Alice
Object#tap_if, Object#tap_unless
Like tap but only executes the block according to the condition.
using Augmented::Objects::Tappable
toast.tap_if(toast.warm?){ |toast| toast.butter }.eat
toast.tap_if(:warm?.to_proc){ |toast| toast.butter }.eat
Object#thru, Object#thru_if, Object#thru_unless
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).
using Augmented::Objects::Thru
filter_words = -> s { s.gsub(/bad/, '').squeeze(' ').strip }
'BAD WORDS, BAD WORDS'.downcase.thru(&filter_words).capitalize
# "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.
using Augmented::Procs::Chainable
sub_two = -> i { i - 2 }
triple = -> i { i * 3 }
add_twenty = -> i { i + 20 }
(sub_two | triple | add_twenty)[5]
# 29Proc#rescues
Wraps a Proc to rescue it from certain exceptions while returning a given value.
using Augmented::Procs::Rescuable
integerify = proc{ |x| Integer(x) }.rescues(ArgumentError, 42)
['1', '2', 'oops!', '4'].map(&integerify)
# [1, 2, 42, 4]Augmented::Strings
String#blank?
Tests if a string is empty or made of whitespace.
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.
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.
using Augmented::Strings::Truncatable
'hello world'.truncate(5)
# "hello"
[(string = 'hello world'), string.truncate!(5)]
# ["hello", "hello"]Augmented::Symbols
Symbol#with
Like Symbol#to_proc but allows you to pass some arguments along.
using Augmented::Symbols::Arguable
class Eleven
def add_many *others
11 + others.reduce(0, :+)
end
end
:add_many.with(1, 2, 3).call(Eleven.new)
# 17
Symbol#eq, Symbol#neq, Symbol#lt, Symbol#lte, Symbol#gt, Symbol#gte
Creates functions that compare an object's attribute.
using Augmented::Symbols::Comparing
class User
def initialize name
@name = name
end
attr_reader :name
end
users = [ User.new('Marianne'), User.new('Jeremy') ]
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.