recls-ruby 2.11.0 → 2.11.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: a1b0ed5f508ef5e3a29ac1f5de51d5d6cee84ba1
-  data.tar.gz: 0deb1a1f4551f35cc8c25acba091e30eaa630109
+SHA256:
+  metadata.gz: 90f7c6438297fa98748b7667ba1076e5dcde179335b787292fbeaea7f6bd6230
+  data.tar.gz: 94e38bcc8b65a233fddd5343907d53c6c529c28757a74c5060d4b7368ebb11ef
 SHA512:
-  metadata.gz: 6852f4c312ef0dc49c6d8027df2655217cfe1587ea2cf95b8030f5986b2e1ecfbc84c6a325c565718fffc8161231d3415a3a1c292dfae2744fd986a89fe546e5
-  data.tar.gz: 9cba60e7075ffb6d3da1ceefc597c54953e23f8fe41d4d5cea4a20840dd9b037c60471d3ddbbf188d9045018cfede80a7d88fd56ba758814814abfae0e26cc1e
+  metadata.gz: 2045617c1731af3391ae762f49874bbae4c700c5ce29b8e80e1f819c68f073d52a4848dd9175a306fa79529e2197beab8af700cd09e5bc581b62776c620de276
+  data.tar.gz: 96fee22ef3cd615e1d0af3c06902188a727951d1f8bcf18d2072cac341ad97941104721558690fec489bdcc9b18f3efdc8e1818252f7e4dc53966d9599447673

data/LICENSE

@@ -1,31 +1,34 @@
-recls.Ruby
+recls.Ruby - BSD 3-Clause License
+
+Copyright (c) 2019-2024, Matthew Wilson and Synesis Information Systems
+Copyright (c) 2003-2019, Matthew Wilson and Synesis Software
 
-Copyright (c) 2003-2016, Matthew Wilson and Synesis Software
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions are met:
 
-* Redistributions of source code must retain the above copyright notice, this
-  list of conditions and the following disclaimer.
-
-* Redistributions in binary form must reproduce the above copyright notice,
-  this list of conditions and the following disclaimer in the documentation
-  and/or other materials provided with the distribution.
-
-* Neither the names of recls or recls.Ruby nor the names of the copyright
-  holder nor the names of its contributors may be used to endorse or promote
-  products derived from this software without specific prior written
-  permission.
-
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
-ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
-WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
-DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
-FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
-DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
-SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
-CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
-OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+1. Redistributions of source code must retain the above copyright notice,
+   this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the names of recls, recls-Ruby,
+   recls.Ruby, nor the name of the copyright holder nor the names of
+   its contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.
 

data/README.md

@@ -1,14 +1,17 @@
 # recls.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
 library with a C++ wrapper. There have been several implementations in other
 languages. **recls.Ruby** is the Ruby version.
 
+
 ## Table of Contents
 
 1. [Introduction](#introduction)
@@ -17,14 +20,17 @@ languages. **recls.Ruby** is the Ruby version.
 4. [Examples](#examples)
 5. [Project Information](#project-information)
 
+
 ## Introduction
 
 T.B.C.
 
+
 ## Installation & usage
 
 Install using `gem install recls-ruby` or add it to your `Gemfile`.
 
+
 ## Components
 
 The main components of **recls.Ruby** are:
@@ -32,36 +38,267 @@ The main components of **recls.Ruby** are:
 * the ``Recls`` module; and
 * the ``Recls::Entry`` class
 
+
 ### The ``Recls`` module
 
 T.B.C.
 
+
 ### The ``Recls::Entry`` class
 
-T.B.C.
+This class represents a file-system entry, and is created either by the `Recls.stat()` method, or is returned from the searches (see above). It has the following (simplified) interface:
+
+```Ruby
+module Recls
+
+  # A file-system entry
+  class Entry
+
+    # ##########################
+    # Name-related attributes
+
+    # (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
+    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)
+    attr_reader :directory_path
+    alias_method :dirname, :directory_path
+    # (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
+    attr_reader :directory_parts
+    # (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
+    attr_reader :file_short_name
+    alias_method :basename, :file_full_name
+    # (String) The entry's file stem
+    attr_reader :file_name_only
+    alias_method :stem, :file_name_only
+    # (String) The entry's file extension
+    attr_reader :file_extension
+    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
+    attr_reader :search_relative_path
+    # (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
+    attr_reader :search_relative_directory_path
+    # ([String]) The #directory_parts relative to #search_directory; +nil+ if no search directory specified
+    attr_reader :search_relative_directory_parts
+
+    # ##########################
+    # Nature attributes
+
+    # indicates whether the given entry existed at the time the entry
+    # instance was created
+    def exist?
+      . . .
+    end
+
+    # indicates whether the given entry is hidden
+    def hidden?
+      . . .
+    end
+
+    # indicates whether the given entry is readonly
+    def readonly?
+      . . .
+    end
+
+  if Recls::Ximpl::OS::OS_IS_WINDOWS
+
+    # [WINDOWS-ONLY] Indicates whether the entry has the *system* bit
+    def system?
+      . . .
+    end
+
+    # [WINDOWS-ONLY] Indicates whether the entry has the *archive* bit
+    def archive?
+      . . .
+    end
+
+    # [WINDOWS-ONLY] Indicates whether the entry is a device
+    def device?
+      . . .
+    end
+
+    # [WINDOWS-ONLY] Indicates whether the entry is *normal*
+    def normal?
+      . . .
+    end
+
+    # [WINDOWS-ONLY] Indicates whether the entry has the *temporary* bit
+    def temporary?
+      . . .
+    end
+
+    # [WINDOWS-ONLY] Indicates whether the entry has the *compressed* bit
+    def compressed?
+      . . .
+    end
+
+    # [WINDOWS-ONLY] Indicates whether the entry has the *encrypted* bit
+    def encrypted?
+      . . .
+    end
+  end
+
+    # indicates whether the given entry represents a directory
+    def directory?
+      . . .
+    end
+
+    alias_method :dir?, :directory?
+
+    # indicates whether the given entry represents a file
+    def file?
+      . . .
+    end
+
+    # indicates whether the given entry represents a link
+    def link?
+      . . .
+    end
+
+    # indicates whether the given entry represents a socket
+    def socket?
+      . . .
+    end
+
+    # ##########################
+    # Size attributes
+
+    # indicates the size of the given entry
+    def size
+      . . .
+    end
+
+    # ##########################
+    # File-system entry attributes
+
+    # indicates the device of the given entry
+    #
+    # 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
+    def ino
+      . . .
+    end
+
+    # number of links to the given entry
+    #
+    # On Windows, this will be 0 if the entry cannot be
+    # opened
+    def nlink
+      . . .
+    end
+
+    # ##########################
+    # Time attributes
+
+    # indicates the last access time of the entry
+    def last_access_time
+      . . .
+    end
+
+    # indicates the modification time of the entry
+    def modification_time
+      . . .
+    end
+
+    # ##########################
+    # Comparison
+
+    # determines whether rhs is an instance of Entry and
+    # refers to the same path
+    def eql?(rhs)
+      . . .
+    end
+
+    # determines whether rhs refers to the same path
+    def ==(rhs)
+      . . .
+    end
+
+    # compares this instance with rhs
+    def <=>(rhs)
+      . . .
+    end
+
+    # the hash
+    def hash
+      . . .
+    end
+
+    # ##########################
+    # Conversion
+
+    # 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)
+    def to_str
+      . . .
+    end
+  end # class Entry
+end # module Recls
+
+
+# ############################## end of file ############################# #
+
+
+```
+
 
 ## Examples
 
 Examples are provided in the ```examples``` directory, along with a markdown description for each. A detailed list TOC of them is provided in [EXAMPLES.md](./EXAMPLES.md).
 
+
 ## Project Information
 
+
 ### Where to get help
 
 [GitHub Page](https://github.com/synesissoftware/recls.Ruby "GitHub Page")
 
+
 ### Contribution guidelines
 
 Defect reports, feature requests, and pull requests are welcome on https://github.com/synesissoftware/recls.Ruby.
 
+
 ### Dependencies
 
 None
 
+
 ### Dependents
 
 **recls.Ruby** is used in the **[libCLImate.Ruby](https://github.com/synesissoftware/libCLImate.Ruby)** library.
 
+
 ### Related projects
 
 * [**recls**](https://github.com/synesissoftware/recls/)
@@ -69,13 +306,17 @@ None
 * [**recls.NET**](https://github.com/synesissoftware/recls.NET/)
 * [**recls.Python**](https://github.com/synesissoftware/recls.Python/)
 
+
 ### License
 
 **recls.Ruby** is released under the 3-clause BSD license. See [LICENSE](./LICENSE) for details.
 
+
 ### Compatibility
 
 For v2.8.x onwards, recls.Ruby is compatible only with Ruby 2.0+; all other
 past and current versions work with Ruby 1.9.3+.
 
 
+<!-- ########################### end of file ########################### -->
+

data/examples/find_files_and_directories.md

@@ -39,39 +39,42 @@ attribute is used to display the relative path.
 
 ```
 files in current directory:
-	build_gem.cmd
-	build_gem.sh
-	CHANGES.md
-	EXAMPLES.md
-	generate_rdoc.sh
-	LICENSE
-	Rakefile
-	README.md
-	recls.gemspec
-	run_all_unit_tests.sh
+  build_gem.cmd
+  build_gem.sh
+  CHANGES.md
+  EXAMPLES.md
+  generate_rdoc.sh
+  LICENSE
+  Rakefile
+  README.md
+  recls.gemspec
+  run_all_unit_tests.sh
 
 directories in current directory:
-	doc
-	examples
-	lib
-	old-gems
-	test
+  doc
+  examples
+  lib
+  old-gems
+  test
 
 files and directories in current directory:
-	build_gem.cmd
-	build_gem.sh
-	CHANGES.md
-	doc
-	examples
-	EXAMPLES.md
-	generate_rdoc.sh
-	lib
-	LICENSE
-	old-gems
-	Rakefile
-	README.md
-	recls.gemspec
-	run_all_unit_tests.sh
-	test
+  build_gem.cmd
+  build_gem.sh
+  CHANGES.md
+  doc
+  examples
+  EXAMPLES.md
+  generate_rdoc.sh
+  lib
+  LICENSE
+  old-gems
+  Rakefile
+  README.md
+  recls.gemspec
+  run_all_unit_tests.sh
+  test
 ```
 
+
+<!-- ########################### end of file ########################### -->
+