recls-ruby 2.12.0 → 2.12.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: adf1c9d879c34d01328e9426fb4232a9ca54bdcbbf97b95fa4bf08a91281b1fe
-  data.tar.gz: 7447488d2bdb53b2df2b7d387ff82a4091220a0553cb001a868a86321dfd49aa
+  metadata.gz: b7ad41cfec6d08d5ba41ef9c6bc47f5b151d61a232f9f7a04ce389ca49487f51
+  data.tar.gz: 9cb9cff1104388001437470dbd6cb82566313f78d82b0a5b323689573f57f5d9
 SHA512:
-  metadata.gz: 33695196ec35f93cbfd5937d6997a461bb1485e2ad4ef5b8728ad002fd30048d4dd804ba13217f9a60e78df986708edb3db66e17b087d6d023e7923f71aa350f
-  data.tar.gz: 471f1adcba4b1c8171ab2781dc4c57f7fac86b59954dc82292d545fb5ae2e4f2123d568a18fbb2f56559a7028fe40740a8288f4f5c49a1c1fe802c654a9304b6
+  metadata.gz: 5c61cd03d38a8d459d9bbfc3f150e0fed22182abef92da86dd135040690088f070d69f55cfa3ccf4312f7d1b122d921eb72b48e2137fa8801e1360d29aec4dfe
+  data.tar.gz: fb1603cbf0f8ffd86c1c679ac08f0d5bf5c770d8d4348a24b74bab1e5440b28f6f35a7e8ef4368252eaf9ab0d5f081935814ebd48ade0c26939340a964b748e0

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 ########################### -->
+