recls-ruby 2.13.1 → 2.13.4

data/TODO.md

@@ -0,0 +1,24 @@
+# recls.Ruby - TODO <!-- omit in toc -->
+
+
+## Functional improvements
+
+* \<none>
+
+
+## Performance improvements
+
+* \<none>
+
+
+## Packaging improvements
+
+* [x] ~~~complete **.github/workflows/ruby.yml** (matrix, gem smoke, warnings job) to match **xqsr3**~~~;
+* [x] ~~~implement **Rakefile** `test` / `default` tasks for `bundle exec rake test`~~~;
+* [x] ~~~fix **recls.gemspec** metadata URIs and homepage to **recls.Ruby** (HTTPS)~~~;
+* [x] ~~~rename gemspec so the filename stem matches `spec.name` (`recls.gemspec` → **recls-ruby.gemspec**)~~~;
+* [x] ~~~obtain a **run_all_unit_tests.sh** (from **misc-dev-scripts**) that skips `tput` when `$TERM` is unset or stdout is not a TTY (CI: `tput: No value for $TERM and no -T specified`)~~~;
+* [x] ~~~after this packaging/boilerplate/CI lift: bump **VERSION** to **2.13.4** and align the gem~~~;
+
+
+<!-- ########################### end of file ########################### -->

data/examples/find_files_and_directories.md

@@ -1,8 +1,9 @@
-# recls.Ruby Example - **find_files_and_directories**
+# recls.Ruby - Example - **find_files_and_directories**
 
 ## Summary
 
-Illustrates finding of FILES, then DIRECTORIES, then both
+Illustrates non-recursive finding of FILES, then DIRECTORIES, then both.
+
 
 ## Source
 

data/examples/find_files_and_directories.recursive.md

@@ -1,8 +1,9 @@
-# recls.Ruby Example - **find_files_and_directories.recursive**
+# recls.Ruby - Example - **find_files_and_directories.recursive**
 
 ## Summary
 
-Illustrates recursive finding of FILES, then DIRECTORIES, then both
+Illustrates recursive finding of FILES, then DIRECTORIES, then both.
+
 
 ## Source
 

data/examples/show_hidden_files.md

@@ -1,8 +1,9 @@
-# recls.Ruby Example - **show_hidden_files**
+# recls.Ruby - Example - **show_hidden_files**
 
 ## Summary
 
-TBC
+Illustrates recursive searching for hidden files via `Recls::SHOW_HIDDEN` and filtering with `Recls::Entry#hidden?`.
+
 
 ## Source
 
@@ -23,9 +24,14 @@ Recls.file_rsearch('.', Recls::WILDCARDS_ALL, Recls::FILES | Recls::SHOW_HIDDEN)
 end
 ```
 
+
 ## Discussion
 
-TBC
+By default, searches omit hidden entries. Including `Recls::SHOW_HIDDEN` causes
+them to be returned; the example then keeps only those for which `#hidden?` is
+true. (The older `Recls.file_rsearch` name is retained for compatibility;
+`Recls.rsearch` is preferred.)
+
 
 ## Example results
 
@@ -39,4 +45,3 @@ TBC
 
 
 <!-- ########################### end of file ########################### -->
-

data/examples/show_readonly_files.md

@@ -1,8 +1,9 @@
-# recls.Ruby Example - **show_hidden_files**
+# recls.Ruby - Example - **show_hidden_files**
 
 ## Summary
 
-TBC
+Illustrates recursive searching for read-only files by filtering with `Recls::Entry#readonly?`.
+
 
 ## Source
 
@@ -22,9 +23,13 @@ Recls.file_rsearch('.', Recls::WILDCARDS_ALL, Recls::FILES).each do |fe|
 end
 ```
 
+
 ## Discussion
 
-TBC
+Unlike hidden entries, read-only files are returned by a normal files search;
+filtering is done solely via `#readonly?`. (The older `Recls.file_rsearch` name
+is retained for compatibility; `Recls.rsearch` is preferred.)
+
 
 ## Example results
 
@@ -35,4 +40,3 @@ TBC
 
 
 <!-- ########################### end of file ########################### -->
-

data/lib/recls/api.rb

@@ -1,10 +1,11 @@
+# frozen_string_literal: true
 # ######################################################################## #
 # File:     recls/api.rb
 #
 # Purpose:  Defines Recls module search functions
 #
 # Created:  9th June 2016
-# Updated:  21st April 2024
+# Updated:  15th August 2026
 #
 # Author:   Matthew Wilson
 #

data/lib/recls/combine_paths_1.rb

@@ -1,14 +1,15 @@
+# frozen_string_literal: true
 # ######################################################################## #
 # File:     recls/compare_paths_1.rb
 #
 # Purpose:  Definition of Recls::compare_paths() for Ruby 1.x
 #
 # Created:  17th February 2014
-# Updated:  21st April 2024
+# Updated:  15th August 2026
 #
 # Author:   Matthew Wilson
 #
-# Copyright (c) 2019-2024, Matthew Wilson and Synesis Information Systems
+# Copyright (c) 2019-2025, Matthew Wilson and Synesis Information Systems
 # Copyright (c) 2014-2019, Matthew Wilson and Synesis Software
 # All rights reserved.
 #
@@ -45,7 +46,16 @@ require 'recls/ximpl/util'
 
 module Recls
 
-  # Combines paths
+  # Combines paths, optionally canonicalising them.
+  #
+  # Unlike `File::join()`, this method takes account of relative vs absolute
+  # elements in the sequence. Specifically, the rightmost non-relative
+  # element, if it exists, anchors the combination, such that any arguments
+  # to the left are ignored. Furthermore, any entries (of type
+  # `Recls::Entry`) in the sequence are given special treatment as follows:
+  # - a rightmost `#file?` or `#device?` is returned as the complete result;
+  # - a rightmost `#directory?` causes all prior elements to be ignored and
+  #   may be combined with subsequent elements;
   #
   # === Signature
   #
@@ -60,7 +70,22 @@ module Recls
 
     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]
+    ix_last_entry = paths.rindex { |path| ::Recls::Entry === path }
+
+    if ix_last_entry
+
+      fe = paths[ix_last_entry]
+
+      if fe.directory?
+
+        paths = paths[ix_last_entry..-1]
+      else
+
+        return fe
+      end
+    end
+
+    paths = paths.map { |path| path.to_str }
 
     return Recls::Ximpl.combine_paths paths, {}
   end

data/lib/recls/combine_paths_2plus.rb

@@ -1,14 +1,15 @@
+# frozen_string_literal: true
 # ######################################################################## #
 # File:     recls/compare_paths_2plus.rb
 #
 # Purpose:  Definition of Recls::compare_paths() for Ruby 2+
 #
 # Created:  17th February 2014
-# Updated:  21st April 2024
+# Updated:  15th August 2026
 #
 # Author:   Matthew Wilson
 #
-# Copyright (c) 2019-2024, Matthew Wilson and Synesis Information Systems
+# Copyright (c) 2019-2025, Matthew Wilson and Synesis Information Systems
 # Copyright (c) 2014-2019, Matthew Wilson and Synesis Software
 # All rights reserved.
 #
@@ -45,7 +46,16 @@ require 'recls/ximpl/util'
 
 module Recls
 
-  # Combines paths, optionally canonicalising them
+  # Combines paths, optionally canonicalising them.
+  #
+  # Unlike `File::join()`, this method takes account of relative vs absolute
+  # elements in the sequence. Specifically, the rightmost non-relative
+  # element, if it exists, anchors the combination, such that any arguments
+  # to the left are ignored. Furthermore, any entries (of type
+  # `Recls::Entry`) in the sequence are given special treatment as follows:
+  # - a rightmost `#file?` or `#device?` is returned as the complete result;
+  # - a rightmost `#directory?` causes all prior elements to be ignored and
+  #   may be combined with subsequent elements;
   #
   # === Signature
   #
@@ -66,7 +76,22 @@ module Recls
 
     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]
+    ix_last_entry = paths.rindex { |path| ::Recls::Entry === path }
+
+    if ix_last_entry
+
+      fe = paths[ix_last_entry]
+
+      if fe.directory?
+
+        paths = paths[ix_last_entry..-1]
+      else
+
+        return fe
+      end
+    end
+
+    paths = paths.map { |path| path.to_str }
 
     return Recls::Ximpl.combine_paths paths, options
   end

data/lib/recls/entry.rb

@@ -1,14 +1,15 @@
+# frozen_string_literal: true
 # ######################################################################## #
 # File:     recls/entry.rb
 #
 # Purpose:  Defines the Recls::Entry class for the recls.Ruby library.
 #
 # Created:  24th July 2012
-# Updated:  21st April 2024
+# Updated:  15th August 2026
 #
 # Author:   Matthew Wilson
 #
-# Copyright (c) 2019-2024, Matthew Wilson and Synesis Information Systems
+# Copyright (c) 2019-2025, Matthew Wilson and Synesis Information Systems
 # Copyright (c) 2012-2019, Matthew Wilson and Synesis Software
 # All rights reserved.
 #
@@ -64,6 +65,7 @@ module Recls
     def initialize(path, file_stat, search_dir, flags)
 
       @file_stat    = file_stat
+      @flags        = flags
 
       @path         = Recls::Ximpl.absolute_path path
       @short_path   = nil
@@ -104,6 +106,8 @@ module Recls
         @short_path       = @file_stat.short_path
         @file_short_name  = Recls::Ximpl::Util.split_path(@short_path)[2]
       else
+
+        ;
       end
     end
 
@@ -237,9 +241,13 @@ module Recls
     # indicates whether the given entry represents a directory
     def directory?
 
-      return false if @file_stat.nil?
+      if @file_stat.nil?
 
-      @file_stat.directory?
+        (Recls::DETAILS_LATER | Recls::DIRECTORIES) == ((Recls::DETAILS_LATER | Recls::DIRECTORIES) & @flags)
+      else
+
+        @file_stat.directory?
+      end
     end
 
     alias_method :dir?, :directory?
@@ -247,9 +255,13 @@ module Recls
     # indicates whether the given entry represents a file
     def file?
 
-      return false if @file_stat.nil?
+      if @file_stat.nil?
+
+        (Recls::DETAILS_LATER | Recls::FILES) == ((Recls::DETAILS_LATER | Recls::FILES) & @flags)
+      else
 
-      @file_stat.file?
+        @file_stat.file?
+      end
     end
 
     # indicates whether the given entry represents a link

data/lib/recls/file_search.rb

@@ -1,10 +1,11 @@
+# frozen_string_literal: true
 # ######################################################################## #
 # File:     recls/file_search.rb
 #
 # Purpose:  Defines the Recls::FileSearch class for the recls.Ruby library.
 #
 # Created:  24th July 2012
-# Updated:  21st April 2024
+# Updated:  15th August 2026
 #
 # Author:   Matthew Wilson
 #
@@ -203,7 +204,7 @@ module Recls
       rescue Errno::ENOENT, Errno::ENXIO
 
         nil
-      rescue SystemCallError => x
+      rescue SystemCallError
 
         # TODO this should be filtered up and/or logged
 

data/lib/recls/flags.rb

@@ -1,10 +1,11 @@
+# frozen_string_literal: true
 # ######################################################################## #
 # File:     recls/flags.rb
 #
 # Purpose:  Defines the Recls::Flags module for the recls.Ruby library.
 #
 # Created:  24th July 2012
-# Updated:  21st April 2024
+# Updated:  15th August 2026
 #
 # Author:   Matthew Wilson
 #

data/lib/recls/foreach.rb

@@ -1,10 +1,11 @@
+# frozen_string_literal: true
 # ######################################################################## #
 # File:     recls/foreach.rb
 #
 # Purpose:  Definition of Recls::foreach() utility function
 #
 # Created:  22nd October 2014
-# Updated:  21st April 2024
+# Updated:  15th August 2026
 #
 # Author:   Matthew Wilson
 #

data/lib/recls/obsolete.rb

@@ -1,10 +1,11 @@
+# frozen_string_literal: true
 # ######################################################################## #
 # File:     recls/obsolete.rb
 #
 # Purpose:  Obsolete elements
 #
 # Created:  19th July 2012
-# Updated:  21st April 2024
+# Updated:  15th August 2026
 #
 # Author:   Matthew Wilson
 #

data/lib/recls/recls.rb

@@ -1,10 +1,11 @@
+# frozen_string_literal: true
 # ######################################################################## #
 # File:     recls/recls.rb
 #
 # Purpose:  Main source file for recls library
 #
 # Created:  19th July 2012
-# Updated:  21st April 2024
+# Updated:  15th August 2026
 #
 # Author:   Matthew Wilson
 #

data/lib/recls/stat.rb

@@ -1,10 +1,11 @@
+# frozen_string_literal: true
 # ######################################################################## #
 # File:     recls/stat.rb
 #
 # Purpose:  Defines the Recls.stat() method for the recls.Ruby library.
 #
 # Created:  24th July 2012
-# Updated:  21st April 2024
+# Updated:  15th August 2026
 #
 # Author:   Matthew Wilson
 #

data/lib/recls/util.rb

@@ -1,10 +1,11 @@
+# frozen_string_literal: true
 # ######################################################################## #
 # File:     recls/util.rb
 #
 # Purpose:  Utility module functions for recls library
 #
 # Created:  17th February 2014
-# Updated:  21st April 2024
+# Updated:  15th August 2026
 #
 # Author:   Matthew Wilson
 #

data/lib/recls/version.rb

@@ -1,14 +1,15 @@
+# frozen_string_literal: true
 # ######################################################################## #
 # File:     recls/version.rb
 #
 # Purpose:  Version for recls library
 #
 # Created:  14th February 2014
-# Updated:  2nd April 2024
+# Updated:  20th August 2026
 #
 # Author:   Matthew Wilson
 #
-# Copyright (c) 2019-2024, Matthew Wilson and Synesis Information Systems
+# Copyright (c) 2019-2025, Matthew Wilson and Synesis Information Systems
 # Copyright (c) 2012-2019, Matthew Wilson and Synesis Software
 # All rights reserved.
 #
@@ -43,7 +44,7 @@
 module Recls
 
   # Current version of the recls.Ruby library
-  VERSION           = '2.13.1'
+  VERSION           = '2.13.4'
 
   private
   # @!visibility private

data/lib/recls/ximpl/os.rb

@@ -1,3 +1,4 @@
+# frozen_string_literal: true
 # ######################################################################## #
 # File:     recls/ximpl/os.rb
 #
@@ -5,7 +6,7 @@
 #           recls library.
 #
 # Created:  16th February 2014
-# Updated:  21st April 2024
+# Updated:  15th August 2026
 #
 # Author:   Matthew Wilson
 #

data/lib/recls/ximpl/unix.rb

@@ -1,14 +1,15 @@
+# frozen_string_literal: true
 # ######################################################################## #
 # File:     recls/ximpl/unix.rb
 #
 # Purpose:  UNIX-specific constructs for the recls library.
 #
 # Created:  19th February 2014
-# Updated:  21st April 2024
+# Updated:  15th August 2026
 #
 # Author:   Matthew Wilson
 #
-# Copyright (c) 2019-2024, Matthew Wilson and Synesis Information Systems
+# Copyright (c) 2019-2026, Matthew Wilson and Synesis Information Systems
 # Copyright (c) 2012-2019, Matthew Wilson and Synesis Software
 # All rights reserved.
 #
@@ -48,15 +49,19 @@ module Recls
   # @!visibility private
   module Ximpl # :nodoc: all
 
+    # File::Stat cannot reliably be subclassed on all Rubies (notably some
+    # Ruby 4 / MinGW builds raise TypeError: wrong instance allocation).
+    # Compose instead and forward File::Stat APIs via method_missing.
+    #
     # @!visibility private
-    class FileStat < File::Stat # :nodoc:
+    class FileStat # :nodoc:
 
       private
       def initialize(path)
 
         @path = path
 
-        super(path)
+        @stat = ::File::Stat.new(path)
       end
 
       public
@@ -74,6 +79,16 @@ module Recls
         return true
       end
 
+      def method_missing(name, *args, &block)
+
+        @stat.__send__(name, *args, &block)
+      end
+
+      def respond_to_missing?(name, include_all = false)
+
+        @stat.respond_to?(name, include_all) || super
+      end
+
       public
       def FileStat.stat(path)
 

data/lib/recls/ximpl/util.rb

@@ -1,14 +1,15 @@
+# frozen_string_literal: true
 # ######################################################################## #
 # File:     recls/ximpl/util.rb
 #
 # Purpose:  Internal implementation constructs for the recls library.
 #
 # Created:  24th July 2012
-# Updated:  21st April 2024
+# Updated:  15th August 2026
 #
 # Author:   Matthew Wilson
 #
-# Copyright (c) 2019-2024, Matthew Wilson and Synesis Information Systems
+# Copyright (c) 2019-2026, Matthew Wilson and Synesis Information Systems
 # Copyright (c) 2012-2019, Matthew Wilson and Synesis Software
 # All rights reserved.
 #
@@ -501,7 +502,12 @@ module Recls
 
       f1_windows_root, f2_directory, dummy1, dummy2, dummy3, dummy4, dummy5 = Util.split_path(path)
 
-      dummy1 = dummy2 = dummy3 = dummy4 = dummy5 = nil
+      # suppress unused warnings
+      dummy1 = dummy1
+      dummy2 = dummy2
+      dummy3 = dummy3
+      dummy4 = dummy4
+      dummy5 = dummy5
 
       unless f1_windows_root
 
@@ -780,7 +786,7 @@ module Recls
       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
+      abs_ix = 0
 
       paths = paths.map { |path| '~' == path[0].to_s ? File.expand_path(path) : path }
 

data/lib/recls/ximpl/windows.rb

@@ -1,14 +1,15 @@
+# frozen_string_literal: true
 # ######################################################################## #
 # File:     recls/ximpl/windows.rb
 #
 # Purpose:  Windows-specific constructs for the recls library.
 #
 # Created:  19th February 2014
-# Updated:  2nd June 2024
+# Updated:  15th August 2026
 #
 # Author:   Matthew Wilson
 #
-# Copyright (c) 2019-2024, Matthew Wilson and Synesis Information Systems
+# Copyright (c) 2019-2026, Matthew Wilson and Synesis Information Systems
 # Copyright (c) 2012-2019, Matthew Wilson and Synesis Software
 # All rights reserved.
 #
@@ -39,8 +40,15 @@
 
 if RUBY_VERSION >= '2'
 
-  require 'fiddle'
-  require 'fiddle/import'
+  begin
+
+    require 'fiddle'
+    require 'fiddle/import'
+  rescue LoadError => e
+
+    # Ruby 4+ no longer ships fiddle as a default gem.
+    raise LoadError, "#{e.message}; on Ruby 4+ Windows, add the 'fiddle' gem (see the project Gemfile)"
+  end
 else
 
   require 'Win32API'
@@ -211,8 +219,12 @@ module Recls
       end # module Kernel32
     end
 
+    # File::Stat cannot reliably be subclassed on all Rubies (notably some
+    # Ruby 4 / MinGW builds raise TypeError: wrong instance allocation).
+    # Compose instead and forward File::Stat APIs via method_missing.
+    #
     # @!visibility private
-    class FileStat < File::Stat # :nodoc:
+    class FileStat # :nodoc:
 
       private
       FILE_ATTRIBUTE_READONLY     = 0x00000001
@@ -260,7 +272,7 @@ module Recls
 
         @attributes = Kernel32.get_file_attributes(path)
 
-        super(path)
+        @stat = ::File::Stat.new(path)
 
         @by_handle_information = ByHandleInformation.new(path)
 
@@ -328,6 +340,17 @@ module Recls
         has_attribute_? FILE_ATTRIBUTE_ENCRYPTED
       end
 
+      # @!visibility private
+      def method_missing(name, *args, &block) # :nodoc:
+
+        @stat.__send__(name, *args, &block)
+      end
+
+      # @!visibility private
+      def respond_to_missing?(name, include_all = false) # :nodoc:
+
+        @stat.respond_to?(name, include_all) || super
+      end
 
       public
       # @!visibility private

data/lib/recls.rb

@@ -1,10 +1,11 @@
+# frozen_string_literal: true
 # ######################################################################## #
 # File:     recls.rb
 #
 # Purpose:  Top-level include for recls.Ruby library
 #
 # Created:  13th January 2012
-# Updated:  20th April 2024
+# Updated:  15th August 2026
 #
 # Author:   Matthew Wilson
 #