recls-ruby 2.9.1 → 2.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 633b42f5042eb49162aafc0a68e7d48cf47e1919
-  data.tar.gz: 9ac21ed45d384c67863c7b4fad0d782dfec077b4
+SHA256:
+  metadata.gz: 606018fcccb7395be01a33399eb15feb0e4b5a6cbda0845469c5f7088347ee1b
+  data.tar.gz: f33b673b8bf6d01ecee1a9ae626bd5e959a9da422541cc5b5deff1741c4f5cd7
 SHA512:
-  metadata.gz: 5f204a82f58c74d870696c52f9f6f6b4d4a3c89a57bdb1cef6f4d6c74c017d21f78504ac67466d3b3fe068bf01c0efadbbb21d453a1bb596c4cdccc3389076c7
-  data.tar.gz: 4c83a6e6ecbd1c791f035a8e5f98faddf662584a21ad69d3ecc64a5e18ea255093e79f171138cdf9d7d2634df089fadab5488457cda258a0d753eab38bbda27c
+  metadata.gz: 2601f4ce4f5b55a21b0d90b4c11d5a9eea22624d826821b82061f015b34ad05b2950d3a77534ee98ca9512c5d541936a759348010327bac57eeb7ca2a7d0f601
+  data.tar.gz: bc608e22ab8de3cc2aa7048e55a283402061262053603d229b9c5b3256ac6a09cffff08a06024ad1d1b794995811ca69730c3761f6ab855372abcfdbcfd65e61

data/lib/recls/api.rb

@@ -4,7 +4,7 @@
 # Purpose:      Defines Recls module search functions
 #
 # Created:      9th June 2016
-# Updated:      21st March 2019
+# Updated:      14th April 2019
 #
 # Author:       Matthew Wilson
 #
@@ -39,11 +39,14 @@
 require 'recls/file_search'
 require 'recls/flags'
 
+=begin
+=end
+
+class Object; end # :nodoc:
+
 module Recls
 
-	# [DEPRECATED] Use +Recls.file_search()+
-	#
-	# @deprecated
+	# [DEPRECATED] Use Recls::file_search()
 	def self.FileSearch(search_root, patterns, options = {})
 
 		Recls::FileSearch.new(search_root, patterns, options)
@@ -55,26 +58,16 @@ module Recls
 	# === 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
-	#   - +options+:: (Hash, Integer) Combination of flags (with
-	#    behaviour as described below for the +flags+ option), or an
-	#    options hash
+	#   - +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 - FILES,
-	#    DIRECTORIES, etc. If the value modulo TYPEMASK is 0,
-	#    then FILES is assumed. The value RECURSIVE is added by the
-	#    function, and so need not be added by the caller; it cannot be
-	#    removed
+	#   - +flags+ (Integer) Combination of flags - FILES, DIRECTORIES, etc. If the value modulo TYPEMASK is 0, then FILES is assumed. The value RECURSIVE is added by the function, and so need not be added by the caller; it cannot be removed
 	#
 	# === Return
-	#  An instance of +::Recls::FileSearch+
-	#
+	# An instance of a class implementing ::Enumerable whose value type is
+	# Recls::Entry
 	def self.file_rsearch(search_root, patterns, options = {})
 
 		case options
@@ -104,29 +97,21 @@ module Recls
 	# === 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
-	#   - +options+:: (Hash, Integer) Combination of flags (with
-	#    behaviour as described below for the +flags+ option), or an
-	#    options hash
+	#   - +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 - FILES,
-	#    DIRECTORIES, RECURSIVE, etc. If the value modulo TYPEMASK is 0,
-	#    then FILES is assumed
+	#   - +flags+ (Integer) Combination of flags - FILES, DIRECTORIES, RECURSIVE, etc. If the value modulo TYPEMASK is 0, then FILES is assumed
 	#
 	# === Return
-	#  An instance of +::Recls::FileSearch+
-	#
+	# An instance of a class implementing ::Enumerable whose value type is
+	# Recls::Entry
 	def self.file_search(search_root, patterns, options = {})
 
 		Recls::FileSearch.new(search_root, patterns, options)
 	end
-end
+end # module Recls
 
 # ############################## end of file ############################# #
 

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:      21st March 2019
+# Updated:      14th April 2019
 #
 # Author:       Matthew Wilson
 #
@@ -38,6 +38,11 @@
 
 require 'recls/ximpl/util'
 
+=begin
+=end
+
+class Object; end # :nodoc:
+
 module Recls
 
 	# Combines paths
@@ -45,11 +50,10 @@ 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
-	#  The combined path
+	# (String) The combined path
 	def self.combine_paths(*paths)
 
 		paths	=	paths.reject { |p| p.nil? }

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:      21st March 2019
+# Updated:      14th April 2019
 #
 # Author:       Matthew Wilson
 #
@@ -38,6 +38,11 @@
 
 require 'recls/ximpl/util'
 
+=begin
+=end
+
+class Object; end # :nodoc:
+
 module Recls
 
 	# Combines paths, optionally canonicalising them
@@ -45,22 +50,16 @@ module Recls
 	# === Signature
 	#
 	# * *Parameters:*
-	#   - +paths+:: ([ (::String, ::Recls::Entry( ]) Array of 1 or more path
-	#     elements to be combined
-	#   - +options+:: (::Hash) Options that moderate the combination
+	#   - +paths+ ([ (::String, ::Recls::Entry) ]) Array of 1 or more path elements to be combined
+	#   - +options+ (::Hash) Options that moderate the combination
 	#
 	# * *Options:*
-	#   - +:canonicalise+:: (boolean) Causes the evaluated path to be
-	#     canonicalised - with +Recls.canonicalise_path+ - before it is
-	#     returned
-	#   - +:clean+:: (boolean) Causes the evaluated path to be cleaned
-	#     (i.e. sent to +cleanpath+) before it is returned. Ignored if
-	#     +:canonicalise+ is specified
-	#   - +:clean_path+:: (boolean) Equivalent to +:clean+, but deprecated
-	#     and may be removed in a future version
+	#   - +:canonicalise+ (boolean) Causes the evaluated path to be canonicalised - with +Recls.canonicalise_path+ - before it is returned
+	#   - +:clean+ (boolean) Causes the evaluated path to be cleaned (i.e. sent to +cleanpath+) before it is returned. Ignored if +:canonicalise+ is specified
+	#   - +:clean_path+ (boolean) Equivalent to +:clean+, but deprecated and may be removed in a future version
 	#
 	# === Return
-	#  The combined path
+	# (String) The combined path
 	def self.combine_paths(*paths, **options)
 
 		paths	=	paths.reject { |p| p.nil? }

data/lib/recls/entry.rb

@@ -4,11 +4,11 @@
 # Purpose:      Defines the Recls::Entry class for the recls.Ruby library.
 #
 # Created:      24th July 2012
-# Updated:      11th July 2016
+# Updated:      14th April 2019
 #
 # Author:       Matthew Wilson
 #
-# Copyright (c) 2012-2016, Matthew Wilson and Synesis Software
+# Copyright (c) 2012-2019, Matthew Wilson and Synesis Software
 # All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without
@@ -41,8 +41,14 @@ require 'recls/ximpl/' + (Recls::Ximpl::OS::OS_IS_WINDOWS ? 'windows' : 'unix')
 require 'recls/ximpl/util'
 require 'recls/flags'
 
+=begin
+=end
+
+class Object; end # :nodoc:
+
 module Recls
 
+	# A file-system entry
 	class Entry
 
 		private
@@ -90,6 +96,7 @@ module Recls
 			@nlink	=	@file_stat.nlink if @file_stat
 
 			if Recls::Ximpl::OS::OS_IS_WINDOWS && @file_stat
+
 				@dev				=	@file_stat.by_handle_information.volume_id
 				@ino				=	@file_stat.by_handle_information.file_index
 				@nlink				=	@file_stat.by_handle_information.num_links
@@ -102,26 +109,43 @@ module Recls
 		# ##########################
 		# 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
 
 		# ##########################
@@ -157,6 +181,7 @@ module Recls
 
 	if Recls::Ximpl::OS::OS_IS_WINDOWS
 
+		# [WINDOWS-ONLY] Indicates whether the entry has the *system* bit
 		def system?
 
 			return false if @file_stat.nil?
@@ -164,6 +189,7 @@ module Recls
 			@file_stat.system?
 		end
 
+		# [WINDOWS-ONLY] Indicates whether the entry has the *archive* bit
 		def archive?
 
 			return false if @file_stat.nil?
@@ -171,6 +197,7 @@ module Recls
 			@file_stat.archive?
 		end
 
+		# [WINDOWS-ONLY] Indicates whether the entry is a device
 		def device?
 
 			return false if @file_stat.nil?
@@ -178,6 +205,7 @@ module Recls
 			@file_stat.device?
 		end
 
+		# [WINDOWS-ONLY] Indicates whether the entry is *normal*
 		def normal?
 
 			return false if @file_stat.nil?
@@ -185,6 +213,7 @@ module Recls
 			@file_stat.normal?
 		end
 
+		# [WINDOWS-ONLY] Indicates whether the entry has the *temporary* bit
 		def temporary?
 
 			return false if @file_stat.nil?
@@ -192,6 +221,7 @@ module Recls
 			@file_stat.temporary?
 		end
 
+		# [WINDOWS-ONLY] Indicates whether the entry has the *compressed* bit
 		def compressed?
 
 			return false if @file_stat.nil?
@@ -199,6 +229,7 @@ module Recls
 			@file_stat.compressed?
 		end
 
+		# [WINDOWS-ONLY] Indicates whether the entry has the *encrypted* bit
 		def encrypted?
 
 			return false if @file_stat.nil?
@@ -355,8 +386,8 @@ module Recls
 
 			path
 		end
-	end
-end
+	end # class Entry
+end # module Recls
 
 # ############################## end of file ############################# #
 

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:      21st March 2019
+# Updated:      14th April 2019
 #
 # Author:       Matthew Wilson
 #
@@ -40,9 +40,14 @@ require 'recls/entry'
 require 'recls/flags'
 require 'recls/ximpl/os'
 
+=begin
+=end
+
+class Object; end # :nodoc:
+
 module Recls
 
-	class FileSearch
+	class FileSearch # :nodoc: all
 
 		include Enumerable
 
@@ -52,20 +57,12 @@ module Recls
 		# === 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
-		#   - +options+:: (Hash, Integer) Combination of flags (with
-		#    behaviour as described below for the +flags+ option), or an
-		#    options hash
+		#   - +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 - FILES,
-		#    DIRECTORIES, RECURSIVE, etc. If the value modulo TYPEMASK is 0,
-		#    then FILES is assumed
+		#   - +flags+ (Integer) Combination of flags - FILES, DIRECTORIES, RECURSIVE, etc. If the value modulo TYPEMASK is 0, then FILES is assumed
 		#
 		# === Return
 		#  An instance of the class
@@ -133,11 +130,14 @@ module Recls
 			@flags			=	flags
 		end
 
+		# (String) The search root
 		attr_reader :search_root
+		# (String) The search patterns
 		attr_reader :patterns
+		# (Integer) The search flags
 		attr_reader :flags
 
-		def each(&blk)
+		def each(&blk) # :nodoc:
 
 			search_root = @search_root
 			search_root = Recls::Ximpl::absolute_path search_root
@@ -179,7 +179,7 @@ module Recls
 		end
 
 		private
-		def FileSearch::is_dots(name)
+		def FileSearch.is_dots(name) # :nodoc:
 
 			case	name
 			when	'.', '..'
@@ -189,12 +189,12 @@ module Recls
 			end
 		end
 
-		def FileSearch::stat_or_nil_(path, flags)
+		def FileSearch.stat_or_nil_(path, flags) # :nodoc:
 
 			begin
 
 				Recls::Ximpl::FileStat.stat path
-			rescue Errno::ENOENT => x
+			rescue Errno::ENOENT, Errno::ENXIO
 
 				nil
 			rescue SystemCallError => x
@@ -217,7 +217,7 @@ module Recls
 		# order to allow calculation of search_relative_path in the
 		# entry.
 
-		def FileSearch::search_directory_(search_root, dir, patterns, flags, &blk)
+		def FileSearch.search_directory_(search_root, dir, patterns, flags, &blk) # :nodoc:
 
 			# array of FileStat instances
 			entries = []
@@ -310,8 +310,8 @@ module Recls
 				FileSearch::search_directory_(search_root, fs.path, patterns, flags, &blk)
 			end
 		end
-	end
-end
+	end # class FileSearch
+end # module Recls
 
 # ############################## end of file ############################# #
 

data/lib/recls/flags.rb

@@ -4,11 +4,11 @@
 # Purpose:      Defines the Recls::Flags module for the recls.Ruby library.
 #
 # Created:      24th July 2012
-# Updated:      27th August 2015
+# Updated:      14th April 2019
 #
 # Author:       Matthew Wilson
 #
-# Copyright (c) 2012-2015, Matthew Wilson and Synesis Software
+# Copyright (c) 2012-2019, Matthew Wilson and Synesis Software
 # All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without
@@ -36,6 +36,11 @@
 # ######################################################################### #
 
 
+=begin
+=end
+
+class Object; end # :nodoc:
+
 module Recls
 
 	# Specifies that files are to be listed
@@ -46,32 +51,43 @@ 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)
 	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
 	DIR_PROGRESS			=	0x00001000
 	# Causes search to terminate if a directory cannot be entered or an
 	# entry's information cannot be stat()'d
 	STOP_ON_ACCESS_FAILURE	=	0x00002000
+	# [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
 	NODE_INDEX				=	0x00008000
 
+	# Causes search to operate recursively
 	RECURSIVE				=	0x00010000
 private
-	NO_SEARCH_LINKS			=	0x00020000
+	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
 	DIRECTORY_PARTS			=	0x00040000
+	# 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
+	# attributes to contain a trailing path-name-separator for directory
+	# entries
 	MARK_DIRECTORIES		=	0x00200000
 
 	# Causes sub-directories that are links to be searched; default is not
 	# to search through links
 	SEARCH_THROUGH_LINKS	=	0x00100000
-end
+end # module Recls
 
 # ############################## end of file ############################# #