xf 0.0.3 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ca75c5042852e2391ad547df17f005f23987bfd780512d5d4e3d3f9d963bf972
-  data.tar.gz: 28cf81f1673af0b96ba1d2e469a181c68539105a45cdaf99970716290c62f22d
+  metadata.gz: 62d3af5779614c09634b6f1e53a0507832f1cddc051693f8ccda36fd29cf1862
+  data.tar.gz: 357c3a4807a9e5edb5d82c02ed06be8acd25d7e8e5e3224caeb8d67c2a4ad27d
 SHA512:
-  metadata.gz: 851f5270c4cd9815bfdf96b0c56ef338b21f0e176990a8e67f3a63c1f50f63d71571c1bb2270bddb3c989a4f48985f968f102e80819b25a7de5d31844afc34ed
-  data.tar.gz: d00cab86f2bd53031e2d7e19cdb0b7eac9185519430a0e600abeb6e021b9a721cf7a777c868122716ebe6397caf2f8d374bb19c0770b593bd02f00f4cee57ebc
+  metadata.gz: c76a5dea28717e733bb1938000fe5efaff5ceb8178f6b46b66d86916bcc1217274cafc05cd6bca3cc0f1986b60f1f93524c18dee29748ad8deea1c74a22ebe35
+  data.tar.gz: 44657cd1c09fbd8e624ebcaf807dfc1c705b4434d8bc51084ff735a59b677eb7cc5785188fa7788b6d5d79f7673a3e3b75151b2334cabf765825c954dc89426c

data/README.md

@@ -2,8 +2,9 @@
 
 [![Gem Version](https://badge.fury.io/rb/xf.svg)](http://badge.fury.io/rb/xf)
 <!-- Replace <id> with Code Climate repository ID. Remove this comment afterwards. -->
-[![Code Climate Maintainability](https://api.codeclimate.com/v1/badges/<id>/maintainability)](https://codeclimate.com/github//xf/maintainability)
-[![Code Climate Test Coverage](https://api.codeclimate.com/v1/badges/<id>/test_coverage)](https://codeclimate.com/github//xf/test_coverage)
+[![Maintainability](https://api.codeclimate.com/v1/badges/905faea654f9e0a1f811/maintainability)](https://codeclimate.com/github/baweaver/xf/maintainability)
+[![Test Coverage](https://api.codeclimate.com/v1/badges/905faea654f9e0a1f811/test_coverage)](https://codeclimate.com/github/baweaver/xf/test_coverage)
+[![Build Status](https://travis-ci.org/baweaver/xf.svg?branch=master)](https://travis-ci.org/baweaver/xf)
 
 <!-- Tocer[start]: Auto-generated, don't remove. -->
 
@@ -26,10 +27,14 @@
 
 ## Features
 
-**Compose**
+**Compose and Pipe**
 
 ```ruby
-%w(1 2 3 4).map(&Xf.compose(:to_i, :succ))
+# 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.
@@ -55,9 +60,9 @@ Let's try setting a value:
 ```ruby
 people = [{name: "Robert", age: 22}, {name: "Roberta", age: 22}, {name: "Foo", age: 42}, {name: "Bar", age: 18}]
 
-older_people = people.map(&Xf.scope(:age) { |age| age + 1 })
+age_scope = Xf.scope(:age)
 
-older_people = people.map(&Xf.scope(:age).set { |age| age + 1 })
+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
@@ -65,7 +70,7 @@ people
 
 # set! will mutate, for those tough ground in issues:
 
-older_people = people.map(&Xf.scope(:age).set! { |age| age + 1 })
+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
@@ -75,20 +80,59 @@ people
 It works much the same as `Hash#dig` in that you can pass multiple comma-seperated values as a deeper path:
 
 ```
-Xf.scope(:children, 0, :name).get.call({name: 'Foo', children: [{name: 'Bar'}]})
+first_child_scope = Xf.scope(:children, 0, :name)
+first_child_scope.get.call({name: 'Foo', children: [{name: 'Bar'}]})
 # => "Bar"
 
-Xf.scope(:children, 0, :name).set('Baz').call({name: 'Foo', children: [{name: '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](https://next.json-generator.com/).
+
+```ruby
+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"]]
+
+# 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
 
-0. [Ruby 2.5.1](https://www.ruby-lang.org)
+0. [Ruby 2.3.x](https://www.ruby-lang.org)
+
+> **Note**: For development you'll want to be using 2.5.0+ for various rake tasks and other niceties.
 
 ## Setup
 

data/lib/xf/identity.rb

@@ -12,7 +12,7 @@ module Xf
     end
 
     def self.version
-      "0.0.3"
+      "0.1.0"
     end
 
     def self.version_label

data/lib/xf/public_api.rb

@@ -1,25 +1,44 @@
 # frozen_string_literal: true
 
 require 'xf/scope'
+require 'xf/trace'
+require 'xf/trace_value'
+require 'xf/trace_key_value'
 
 module Xf
   module PublicApi
-    # Composes a list of functions, or items that respond to `to_proc`, into
+    # Combines a list of functions, or items that respond to `to_proc`, into
     # a function chain that can be called against a target.
     #
+    # @note
+    #   This _could_ be done with reduce, but we're trying to keep performance
+    #   as close to vanilla as possible.
+    #
     # @param *fns [#to_proc] List of objects coercible into Procs
     #
     # @return [Proc[Any] -> Any]
-    def compose(*fns)
-      chain = fns.map(&:to_proc)
-
+    def pipe(*fns)
       Proc.new { |target|
-        chain.reduce(target) { |t, fn| fn.call(t) }
+        new_value = target
+        fns.each { |fn| new_value = fn.to_proc.call(new_value) }
+        new_value
       }
     end
 
+    alias_method :p, :pipe
+
+    # The more traditional functional Compose, where things go in the opposite
+    # order. Pipe is probably more intuitive to Rubyists, which is why this
+    # is an implementation of pipe.
+    #
+    # @see #pipe
+    def compose(*fns)
+      pipe(*fns.reverse)
+    end
+
     alias_method :c, :compose
 
+
     # Creates a Scope.
     #
     # @see Xf::Scope
@@ -28,13 +47,98 @@ module Xf
     #   See the README for more instructions on usage. Will likely propogate
     #   more examples here and into the specs later.
     #
-    # @param *path [Array[Any]] Hash#dig accessible segments
+    # @param *paths [Array[Any]] Hash#dig accessible segments
     #
     # @return [Xf::Scope]
-    def scope(*path)
-      Scope.new(path)
+    def scope(*paths)
+      Scope.new(paths.flatten)
     end
 
     alias_method :s, :scope
+
+    # Creates a Trace.
+    #
+    # @see Xf::Trace
+    #
+    # @param trace_path [Any]
+    #   Any hash key to dive searching for.
+    #
+    # @return [Xf::Trace]
+    def trace(trace_path)
+      Trace.new(trace_path)
+    end
+
+    alias_method :t, :trace
+
+    # Creates a TraceValue, which matches against a value rather than a key.
+    #
+    # @see Xf::TraceValue
+    #
+    # @param trace_path [Any]
+    #   Any hash value to dive searching for
+    #
+    # @return [Xf::TraceValue]
+    def trace_value(trace_path)
+      TraceValue.new(trace_path)
+    end
+
+    alias_method :tv, :trace_value
+
+    # Creates a TraceKeyValue, which matches against a value rather than a key.
+    #
+    # @see Xf::TraceKeyValue
+    #
+    # @param trace_path [Any]
+    #   Any hash value to dive searching for
+    #
+    # @return [Xf::TraceValue]
+    def trace_key_value(trace_key, trace_value)
+      TraceKeyValue.new(trace_key, trace_value)
+    end
+
+    alias_method :tkv, :trace_key_value
+
+    # Clamps a value to be within a range. Works with numbers, dates, and other
+    # items. More of a utility function.
+    #
+    # @param start_range [Any]
+    #   Start of a range
+    #
+    # @param end_range [Any]
+    #   End of a range
+    #
+    # @return [Proc[Any] -> Any]
+    #   Proc that returns a value that's been clamped to the given range
+    def clamp(start_range, end_range)
+      Proc.new { |target|
+        next start_range if target < start_range
+        next end_range   if target > end_range
+
+        target
+      }
+    end
+
+    # Counts by a function. This is entirely because I hackney this everywhere in
+    # pry anyways, so I want a function to do it for me already.
+    #
+    # @param targets [Array[Any]] Targets to count
+    # @param &fn     [Proc]       Function to define count key
+    #
+    # @return [Hash[Any, Integer]] Counts
+    def count_by(targets, &fn)
+      fn ||= -> v { v }
+
+      targets.each_with_object(Hash.new(0)) { |target, counts|
+        counts[fn[target]] += 1
+      }
+    end
+
+    # Solely meant as a tap addendum
+    #
+    # @return [Proc[Any] -> nil]
+    #   nil from puts result
+    def log
+      Proc.new { |target| puts target }
+    end
   end
 end

data/lib/xf/scope.rb

@@ -48,32 +48,56 @@ module Xf
       Proc.new { |hash| set_value!(hash, value, &fn) }
     end
 
-    # Private API - Methods below here are subject to change, please don't use
-    # them directly.
-
-    private def get_value(hash)
+    # Direct value getter, though it may be wiser to use Hash#dig here
+    # instead if you're concerned about speed.
+    #
+    # @param hash [Hash] Hash to get value from
+    #
+    # @return [Any]
+    def get_value(hash)
       hash.dig(*@paths)
     end
 
-    private def set_value(hash, value = nil, &fn)
+    # Sets a value at the bottom of a path without mutating the original.
+    #
+    # @param hash [Hash]
+    #   Hash to set value on
+    #
+    # @param value = nil [Any]
+    #   Value to set
+    #
+    # @param &fn [Proc]
+    #   If present, current value is yielded to it and the return
+    #   value is the new set value
+    #
+    # @return [Hash]
+    #   Clone of the original with the value set
+    def set_value(hash, value = nil, &fn)
       set_value!(deep_clone(hash), value, &fn)
     end
 
-    private def set_value!(hash, value = nil, &fn)
+    # Mutating form of `#set_value`
+    #
+    # @see set_value
+    def set_value!(hash, value = nil, &fn)
       lead_in    = @paths[0..-2]
       target_key = @paths[-1]
 
-      dive = lead_in.reduce(hash) { |h, s| h[s] }
+      new_hash = hash
+      lead_in.each { |s| new_hash = new_hash[s] }
 
       new_value = block_given? ?
-        yield(dive[target_key]) :
+        yield(new_hash[target_key]) :
         value
 
-      dive[target_key] = new_value
+      new_hash[target_key] = new_value
 
       hash
     end
 
+    # Private API - Methods below here are subject to change, please don't use
+    # them directly.
+
     private def deep_clone(hash)
       Marshal.load(Marshal.dump(hash))
     end

data/lib/xf/trace.rb

@@ -0,0 +1,108 @@
+module Xf
+  # A more abstract version of a Scope in which the lead key is treated as
+  # if it could be anywhere in a hash tree. A Trace will dive until it
+  # finds _all_ matching nodes.
+  #
+  # Note that this can potentially be slow, but is also very difficult to emulate
+  # succinctly inline in vanilla Ruby.
+  #
+  # @author baweaver
+  # @since 0.1.0
+  #
+  class Trace
+    # Creates a Scope
+    #
+    # @param trace_path [Any]
+    #   What node to try and locate
+    #
+    # @return [Xf::Trace]
+    def initialize(trace_path)
+      @trace_path = trace_path
+    end
+
+    def get
+      Proc.new { |target| get_value(target) }
+    end
+
+    def get_value(hash)
+      retrieved_values = []
+
+      recursing_dive(hash) { |h, k, v| retrieved_values.push(v) }
+
+      retrieved_values
+    end
+
+    # Sets a value in a Hash
+    #
+    # @param value = nil [Any]
+    #   Value to set at the target
+    #
+    # @param &fn [Proc]
+    #   Block to yield target value to. Returned value will be set as the new
+    #   value at the target.
+    #
+    # @return [Proc[Hash] -> Hash]
+    #   New Hash with transformation applied
+    def set(value = nil, &fn)
+      Proc.new { |hash| set_value(hash, value, &fn) }
+    end
+
+    # Mutates a value in a Hash
+    #
+    # @see #set
+    #
+    # @note
+    #   This method does the same thing as `#set`, except that it mutates the
+    #   target value instead of creating a clone first.
+    #
+    def set!(value = nil, &fn)
+      Proc.new { |hash| set_value!(hash, value, &fn) }
+    end
+
+    def set_value(hash, value = nil, &fn)
+      set_value!(deep_clone(hash), value, &fn)
+    end
+
+    def set_value!(hash, value = nil, &fn)
+      recursing_dive(hash) { |h, k, v|
+        h[k] = block_given? ? yield(v) : value
+      }
+
+      hash
+    end
+
+    # Private API - Methods below here are subject to change, please don't use
+    # them directly.
+
+    # Match is defined as having complete access to a hash, key, and value
+    # to make it easier to override for other future fun tasks.
+    #
+    # In the base case of trace we only _really_ care about the key matching
+    # for speed reasons. If you really want power though you could rig this
+    # up to work with Qo to query things.
+    #
+    # @param hash    [Hash] [description]
+    # @param key     [Any]  [description]
+    # @param value   [Any]  [description]
+    # @param matcher [#===] [description]
+    #
+    # @return [type] [description]
+    private def match?(hash, key, value, matcher)
+      matcher === key
+    end
+
+    private def deep_clone(hash)
+      Marshal.load(Marshal.dump(hash))
+    end
+
+    private def recursing_dive(target_hash, &fn)
+      target_hash.each { |k, v|
+        yield(target_hash, k, v) if match?(target_hash, k, v, @trace_path)
+
+        next unless target_hash[k].is_a?(Hash)
+
+        recursing_dive(target_hash[k], &fn)
+      }
+    end
+  end
+end

data/lib/xf/trace_key_value.rb

@@ -0,0 +1,22 @@
+module Xf
+  # Traces based on a key and a value matching. Only overrides the `match?`
+  # method to redefine a matched node.
+  #
+  # @author baweaver
+  # @since 0.1.0
+  #
+  class TraceKeyValue < Trace
+    def initialize(trace_key, trace_value)
+      @trace_key   = trace_key
+      @trace_value = trace_value
+    end
+
+    # Private API - Methods below here are subject to change, please don't use
+    # them directly.
+
+    # @see Trace#match?
+    private def match?(hash, key, value, matcher)
+      @trace_key === key && @trace_value === value
+    end
+  end
+end

data/lib/xf/trace_value.rb

@@ -0,0 +1,19 @@
+module Xf
+  # Traces based on a value matching. Only overrides the `match?`
+  # method to redefine a matched node.
+  #
+  # @see Xf::Trace
+  #
+  # @author baweaver
+  # @since 0.1.0
+  #
+  class TraceValue < Trace
+    # Private API - Methods below here are subject to change, please don't use
+    # them directly.
+
+    # @see Trace#match?
+    private def match?(hash, key, value, matcher)
+      matcher === value
+    end
+  end
+end

metadata

@@ -1,71 +1,71 @@
 --- !ruby/object:Gem::Specification
 name: xf
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.1.0
 platform: ruby
 authors:
 - Brandon Weaver
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-04-21 00:00:00.000000000 Z
+date: 2018-04-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: bundler-audit
+  name: gemsmith
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.6'
+        version: '12.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.6'
+        version: '12.0'
 - !ruby/object:Gem::Dependency
-  name: codeclimate-test-reporter
+  name: git-cop
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '2.2'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '2.2'
 - !ruby/object:Gem::Dependency
-  name: gemsmith
+  name: bundler-audit
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '12.0'
+        version: '0.6'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '12.0'
+        version: '0.6'
 - !ruby/object:Gem::Dependency
-  name: git-cop
+  name: codeclimate-test-reporter
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.2'
+        version: '1.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.2'
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: guard-rspec
   requirement: !ruby/object:Gem::Requirement
@@ -164,6 +164,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.54'
+- !ruby/object:Gem::Dependency
+  name: benchmark-ips
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: qo
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
 description: 
 email:
 - keystonelemur@gmail.com
@@ -179,6 +207,9 @@ files:
 - lib/xf/identity.rb
 - lib/xf/public_api.rb
 - lib/xf/scope.rb
+- lib/xf/trace.rb
+- lib/xf/trace_key_value.rb
+- lib/xf/trace_value.rb
 homepage: https://www.github.com/baweaver/xf
 licenses:
 - MIT
@@ -192,9 +223,9 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - "~>"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: '2.5'
+      version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="