recls-ruby 2.12.0.1 → 2.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b7ad41cfec6d08d5ba41ef9c6bc47f5b151d61a232f9f7a04ce389ca49487f51
-  data.tar.gz: 9cb9cff1104388001437470dbd6cb82566313f78d82b0a5b323689573f57f5d9
+  metadata.gz: 6d6532f17abe260ced9482626db483f1f41d27e9bb152bbd870b5b525bba4399
+  data.tar.gz: eb78ee7591a8014fa293b236ef5e7ae8a35ecd3559105ea07eab6fe132e37955
 SHA512:
-  metadata.gz: 5c61cd03d38a8d459d9bbfc3f150e0fed22182abef92da86dd135040690088f070d69f55cfa3ccf4312f7d1b122d921eb72b48e2137fa8801e1360d29aec4dfe
-  data.tar.gz: fb1603cbf0f8ffd86c1c679ac08f0d5bf5c770d8d4348a24b74bab1e5440b28f6f35a7e8ef4368252eaf9ab0d5f081935814ebd48ade0c26939340a964b748e0
+  metadata.gz: 730ea68a021a6657485d618aaf10cc42284a138330c4e5b8e2c48ebafef46f1955b26ada22a9008aa6b9f3bacb6271354f6dd07fe179177165892299f5a35fde
+  data.tar.gz: 0d57bec94aaa38ec8cd3d1577570e571e00fd3fd503d621ba4cd65325e49ff7f215977cb7b12a3d6260aef00523fd37bef248c5a7cb92b83532b16d89640ccb7

data/examples/show_hidden_files.md

@@ -19,7 +19,7 @@ require 'recls'
 # 2. Filter returned entries by hidden? attribute
 Recls.file_rsearch('.', Recls::WILDCARDS_ALL, Recls::FILES | Recls::SHOW_HIDDEN).each do |fe|
 
-  puts fe.path if fe.hidden?
+  puts fe if fe.hidden?
 end
 ```
 

data/examples/show_hidden_files.rb

@@ -10,6 +10,6 @@ require 'recls'
 # 2. Filter returned entries by hidden? attribute
 Recls.file_rsearch('.', Recls::WILDCARDS_ALL, Recls::FILES | Recls::SHOW_HIDDEN).each do |fe|
 
-  puts fe.path if fe.hidden?
+  puts fe if fe.hidden?
 end
 

data/examples/show_readonly_files.md

@@ -18,7 +18,7 @@ require 'recls'
 # 1. Filter returned entries by readonly? attribute
 Recls.file_rsearch('.', Recls::WILDCARDS_ALL, Recls::FILES).each do |fe|
 
-  puts fe.path if fe.readonly?
+  puts fe if fe.readonly?
 end
 ```
 

data/examples/show_readonly_files.rb

@@ -9,6 +9,6 @@ require 'recls'
 # 1. Filter returned entries by readonly? attribute
 Recls.file_rsearch('.', Recls::WILDCARDS_ALL, Recls::FILES).each do |fe|
 
-  puts fe.path if fe.readonly?
+  puts fe if fe.readonly?
 end
 

data/lib/recls/api.rb

@@ -66,7 +66,7 @@ module Recls
   #   - +options+ (+Hash+, +Integer+) Combination of flags (with behaviour as described below for the +flags+ option), or an options hash;
   #
   # * *Options:*
-  #   - +flags+ (+Integer+) Combination of flags - +Recls::FILES+, +Recls::DIRECTORIES+, etc. If the value modulo +Recls::TYPEMASK+ is 0, then +Recls::FILES+ is assumed. The value +Recls::RECURSIVE+ is added by the function, and so need not be added by the caller; it cannot be removed
+  #   - +flags+ (+Integer+) Combination of flags - +Recls::FILES+, +Recls::DIRECTORIES+, etc. If the value modulo +Recls::TYPEMASK+ is 0, then +Recls::FILES+ is assumed. The value +Recls::RECURSIVE+ is added by the function, and so need not be added by the caller; it cannot be removed;
   #
   # === Return
   # An instance of a class implementing +Enumerable+ whose value type is
@@ -105,7 +105,7 @@ module Recls
   #   - +options+ (+Hash+, +Integer+) Combination of flags (with behaviour as described below for the +flags+ option), or an options hash;
   #
   # * *Options:*
-  #   - +flags+ (+Integer+) Combination of flags - +Recls::FILES+, +Recls::DIRECTORIES+, +Recls::RECURSIVE+, etc. If the value modulo +Recls::TYPEMASK+ is 0, then +Recls::FILES+ is assumed
+  #   - +flags+ (+Integer+) Combination of flags - +Recls::FILES+, +Recls::DIRECTORIES+, +Recls::RECURSIVE+, etc. If the value modulo +Recls::TYPEMASK+ is 0, then +Recls::FILES+ is assumed;
   #
   # === Return
   # An instance of a class implementing +Enumerable+ whose value type is

data/lib/recls/combine_paths_1.rb

@@ -53,17 +53,18 @@ module Recls
   # === Signature
   #
   # * *Parameters:*
-  #   - +paths+ (+[ String, Recls::Entry ]+) Array of 1 or more path elements to be combined;
+  #   - +paths+ (+[ (String, Recls::Entry) ]+) Array of 1 or more path elements to be combined;
   #
   # === Return
   # (+String+) The combined path.
   def self.combine_paths(*paths)
 
-    paths = paths.reject { |p| p.nil? }
-    paths = paths.map { |p| 'Recls::Entry' == p.class.to_s ? p.path : p }
+    paths.reject! { |p| p.nil? }
 
     raise ArgumentError, 'must specify one or more path elements' if paths.empty?
 
+    ix_last_entry = paths.rindex { |path| ::Recls::Entry === path } and return paths[ix_last_entry]
+
     return Recls::Ximpl.combine_paths paths, {}
   end
 end # module Recls

data/lib/recls/combine_paths_2plus.rb

@@ -53,7 +53,7 @@ module Recls
   # === Signature
   #
   # * *Parameters:*
-  #   - +paths+ (+[ String, Recls::Entry ]+) Array of 1 or more path elements to be combined;
+  #   - +paths+ (+[ (String, Recls::Entry) ]+) Array of 1 or more path elements to be combined;
   #   - +options+ (+Hash+) Options that moderate the combination;
   #
   # * *Options:*
@@ -65,11 +65,12 @@ module Recls
   # (+String+) The combined path.
   def self.combine_paths(*paths, **options)
 
-    paths = paths.reject { |p| p.nil? }
-    paths = paths.map { |p| 'Recls::Entry' == p.class.to_s ? p.path : p }
+    paths.reject! { |p| p.nil? }
 
     raise ArgumentError, 'must specify one or more path elements' if paths.empty?
 
+    ix_last_entry = paths.rindex { |path| ::Recls::Entry === path } and return paths[ix_last_entry]
+
     return Recls::Ximpl.combine_paths paths, options
   end
 end # module Recls

data/lib/recls/entry.rb

@@ -398,5 +398,35 @@ module Recls
 end # module Recls
 
 
+# We now monkey-patch `::String` cautiously, to facilitate constructs such
+# as:
+#
+#      cwd = Recls.stat @cwd
+#      assert_equal @cwd, cwd
+
+
+=begin
+=end
+
+# @!visibility private
+class String # :nodoc:
+
+  # TODO: work out if can use `super` for all supported versions of Ruby
+
+  # @!visibility private
+  alias_method :String_modified_for_Recls_Entry_for_original_op_eq, :== # :nodoc:
+
+  def == rhs
+
+    if ::Recls::Entry === rhs
+
+      rhs = rhs.path
+    end
+
+    String_modified_for_Recls_Entry_for_original_op_eq rhs
+  end
+end
+
+
 # ############################## end of file ############################# #
 

data/lib/recls/file_search.rb

@@ -89,7 +89,7 @@ module Recls
         flags = options[:flags] || 0
       else
 
-        raise ArgumentError, "options parameter must a #{::Hash}, nil, or an integer specifying flags - an instance of #{options.class} given"
+        raise ArgumentError, "options parameter must a `#{::Hash}`, `nil`, or an integer specifying flags - an instance of `#{options.class}` given"
       end
 
 

data/lib/recls/recls.rb

@@ -37,16 +37,6 @@
 # ######################################################################## #
 
 
-require 'recls/version'
-
-require 'recls/api'
-require 'recls/entry'
-require 'recls/file_search'
-require 'recls/foreach'
-require 'recls/stat'
-require 'recls/util'
-require 'recls/ximpl/os'
-
 # The *recls* module
 #
 # == Significant Components
@@ -62,6 +52,21 @@ require 'recls/ximpl/os'
 # - Recls::file_search
 # - Recls::foreach
 # - Recls::stat
+module Recls
+end # module Recls
+
+
+require 'recls/version'
+
+require 'recls/api'
+require 'recls/entry'
+require 'recls/file_search'
+require 'recls/foreach'
+require 'recls/stat'
+require 'recls/util'
+require 'recls/ximpl/os'
+
+
 module Recls
 
   # The string sequence used to separate names in paths, e.g. "/" on UNIX
@@ -80,6 +85,7 @@ module Recls
   end
 end # module Recls
 
+
 require 'recls/obsolete'
 
 

data/lib/recls/stat.rb

@@ -109,7 +109,7 @@ module Recls
   #
   # * *Parameters:*
   #   - +path+ (+String+) A path to evaluate. May not be +nil+;
-  #   - +search_root+ (+String+, +Recls::Entry+) A directory from which the returned Entry instance's search-relative attributes are evaluated;
+  #   - +search_root+ (+String+, +Recls::Entry+) A directory from which the returned +Entry+ instance's search-relative attributes are evaluated;
   #   - +flags+ (+Integer+) A bit-combined set of flags (such as +Recls::DIRECTORIES+, +Recls::FILES+, +Recls::RECURSIVE+, +Recls::DETAILS_LATER+, and so on);
   #
   # ==== Parameter Ordering
@@ -132,12 +132,17 @@ module Recls
     search_root = nil
     message     = nil
 
-    path = File.expand_path(path) if path =~ /^~[\\\/]*/
+    path_is_entry = ::Recls::Entry === path
+
+    unless path_is_entry
+
+      path = File.expand_path(path) if path =~ /^~[\\\/]*/
+    end
 
     case args.size
     when 0
 
-      ;
+      return path if path_is_entry
     when 1
 
       case args[0]
@@ -149,7 +154,7 @@ module Recls
         search_root = args[0]
       else
 
-        message = "argument '#{args[0]}' (#{args[0].class}) not valid"
+        message = "argument '#{args[0]}' (of type `#{args[0].class}`) not valid"
       end
     when 2
 
@@ -171,7 +176,7 @@ module Recls
       message = "too many arguments"
     end
 
-    raise ArgumentError, "#{message}: Recls.stat() takes one (path), two (path+flags or path+search_root), or three (path+search_root+flags) arguments" if message
+    raise ArgumentError, "#{message}: `Recls.stat()` takes one (path), two (path+flags or path+search_root), or three (path+search_root+flags) arguments" if message
 
     Recls::Ximpl.stat_prep(path, search_root, flags)
   end

data/lib/recls/util.rb

@@ -61,8 +61,6 @@ module Recls
   # (+String+) The absolute form of the path.
   def self.absolute_path(path)
 
-    return path.path if 'Recls::Entry' === path.class.to_s
-
     Recls::Ximpl.absolute_path path
   end
 
@@ -78,7 +76,7 @@ module Recls
   # (+String+) The canonical form of the path.
   def self.canonicalise_path(path)
 
-    path = path.path if 'Recls::Entry' === path.class.to_s
+    return path.path if ::Recls::Entry === path
 
     Recls::Ximpl.canonicalise_path path
   end
@@ -132,16 +130,12 @@ module Recls
   # === Signature
   #
   # * *Parameters:*
-  #   - +path+ (+String+, +Recls::Entry+) The path;
+  #   - +path+ (+String+, +Recls::Entry+, +nil+) The path to be evaluated;
   #
   # === Return
   # (boolean) +true+ if +path+ is absolute; +false+ otherwise.
   def self.absolute_path?(path)
 
-    return nil if path.nil?
-
-    return true if 'Recls::Entry' === path.class.to_s
-
     Recls::Ximpl.absolute_path? path
   end
 end # module Recls

data/lib/recls/version.rb

@@ -46,7 +46,7 @@ class Object; end # :nodoc:
 module Recls
 
   # Current version of the recls.Ruby library
-  VERSION           = '2.12.0.1'
+  VERSION           = '2.13.0'
 
   private
   # @!visibility private

data/lib/recls/ximpl/util.rb

@@ -454,6 +454,8 @@ module Recls # :nodoc:
     # @!visibility private
     def self.canonicalise_path(path) # :nodoc:
 
+      raise ArgumentError, "`path` must be an instance of `::String` or `nil`" if $DEBUG && !path.nil? && !path.is_a?(::String)
+
       return nil if not path
       return '' if path.empty?
 
@@ -495,7 +497,7 @@ module Recls # :nodoc:
         return path
       else
 
-        raise TypeError, "parameter path ('#{path}') is of type #{path.class} must be nil or an instance of #{::String} or #{::Recls::Entry}"
+        raise TypeError, "parameter path ('#{path}') is of type `#{path.class}` must be `nil` or an instance of `#{::String}` or `#{::Recls::Entry}`"
       end
 
       f1_windows_root, f2_directory, dummy1, dummy2, dummy3, dummy4, dummy5 = Util.split_path(path)
@@ -529,7 +531,7 @@ module Recls # :nodoc:
         return path.path
       else
 
-        raise TypeError, "parameter path ('#{path}') is of type #{path.class} must be an instance of #{::String} or Recls::Entry"
+        raise TypeError, "parameter path ('#{path}') is of type `#{path.class}` must be an instance of `#{::String}` or `#{::Recls::Entry}`"
       end
 
       return '' if path.empty?
@@ -776,7 +778,9 @@ module Recls # :nodoc:
     # @!visibility private
     def self.combine_paths(paths, options) # :nodoc:
 
-      paths   = [ paths ] unless ::Array === paths
+      raise ArgumentError, "`paths` must be an instance of `::Array`" if $DEBUG && !paths.is_a?(::Array)
+      raise ArgumentError, "`paths` elements must be instances of `::String`" if $DEBUG && paths.any? { |s| !s.is_a?(::String) }
+
       abs_ix  = 0
 
       paths = paths.map { |path| '~' == path[0].to_s ? File.expand_path(path) : path }
@@ -840,7 +844,7 @@ module Recls # :nodoc:
 
       rescue SystemCallError => x
 
-        $stderr.puts "exception (#{x.class}): #{x}" if $DEBUG
+        $stderr.puts "exception (`#{x.class}`): #{x}" if $DEBUG
 
         if(0 != (STOP_ON_ACCESS_FAILURE & flags))
 

data/test/unit/tc_recls_entry.rb

@@ -27,14 +27,29 @@ class Test_Recls_entry < Test::Unit::TestCase
     cwd = Recls.stat @cwd
 
     assert_equal @cwd, cwd.path
+    assert_equal @cwd, cwd
+
+    cwd2 = Recls.stat cwd
+
+    assert_equal @cwd, cwd.path
+    assert_equal @cwd, cwd
+
+    assert_equal cwd.object_id, cwd2.object_id
   end
 
   def test_entry_does_mark_directory
 
     cwd = Recls.stat @cwd, Recls::MARK_DIRECTORIES
 
-    # assert_equal "#{@cwd}#{Recls::PATH_NAME_SEPARATOR}", cwd.path
     assert_equal "#{@cwd}/", cwd.path
+    assert_equal "#{@cwd}/", cwd
+
+    cwd2 = Recls.stat cwd, Recls::MARK_DIRECTORIES
+
+    assert_equal "#{@cwd}/", cwd.path
+    assert_equal "#{@cwd}/", cwd
+
+    assert_not_equal cwd.object_id, cwd2.object_id
   end
 end
 

data/test/unit/tc_recls_util.rb

@@ -6,6 +6,10 @@ $:.unshift File.join(File.dirname(__FILE__), '../..', 'lib')
 
 require 'recls/util'
 
+if RUBY_VERSION >= '2'
+
+  require 'xqsr3/extensions/test/unit'
+end
 require 'test/unit'
 
 
@@ -13,7 +17,13 @@ class Test_combine_paths < Test::Unit::TestCase
 
   def test_nil_nil
 
-    assert_raise(::ArgumentError) { Recls.combine_paths(nil, nil) }
+    if RUBY_VERSION >= '2'
+
+      assert_raise_with_message(::ArgumentError, /must specify one or more path elements/) { Recls.combine_paths(nil, nil) }
+    else
+
+      assert_raise(::ArgumentError) { Recls.combine_paths(nil, nil) }
+    end
   end
 
   def test_origin_nil
@@ -56,26 +66,29 @@ class Test_combine_paths < Test::Unit::TestCase
     assert_equal 'abc/def/ghi', Recls.combine_paths('abc/', 'def/ghi')
     assert_equal 'abc/./def/ghi', Recls.combine_paths('abc/.', 'def/ghi')
     assert_equal 'abc/./def/ghi', Recls.combine_paths('abc/./', 'def/ghi')
+
     if RUBY_VERSION >= '2'
-    assert_equal 'abc/./def/ghi', Recls.combine_paths('abc/.', 'def/ghi', clean_path: false)
-    assert_equal 'abc/./def/ghi', Recls.combine_paths('abc/./', 'def/ghi', clean: false)
-    assert_equal 'abc/def/ghi', Recls.combine_paths('abc/.', 'def/ghi', clean_path: true)
-    assert_equal 'abc/def/ghi', Recls.combine_paths('abc/./', 'def/ghi', clean: true)
-    assert_equal 'abc/def/ghi', Recls.combine_paths('abc/./.', 'def/ghi', clean_path: true)
-    assert_equal 'abc/../def/ghi', Recls.combine_paths('abc/..', 'def/ghi')
-    assert_equal 'def/ghi', Recls.combine_paths('abc/..', 'def/ghi', clean_path: true)
+
+      assert_equal 'abc/./def/ghi', Recls.combine_paths('abc/.', 'def/ghi', clean_path: false)
+      assert_equal 'abc/./def/ghi', Recls.combine_paths('abc/./', 'def/ghi', clean: false)
+      assert_equal 'abc/def/ghi', Recls.combine_paths('abc/.', 'def/ghi', clean_path: true)
+      assert_equal 'abc/def/ghi', Recls.combine_paths('abc/./', 'def/ghi', clean: true)
+      assert_equal 'abc/def/ghi', Recls.combine_paths('abc/./.', 'def/ghi', clean_path: true)
+      assert_equal 'abc/../def/ghi', Recls.combine_paths('abc/..', 'def/ghi')
+      assert_equal 'def/ghi', Recls.combine_paths('abc/..', 'def/ghi', clean_path: true)
     end
   end
 
   def test_multiple_relative
 
     if RUBY_VERSION >= '2'
-    assert_equal 'a/b/c/d/e/f/g', Recls.combine_paths('a', 'b', 'c', 'd/e/f/', 'g', clean: false)
-    assert_equal 'a/b/c/d/e/f/g', Recls.combine_paths('a', 'b', 'c', 'd/e/f/', 'g', clean: true)
 
-    assert_equal 'a/b/c/../d/e/f/g', Recls.combine_paths('a', 'b', 'c', '..', 'd/e/f/', 'g', clean: false)
-    assert_equal 'a/b/d/e/f/g', Recls.combine_paths('a', 'b', 'c', '..', 'd/e/f/', 'g/', clean: true)
-    assert_equal 'a/b/d/e/f/g/', Recls.combine_paths('a', 'b', 'c', '..', 'd/e/f/', 'g/', canonicalise: true)
+      assert_equal 'a/b/c/d/e/f/g', Recls.combine_paths('a', 'b', 'c', 'd/e/f/', 'g', clean: false)
+      assert_equal 'a/b/c/d/e/f/g', Recls.combine_paths('a', 'b', 'c', 'd/e/f/', 'g', clean: true)
+
+      assert_equal 'a/b/c/../d/e/f/g', Recls.combine_paths('a', 'b', 'c', '..', 'd/e/f/', 'g', clean: false)
+      assert_equal 'a/b/d/e/f/g', Recls.combine_paths('a', 'b', 'c', '..', 'd/e/f/', 'g/', clean: true)
+      assert_equal 'a/b/d/e/f/g/', Recls.combine_paths('a', 'b', 'c', '..', 'd/e/f/', 'g/', canonicalise: true)
     end
   end
 
@@ -91,11 +104,22 @@ class Test_combine_paths < Test::Unit::TestCase
 
     assert_equal '/f/g', Recls.combine_paths('/', 'a', 'b', 'c', 'd/e', '/f/g')
     assert_equal '/f/g/', Recls.combine_paths('/', 'a', 'b', 'c', 'd/e', '/f/g/')
+
     if RUBY_VERSION >= '2'
-    assert_equal '/f/g', Recls.combine_paths('/', 'a', 'b', 'c', 'd/e', '/f/g/', clean: true)
-    assert_equal '/f/g/', Recls.combine_paths('/', 'a', 'b', 'c', 'd/e', '/f/g/', canonicalise: true)
+
+      assert_equal '/f/g', Recls.combine_paths('/', 'a', 'b', 'c', 'd/e', '/f/g/', clean: true)
+      assert_equal '/f/g/', Recls.combine_paths('/', 'a', 'b', 'c', 'd/e', '/f/g/', canonicalise: true)
     end
   end
+
+  def test_combining_with_entries
+
+    f_g = Recls.stat('/f/g', Recls::DETAILS_LATER)
+    b = Recls.stat('b', Recls::DETAILS_LATER)
+
+    assert_equal '/f/g', Recls.combine_paths('/', 'a', 'b', 'c', 'd/e', f_g)
+    assert_equal '/f/g', Recls.combine_paths('/', 'a', b, 'c', 'd/e', f_g)
+  end
 end
 
 class Test_canonicalise_path < Test::Unit::TestCase
@@ -128,6 +152,14 @@ class Test_canonicalise_path < Test::Unit::TestCase
     assert_equal('a', Recls.canonicalise_path('a'))
     assert_equal('file', Recls.canonicalise_path('file'))
     assert_equal('file.ext', Recls.canonicalise_path('file.ext'))
+
+    a = Recls.stat 'a', Recls::DETAILS_LATER
+    file = Recls.stat 'file', Recls::DETAILS_LATER
+    file_ext = Recls.stat 'file.ext', Recls::DETAILS_LATER
+
+    assert_equal(Recls.canonicalise_path(a.path), Recls.canonicalise_path(a))
+    assert_equal(Recls.canonicalise_path(file.path), Recls.canonicalise_path(file))
+    assert_equal(Recls.canonicalise_path(file_ext.path), Recls.canonicalise_path(file_ext))
   end
 
   def test_zero_parts

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: recls-ruby
 version: !ruby/object:Gem::Version
-  version: 2.12.0.1
+  version: 2.13.0
 platform: ruby
 authors:
 - Matt Wilson