tree_filter 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 1e4aed6475c535ad77186d563ce4eb1aae077440
+  data.tar.gz: b6aaf6e676e1c2fd16022e37aea6fa47a713c828
+SHA512:
+  metadata.gz: 155685535bc93a517363950614df705167ea5209f099fdca991fc6528788ff281bb1719ea5d64f14dcf1f1a19e3a27d109e7c23af1d7514350dfb0930a8a7233
+  data.tar.gz: d79a3622fb629cdccdfb1a677accd723002b43fed72a26d460d927ce28b0a5220b480eb2d0d5163ae54b081708d891d3573ac00e390df14e56e0d6d3da4d9b88

data/HISTORY.md

@@ -0,0 +1,5 @@
+# Tree Filter History
+
+## 1.0.0 - 18 March 2015
+
+* Initial release!

data/LICENSE

@@ -0,0 +1,14 @@
+
+   Copyright 2015 Square Inc.
+
+   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 the License.

data/README.md

@@ -0,0 +1,85 @@
+# Tree Filter
+
+Filter arbitrary data trees with a concise query language. Similar to how the
+Jenkins API works, if you happen to be familiar with that.
+
+    name,environments             # Select specific attributes from a hash
+    environments[id,last_deploy]  # Select attributes from sub-hash
+    environments[*]               # Select all attributes
+
+## Usage
+
+```ruby
+require 'tree_filter'
+
+data = {
+  'name' => 'don',
+  'contact' => {
+    'phone' => '415-123-4567',
+    'email' => 'don@example.com'
+  }
+}
+
+TreeFilter.new("name,contact[email]").filter(data)
+# => {'name' => 'don', 'contact' => {'email' => 'don@example.com'}}
+```
+
+Different data structures can be presented dependent on whether they are
+explicitly expanded or not. This is typically used when referring to other
+resources in an API response.
+
+```ruby
+data = {
+  'name' => 'don',
+  'contact' => TreeFilter::Leaf.new('/contact-data/1', {
+    'phone' => '415-123-4567',
+    'email' => 'don@example.com'
+  })
+}
+
+TreeFilter.new("*").filter(data)
+# => {'name' => 'don', 'contact' => '/contact-data/1'}
+
+TreeFilter.new("contact[*]").filter(data)
+# => {'contact' => {'phone' => '415-123-4567', 'email' => 'don@example.com'}}
+```
+
+For nested data structures, evaluation can be defered until it is actually
+required. This can defer resource lookups, and also allows cyclic structures!
+
+```ruby
+data = { 'name' => 'don', }
+
+data['contact'] = TreeFilter::Leaf.new(
+  '/contact-data/1',
+  TreeFilter::Defer.new(->{{
+    'email' => 'don@example.com',
+    'person' => TreeFilter::Leaf.new('/person/1', data)
+  }})
+)
+
+TreeFilter.new("contact[person[contact[email]]]").filter(data)
+# => {'contact' => {'person' => {'contact' => {'email' => 'don@example.com'}}}}
+```
+
+## Compatibility
+
+All rubies that ruby core supports! Should work on JRuby and Rubinius too.
+
+## Support
+
+Make a [new github
+issue](https://github.com/square/ruby-tree_filter/issues/new).
+
+## Contributing
+
+Fork and patch! Before any changes are merged to master, we need you to sign an
+[Individual Contributor
+Agreement](https://spreadsheets.google.com/a/squareup.com/spreadsheet/viewform?formkey=dDViT2xzUHAwRkI3X3k5Z0lQM091OGc6MQ&ndplr=1)
+(Google Form).
+
+Run tests:
+
+    gem install bundler
+    bundle
+    bundle exec rspec

data/lib/tree_filter.rb

@@ -0,0 +1,170 @@
+require 'stringio'
+
+# Allows filtering of complex data-structure using a string query language.
+#
+# Query examples:
+#
+#     name,environments             # Select specific attributes from a hash
+#     environments[id,last_deploy]  # Select attributes from sub-hash
+#     environments[*]               # Select all attributes
+#
+# Two special objects are provided for richer data structure evaluation, Leaf
+# and Defer. See their documentation respectively.
+#
+# More examples in unit specs.
+class TreeFilter
+  def initialize(input)
+    @input = StringIO.new(input)
+  end
+
+  def filter(value)
+    slice.filter(value)
+  end
+
+  module JsonTerminal
+    # This breaks the contract of `to_json`, since only terminal classes
+    # (hard-coded into activesupport) should return themselves. We need to use
+    # `as_json` to expand other classes, however. Data structures containing
+    # this object should always be filtered before being converted though, so
+    # in practice this shouldn't be an issue.
+    def as_json(*args)
+      self
+    end
+  end
+
+  # Allows different data structures to be presented dependent on whether it is
+  # explicitly selected or not. Usually used to provide a "summary" object by
+  # default, and then only include detail if explicitly asked for.
+  #
+  #     data = {'a' => TreeFilter::Leaf.new('/a', {'id' => 'a'})}
+  #
+  #     TreeFilter.new("env").filter(data)    # => {'env' => '/a'}
+  #     TreeFilter.new("env[*]").filter(data) # => {'env' => {'id' => 'a'}}
+  #
+  # @note All data structures containing this object must be filtered before
+  # converting to JSON, otherwise you will get a stack overflow error.
+  Leaf = Struct.new(:left, :right) do
+    include JsonTerminal
+  end
+
+  # The wrapped lamda will not be executed unless it is actually required in
+  # the filtered response. This can be used for performance optimization, and
+  # also to break cycles.
+  #
+  #     data = {'a' => 1, 'b' => TreeFilter::Defer.new(->{ raise })}
+  #
+  #     TreeFilter.new("a").filter(data) # => {'a' => 1}
+  #     TreeFilter.new("b").filter(data) # => raise
+  #
+  # @note All data structures containing this object must be filtered before
+  # converting to JSON, otherwise you will get a stack overflow error.
+  Defer = Struct.new(:f) do
+    include JsonTerminal
+
+    def call
+      f.call
+    end
+  end
+
+  def inspect
+    "<TreeFilter #{slice.attrs.inspect}>"
+  end
+  private
+
+  # Indicates no more filtering for the given object, return it as is.
+  class NullSlice
+    def filter(x)
+      case x
+      when Leaf
+        filter(x.left)
+      when Defer
+        filter(x.call)
+      else
+        x
+      end
+    end
+  end
+
+  Slice = Struct.new(:attrs) do
+    def inspect
+      "<Slice #{@attrs.inspect}>"
+    end
+
+    def initialize(attrs = {})
+      super
+      @attrs = attrs
+    end
+
+    def filter(value)
+      # With activesupport this will always be evaluated, because `as_json` is
+      # monkey-patched on to Object.
+      value = value.as_json if value.respond_to?(:as_json)
+
+      case value
+      when Hash
+        slices = @attrs.dup
+
+        if @attrs.keys.include?('*')
+          slices.delete("*")
+          extra = value.keys - slices.keys - ['*']
+          extra.each do |k|
+            slices[k] = nil
+          end
+        end
+
+        slices.each_with_object({}) do |(attr, slice), ret|
+          slice ||= NullSlice.new
+
+          val = value[attr]
+
+          filtered = case val
+          when Array
+            val.map {|x| slice.filter(x) }
+          else
+            slice.filter(val)
+          end
+
+          ret[attr] = filtered
+        end
+      when Array
+        value.map {|x| filter(x) }
+      when Defer
+        filter(value.call)
+      when Leaf
+        filter(value.right)
+      else
+        value
+      end
+    end
+  end
+
+  def slice
+    @slice ||= parse(@input)
+  end
+
+  def parse(input)
+    slices = {}
+    label  = ""
+
+    while char = input.read(1)
+      case char
+      when ','
+        unless label.empty?
+          slices[label] = nil
+          label = ""
+        end
+      when '['
+        slices[label] = parse(input)
+        label = ""
+      when ']'
+        break
+      else
+        label << char
+      end
+    end
+
+    slices[label] = nil unless label.empty?
+
+    return Slice.new(slices)
+  end
+end

data/spec/tree_filter_spec.rb

@@ -0,0 +1,127 @@
+require 'json'
+
+require 'tree_filter'
+
+describe 'Tree filter spec:' do
+  def filter(data, input)
+    TreeFilter.new(input).filter(data)
+  end
+
+  describe 'filtering a hash' do
+    it 'only includes specified attributes' do
+      data = {'a' => 1, 'b' => 2, 'c' => 3}
+
+      expect(filter(data, 'a,b')).to eq('a' => 1, 'b' => 2)
+    end
+
+    it 'can include sub-tree attributes' do
+      data = {'a' => {'c' => 3, 'd' => 4}, 'b' => 2}
+
+      expect(filter(data, 'a[c]')).to eq('a' => {'c' => 3})
+    end
+
+    it 'can traverse arbitrary depth' do
+      data = {'a' => {'b' => {'c' => 1, 'd' => 2}, 'e' => 3, 'f' => 4}}
+
+      expect(filter(data, 'a[b[c],e]')).to \
+        eq('a' => {'b' => {'c' => 1}, 'e' => 3})
+    end
+
+    it 'includes nil values' do
+      data = {'a' => 1, 'b' => nil, 'c' => 3}
+
+      expect(filter(data, 'a,b')).to eq('a' => 1, 'b' => nil)
+    end
+
+    it 'can defer evaluation of lambdas' do
+      data = {
+        'a' => TreeFilter::Defer.new(->{ 1 }),
+        'b' => TreeFilter::Defer.new(->{ raise })
+      }
+
+      expect(filter(data, 'a')).to eq('a' => 1)
+    end
+
+    it 'filters defered evaluations' do
+      data = {
+        'a' => TreeFilter::Defer.new(->{{'b' => 1, 'c' => 2}}),
+      }
+
+      expect(filter(data, 'a[b]')).to eq('a' => {'b' => 1})
+    end
+
+    it 'allows cyclic references with defer' do
+      data = {
+        'a' => TreeFilter::Leaf.new(1, TreeFilter::Defer.new(->{ data }))
+      }
+
+      expect(filter(data, 'a[a[a]]').to_json).to \
+        eq({'a' => {'a' => {'a' => 1}}}.to_json)
+    end
+
+    it 'handles null filter' do
+      data = {'a' => {'c' => 3, 'd' => 4}, 'b' => 2}
+
+      expect(filter(data, 'a[]')).to eq('a' => {})
+    end
+
+    it 'allows leaf alternation' do
+      data = {'a' => TreeFilter::Leaf.new('/a', 'id' => 'a', 'name' => 'b')}
+
+      expect(filter(data, 'a')).to eq('a' => '/a')
+      expect(filter(data, 'a[id]')).to eq('a' => {'id' => 'a'})
+    end
+
+    it 'allows recursive leaf alternation' do
+      data = {'a' => TreeFilter::Leaf.new('',
+        'b' => TreeFilter::Leaf.new('/b', 'f')
+      )}
+
+      expect(filter(data, 'a[b]')).to eq('a' => {'b' => '/b'})
+    end
+
+    it 'allows * for all attributes' do
+      data = {'a' => {'c' => 3, 'd' => 4}, 'b' => 2}
+
+      expect(filter(data, 'a[*]')).to eq('a' => {'c' => 3, 'd' => 4})
+    end
+
+    it 'takes left tree for *' do
+      data = {'a' => {'c' => TreeFilter::Leaf.new('/c', 'fail')}, 'b' => 2}
+
+      expect(filter(data, 'a[*]')).to eq('a' => {'c' => '/c'})
+    end
+
+    it 'converts objects to JSON' do
+      a = Object.new
+      def a.as_json(*args)
+        {'a' => 1, 'b' => 2}
+      end
+
+      data = {'a' => a}
+
+      expect(filter(a, 'b')).to eq('b' => 2)
+    end
+  end
+
+  describe 'filtering an array' do
+    it 'applies filter to each element' do
+      data = [{'a' => 1, 'b' => 2}, {'a' => 3, 'b' => 4}]
+
+      expect(filter(data, 'a')).to eq([{'a' => 1}, {'a' => 3}])
+    end
+
+    it 'allows leaf alternation' do
+      data = ['a' => TreeFilter::Leaf.new('/a', 'id' => 'a', 'name' => 'b')]
+
+      expect(filter(data, 'a[id]')).to eq(['a' => {'id' => 'a'}])
+    end
+  end
+
+  it 'does not try to recurse into plain values' do
+      data = {'a' => 'b'}
+
+      expect(filter(data, 'a[*]')).to eq('a' => 'b')
+  end
+end
+

data/tree_filter.gemspec

@@ -0,0 +1,27 @@
+# -*- encoding: utf-8 -*-
+Gem::Specification.new do |gem|
+  gem.authors       = ["Xavier Shay"]
+  gem.email         = ["xavier@squareup.com"]
+  gem.description   =
+    %q{Filter arbitrary data trees with a concise query language.}
+  gem.summary       = %q{
+    Filter arbitrary data trees (hashes, arrays, values) with a concise query
+    language. Handles cyclic structures.
+  }
+  gem.homepage      = "http://github.com/square/ruby-tree_filter"
+
+  gem.executables   = []
+  gem.required_ruby_version = '>= 1.9.0'
+  gem.files         = Dir.glob("{spec,lib}/**/*.rb") + %w(
+                        README.md
+                        HISTORY.md
+                        LICENSE
+                        tree_filter.gemspec
+                      )
+  gem.test_files    = Dir.glob("spec/**/*.rb")
+  gem.name          = "tree_filter"
+  gem.require_paths = ["lib"]
+  gem.license       = "Apache 2.0"
+  gem.version       = '1.0.0'
+  gem.has_rdoc      = false
+end

metadata

@@ -0,0 +1,53 @@
+--- !ruby/object:Gem::Specification
+name: tree_filter
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Xavier Shay
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-03-19 00:00:00.000000000 Z
+dependencies: []
+description: Filter arbitrary data trees with a concise query language.
+email:
+- xavier@squareup.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- HISTORY.md
+- LICENSE
+- README.md
+- lib/tree_filter.rb
+- spec/tree_filter_spec.rb
+- tree_filter.gemspec
+homepage: http://github.com/square/ruby-tree_filter
+licenses:
+- Apache 2.0
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 1.9.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: Filter arbitrary data trees (hashes, arrays, values) with a concise query
+  language. Handles cyclic structures.
+test_files:
+- spec/tree_filter_spec.rb
+has_rdoc: false