blank_empty_nil_filters 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 31f1a60dad0e7ba230e21358acf7a044d79852ac
-  data.tar.gz: 7ace2d848b525742ba194b7300e21ef1716a6366
+SHA256:
+  metadata.gz: adbf79bbbb71e8dfed6243cf91759f9279b3970ad269e0f861c36172920b1e23
+  data.tar.gz: 695e3e289ad0548df29683d72cc0b254ce8772b7450eb7dc4f09fd2f421dcf20
 SHA512:
-  metadata.gz: 99a10a6017b9dbbeafcff7acdd8ef9d15fca64dbc638dabbf479113017533fb3ca219351b47f2f38332deec2d16de6eea2f9b9ed822e5a86d8277925ad3c65fc
-  data.tar.gz: bf611e7b505e56e571e4bc78cd2ff61c48b49a23fe993db5773c5f46e5cb41bd16b9006f016f0d07daa6e6e6604afbb7057d02b6816935e0b00b2c799f71c0c1
+  metadata.gz: bc6654261141905a9f63409dffb74caea814663102401992ee3eed3b63f0a528c5cd8fc07d2f4477786f800024a6b463087b27265b3c2b50318a8ccb1ded9242
+  data.tar.gz: 4a14c426a1e5b5c65edf90558f8843d03bb6f293e8d55ab96ead2e301782fa3f37b4c27c2773ddb2b7a4bc8371ccaefdff8e906b6531abc49e42dd8609fe5979

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    blank_empty_nil_filters (0.1.1)
+    blank_empty_nil_filters (0.1.2)
 
 GEM
   remote: https://rubygems.org/
@@ -138,4 +138,4 @@ DEPENDENCIES
   yard
 
 BUNDLED WITH
-   2.0.1
+   2.2.0.rc.1

data/README.md

@@ -4,18 +4,29 @@ Ruby gem to extend Hash and Array with filters for blank, empty, and nil values.
 
 Build status: [![CircleCI](https://circleci.com/gh/aks/blank_empty_nil_filters/tree/master.svg?style=svg)](https://circleci.com/gh/aks/blank_empty_nil_filters/tree/master)
 
-This module creates new methods to be prepended to the Array, Hash, String,
-and Object classes to implement recursive filters for _blank_, _empty_, and
-nil values.
-
-Note: `ActiveSupport` provides _some_ of these methods, but in general is a *much* larger body
-of code.  This module are only those methods related to "blank", "empty" or nil. Also,
-`ActiveSupport` uses `Regexp` `match` to determine blankness, while this code uses a
-non-destructive `strip`, which is both faster and less sensitive to non-UTF8 string error
-conditions.
-
-In general an _empty_ value has zero length, and a _blank_ value is either empty or has
-all blank values (e.g., `to_s.strip.length.zero?`)
+This module creates new methods to be prepended to the Array, Hash,
+String, and Object classes to implement recursive filters for _blank_,
+_empty_, and nil values.
+
+The methods can select or reject values which are blank _(whitespace)_, 
+empty _(zero length)_, or nil, and do so recursively.
+
+The default behavior is to filter recursively, without limit.
+However, optional arguments may be applied to any filter method to
+indicate the _start_ level and the _depth_ to which filtering should
+be done.  This is useful if, say, a hash needs to retain its top-level
+keys, regardless of whether or not its values are empty, but deeper
+level hashes can be completely removed if they are empty.
+
+Note: `ActiveSupport` provides _some_ of these methods, but in general
+is a *much* larger body of code.  This module are only those methods
+related to "blank", "empty" or nil. Also, `ActiveSupport` uses
+`Regexp` `match` to determine blankness, while this code uses a
+non-destructive `strip`, which is both faster and less sensitive to
+non-UTF8 string error conditions.
+
+In general an _empty_ value has zero length, and a _blank_ value is either 
+empty or has all blank values (e.g., `to_s.strip.length.zero?`)
 
 In the descriptions below, `aoh` is an `Array` or `Hash` object.
 
@@ -67,6 +78,7 @@ hash.nil_value_keys         # keys from nil values
 ```
 
 All of the `no_*` methods have aliases of `reject_*`.  For example, `reject_empty_values`.
+All of the `only_*` methods have aliases of `select_*`; eg: `select_nil_values`.
 Some folks prefer the shorter names, some prefer the longer ones.  Take your pick.
 
 ```ruby
@@ -75,6 +87,19 @@ aoh.reject_blank_values     # aoh.no_blank_values
 aoh.reject_nil_values       # aoh.no_nil_values
 ```
 
+Any of the above methods can be provided optional arguments of _start_ and _depth_
+to indicate levels at which filter _(selecting or rejecting)_ should start and 
+stop.
+
+```ruby
+aoh.no_empty_values(1)      # no empty items at level 1 or higher; leave level 0 alone
+aoh.no_blank_values(1)      # no blank items at level 1 or higher; leave level 0 alone
+aoh.no_nil_values(1, 4)     # no nil items at level 1 until level 4; level level 0 alone
+```
+
+Note that it is important to use a `depth`  value to prevent infinite loops when there 
+are recursive data structures.
+
 All of the above methods are wrappers around two general purpose methods:
 
 ```ruby

data/blank_empty_nil_filters.gemspec

@@ -0,0 +1,39 @@
+# encoding: utf-8
+
+$:.unshift File.expand_path('../lib', __FILE__)
+require 'blank_empty_nil_filters/version'
+
+Gem::Specification.new do |s|
+  s.name          = 'blank_empty_nil_filters'
+  s.version       = BlankEmptyNilFilters::VERSION
+  s.authors       = ['Alan Stebbens']
+  s.email         = ['aks@stebbens.org']
+  s.homepage      = 'https://github.com/aks/blank_empty_nil_filters'
+  s.licenses      = ['MIT']
+  s.summary       = 'Extensions for filtering empty, blank, and nil values from Hashes and Arrays',
+  s.description   = <<~TEXT
+                    Extentions for convenient filtering of blank, empty, and nil values from
+                    Hash and Array instances.
+                  TEXT
+
+  s.files         = Dir.glob('{bin/*,lib/**/*,[A-Z]*}')
+  s.platform      = Gem::Platform::RUBY
+  s.require_paths = ['lib']
+
+  s.add_development_dependency "bundler"
+  s.add_development_dependency "fuubar"
+  s.add_development_dependency "guard"
+  s.add_development_dependency "guard-rspec"
+  s.add_development_dependency "guard-yard"
+  s.add_development_dependency "pry-byebug"
+  s.add_development_dependency "rake"
+  s.add_development_dependency "redcarpet"
+  s.add_development_dependency "rspec"
+  s.add_development_dependency "rspec_junit"
+  s.add_development_dependency "rspec_junit_formatter"
+  s.add_development_dependency "rubocop"
+  s.add_development_dependency "simplecov"
+  s.add_development_dependency "spring"
+  s.add_development_dependency "terminal-notifier-guard" if /Darwin/.match?(`uname -a`.strip)
+  s.add_development_dependency "yard"
+end

data/lib/blank_empty_nil_filters.rb

@@ -3,126 +3,174 @@
 # See README.me for the descriptions.
 
 module BlankEmptyNilFilters
+  # These filter methods are used on both the Array and Hash extensions
+  module FilterMethods
+    def maybe_recurse(val, scanner, condition, start, depth, level)
+      if level >= start && (depth.nil? || level < depth)
+        if val.respond_to?(scanner)
+          val.send(scanner, condition, start, depth, level+1) # recurse
+        else
+          val
+        end
+      else
+        val
+      end
+    end
+
+    def maybe_apply(val, condition, start, depth, level)
+      val.send(condition) if level >= start && (depth.nil? || level < depth)
+    end
+  end
+
   module ArrayExtensions
-    def no_empty_values
-      reject_values(:is_empty?)
+    def no_empty_values(start = 0, depth = nil, level = 0)
+      reject_values(:is_empty?, start, depth, level)
     end
     alias reject_empty_values no_empty_values
 
-    def no_blank_values
-      reject_values(:is_blank?)
+    def no_blank_values(start = 0, depth = nil, level = 0)
+      reject_values(:is_blank?, start, depth, level)
     end
     alias reject_blank_values no_blank_values
 
-    def no_nil_values
-      reject_values(:nil?)
+    def no_nil_values(start = 0, depth = nil, level = 0)
+      reject_values(:nil?, start, depth, level)
     end
     alias reject_nil_values no_nil_values
 
-    def only_empty_values
-      select_values(:is_empty?)
+    def only_empty_values(start = 0, depth = nil, level = 0)
+      select_values(:is_empty?, start, depth, level)
     end
+    alias select_empty_values only_empty_values
 
-    def only_blank_values
-      select_values(:is_blank?)
+    def only_blank_values(start = 0, depth = nil, level = 0)
+      select_values(:is_blank?, start, depth, level)
     end
+    alias select_blank_values only_blank_values
 
-    def only_nil_values
-      select_values(:is_nil?)
+    def only_nil_values(start = 0, depth = nil, level = 0)
+      select_values(:is_nil?, start, depth, level)
     end
+    alias select_nil_values only_nil_values
 
-    def is_empty?
-      length.zero? || reject_empty_values.length.zero?
+    def is_empty?(start = 0, depth = nil, level = 0)
+      length.zero? || no_empty_values(start, depth, level).length.zero?
     end
 
-    def is_blank?
-      is_empty? || reject_blank_values.length.zero?
+    def is_blank?(start = 0, depth = nil, level = 0)
+      is_empty? || no_blank_values(start, depth, level).length.zero?
     end
 
-    def reject_values(filter)
-      map { |val| val.respond_to?(:reject_values) ? val.reject_values(filter) : val }
-        .reject { |val| val.send(filter) }
+    # @param [Symbol] condition the name of the filter method (eg: :is_empty?)
+    # @param [Integer] start the starting level at which filtering occurs; default: 0
+    # @param [Integer|nil] depth the maximum level at which filtering occurs; defaults to nil for no limit
+    # @param [Integer] level the current level; defaults to 0
+    # @return [Array] the filtered array after having recursively applied +condition+ to each
+    #                 element and removing those for which the condition is true
+    def reject_values(condition, start = 0, depth = nil, level = 0)
+      filter_values(:reject_values, :reject, condition, start, depth, level)
     end
     alias no_values reject_values
 
-    def select_values(filter)
-      map { |val| val.respond_to?(:select_values) ? val.select_values(filter) : val }
-        .select { |val| val.send(filter) }
+    # @param [Symbol] condition the name of the filter method (eg: :is_empty?)
+    # @param [Integer] start the starting level at which filtering occurs; default: 0
+    # @param [Integer|nil] depth the maximum level at which filtering occurs; nil = no limit
+    # @param [Integer] level the current level; defaults to 0
+    # @return [Array] the filtered array after having recursively applied +condition+ to each element
+    #                 element and selecting out those for which the condition is true
+    def select_values(condition, start = 0, depth = nil, level = 0)
+      filter_values(:select_values, :select, condition, start, depth, level)
     end
     alias only_values select_values
+
+    private
+
+    include FilterMethods
+
+    def filter_values(scanner, selector, condition, start, depth, level)
+      map { |val| maybe_recurse(val, scanner, condition, start, depth, level) }
+        .send(selector) { |val| maybe_apply(val, condition, start, depth, level) }
+    end
   end
 
   module HashExtensions
-    def no_empty_values
-      reject_values(:is_empty?)
+    def no_empty_values(start = 0, depth = nil, level = 0)
+      reject_values(:is_empty?, start, depth, level)
     end
     alias reject_empty_values no_empty_values
 
-    def only_empty_values
-      select_values(:is_empty?)
+    def only_empty_values(start = 0, depth = nil, level = 0)
+      select_values(:is_empty?, start, depth, level)
     end
     alias select_empty_values only_empty_values
 
-    def no_blank_values
-      reject_values(:is_blank?)
+    def no_blank_values(start = 0, depth = nil, level = 0)
+      reject_values(:is_blank?, start, depth, level)
     end
     alias reject_blank_values no_blank_values
 
-    def only_blank_values
-      select_values(:is_blank?)
+    def only_blank_values(start = 0, depth = nil, level = 0)
+      select_values(:is_blank?, start, depth, level)
     end
     alias select_blank_values only_blank_values
 
-    def no_nil_values
-      reject_values(:nil?)
+    def no_nil_values(start = 0, depth = nil, level = 0)
+      reject_values(:nil?, start, depth, level)
     end
     alias reject_nil_values no_nil_values
 
-    def only_nil_values
-      select_values(:nil?)
+    def only_nil_values(start = 0, depth = nil, level = 0)
+      select_values(:nil?, start, depth, level)
     end
     alias select_nil_values only_nil_values
 
-    def empty_value_keys
-      only_empty_values.keys
+    def empty_value_keys(start = 0, depth = nil, level = 0)
+      only_empty_values(start, depth, level).keys
     end
 
-    def blank_value_keys
-      only_blank_values.key
+    def blank_value_keys(start = 0, depth = nil, level = 0)
+      only_blank_values(start, depth, level).keys
     end
 
-    def nil_value_keys
-      only_nil_values.keys
+    def nil_value_keys(start = 0, depth = nil, level = 0)
+      only_nil_values(start, depth, level).keys
     end
 
-    def non_empty_value_keys
-      no_empty_values.key
+    def non_empty_value_keys(start = 0, depth = nil, level = 0)
+      no_empty_values(start, depth, level).keys
     end
 
-    def non_blank_value_keys
-      no_blank_values.keys
+    def non_blank_value_keys(start = 0, depth = nil, level = 0)
+      no_blank_values(start, depth, level).keys
     end
 
-    def non_nil_value_keys
-      no_nil_values.keys
+    def non_nil_value_keys(start = 0, depth = nil, level = 0)
+      no_nil_values(start, depth, level).keys
     end
 
-    def is_empty?
-      length.zero? || no_empty_values.length.zero?
+    def is_empty?(start = 0, depth = nil, level = 0)
+      length.zero? || no_empty_values(start, depth, level).length.zero?
     end
 
-    def is_blank?
-      length.zero? || reject_blank_values.length.zero?
+    def is_blank?(start = 0, depth = nil, level = 0)
+      length.zero? || reject_blank_values(start, depth, level).length.zero?
+    end
+
+    def reject_values(condition, start = 0, depth = nil, level = 0)
+      filter_hash_values(:reject_values, :reject, condition, start, depth, level)
     end
 
-    def reject_values(filter)
-      dup.transform_values { |val| val.respond_to?(:reject_values) ? val.reject_values(filter) : val }
-         .reject { |_key, val| val.send(filter) }
+    def select_values(condition, start = 0, depth = nil, level = 0)
+      filter_hash_values(:select_values, :select, condition, start, depth, level)
     end
 
-    def select_values(filter)
-      dup.transform_values { |val| val.respond_to?(:select_values) ? val.select_values(filter) : val }
-         .select { |_key, val| val.send(filter) }
+    private
+
+    include FilterMethods
+
+    def filter_hash_values(scanner, selector, condition, start, depth, level)
+      dup.transform_values { |val| maybe_recurse(val, scanner, condition, start, depth, level) }
+        .send(selector) { |_key, val| maybe_apply(val, condition, start, depth, level) }
     end
   end
 

data/lib/blank_empty_nil_filters/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module BlankEmptyNilFilters
-  VERSION = '0.1.1'
+  VERSION = '0.1.2'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: blank_empty_nil_filters
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Alan Stebbens
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-05-23 00:00:00.000000000 Z
+date: 2020-08-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -249,6 +249,7 @@ files:
 - LICENSE.md
 - README.md
 - Rakefile
+- blank_empty_nil_filters.gemspec
 - lib/blank_empty_nil_filters.rb
 - lib/blank_empty_nil_filters/version.rb
 homepage: https://github.com/aks/blank_empty_nil_filters
@@ -270,8 +271,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.6.14
+rubygems_version: 3.1.2
 signing_key: 
 specification_version: 4
 summary: '["Extensions for filtering empty, blank, and nil values from Hashes and