Xf

Xf - Short for Xform or Transform Functions meant to manipulate Enumerables, namely deep Hashes.

Articles

How it was made

• Xf Part One - Scopes
• Xf Part Two - Traces

Table of Contents

• Features
• Screencasts
• Requirements
• Setup
• Usage
• Tests
• Versioning
• Code of Conduct
• Contributions
• License
• History
• Credits

Features

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 key
• TraceValue - Match on value
• TraceKeyValue - 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.

Screencasts

Requirements

1. Ruby 2.3.x

Note: For development you'll want to be using 2.5.0+ for various rake tasks and other niceties.

Setup

To install, run:

gem install xf

Add the following to your Gemfile:

gem "xf"

Usage

Tests

To test, run:

bundle exec rake

Versioning

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.

Code of Conduct

Please note that this project is released with a CODE OF CONDUCT. By participating in this project you agree to abide by its terms.

Contributions

Read CONTRIBUTING for details.

License

Copyright 2018 Brandon Weaver. Read LICENSE for details.

History

Read CHANGES for details. Built with Gemsmith.

Credits

Developed by Brandon Weaver