Xf - Short for Xform or Transform Functions meant to manipulate Enumerables, namely deep Hashes.
- Features
- Screencasts
- Requirements
- Setup
- Usage
- Tests
- Versioning
- Code of Conduct
- Contributions
- License
- History
- Credits
Compose and Pipe
# Read left to right
%w(1 2 3 4).map(&Xf.pipe(:to_i, :succ))
# Read right to left
%w(1 2 3 4).map(&Xf.compose(:succ, :to_i))If it looks like a Proc, or can be convinced to become one, it will work there.
Scopes
A Scope is a play on a concept from Haskell called a Lense.
The idea is to be able to define a path to a transformation and either get or set against it as a first class function. Well, easier shown than explained.
To start with we can do a few gets:
people = [{name: "Robert", age: 22}, {name: "Roberta", age: 22}, {name: "Foo", age: 42}, {name: "Bar", age: 18}]
people.map(&Xf.scope(:age).get)
# => [22, 22, 42, 18]
people.map(&Xf.scope(:age).get { |v| v > 20 })
# => [true, true, true, false]Let's try setting a value:
people = [{name: "Robert", age: 22}, {name: "Roberta", age: 22}, {name: "Foo", age: 42}, {name: "Bar", age: 18}]
age_scope = Xf.scope(:age)
older_people = people.map(&age_scope.set { |age| age + 1 })
# => [{:name=>"Robert", :age=>23}, {:name=>"Roberta", :age=>23}, {:name=>"Foo", :age=>43}, {:name=>"Bar", :age=>19}]
people
# => [{:name=>"Robert", :age=>22}, {:name=>"Roberta", :age=>22}, {:name=>"Foo", :age=>42}, {:name=>"Bar", :age=>18}]
# set! will mutate, for those tough ground in issues:
older_people = people.map(&age_scope.set! { |age| age + 1 })
# => [{:name=>"Robert", :age=>23}, {:name=>"Roberta", :age=>23}, {:name=>"Foo", :age=>43}, {:name=>"Bar", :age=>19}]
people
# => [{:name=>"Robert", :age=>23}, {:name=>"Roberta", :age=>23}, {:name=>"Foo", :age=>43}, {:name=>"Bar", :age=>19}]It works much the same as Hash#dig in that you can pass multiple comma-seperated values as a deeper path:
first_child_scope = Xf.scope(:children, 0, :name)
first_child_scope.get.call({name: 'Foo', children: [{name: 'Bar'}]})
# => "Bar"
first_child_scope.set('Baz').call({name: 'Foo', children: [{name: 'Bar'}]})
# => {:name=>"Foo", :children=>[{:name=>"Baz"}]}
That means array indexes work too, and on both get and set methods!
Traces
A Trace is a lot like a scope, except it'll keep digging until it finds a matching value. It takes a single path instead of a set like Scope. Currently there are three types:
Trace- Match on keyTraceValue- Match on valueTraceKeyValue- Match on both key and value
Tracers all implement === for matchers, which makes them more flexible but also
a good deal slower than Scopes. Keep that in mind.
Let's take a look at a few options real quick. We'll be sampling some data from
people.json, which is generated from JSON Generator.
require 'json'
people = JSON.parse(File.read('people.json'))
first_name_trace = Xf.trace('first')
# Remember it gets _all_ matching values, resulting in a nested array. Use
# `flat_map` if you want a straight list.
people.map(&first_name_trace.get)
# => [["Erickson"], ["Pugh"], ["Mullen"], ["Jacquelyn"], ["Miller"], ["Jolene"]]
# It can take a function too that gives back the parent hash and key as well.
#
# Why no shorthand? Arity of the function, and you can't have more than one `&`
# in the same code block. Ruby's no fan of it.
people.map(&first_name_trace.get { |h, k, v| v.downcase })
# => [["erickson"], ["pugh"], ["mullen"], ["jacquelyn"], ["miller"], ["jolene"]]
# You can even compose them if you want to. Just remember compose
people.flat_map(&Xf.compose(first_name_trace.set('Spartacus'), first_name_trace.get))
# => ["Spartacus", "Spartacus", "Spartacus", "Spartacus", "Spartacus", "Spartacus"]Depending on requests, I may make a NarrowScope that only returns the first match instead of digging the entire hash. At the moment most of my usecases involve data that's not so kind as to give me that option.
Note: For development you'll want to be using 2.5.0+ for various rake tasks and other niceties.
To install, run:
gem install xf
Add the following to your Gemfile:
gem "xf"
To test, run:
bundle exec rake
Read Semantic Versioning for details. Briefly, it means:
- Major (X.y.z) - Incremented for any backwards incompatible public API changes.
- Minor (x.Y.z) - Incremented for new, backwards compatible, public API enhancements/fixes.
- Patch (x.y.Z) - Incremented for small, backwards compatible, bug fixes.
Please note that this project is released with a CODE OF CONDUCT. By participating in this project you agree to abide by its terms.
Read CONTRIBUTING for details.
Copyright 2018 Brandon Weaver. Read LICENSE for details.
Read CHANGES for details. Built with Gemsmith.
Developed by Brandon Weaver