recls-ruby 2.13.0 → 2.13.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6d6532f17abe260ced9482626db483f1f41d27e9bb152bbd870b5b525bba4399
-  data.tar.gz: eb78ee7591a8014fa293b236ef5e7ae8a35ecd3559105ea07eab6fe132e37955
+  metadata.gz: 9e34f60c35aebc4cf9cb1e217c1e7cf3e0211abee3eddb8e6306daa601c36461
+  data.tar.gz: 888951b3419b4be2b453449a3f25b0ee725e78539449caf469c767bbc329fbd4
 SHA512:
-  metadata.gz: 730ea68a021a6657485d618aaf10cc42284a138330c4e5b8e2c48ebafef46f1955b26ada22a9008aa6b9f3bacb6271354f6dd07fe179177165892299f5a35fde
-  data.tar.gz: 0d57bec94aaa38ec8cd3d1577570e571e00fd3fd503d621ba4cd65325e49ff7f215977cb7b12a3d6260aef00523fd37bef248c5a7cb92b83532b16d89640ccb7
+  metadata.gz: d0756416a3dc1d95aae37a46e7d3db1bbea1347e7b0cc369088910662698361dcedf718da31d818b976fc78b342766dd155c969fab8593f90e6c644e8cc44d04
+  data.tar.gz: 85291a5a45c3b430f92fbed82f9033bc53d524fa67dde8fd40b6f85581032b625c0756e944ab57fb6a74c3b9f60e92264f05dd7cdd606f2e5ecd8f61b1cd774e

data/README.md

@@ -1,32 +1,37 @@
-# recls.Ruby
+# recls.Ruby <!-- omit in toc -->
 
-**rec**ursive **ls**, for Ruby
+**rec**-ursive **ls**, for Ruby
 
 [![Gem Version](https://badge.fury.io/rb/recls-ruby.svg)](https://badge.fury.io/rb/recls-ruby)
 
 
 ## Introduction
 
-**recls** stands for **rec**ursive **ls**. The first recls library was a C
+**recls** stands for **rec**-ursive **ls**. The first recls library was a C
 library with a C++ wrapper. There have been several implementations in other
 languages. **recls.Ruby** is the Ruby version.
 
 
-## Table of Contents
+## Table of Contents <!-- omit in toc -->
 
-1. [Introduction](#introduction)
-2. [Installation](#installation)
-3. [Components](#components)
-4. [Examples](#examples)
-5. [Project Information](#project-information)
+- [Introduction](#introduction)
+- [Installation](#installation)
+- [Components](#components)
+  - [The ``Recls`` module](#the-recls-module)
+  - [The ``Recls::Entry`` class](#the-reclsentry-class)
+- [Examples](#examples)
+- [Project Information](#project-information)
+  - [Where to get help](#where-to-get-help)
+  - [Contribution guidelines](#contribution-guidelines)
+  - [Dependencies](#dependencies)
+  - [Development dependencies](#development-dependencies)
+  - [Dependents](#dependents)
+  - [Related projects](#related-projects)
+  - [License](#license)
+  - [Compatibility](#compatibility)
 
 
-## Introduction
-
-T.B.C.
-
-
-## Installation & usage
+## Installation
 
 Install using `gem install recls-ruby` or add it to your `Gemfile`.
 
@@ -57,26 +62,24 @@ module Recls
     # ##########################
     # Name-related attributes
 
-    # (+String+) A normalised form of #path that can be used in comparisons
+    # (+String+) A normalised form of {.path} that can be used in comparisons
     attr_reader :compare_path
-
     # (+String+) The full-path of the instance
     attr_reader :path
-    # (+String+) The (Windows) short-form of #path, or +nil+ if not on Windows
+    # (+String+) The (Windows) short-form of {.path}, or +nil+ if not on Windows
     attr_reader :short_path
     # (+String+) The (Windows) drive. +nil+ if does not exist
     attr_reader :drive
-    # (+String+) The full path of the entry's directory (taking into account the
-    # #drive if on Windows)
+    # (+String+) The full path of the entry's directory (taking into account the {.drive} if on Windows)
     attr_reader :directory_path
     alias_method :dirname, :directory_path
-    # (+String+) The entry's directory (excluding the #drive if on Windows)
+    # (+String+) The entry's directory (excluding the {.drive} if on Windows)
     attr_reader :directory
-    # (+[ String ]+) An array of directory parts, where each part ends in Recls::PATH_NAME_SEPARATOR
+    # ( +[+ +String+ +]+ ) An array of directory parts, where each part ends in {Recls::PATH_NAME_SEPARATOR}
     attr_reader :directory_parts
-    # (+String+) The entry's file name (combination of #stem + #extension)
+    # (+String+) The entry's file name (combination of {.stem} + {.extension})
     attr_reader :file_full_name
-    # (+String+) The (Windows) short-form of #basename, or +nil+ if not on Windows
+    # (+String+) The (Windows) short-form of {.basename}, or +nil+ if not on Windows
     attr_reader :file_short_name
     alias_method :basename, :file_full_name
     # (+String+) The entry's file stem
@@ -87,13 +90,13 @@ module Recls
     alias_method :extension, :file_extension
     # (+String+) The search directory if specified; +nil+ otherwise
     attr_reader :search_directory
-    # (+String+) The #path relative to #search_directory; +nil+ if no search directory specified
+    # (+String+) The +#path+ relative to {.search_directory}; +nil+ if no search directory specified
     attr_reader :search_relative_path
-    # (+String+) The #directory relative to #search_directory; +nil+ if no search directory specified
+    # (+String+) The +#directory+ relative to {.search_directory}; +nil+ if no search directory specified
     attr_reader :search_relative_directory
-    # (+String+) The #directory_path relative to #search_directory; +nil+ if no search directory specified
+    # (+String+) The +#directory_path+ relative to {.search_directory}; +nil+ if no search directory specified
     attr_reader :search_relative_directory_path
-    # (+[ String ]+) The #directory_parts relative to #search_directory; +nil+ if no search directory specified
+    # ( +[+ +String+ +]+ ) The +#directory_parts+ relative to {.search_directory}; +nil+ if no search directory specified
     attr_reader :search_relative_directory_parts
 
     # ##########################
@@ -117,37 +120,37 @@ module Recls
 
   if Recls::Ximpl::OS::OS_IS_WINDOWS
 
-    # [WINDOWS-ONLY] Indicates whether the entry has the *system* bit
+    # (*WINDOWS-ONLY*) Indicates whether the entry has the *system* bit
     def system?
       . . .
     end
 
-    # [WINDOWS-ONLY] Indicates whether the entry has the *archive* bit
+    # (*WINDOWS-ONLY*) Indicates whether the entry has the *archive* bit
     def archive?
       . . .
     end
 
-    # [WINDOWS-ONLY] Indicates whether the entry is a device
+    # (*WINDOWS-ONLY*) Indicates whether the entry is a device
     def device?
       . . .
     end
 
-    # [WINDOWS-ONLY] Indicates whether the entry is *normal*
+    # (*WINDOWS-ONLY*) Indicates whether the entry is *normal*
     def normal?
       . . .
     end
 
-    # [WINDOWS-ONLY] Indicates whether the entry has the *temporary* bit
+    # (*WINDOWS-ONLY*) Indicates whether the entry has the *temporary* bit
     def temporary?
       . . .
     end
 
-    # [WINDOWS-ONLY] Indicates whether the entry has the *compressed* bit
+    # (*WINDOWS-ONLY*) Indicates whether the entry has the *compressed* bit
     def compressed?
       . . .
     end
 
-    # [WINDOWS-ONLY] Indicates whether the entry has the *encrypted* bit
+    # (*WINDOWS-ONLY*) Indicates whether the entry has the *encrypted* bit
     def encrypted?
       . . .
     end
@@ -188,24 +191,21 @@ module Recls
 
     # indicates the device of the given entry
     #
-    # On Windows, this will be 0 if the entry cannot be
-    # opened
+    # On Windows, this will be 0 if the entry cannot be opened
     def dev
       . . .
     end
 
     # indicates the ino of the given entry
     #
-    # On Windows, this will be 0 if the entry cannot be
-    # opened
+    # On Windows, this will be 0 if the entry cannot be opened
     def ino
       . . .
     end
 
     # number of links to the given entry
     #
-    # On Windows, this will be 0 if the entry cannot be
-    # opened
+    # On Windows, this will be 0 if the entry cannot be opened
     def nlink
       . . .
     end
@@ -226,8 +226,8 @@ module Recls
     # ##########################
     # Comparison
 
-    # determines whether rhs is an instance of Entry and
-    # refers to the same path
+    # determines whether rhs is an instance of {Recls::Entry} and refers to
+    # the same path
     def eql?(rhs)
       . . .
     end
@@ -250,14 +250,12 @@ module Recls
     # ##########################
     # Conversion
 
-    # represents the entry as a string (in the form of
-    # the full path)
+    # represents the entry as a string (in the form of the full path)
     def to_s
       . . .
     end
 
-    # represents the entry as a string (in the form of
-    # the full path)
+    # represents the entry as a string (in the form of the full path)
     def to_str
       . . .
     end
@@ -294,6 +292,11 @@ Defect reports, feature requests, and pull requests are welcome on https://githu
 None
 
 
+### Development dependencies
+
+None
+
+
 ### Dependents
 
 **recls.Ruby** is used in the **[libCLImate.Ruby](https://github.com/synesissoftware/libCLImate.Ruby)** library.

data/examples/find_files_and_directories.md

@@ -14,22 +14,22 @@ $:.unshift File.join(File.dirname(__FILE__), '..', 'lib')
 require 'recls'
 
 puts "files in current directory:"
-Recls.file_search(nil, nil, Recls::FILES).each { |fe| puts "\t#{fe.search_relative_path}" }
+Recls.search(nil, nil, Recls::FILES).each { |fe| puts "\t#{fe.search_relative_path}" }
 puts
 
 puts "directories in current directory:"
-Recls.file_search(nil, nil, Recls::DIRECTORIES).each { |fe| puts "\t#{fe.search_relative_path}" }
+Recls.search(nil, nil, Recls::DIRECTORIES).each { |fe| puts "\t#{fe.search_relative_path}" }
 puts
 
 puts "files and directories in current directory:"
-Recls.file_search(nil, nil, Recls::DIRECTORIES | Recls::FILES).each { |fe| puts "\t#{fe.search_relative_path}" }
+Recls.search(nil, nil, Recls::DIRECTORIES | Recls::FILES).each { |fe| puts "\t#{fe.search_relative_path}" }
 puts
 ```
 
 ## Discussion
 
 The code is pretty self-explanatory, in that there are three searches using
-the ```Recls.file_search()``` module method, passing FILES, DIRECTORIES, and
+the ```Recls.search()``` module method, passing FILES, DIRECTORIES, and
 FILES|DIRECTORIES, respectively. For each search, a simple block is
 presented, which takes a single-parameter of the file-entry (of type
 ``Recls::Entry``) from which the ``#search_relative_path`` instance

data/examples/find_files_and_directories.rb

@@ -5,15 +5,15 @@ $:.unshift File.join(File.dirname(__FILE__), '..', 'lib')
 require 'recls'
 
 puts "files in current directory:"
-Recls.file_search(nil, nil, Recls::FILES).each { |fe| puts "\t#{fe.search_relative_path}" }
+Recls.search(nil, nil, Recls::FILES).each { |fe| puts "\t#{fe.search_relative_path}" }
 puts
 
 puts "directories in current directory:"
-Recls.file_search(nil, nil, Recls::DIRECTORIES).each { |fe| puts "\t#{fe.search_relative_path}" }
+Recls.search(nil, nil, Recls::DIRECTORIES).each { |fe| puts "\t#{fe.search_relative_path}" }
 puts
 
 puts "files and directories in current directory:"
-Recls.file_search(nil, nil, Recls::DIRECTORIES | Recls::FILES).each { |fe| puts "\t#{fe.search_relative_path}" }
+Recls.search(nil, nil, Recls::DIRECTORIES | Recls::FILES).each { |fe| puts "\t#{fe.search_relative_path}" }
 puts
 
 

data/lib/recls/api.rb

@@ -4,7 +4,7 @@
 # Purpose:  Defines Recls module search functions
 #
 # Created:  9th June 2016
-# Updated:  20th April 2024
+# Updated:  21st April 2024
 #
 # Author:   Matthew Wilson
 #
@@ -44,34 +44,44 @@ require 'recls/flags'
 =begin
 =end
 
-# @!visibility private
-class Object; end # :nodoc:
-
 module Recls
 
-  # [DEPRECATED] Use +Recls::file_search()+
+  # (*DEPRECATED*) Use {Recls.search}
   def self.FileSearch(search_root, patterns, options = {})
 
-    Recls::FileSearch.new(search_root, patterns, options)
+    self.search(search_root, patterns, options)
   end
 
+  # (*DEPRECATED*) Use {Recls.rsearch}
+  def self.file_rsearch(search_root, patterns, options = {})
+
+    self.rsearch(search_root, patterns, options)
+  end
+
+  # (*DEPRECATED*) Use {Recls.search}
+  def self.file_search(search_root, patterns, options = {})
+
+    self.search(search_root, patterns, options)
+  end
+
+
   # Initialises a +FileSearch+ instance, which acts recursively, as an
-  # +Enumerable+ of +Recls::Entry+
+  # +Enumerable+ of {Recls::Entry}
   #
   # === Signature
   #
   # * *Parameters:*
-  #   - +search_root+ (+String+, +Recls::Entry+) The root directory of the search. May be +nil+, in which case the current directory is assumed;
-  #   - +patterns+ (+String+, +Array+) The pattern(s) for which to search. May be +nil+, in which case +Recls::WILDCARDS_ALL+ is assumed;
+  #   - +search_root+ (+String+, {Recls::Entry}) The root directory of the search. May be +nil+, in which case the current directory is assumed;
+  #   - +patterns+ (+String+, +Array+) The pattern(s) for which to search. May be +nil+, in which case {Recls::WILDCARDS_ALL} is assumed;
   #   - +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
-  # +Recls::Entry+.
-  def self.file_rsearch(search_root, patterns, options = {})
+  # {Recls::Entry}.
+  def self.rsearch(search_root, patterns, options = {})
 
     case options
     when ::NilClass
@@ -95,22 +105,22 @@ module Recls
   end
 
   # Initialises a +FileSearch+ instance, which acts as an +Enumerable+
-  # of +Recls::Entry+
+  # of {Recls::Entry}
   #
   # === Signature
   #
   # * *Parameters:*
-  #   - +search_root+ (+String+, +Recls::Entry+) The root directory of the search. May be +nil+, in which case the current directory is assumed;
-  #   - +patterns+ (+String+, +Array+) The pattern(s) for which to search. May be +nil+, in which case +Recls::WILDCARDS_ALL+ is assumed;
+  #   - +search_root+ (+String+, {Recls::Entry}) The root directory of the search. May be +nil+, in which case the current directory is assumed;
+  #   - +patterns+ (+String+, +Array+) The pattern(s) for which to search. May be +nil+, in which case {Recls::WILDCARDS_ALL} is assumed;
   #   - +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
-  # +Recls::Entry+.
-  def self.file_search(search_root, patterns, options = {})
+  # {Recls::Entry}.
+  def self.search(search_root, patterns, options = {})
 
     Recls::FileSearch.new(search_root, patterns, options)
   end

data/lib/recls/combine_paths_1.rb

@@ -4,7 +4,7 @@
 # Purpose:  Definition of Recls::compare_paths() for Ruby 1.x
 #
 # Created:  17th February 2014
-# Updated:  20th April 2024
+# Updated:  21st April 2024
 #
 # Author:   Matthew Wilson
 #
@@ -43,9 +43,6 @@ require 'recls/ximpl/util'
 =begin
 =end
 
-# @!visibility private
-class Object; end # :nodoc:
-
 module Recls
 
   # Combines paths
@@ -53,7 +50,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;
   #
   # === Return
   # (+String+) The combined path.

data/lib/recls/combine_paths_2plus.rb

@@ -4,7 +4,7 @@
 # Purpose:  Definition of Recls::compare_paths() for Ruby 2+
 #
 # Created:  17th February 2014
-# Updated:  20th April 2024
+# Updated:  21st April 2024
 #
 # Author:   Matthew Wilson
 #
@@ -43,9 +43,6 @@ require 'recls/ximpl/util'
 =begin
 =end
 
-# @!visibility private
-class Object; end # :nodoc:
-
 module Recls
 
   # Combines paths, optionally canonicalising them
@@ -53,7 +50,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:*

data/lib/recls/entry.rb

@@ -4,7 +4,7 @@
 # Purpose:  Defines the Recls::Entry class for the recls.Ruby library.
 #
 # Created:  24th July 2012
-# Updated:  20th April 2024
+# Updated:  21st April 2024
 #
 # Author:   Matthew Wilson
 #
@@ -46,9 +46,6 @@ require 'recls/flags'
 =begin
 =end
 
-# @!visibility private
-class Object; end # :nodoc:
-
 module Recls
 
   # A file-system entry
@@ -113,26 +110,24 @@ module Recls
     # ##########################
     # Name-related attributes
 
-    # (+String+) A normalised form of #path that can be used in comparisons
+    # (+String+) A normalised form of {.path} that can be used in comparisons
     attr_reader :compare_path
-
     # (+String+) The full-path of the instance
     attr_reader :path
-    # (+String+) The (Windows) short-form of #path, or +nil+ if not on Windows
+    # (+String+) The (Windows) short-form of {.path}, or +nil+ if not on Windows
     attr_reader :short_path
     # (+String+) The (Windows) drive. +nil+ if does not exist
     attr_reader :drive
-    # (+String+) The full path of the entry's directory (taking into account the
-    # #drive if on Windows)
+    # (+String+) The full path of the entry's directory (taking into account the {.drive} if on Windows)
     attr_reader :directory_path
     alias_method :dirname, :directory_path
-    # (+String+) The entry's directory (excluding the #drive if on Windows)
+    # (+String+) The entry's directory (excluding the {.drive} if on Windows)
     attr_reader :directory
-    # (+[ String ]+) An array of directory parts, where each part ends in Recls::PATH_NAME_SEPARATOR
+    # ( +[+ +String+ +]+ ) An array of directory parts, where each part ends in {Recls::PATH_NAME_SEPARATOR}
     attr_reader :directory_parts
-    # (+String+) The entry's file name (combination of #stem + #extension)
+    # (+String+) The entry's file name (combination of {.stem} + {.extension})
     attr_reader :file_full_name
-    # (+String+) The (Windows) short-form of #basename, or +nil+ if not on Windows
+    # (+String+) The (Windows) short-form of {.basename}, or +nil+ if not on Windows
     attr_reader :file_short_name
     alias_method :basename, :file_full_name
     # (+String+) The entry's file stem
@@ -143,13 +138,13 @@ module Recls
     alias_method :extension, :file_extension
     # (+String+) The search directory if specified; +nil+ otherwise
     attr_reader :search_directory
-    # (+String+) The #path relative to #search_directory; +nil+ if no search directory specified
+    # (+String+) The +#path+ relative to {.search_directory}; +nil+ if no search directory specified
     attr_reader :search_relative_path
-    # (+String+) The #directory relative to #search_directory; +nil+ if no search directory specified
+    # (+String+) The +#directory+ relative to {.search_directory}; +nil+ if no search directory specified
     attr_reader :search_relative_directory
-    # (+String+) The #directory_path relative to #search_directory; +nil+ if no search directory specified
+    # (+String+) The +#directory_path+ relative to {.search_directory}; +nil+ if no search directory specified
     attr_reader :search_relative_directory_path
-    # (+[ String ]+) The #directory_parts relative to #search_directory; +nil+ if no search directory specified
+    # ( +[+ +String+ +]+ ) The +#directory_parts+ relative to {.search_directory}; +nil+ if no search directory specified
     attr_reader :search_relative_directory_parts
 
     # ##########################
@@ -182,7 +177,7 @@ module Recls
 
   if Recls::Ximpl::OS::OS_IS_WINDOWS
 
-    # [WINDOWS-ONLY] Indicates whether the entry has the *system* bit
+    # (*WINDOWS-ONLY*) Indicates whether the entry has the *system* bit
     def system?
 
       return false if @file_stat.nil?
@@ -190,7 +185,7 @@ module Recls
       @file_stat.system?
     end
 
-    # [WINDOWS-ONLY] Indicates whether the entry has the *archive* bit
+    # (*WINDOWS-ONLY*) Indicates whether the entry has the *archive* bit
     def archive?
 
       return false if @file_stat.nil?
@@ -198,7 +193,7 @@ module Recls
       @file_stat.archive?
     end
 
-    # [WINDOWS-ONLY] Indicates whether the entry is a device
+    # (*WINDOWS-ONLY*) Indicates whether the entry is a device
     def device?
 
       return false if @file_stat.nil?
@@ -206,7 +201,7 @@ module Recls
       @file_stat.device?
     end
 
-    # [WINDOWS-ONLY] Indicates whether the entry is *normal*
+    # (*WINDOWS-ONLY*) Indicates whether the entry is *normal*
     def normal?
 
       return false if @file_stat.nil?
@@ -214,7 +209,7 @@ module Recls
       @file_stat.normal?
     end
 
-    # [WINDOWS-ONLY] Indicates whether the entry has the *temporary* bit
+    # (*WINDOWS-ONLY*) Indicates whether the entry has the *temporary* bit
     def temporary?
 
       return false if @file_stat.nil?
@@ -222,7 +217,7 @@ module Recls
       @file_stat.temporary?
     end
 
-    # [WINDOWS-ONLY] Indicates whether the entry has the *compressed* bit
+    # (*WINDOWS-ONLY*) Indicates whether the entry has the *compressed* bit
     def compressed?
 
       return false if @file_stat.nil?
@@ -230,7 +225,7 @@ module Recls
       @file_stat.compressed?
     end
 
-    # [WINDOWS-ONLY] Indicates whether the entry has the *encrypted* bit
+    # (*WINDOWS-ONLY*) Indicates whether the entry has the *encrypted* bit
     def encrypted?
 
       return false if @file_stat.nil?
@@ -289,8 +284,7 @@ module Recls
 
     # indicates the device of the given entry
     #
-    # On Windows, this will be 0 if the entry cannot be
-    # opened
+    # On Windows, this will be 0 if the entry cannot be opened
     def dev
 
       @dev
@@ -298,8 +292,7 @@ module Recls
 
     # indicates the ino of the given entry
     #
-    # On Windows, this will be 0 if the entry cannot be
-    # opened
+    # On Windows, this will be 0 if the entry cannot be opened
     def ino
 
       @ino
@@ -307,8 +300,7 @@ module Recls
 
     # number of links to the given entry
     #
-    # On Windows, this will be 0 if the entry cannot be
-    # opened
+    # On Windows, this will be 0 if the entry cannot be opened
     def nlink
 
       @nlink
@@ -336,8 +328,8 @@ module Recls
     # ##########################
     # Comparison
 
-    # determines whether rhs is an instance of Entry and
-    # refers to the same path
+    # determines whether rhs is an instance of {Recls::Entry} and refers to
+    # the same path
     def eql?(rhs)
 
       case rhs
@@ -381,15 +373,13 @@ module Recls
     # ##########################
     # Conversion
 
-    # represents the entry as a string (in the form of
-    # the full path)
+    # represents the entry as a string (in the form of the full path)
     def to_s
 
       path
     end
 
-    # represents the entry as a string (in the form of
-    # the full path)
+    # represents the entry as a string (in the form of the full path)
     def to_str
 
       path

data/lib/recls/file_search.rb

@@ -4,7 +4,7 @@
 # Purpose:  Defines the Recls::FileSearch class for the recls.Ruby library.
 #
 # Created:  24th July 2012
-# Updated:  20th April 2024
+# Updated:  21st April 2024
 #
 # Author:   Matthew Wilson
 #
@@ -45,27 +45,25 @@ require 'recls/ximpl/os'
 =begin
 =end
 
-# @!visibility private
-class Object; end # :nodoc:
-
 module Recls
 
+  # @!visibility private
   class FileSearch # :nodoc: all
 
     include Enumerable
 
     # Initialises a +FileSearch+ instance, which acts as an +Enumerable+
-    # of +Recls::Entry+
+    # of {Recls::Entry}
     #
     # === Signature
     #
     # * *Parameters:*
-    #   - +search_root+ (+String+, +Recls::Entry+) The root directory of the search. May be +nil+, in which case the current directory is assumed;
-    #   - +patterns+ (+String+, +Array+) The pattern(s) for which to search. May be +nil+, in which case +Recls::WILDCARDS_ALL+ is assumed;
+    #   - +search_root+ (+String+, {Recls::Entry}) The root directory of the search. May be +nil+, in which case the current directory is assumed;
+    #   - +patterns+ (+String+, +Array+) The pattern(s) for which to search. May be +nil+, in which case {Recls::WILDCARDS_ALL} is assumed;
     #   - +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 the class.
@@ -140,7 +138,7 @@ module Recls
     attr_reader :flags
 
     # Calls the block once for each found file, passing a single
-    # parameter that is a Recls::Entry instance
+    # parameter that is a {Recls::Entry} instance
     #
     # @!visibility private
     def each(&blk) # :nodoc:

data/lib/recls/flags.rb

@@ -4,7 +4,7 @@
 # Purpose:  Defines the Recls::Flags module for the recls.Ruby library.
 #
 # Created:  24th July 2012
-# Updated:  20th April 2024
+# Updated:  21st April 2024
 #
 # Author:   Matthew Wilson
 #
@@ -40,9 +40,6 @@
 =begin
 =end
 
-# @!visibility private
-class Object; end # :nodoc:
-
 module Recls
 
   # Specifies that files are to be listed
@@ -53,21 +50,20 @@ module Recls
   LINKS                   = 0x00000004
   # Specifies that devices are to be listed
   DEVICES                 = 0x00000008
-  # Type mask (combination of +Recls::FILES+, +Recls::DIRECTORIES+, +Recls::LINKS+, +Recls::DEVICES+)
+  # Type mask (combination of {Recls::FILES}, {Recls::DIRECTORIES}, {Recls::LINKS}, {Recls::DEVICES})
   TYPEMASK                = 0x000000ff
 
   # Specifies that hidden items are to be shown and hidden directories are
   # to be searched
   SHOW_HIDDEN             = 0x00000100
 
-  # [IGNORED] This for compatibility with *recls* libraries written in other languages
+  # (*IGNORED*) This for compatibility with *recls* libraries written in other languages
   DIR_PROGRESS            = 0x00001000
-  # Causes search to terminate if a directory cannot be entered or an
-  # entry's information cannot be +stat()+'d
+  # Causes search to terminate if a directory cannot be entered or an entry's file-system information cannot be obtained from the operating system
   STOP_ON_ACCESS_FAILURE  = 0x00002000
-  # [IGNORED] This for compatibility with *recls* libraries written in other languages
+  # (*IGNORED*) This for compatibility with *recls* libraries written in other languages
   LINK_COUNT              = 0000004000
-  # [IGNORED] This for compatibility with *recls* libraries written in other languages
+  # (*IGNORED*) This for compatibility with *recls* libraries written in other languages
   NODE_INDEX              = 0x00008000
 
   # Causes search to operate recursively
@@ -76,13 +72,13 @@ private
   # @!visibility private
   NO_SEARCH_LINKS         = 0x00020000 # :nodoc:
 public
-  # [IGNORED] In previous versions the Recls::Entry#directory_parts property was not obtained (for performance reasons) unless this flag was specified. In current version the parts are always obtained
+  # (*IGNORED*) In previous versions the {Recls::Entry.directory_parts} property was not obtained (for performance reasons) unless this flag was specified. In current version the parts are always obtained
   DIRECTORY_PARTS         = 0x00040000
-  # Causes operations (such as +Recls::stat()+) to obtain a result even when
+  # Causes operations (such as {Recls.stat}) to obtain a result even when
   # no corresponding file-system entity does not exist
   DETAILS_LATER           = 0x00080000
 
-  # Causes the +Recls::Entry#path+ and +Recls::Entry#search_relative_path+
+  # Causes the {Recls::Entry.path} and {Recls::Entry.search_relative_path}
   # attributes to contain a trailing path-name-separator for directory
   # entries
   MARK_DIRECTORIES        = 0x00200000

data/lib/recls/foreach.rb

@@ -4,7 +4,7 @@
 # Purpose:  Definition of Recls::foreach() utility function
 #
 # Created:  22nd October 2014
-# Updated:  20th April 2024
+# Updated:  21st April 2024
 #
 # Author:   Matthew Wilson
 #
@@ -43,9 +43,6 @@ require 'recls/file_search'
 =begin
 =end
 
-# @!visibility private
-class Object; end # :nodoc:
-
 module Recls
 
   private
@@ -87,22 +84,22 @@ module Recls
   end # class FileSearchLineEnumerator
   public
 
-  # Performs a recursive search and enumerates the lines of all files
-  # found
+  # Performs an optionally-recursive search and enumerates the lines of all
+  # files found
   #
   # === Signature
   #
   # * *Parameters:*
-  #   - +searchable+ A searchable instance obtained from +Recls::file_search()+ or +Recls::file_rsearch()+;
-  #   - +search_root+ (+String+, +Recls::Entry+) The root directory of the search. May be +nil+, in which case the current directory is assumed;
-  #   - +patterns+ (+String+, +Array+) The pattern(s) for which to search. May be +nil+, in which case +Recls::WILDCARDS_ALL+ is assumed;
+  #   - +searchable+ A searchable instance obtained from {Recls::search} or {Recls::rsearch};
+  #   - +search_root+ (+String+, {Recls::Entry}) The root directory of the search. May be +nil+, in which case the current directory is assumed;
+  #   - +patterns+ (+String+, +Array+) The pattern(s) for which to search. May be +nil+, in which case {Recls::WILDCARDS_ALL} is assumed;
   #   - +options+ (+Hash+) An options hash;
   #   - +flags+ (+Integer+) Combination of flags (with behaviour as described below for the +flags+ option);
   #
   # * *Block:*
   # An optional block that will be executed once for each line in each file
   # found, where the block must take 1, 2, or 3 parameters, representing the
-  # line [ + file-line-index [ + entry ]]. If no block is given, an
+  # +line+ [, +file_line_index+ [, +entry+ ]]. If no block is given, an
   # enumerator is returned.
   #
   # ==== Parameter Ordering

data/lib/recls/obsolete.rb

@@ -4,7 +4,7 @@
 # Purpose:  Obsolete elements
 #
 # Created:  19th July 2012
-# Updated:  20th April 2024
+# Updated:  21st April 2024
 #
 # Author:   Matthew Wilson
 #
@@ -43,10 +43,7 @@
 
 if not defined? RECLS_NO_OBSOLETE
 
-  # :stopdoc:
-
-  # @!visibility private
-  module Recls # :nodoc: all
+  module Recls
 
     # @!visibility private
     def self.pathNameSeparator
@@ -116,8 +113,6 @@ if not defined? RECLS_NO_OBSOLETE
       alias_method :creationTime, :modification_time
     end
   end # module Recls
-
-  # :startdoc:
 end
 
 

data/lib/recls/recls.rb

@@ -4,7 +4,7 @@
 # Purpose:  Main source file for recls library
 #
 # Created:  19th July 2012
-# Updated:  20th April 2024
+# Updated:  21st April 2024
 #
 # Author:   Matthew Wilson
 #
@@ -37,21 +37,22 @@
 # ######################################################################## #
 
 
-# The *recls* module
+# The main *recls* module
 #
-# == Significant Components
-# - Recls::Entry
-# - Recls::absolute_path
-# - Recls::absolute_path?
-# - Recls::canonicalise_path
-# - Recls::derive_relative_path
-# - Recls::directory?
-# - Recls::exist?
-# - Recls::file?
-# - Recls::file_rsearch
-# - Recls::file_search
-# - Recls::foreach
-# - Recls::stat
+# === Significant Components
+# - {Recls::Entry} - a file-system entry
+# - {Recls.absolute_path} - converts a path to absolute;
+# - {Recls.absolute_path?} - determines whether a path is absolute;
+# - {Recls.canonicalise_path} - canonicalises a path;
+# - {Recls.combine_paths} - combines a number of path elements;
+# - {Recls.derive_relative_path} - derives a relative path, with respect to a given origin;
+# - {Recls.directory?} - obtains an {Recls::Entry} for the path if it exists and is a directory, or +nil+ otherwise;
+# - {Recls.exist?} - obtains an {Recls::Entry} for the path if it exists, or +nil+ otherwise;
+# - {Recls.file?} - obtains an {Recls::Entry} for the path if it exists and is a file, or +nil+ otherwise;
+# - {Recls.foreach} - performs an optionally-recursive search and enumerates the lines of all files found
+# - {Recls.rsearch} - conducts a recursive search under a given search-directory for entries matching given pattern(s);
+# - {Recls.search} - conducts a non-recursive search under a given search-directory for entries matching given pattern(s);
+# - {Recls.stat} - attempts to obtain an {Recls::Entry} for the given path, or +nil+ if it fails to do so;
 module Recls
 end # module Recls
 

data/lib/recls/stat.rb

@@ -4,7 +4,7 @@
 # Purpose:  Defines the Recls.stat() method for the recls.Ruby library.
 #
 # Created:  24th July 2012
-# Updated:  20th April 2024
+# Updated:  21st April 2024
 #
 # Author:   Matthew Wilson
 #
@@ -44,25 +44,22 @@ require 'recls/flags'
 =begin
 =end
 
-# @!visibility private
-class Object; end # :nodoc:
-
 module Recls
 
-  # Equivalent to a Recls::stat() but only returns (a non-+nil+ value) if the
+  # Equivalent to {Recls.stat} but only returns (a non-+nil+ value) if the
   # path exists _and_ represents a directory
   #
   # This has two advantages over +File.directory?+: it obtains a
-  # Recls::Entry in the case where the path represents a directory; and
-  # it does '~' interpretation
+  # {Recls::Entry} in the case where the path represents a directory; and
+  # it does +'~'+ interpretation
   #
   # === Signature
   #
   # * *Parameters:*
-  #   - +path+ (+String+, +Recls::Entry+) The path;
+  #   - +path+ (+String+, {Recls::Entry}) The path;
   #
   # === Return
-  # (+Recls::Entry+, +nil+) The entry if +path+ exists and is a directory; +nil+ otherwise.
+  # ({Recls::Entry}, +nil+) The entry if +path+ exists and is a directory; +nil+ otherwise.
   def self.directory?(path, *args)
 
     fe = self.stat(path, *args)
@@ -75,20 +72,20 @@ module Recls
     fe
   end
 
-  # Equivalent to a Recls::stat() but only returns (a non-+nil+ value) if the
+  # Equivalent to {Recls.stat} but only returns (a non-+nil+ value) if the
   # path exists _and_ represents a file
   #
   # This has two advantages over +File.file?+: it obtains a
-  # Recls::Entry in the case where the path represents a file; and
-  # it does '~' interpretation
+  # {Recls::Entry} in the case where the path represents a file; and
+  # it does +'~'+ interpretation
   #
   # === Signature
   #
   # * *Parameters:*
-  #   - +path+ (+String+, +Recls::Entry+) The path;
+  #   - +path+ (+String+, {Recls::Entry}) The path;
   #
   # === Return
-  # (+Recls::Entry+, +nil+) The entry if +path+ exists and is a file; +nil+ otherwise.
+  # ({Recls::Entry}, +nil+) The entry if +path+ exists and is a file; +nil+ otherwise.
   def self.file?(path, *args)
 
     fe = self.stat(path, *args)
@@ -101,7 +98,7 @@ module Recls
     fe
   end
 
-  # Obtains a single Recls::Entry instance from a path, according to the
+  # Obtains a single {Recls::Entry} instance from a path, according to the
   # given arguments, which can be any combination of search-root and
   # flags, as discussed below
   #
@@ -109,8 +106,8 @@ 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;
-  #   - +flags+ (+Integer+) A bit-combined set of flags (such as +Recls::DIRECTORIES+, +Recls::FILES+, +Recls::RECURSIVE+, +Recls::DETAILS_LATER+, and so on);
+  #   - +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
   #
@@ -122,9 +119,9 @@ module Recls
   # - +path+, +search_root+, +flags+
   #
   # === Return
-  # (+Recls::Entry+) An entry representing the path on the file-system, or
+  # ({Recls::Entry}) An entry representing the path on the file-system, or
   # +nil+ if the path does not refer to an existing entity. If the
-  # +Recls::DETAILS_LATER+ flag is included, then an entry is returned
+  # {Recls::DETAILS_LATER} flag is included, then an entry is returned
   # regardless of its existence.
   def self.stat(path, *args)
 

data/lib/recls/util.rb

@@ -4,7 +4,7 @@
 # Purpose:  Utility module functions for recls library
 #
 # Created:  17th February 2014
-# Updated:  20th April 2024
+# Updated:  21st April 2024
 #
 # Author:   Matthew Wilson
 #
@@ -45,9 +45,6 @@ require 'recls/ximpl/os'
 =begin
 =end
 
-# @!visibility private
-class Object; end # :nodoc:
-
 module Recls
 
   # Obtains the absolute form of the given path
@@ -55,7 +52,7 @@ module Recls
   # === Signature
   #
   # * *Parameters:*
-  #   - +path+ (+String+, +Recls::Entry+) The path;
+  #   - +path+ (+String+, {Recls::Entry}) The path;
   #
   # === Return
   # (+String+) The absolute form of the path.
@@ -64,13 +61,13 @@ module Recls
     Recls::Ximpl.absolute_path path
   end
 
-  # Canonicalises the given path, by removing dots ('.' and '..')
-  # directories
+  # Canonicalises the given path, by removing dots directories,
+  # i.e. +'.'+ and +'..'+
   #
   # === Signature
   #
   # * *Parameters:*
-  #   - +path+ (+String+, +Recls::Entry+) The path;
+  #   - +path+ (+String+, {Recls::Entry}) The path;
   #
   # === Return
   # (+String+) The canonical form of the path.
@@ -87,8 +84,8 @@ module Recls
   # === Signature
   #
   # * *Parameters:*
-  #   - +origin+ (+String+, +Recls::Entry+) The path against which +path+ will be evaluated;
-  #   - +path+ (+String+, +Recls::Entry+) The path to evaluate;
+  #   - +origin+ (+String+, {Recls::Entry}) The path against which +path+ will be evaluated;
+  #   - +path+ (+String+, {Recls::Entry}) The path to evaluate;
   #
   # === Return
   # (+String+) The relative form of the path.
@@ -108,16 +105,16 @@ end
 
 module Recls
 
-  # Indicates whether the given path exists, obtaining a Recls::Entry
+  # Indicates whether the given path exists, obtaining a {Recls::Entry}
   # instance if so
   #
   # === Signature
   #
   # * *Parameters:*
-  #   - +path+ (+String+, +Recls::Entry+) The path;
+  #   - +path+ (+String+, {Recls::Entry}) The path;
   #
   # === Return
-  # (+Recls::Entry+, +nil+) The entry if +path+ exists; +nil+ otherwise.
+  # ({Recls::Entry}, +nil+) The entry if +path+ exists; +nil+ otherwise.
   def self.exist?(path)
 
     return nil if path.nil?
@@ -130,7 +127,7 @@ module Recls
   # === Signature
   #
   # * *Parameters:*
-  #   - +path+ (+String+, +Recls::Entry+, +nil+) The path to be evaluated;
+  #   - +path+ (+String+, {Recls::Entry}, +nil+) The path to be evaluated;
   #
   # === Return
   # (boolean) +true+ if +path+ is absolute; +false+ otherwise.

data/lib/recls/version.rb

@@ -4,7 +4,7 @@
 # Purpose:  Version for recls library
 #
 # Created:  14th February 2014
-# Updated:  20th April 2024
+# Updated:  21st April 2024
 #
 # Author:   Matthew Wilson
 #
@@ -40,13 +40,10 @@
 =begin
 =end
 
-# @!visibility private
-class Object; end # :nodoc:
-
 module Recls
 
   # Current version of the recls.Ruby library
-  VERSION           = '2.13.0'
+  VERSION           = '2.13.0.1'
 
   private
   # @!visibility private

data/lib/recls/ximpl/os.rb

@@ -5,7 +5,7 @@
 #           recls library.
 #
 # Created:  16th February 2014
-# Updated:  20th April 2024
+# Updated:  21st April 2024
 #
 # Author:   Matthew Wilson
 #
@@ -41,14 +41,12 @@
 =begin
 =end
 
-# :stopdoc:
-
-# @!visibility private
-module Recls # :nodoc:
+module Recls
 
   # @!visibility private
   module Ximpl # :nodoc: all
 
+    # @!visibility private
     module OS # :nodoc: all
 
       # @!visibility private
@@ -95,7 +93,6 @@ module Recls # :nodoc:
   end # module Ximpl
 end # module Recls
 
-# :startdoc:
 
 # ############################## end of file ############################# #
 

data/lib/recls/ximpl/unix.rb

@@ -4,7 +4,7 @@
 # Purpose:  UNIX-specific constructs for the recls library.
 #
 # Created:  19th February 2014
-# Updated:  20th April 2024
+# Updated:  21st April 2024
 #
 # Author:   Matthew Wilson
 #
@@ -43,9 +43,7 @@ require 'recls/ximpl/util'
 =begin
 =end
 
-# :stopdoc:
-
-module Recls # :nodoc:
+module Recls
 
   # @!visibility private
   module Ximpl # :nodoc: all
@@ -54,8 +52,7 @@ module Recls # :nodoc:
     class FileStat < File::Stat # :nodoc:
 
       private
-      # @!visibility private
-      def initialize(path) # :nodoc:
+      def initialize(path)
 
         @path = path
 
@@ -63,11 +60,9 @@ module Recls # :nodoc:
       end
 
       public
-      # @!visibility private
-      attr_reader :path # :nodoc:
+      attr_reader :path
 
-      # @!visibility private
-      def hidden? # :nodoc:
+      def hidden?
 
         basename = File.basename @path
 
@@ -80,18 +75,14 @@ module Recls # :nodoc:
       end
 
       public
-      # @!visibility private
-      def FileStat.stat(path) # :nodoc:
+      def FileStat.stat(path)
 
         Recls::Ximpl::FileStat.new(path)
-
       end
     end # class FileStat
   end # module Ximpl
 end # module Recls
 
-# :startdoc:
-
 
 # ############################## end of file ############################# #
 

data/lib/recls/ximpl/util.rb

@@ -4,7 +4,7 @@
 # Purpose:  Internal implementation constructs for the recls library.
 #
 # Created:  24th July 2012
-# Updated:  20th April 2024
+# Updated:  21st April 2024
 #
 # Author:   Matthew Wilson
 #
@@ -46,13 +46,12 @@ require 'pathname'
 =begin
 =end
 
-# :stopdoc:
-
-module Recls # :nodoc:
+module Recls
 
   # @!visibility private
   module Ximpl # :nodoc: all
 
+    # @!visibility private
     module Util # :nodoc: all
 
       # @!visibility private
@@ -832,8 +831,7 @@ module Recls # :nodoc:
     #
     # Some known conditions:
     #
-    # * (Mac OSX) /dev/fd/<N> - some of these stat() as directories but
-    #    Dir.new fails with ENOTDIR
+    # * (Mac OSX) /dev/fd/<N> - some of these +stat()+ as directories but +Dir.new+ fails with +ENOTDIR+;
     #
     # @!visibility private
     def self.dir_entries_maybe(dir, flags) # :nodoc:
@@ -877,8 +875,6 @@ module Recls # :nodoc:
   end # module Ximpl
 end # module Recls
 
-# :startdoc:
-
 
 # ############################## end of file ############################# #
 

data/lib/recls/ximpl/windows.rb

@@ -4,7 +4,7 @@
 # Purpose:  Windows-specific constructs for the recls library.
 #
 # Created:  19th February 2014
-# Updated:  20th April 2024
+# Updated:  21st April 2024
 #
 # Author:   Matthew Wilson
 #
@@ -43,9 +43,7 @@ require 'Win32API'
 =begin
 =end
 
-# :stopdoc:
-
-module Recls # :nodoc:
+module Recls
 
   # @!visibility private
   module Ximpl # :nodoc: all
@@ -225,8 +223,6 @@ module Recls # :nodoc:
   end # module Ximpl
 end # module Recls
 
-# :startdoc:
-
 
 # ############################## end of file ############################# #
 

data/test/scratch/test_foreach.rb

@@ -17,7 +17,6 @@ Recls.foreach(Recls::FileSearch.new(nil, '*.rb', Recls::RECURSIVE)).each do |lin
   puts "#{fe.search_relative_path}(#{line_number + 1}): #{line}"
 
   count_1 += 1
-  break if 20 == count_1
 end
 
 puts
@@ -32,7 +31,6 @@ e.each do |line, line_number, fe|
   puts "#{fe.search_relative_path}(#{line_number + 1}): #{line}"
 
   count_2 += 1
-  break if 20 == count_2
 end
 
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: recls-ruby
 version: !ruby/object:Gem::Version
-  version: 2.13.0
+  version: 2.13.0.1
 platform: ruby
 authors:
 - Matt Wilson
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-04-20 00:00:00.000000000 Z
+date: 2024-04-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: xqsr3