enumpath 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f0c82457a7964b42629b6a3ea752d1cb9a3a383b41fde79d9fd249f25a73cdbf
+  data.tar.gz: 57353f0105eb540fc1bf9202811b80c5afba4c6268e00e5fa9d644521fc53911
+SHA512:
+  metadata.gz: 1c235bf4d538e646697f21f0411f1f4bf74e982957e1092dd05d41f6363bf37fd7bea5a74c3bca223f2e0521bad82f637f89b8eaff4332ae1354c546986e7af7
+  data.tar.gz: 39d33c4b50f464dfc8de6fe1b5b0d3edd8f528ca1714ff0b69e767aa09c5a4b13211ee78c9d07aad2e5c2f98e450a23c792bca915c2ddcafe5cf57831e1b243b

data/.gitignore

@@ -0,0 +1,15 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status
+
+.byebug_history
+.ruby-gemset
+.ruby-version

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.travis.yml

@@ -0,0 +1,5 @@
+sudo: false
+language: ruby
+rvm:
+  - 2.5.1
+before_install: gem install bundler -v 1.16.1

data/.yardopts

@@ -0,0 +1 @@
+--no-private - LICENSE

data/CONTRIBUTING.md

@@ -0,0 +1,91 @@
+# Contributing
+
+Thanks for being interested in our project! We welcome [all kinds of contributions](https://opensource.guide/how-to-contribute/). There are a few things you should know before contributing to this repository:
+
+1. All contributors must agree to our Contributor License Agreement before any merge requests will be accepted.
+2. Please first discuss the change you wish to make via issue, email, or any other method with the owners of this repository before making a change.
+3. Please note we have a code of conduct, please follow it in all your interactions with the project.
+
+## Pull Request Process
+
+1. Fork the repo.
+2. Make sure the tests pass before you begin working.
+3. Make your changes, with new passing tests. Follow the [Ruby Style Guide](https://github.com/rubocop-hq/ruby-style-guide).
+4. Push to your fork. Write a [good commit message](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html).
+5. Submit a [good pull request](https://blog.github.com/2015-01-21-how-to-write-the-perfect-pull-request/).
+6. Others will give constructive feedback. This is a time for discussion and improvements, and making the necessary changes will be required before we can merge the contribution.
+
+## Code of Conduct
+
+### Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, sex characteristics, gender identity and expression,
+level of experience, education, socio-economic status, nationality, personal
+appearance, race, religion, or sexual identity and orientation.
+
+### Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+  advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+### Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+### Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+### Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at [INSERT EMAIL ADDRESS]. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+### Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html
+
+[homepage]: https://www.contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/

data/Gemfile

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
+
+# Specify your gem's dependencies in enumpath.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,56 @@
+PATH
+  remote: .
+  specs:
+    enumpath (0.1.0)
+      mini_cache (~> 1.1.0)
+      to_regexp (~> 0.2.1)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    benchmark-perf (0.2.1)
+    byebug (10.0.2)
+    coderay (1.1.2)
+    diff-lcs (1.3)
+    method_source (0.9.0)
+    mini_cache (1.1.0)
+    null-logger (0.1.5)
+    pry (0.11.3)
+      coderay (~> 1.1.0)
+      method_source (~> 0.9.0)
+    pry-byebug (3.6.0)
+      byebug (~> 10.0)
+      pry (~> 0.10)
+    rake (12.3.1)
+    rspec (3.8.0)
+      rspec-core (~> 3.8.0)
+      rspec-expectations (~> 3.8.0)
+      rspec-mocks (~> 3.8.0)
+    rspec-benchmark (0.3.0)
+      benchmark-perf (~> 0.2.0)
+      rspec (>= 3.0.0, < 4.0.0)
+    rspec-core (3.8.0)
+      rspec-support (~> 3.8.0)
+    rspec-expectations (3.8.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.8.0)
+    rspec-mocks (3.8.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.8.0)
+    rspec-support (3.8.0)
+    to_regexp (0.2.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler (~> 1.16)
+  enumpath!
+  null-logger (~> 0.1)
+  pry-byebug (~> 3.6)
+  rake (~> 12.3)
+  rspec (~> 3.8)
+  rspec-benchmark (~> 0.3.0)
+
+BUNDLED WITH
+   1.16.3

data/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under th

data/README.md

@@ -0,0 +1,492 @@
+# Enumpath
+
+A JSONPath-compatible library for safely navigating nested Ruby objects using path expressions.
+
+## Introduction
+
+Enumpath is an implementation of the [JSONPath][jsonpath] spec for Ruby objects, plus some added sugar. It's like Ruby's native `Enumerable#dig` method, but fancier. It is designed for situations where you need to provide a dynamic way of describing a complex path through nested enumerable objects. This makes it exceptionally well suited for flexible ETL (Extract, Transform, Load) processes by allowing you to define paths through your data in a simple, easily readable, easily storable syntax.
+
+Enumpath path expressions look like this:
+
+```
+$.pets.cats.0.name
+
+$.pets[cats,dogs].*.name
+
+pets..name
+
+['pets']..[?(@.age > 10)].name
+
+..age
+
+pets.cats.-1
+```
+
+Enumpath has the following benefits over vanilla `Enumerable#dig`:
+
+- Paths can be described as simple strings
+- It's smart enough to figure out which path segments are integer indexes versus symbolic keys versus string keys
+- It enables the use of wildcard, recursive descent, filter, subscript, union, and slice operators to describe complex paths through the data
+
+Like `Enumerable#dig`, Enumpath protects against missing path segments and returns safely if the full path cannot be resolved.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'enumpath'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install enumpath
+
+## Usage
+
+Enumpath exposes a simple interface via `Enumpath.apply` that takes a path and an enumerable.
+
+```ruby
+party = { food: %w(pizza tacos) }
+Enumpath.apply('food.0', party) # => ["pizza"]
+```
+
+The result of `Enumpath.apply` is an array of values that were extracted according to the path. Technically it's an instance of `Enumpath::Results` which is an Array-like object that allows you to chain further calls to `.apply` like this:
+
+```ruby
+party = { food: %w(pizza tacos) }
+results = Enumpath.apply('food.*', party) # => ["pizza", "tacos"]
+results.apply("[?(@ == 'pizza')]") # => ["pizza"]
+```
+
+In the event that the path doesn't match anything, an empty results set is returned:
+
+```ruby
+party = { food: %w(pizza tacos) }
+Enumpath.apply("drinks.*", party) # => []
+```
+
+> This is a thoughtful deviation from the original JSONPath spec which would return `false` on no matches.
+
+## Operator Reference
+
+Enumpath currently implements the following path operators:
+
+operator | summary | basic examples
+:---: | --- | ---
+`$` | **Root**; only valid at the beginning of a path and it is entirely optional | `$.puppies` is equivalent to `puppies`
+`.` or `[]` | **[Child](#child-operator)**; can be dot notation or bracket, and bracketed child operators can optionally be wrapped in single quotes | `locations`, `0`, `[departments]`, and `['human resources']` are all valid child operators
+`*` | **[Wildcard](#wildcard-operator)**; applies the remaining path to each member of the current enumerable | `children.*.name` would result in an array containing the names of all the children
+`..` | **[Recursive descent](#recursive-descent-operator)**; applies the remaining path to all members at every level of the current enumerable, including to the current enumerable itself | `..name` would find all the `name` members all the way down through the enumerable regardless of nesting level
+`[start:end:step]` | **[Slice](#slice-operator)**; similar in functionality to Ruby's `Array#slice` method with the addition of a step argument | `[1:8:2]` would operate on indices 1, 3, 5, and 7
+`[child1,child2[,...]]` | **[Union](#union-operator)**; combines the results from multiple child operators | `authors.*[first_name,last_name]` is equivalent to `authors.*.first_name` + `authors.*.last_name`
+`?()` | **[Filter expression](#filter-expression-operator)**; evaluates boolean expressions against the current enumerable; only the members of enumerable that meet the criteria are passed through | `[?(@.price > 10 && @.price <= 20 )]` would return all items whose price is greater than 10 and less than or equal to 20
+`()` | **[Subscript expression](#subscript-expression-operator)**; evaluates an expression as a subscript on the current enumerator | `[(@.length - 1)]` would apply a child operator equal to the `#length` of the current enumerable minus 1 to the current enumerable (i.e. the last member of an array)
+
+### Child operator
+
+Syntax: `child` or `[child]` or `['child']`
+
+Child operators match on an index, key, member, or property of the enumerable. In its non-normalized form a child operator is preceded by `.` or wrapped in '[]'. In bracket notation the child may optionally be wrapped in single quotes. Enumpath will attempt to resolve the data type of the child operator in the following order of precedence:
+
+1. as an integer key or index (if the segment is integer-like),
+2. then as a string key,
+3. then as a symbol key,
+4. and finally as a public property (i.e. a public method of the target that expects no arguments)
+
+#### Examples
+
+```
+Car = Struct.new(:color, :transmition, :owners)
+hiundai = Car.new('blue', :automatic, [{ name: 'Bill' }, { name: 'Ted' }])
+subaru = Car.new('gold', :standard, [{ name: 'Kate' }])
+jeep = Car.new('black', :automatic, [])
+garages = [{ 'cars' => [hiundai, subaru] }, { 'cars' => [jeep] }]
+Enumpath.apply('1', garages) # => [{"cars"=>[#<struct Car color="black", transmition=:automatic, owners=[]>]}]
+Enumpath.apply('0.cars.-1', garages) # => [#<struct Car color="gold", transmition=:standard, owners=[{:name=>"Kate"}]>]
+Enumpath.apply('1.cars.0.owners.length', garages) # => [0]
+```
+
+### Wildcard operator
+
+Syntax: `*` or `[*]`
+
+Wildcards match each immediate member of the enumerable.
+
+### Recursive descent operator
+
+Syntax: `..`
+
+Applies the remaining path expression segments recursively to all members of the enumerable regardless of their nesting level, including the enumerable itself.
+
+### Slice operator
+
+Syntax: `[start:end:step]`, `[start:]`, `[start:end]`, `[start::step]`, `[:end]`, `[:end:step]`, `[::step]`, ...
+
+The slice operator selects a range of elements like Ruby's _`start...end`_ literal, excluding the end value, and then selects each _step_ items. The _start_, _end_, and _step_ arguments default to `0`, `Enumerable#length`, and `1` respectively. The remaining path expression segments are passed to each member whose index is included by the slice operator.
+
+The operator accepts a mixed bag of argument combinations. For instance, these are all valid slice operators:
+
+- `[1:8]`: passes through the members of the enumerable at indices 1 – 7
+- `[1:]`: passes through the members of the enumerable at indices 1 – `Enumerable#length`
+- `[:8]`: passes through the members of the enumerable at indices 0 – 7
+- `[:8:2]`: passes through the members of the enumerable at indices 0, 2, 4, and 6
+- `[::2]`: passes through the members of the enumerable at indices 0, 2, 4, 6, 8, ... up to `Enumerable#length`
+
+### Union operator
+
+Syntax: `[child1,child2,...]`
+
+The union operator combines the results of two or more child operators. There is no limit to the number of child operators you can specify in a single union. Each child operator is separated by a comma (`,`). White space is stripped from around each child operator. Child operators can optionally be wrapped in single quotes. Bracket notation is not supporter in this context.
+
+The following are all valid union operators:
+
+- `[first,last]`
+- `[first,middle,last]`
+- `['first', middle , last]`
+
+### Filter expression operator
+
+Syntax: `[?(expression)]`, `[?(expression && expression)]`, `[?(expression || expression)]`, ...
+
+A filter expression is made up of one or more boolean expressions. Each boolean expression consists of a child operator (`@.child` or `child`; the leading `@.` is optional), plus an optional pair of comparison operator and operand. The comparison operator can be any one of `==`, `!=`, `>=`, `<=`, `<=>`, `>`, `<`, `=~`, `!~`. The operand can be a string (`'some string'`), symbol (`:some_symbol`), boolean constant (`true` or `false`), nil constant (`nil`), regular expression (`/^Some\s+/i`), or numeric value (`10` or `1.0`). If an operator and operand are not included in an expression then the value located at the child operator is evaluated for truthiness. Multiple expression groups can be chained together with `&&` or `||` logical operators, but note that parenthetical grouping of expressions is not supported; the results of each are applied to the previous running result in order. Any member of the current enumerable that passes the net result of the filter expression will be included in further processing of the path.
+
+The following are all valid filter expressions:
+
+- `[?(@.isbn)]`: any member who has an `isbn` value that is not falsey
+- `[?(isbn)]`: equivalent to the previous example
+- `[?(@.price == 8)]`: any member whose `price` value is equal to 8
+- `[?(@.price == 8 || @.price == 10)]`: members with a `price` of 8 _or_ 10
+- `[?(@.price > 2 && @.price < 10)]`: members with a `price` greater than 8 _and_ less than 10
+- `[?(@.name =~ /bob/i || @.name == 'Mark')]`: any member whose `name` matches the regex `/bob/i` or equals `'Mark'`
+
+> Regular expression operands are safely parsed using the `to_regexp` gem
+
+### Subscript expression operator
+
+Syntax: `[(expression)]`
+
+A subscript expression is made up of a singe expression that consists of a child operator (`@.child` or `child`; the leading `@.` is optional), plus an optional pair of arithmetic operator and operand. The arithmetic operator can be any one of `+`, `-`, `**`, `*`, `/`, or `%`. The operand can be a string (`'some string'`), symbol (`:some_symbol`), or numeric value (`10` or `1.0`). The expression is evaluated and the result becomes the subscript. If an operator and operand are not included in an expression then the value located at the child operator is used as the subscript. If the subscript represents a valid child path for the enumerable, the value of that member will be passed along for further processing of the path.
+
+The following are all valid filter expressions:
+
+- `[(@.length - 1)]`: the subscript becomes the length of the current enumerable, minus 1
+- `[(length / 2)]`: the subscript becomes the index at half the length of the enumerable
+- `[(@.type)]`: the subscript becomes the value at the `type` key, member, or property of the enumerable
+
+## Examples
+
+Given the same store example from the JSONPath project:
+
+```ruby
+store_info = {
+  store: {
+    book: [
+      { category: "reference",
+        author: "Nigel Rees",
+        title: "Sayings of the Century",
+        price: 8.95 },
+      { category: "fiction",
+        author: "Evelyn Waugh",
+        title: "Sword of Honour",
+        price: 12.99 },
+      { category: "fiction",
+        author: "Herman Melville",
+        title: "Moby Dick",
+        isbn: "0-553-21311-3",
+        price: 8.99 },
+      { category: "fiction",
+        author: "J. R. R. Tolkien",
+        title: "The Lord of the Rings",
+        isbn: "0-395-19395-8",
+        price: 22.99 }
+    ],
+    bicycle: { color: "red", price: 19.95 }
+  }
+}
+
+# The authors of all the books in the store
+Enumpath.apply("$.store.book[*].author", store_info)
+# => ["Nigel Rees", "Evelyn Waugh", "Herman Melville", "J. R. R. Tolkien"]
+
+# All prices in the store
+Enumpath.apply("$..price", store_info)
+# => [8.95, 12.99, 8.99, 22.99, 19.95]
+
+# All things in store, which are some books and a red bicycle
+Enumpath.apply("$.store.*", store_info)
+# => [[{:category=>"reference",
+#       :author=>"Nigel Rees",
+#       :title=>"Sayings of the Century",
+#       :price=>8.95},
+#      {:category=>"fiction",
+#       :author=>"Evelyn Waugh",
+#       :title=>"Sword of Honour",
+#       :price=>12.99},
+#      {:category=>"fiction",
+#       :author=>"Herman Melville",
+#       :title=>"Moby Dick",
+#       :isbn=>"0-553-21311-3",
+#       :price=>8.99},
+#      {:category=>"fiction",
+#       :author=>"J. R. R. Tolkien",
+#       :title=>"The Lord of the Rings",
+#       :isbn=>"0-395-19395-8",
+#       :price=>22.99}],
+#     {:color=>"red", :price=>19.95}]
+
+# The third book
+Enumpath.apply("$..book[2]", store_info)
+# => [{:category=>"fiction", :author=>"Herman Melville", :title=>"Moby Dick", :isbn=>"0-553-21311-3", :price=>8.99}]
+
+# The last book in order
+Enumpath.apply("$..book[(@.length-1)]", store_info)
+Enumpath.apply("$..book[-1:]", store_info)
+# => Both return: [{:category=>"fiction", :author=>"J. R. R. Tolkien", :title=>"The Lord of the Rings", :isbn=>"0-395-19395-8", :price=>22.99}]
+
+# The first two books in order. Both of these path expressions are equivalent
+Enumpath.apply("$..book[0,1]", store_info)
+Enumpath.apply("$..book[:2]", store_info)
+# => [{:category=>"reference",
+#      :author=>"Nigel Rees",
+#      :title=>"Sayings of the Century",
+#      :price=>8.95},
+#     {:category=>"fiction",
+#      :author=>"Evelyn Waugh",
+#      :title=>"Sword of Honour",
+#      :price=>12.99}]
+
+# All books with an isbn number
+Enumpath.apply("$..book[?(@.isbn)]", store_info)
+# => [{:category=>"fiction",
+#      :author=>"Herman Melville",
+#      :title=>"Moby Dick",
+#      :isbn=>"0-553-21311-3",
+#      :price=>8.99},
+#     {:category=>"fiction",
+#      :author=>"J. R. R. Tolkien",
+#      :title=>"The Lord of the Rings",
+#      :isbn=>"0-395-19395-8",
+#      :price=>22.99}]
+
+# All books with a price less than 10
+Enumpath.apply("$..book[?(@.price<10)]", store_info)
+# => [{:category=>"reference",
+#      :author=>"Nigel Rees",
+#      :title=>"Sayings of the Century",
+#      :price=>8.95},
+#     {:category=>"fiction",
+#      :author=>"Herman Melville",
+#      :title=>"Moby Dick",
+#      :isbn=>"0-553-21311-3",
+#      :price=>8.99}]
+
+# All members of the enumerable, recursively
+Enumpath.apply("$..*", store_info)
+# => [{:book=>
+#       [{:category=>"reference",
+#         :author=>"Nigel Rees",
+#         :title=>"Sayings of the Century",
+#         :price=>8.95},
+#        {:category=>"fiction",
+#         :author=>"Evelyn Waugh",
+#         :title=>"Sword of Honour",
+#         :price=>12.99},
+#        {:category=>"fiction",
+#         :author=>"Herman Melville",
+#         :title=>"Moby Dick",
+#         :isbn=>"0-553-21311-3",
+#         :price=>8.99},
+#        {:category=>"fiction",
+#         :author=>"J. R. R. Tolkien",
+#         :title=>"The Lord of the Rings",
+#         :isbn=>"0-395-19395-8",
+#         :price=>22.99}],
+#      :bicycle=>{:color=>"red", :price=>19.95}},
+#     [{:category=>"reference",
+#       :author=>"Nigel Rees",
+#       :title=>"Sayings of the Century",
+#       :price=>8.95},
+#      {:category=>"fiction",
+#       :author=>"Evelyn Waugh",
+#       :title=>"Sword of Honour",
+#       :price=>12.99},
+#      {:category=>"fiction",
+#       :author=>"Herman Melville",
+#       :title=>"Moby Dick",
+#       :isbn=>"0-553-21311-3",
+#       :price=>8.99},
+#      {:category=>"fiction",
+#       :author=>"J. R. R. Tolkien",
+#       :title=>"The Lord of the Rings",
+#       :isbn=>"0-395-19395-8",
+#       :price=>22.99}],
+#     {:color=>"red", :price=>19.95},
+#     {:category=>"reference",
+#      :author=>"Nigel Rees",
+#      :title=>"Sayings of the Century",
+#      :price=>8.95},
+#     {:category=>"fiction",
+#      :author=>"Evelyn Waugh",
+#      :title=>"Sword of Honour",
+#      :price=>12.99},
+#     {:category=>"fiction",
+#      :author=>"Herman Melville",
+#      :title=>"Moby Dick",
+#      :isbn=>"0-553-21311-3",
+#      :price=>8.99},
+#     {:category=>"fiction",
+#      :author=>"J. R. R. Tolkien",
+#      :title=>"The Lord of the Rings",
+#      :isbn=>"0-395-19395-8",
+#      :price=>22.99},
+#     "reference",
+#     "Nigel Rees",
+#     "Sayings of the Century",
+#     8.95,
+#     "fiction",
+#     "Evelyn Waugh",
+#     "Sword of Honour",
+#     12.99,
+#     "fiction",
+#     "Herman Melville",
+#     "Moby Dick",
+#     "0-553-21311-3",
+#     8.99,
+#     "fiction",
+#     "J. R. R. Tolkien",
+#     "The Lord of the Rings",
+#     "0-395-19395-8",
+#     22.99,
+#     "red",
+#     19.95]
+```
+
+## Options
+
+### :return_type
+
+By default, Enumpath returns the values that match the path expression. Like the original JSONPath implementation, Enumpath also supports returning path results instead of values. This can be useful for collecting static paths from dynamic paths.
+
+```ruby
+party = { food: %w(pizza tacos) }
+Enumpath.apply("food.*", party, result_type: :path) # => ["$['food'][0]", "$['food'][1]"]
+```
+
+Each returned path is a valid path expression that can be used in calls to `Enumpath.apply`. If you want to be explicit about returning values instead of paths you can specify that with the option `result_type: :value`.
+
+### :verbose
+
+Seeing how your path expression is being applied to an enumerable can be helpful in understanding the path expression syntax. Enumpath has a built-in logger to assist with this. It can be enabled by simply passing `verbose: true` as an option on `Enumpath.apply`. By default this will log debugging information to STDOUT, however you can provide your own logger.
+
+For example:
+
+```ruby
+Enumpath.logger.logger = ::Logger.new('log/enumpath.log')
+```
+
+Once enabled, it will log debugging information like so:
+
+```
+Enumpath.apply('$.store.book', store_info, verbose: true)
+
+--------------------------------------
+Enumpath: Path normalized
+--------------------------------------
+original  : $.store.book
+normalized: ["store", "book"]
+--------------------------------------
+Enumpath: Applying
+--------------------------------------
+operator: ["store", "book"]
+to      : {:store=>{:book=>[{:category=>"reference", :author...
+--------------------------------------
+Enumpath: Child operator detected
+  --------------------------------------
+  Enumpath: Applying
+  --------------------------------------
+  operator: ["book"]
+  to      : {:book=>[{:category=>"reference", :author=>"Nigel ...
+  --------------------------------------
+  Enumpath: Child operator detected
+    --------------------------------------
+    Enumpath: Storing
+    --------------------------------------
+    resolved_path: ["store", "book"]
+    enum        : [{:category=>"reference", :author=>"Nigel Rees", :...
+    --------------------------------------
+    Enumpath: New Result
+    --------------------------------------
+    result: [{:category=>"reference", :author=>"Nigel Rees", :...
+```
+
+You can also control verbose mode via `Enumpath.verbose = true` and `Enumpath.verbose = false`.
+
+## Path normalization
+
+When you give a string path to Enumpath it will automatically normalize it to an array of path segments. You can also pass it an array of path segments to avoid the normalization, for instance if the normalization process is having trouble parsing your path, or you happen to have a pre-normalized path already. For example the path `['pets']..[?(@.age > 10)].name` is represented in normalized form as `['pets', '..', '?(@.age > 10)', 'name']`. For the most part you should stick with string paths and let Enumpath normalize on its own.
+
+### Normalized path caching
+
+To save a little bit of time on consecutive calls Enumpath caches the normalized version of each path. This is an implementation detail that can generally be ignored but if you run into trouble with it you can clear the cache with `Enumpath.path_cache.reset`.
+
+## Deviations from the Original JSONPath Spec
+
+1. The JSONPath spec required that `false` be returned when no matches were found, but Enumpath will return an empty result set (`[]`) instead. This is a thoughtful divergence based on the principle of least astonishment and the robustness principle.
+
+2. Enumpath supports relative child indexes, which the original implementation did not support. For instance:
+
+        # Get the last element. Both are equivalent to `$..book[-1:]`
+        Enumpath.apply('$..book.-1', store_info)
+        Enumpath.apply('$..book[-1]', store_info)
+
+3. The original implementations of JSONPath allowed unchecked evaluation of filter and subscript expressions. Enumpath limits those expressions to a reasonable subset of operations as detailed in the [Operator Reference](#operator-reference) section and uses `public_send` rather than `eval` to resolve expressions as necessary.
+
+4. The original JSONPath spec did not include support for using logical operators to chain expressions in filter expression operators. This addition was inspired by [Gergely Brautigam's](https://skarlso.github.io/2017/05/28/replace-eval-with-object-send-and-a-parser/) work on [joshbuddy/jsonpath](https://github.com/joshbuddy/jsonpath)
+
+## Requirements
+
+Enumpath requires Ruby 2.3.0 or higher.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rspec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at [https://github.com/youearnedit/enumpath](). Please read [CONTRIBUTING.md]() for details on our code of conduct, and the process for submitting pull requests to us.
+
+## Versioning
+
+We use [SemVer](http://semver.org/) for versioning. For the versions available, see the [tags](https://github.com/youearnedit/enumpath/tags) on this repository.
+
+## Authors
+
+- [Chris Bloom](https://github.com/chrisbloom7) - YouEarnedIt
+
+See also the list of [contributors](https://github.com/youearnedit/enumpath/graphs/contributors) who participated in this project.
+
+## License
+
+Copyright 2018 YouEarnedIt.com
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at
+
+[www.apache.org/licenses/LICENSE-2.0](http://www.apache.org/licenses/LICENSE-2.0)
+
+Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+
+## Acknowledgements
+
+This project is maintained by the Engineering team at [YouEarnedIt](http://youearnedit.com), an employee engagement and performance metrics platform, headquartered in Austin, TX.
+
+Enumpath is based on [Stefan Goessner's JSONPath spec][jsonpath], and was inspired by several similar libraries:
+
+- [nickcharlton/keypath-ruby](https://github.com/nickcharlton/keypath-ruby)
+- [joshbuddy/jsonpath](https://github.com/joshbuddy/jsonpath)
+
+[jsonpath]: http://goessner.net/articles/JsonPath/