recls-ruby 2.8.2 → 2.11.0

data/lib/recls/file_search.rb

@@ -4,11 +4,11 @@
 # Purpose:      Defines the Recls::FileSearch class for the recls.Ruby library.
 #
 # Created:      24th July 2012
-# Updated:      13th June 2016
+# 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
@@ -40,12 +40,33 @@ 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
 
+		# Initialises a +FileSearch+ instance, which acts as an +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
+		#   - +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
+		#
+		# === Return
+		#  An instance of the class
+		#
 		def initialize(search_root, patterns, options={})
 
 			# for backwards compatibility, we allow for options to
@@ -101,19 +122,26 @@ module Recls
 			end
 
 			# now de-dup the patterns, to avoid duplicates in search
-			patterns	=	patterns.flatten
-			patterns	=	patterns.uniq
+			patterns		=	patterns.flatten
+			patterns		=	patterns.uniq
 
 			@search_root	=	search_root
-			@patterns	=	patterns
-			@flags		=	flags
+			@patterns		=	patterns
+			@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)
+		# Calls the block once for each found file, passing a single
+		# parameter that is a Recls::Entry instance
+		#
+		# @!visibility private
+		def each(&blk) # :nodoc:
 
 			search_root = @search_root
 			search_root = Recls::Ximpl::absolute_path search_root
@@ -155,7 +183,8 @@ module Recls
 		end
 
 		private
-		def FileSearch::is_dots(name)
+		# @!visibility private
+		def FileSearch.is_dots(name) # :nodoc:
 
 			case	name
 			when	'.', '..'
@@ -165,12 +194,13 @@ module Recls
 			end
 		end
 
-		def FileSearch::stat_or_nil_(path, flags)
+		# @!visibility private
+		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
@@ -193,7 +223,8 @@ module Recls
 		# order to allow calculation of search_relative_path in the
 		# entry.
 
-		def FileSearch::search_directory_(search_root, dir, patterns, flags, &blk)
+		# @!visibility private
+		def FileSearch.search_directory_(search_root, dir, patterns, flags, &blk) # :nodoc:
 
 			# array of FileStat instances
 			entries = []
@@ -252,6 +283,8 @@ module Recls
 
 				match	=	false
 
+				match	||=	(0 == (Recls::TYPEMASK & flags))
+
 				match	||=	(0 != (Recls::FILES & flags) && fs.file?)
 				match	||=	(0 != (Recls::DIRECTORIES & flags) && fs.directory?)
 				match	||=	(0 != (Recls::DEVICES & flags) && fs.blockdev?)
@@ -286,8 +319,9 @@ 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,44 @@ 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 ############################# #
 
+

data/lib/recls/foreach.rb

@@ -4,11 +4,11 @@
 # Purpose:      Definition of Recls::foreach() utility function
 #
 # Created:      22nd October 2014
-# Updated:      9th June 2016
+# Updated:      26th May 2020
 #
 # 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
@@ -38,23 +38,31 @@
 
 require 'recls/file_search'
 
+=begin
+=end
+
+class Object; end # :nodoc:
+
 module Recls
 
 	private
-	class FileSearchLineEnumerator
+	# @!visibility private
+	class FileSearchLineEnumerator # :nodoc: all
 
 		include Enumerable
 
+		# @!visibility private
 		def initialize(fs)
 
 			@fs = fs
 		end
 
+		# @!visibility private
 		def each(&block)
 
 			@fs.each do |fe|
 
-				IO::readlines(fe).each_with_index do |line, index|
+				IO.readlines(fe).each_with_index do |line, index|
 
 					case	block.arity
 					when	1
@@ -69,21 +77,51 @@ module Recls
 				end
 			end
 		end
-	end
+	end # class FileSearchLineEnumerator
 	public
 
+	# Performs a 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
+	#   - +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
+	# enumerator is returned.
+	#
+	# ==== Parameter Ordering
+	#
+	# The parameters may be expressed in any of the following permutations:
+	# - +searchable+
+	# - +search_root+, +patterns+, +flags+
+	# - +search_root+, +patterns+, +options+
+	#
+	# === Return
+	#
 	def self.foreach(*args, &block)
 
 		fs = nil
 
 		case	args.length
 		when	1
+
 			raise ArgumentError "Single argument must be of type #{Recls::FileSearch}" unless args[0].kind_of? Recls::FileSearch
 
 			fs = args[0]
 		when	3
+
 			fs = Recls::FileSearch.new(args[0], args[1], args[2])
 		else
+
 			raise ArgumentError "Function requires single argument (#{Recls::FileSearch}) or three arguments (directory, patterns, flags)"
 		end
 
@@ -97,7 +135,8 @@ module Recls
 			return FileSearchLineEnumerator.new(fs)
 		end
 	end
-end
+end # module Recls
 
 # ############################## end of file ############################# #
 
+

data/lib/recls/obsolete.rb

@@ -0,0 +1,119 @@
+# ######################################################################### #
+# File:         recls/obsolete.rb
+#
+# Purpose:      Obsolete elements
+#
+# Created:      19th July 2012
+# Updated:      14th April 2019
+#
+# Author:       Matthew Wilson
+#
+# Copyright (c) 2012-2019, 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.
+#
+# 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.
+#
+# ######################################################################### #
+
+
+
+# ######################################################################### #
+# Obsolete symbols
+
+if not defined? RECLS_NO_OBSOLETE
+
+	module Recls # :nodoc: all
+
+		# @!visibility private
+		def self.pathNameSeparator
+
+			PATH_NAME_SEPARATOR
+		end
+
+		# @!visibility private
+		def self.pathSeparator
+
+			PATH_SEPARATOR
+		end
+
+		# @!visibility private
+		def self.wildcardsAll
+
+			WILDCARDS_ALL
+		end
+
+		class FileSearch # :nodoc:
+
+			# @!visibility private
+			alias_method :searchRoot, :search_root
+			# @!visibility private
+			alias_method :pattern, :patterns
+		end
+
+		class Entry # :nodoc:
+
+			# @!visibility private
+			alias_method :uncDrive, :drive
+			# @!visibility private
+			alias_method :directoryPath, :directory_path
+			# @!visibility private
+			alias_method :directoryParts, :directory_parts
+			# @!visibility private
+			alias_method :file, :file_full_name
+			# @!visibility private
+			alias_method :shortFile, :file_short_name
+			# @!visibility private
+			alias_method :fileBaseName, :file_name_only
+			# @!visibility private
+			alias_method :fileName, :file_name_only
+			# @!visibility private
+			alias_method :fileExt, :file_extension
+			# @!visibility private
+			alias_method :searchDirectory, :search_directory
+			# @!visibility private
+			alias_method :searchRelativePath, :search_relative_path
+
+			# @!visibility private
+			alias_method :isDirectory, :directory?
+			# @!visibility private
+			alias_method :isFile, :file?
+			#alias_method :isLink, :link?
+			# @!visibility private
+			alias_method :isReadOnly, :readonly?
+			# @!visibility private
+			def isUNC
+
+				d = drive
+
+				d and d.size > 2
+			end
+
+			# @!visibility private
+			alias_method :creationTime, :modification_time
+		end
+	end # module Recls
+end
+
+# ############################## end of file ############################# #
+
+

data/lib/recls/recls.rb

@@ -4,11 +4,11 @@
 # Purpose:      Main source file for recls library
 #
 # Created:      19th July 2012
-# Updated:      9th June 2016
+# 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
@@ -39,76 +39,47 @@
 require 'recls/version'
 
 require 'recls/api'
+require 'recls/entry'
 require 'recls/file_search'
 require 'recls/foreach'
 require 'recls/stat'
 require 'recls/util'
 require 'recls/ximpl/os'
 
+# The *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
+module Recls
+
+end # module Recls
+
 module Recls
 
 	# Represents the "all" wildcards string for the ambient operating
 	# system
 	WILDCARDS_ALL = Recls::Ximpl::OS::WILDCARDS_ALL
 
+	# The string sequence used to separate names in paths, e.g. "/" on UNIX
 	PATH_NAME_SEPARATOR = Recls::Ximpl::OS::PATH_NAME_SEPARATOR
 
+	# The string sequence used to separate paths, e.g. ":" on UNIX
 	PATH_SEPARATOR = Recls::Ximpl::OS::PATH_SEPARATOR
-end
-
-# ######################################################################### #
-# Obsolete symbols
-
-if not defined? RECLS_NO_OBSOLETE
-
-	module Recls
-
-		def self.pathNameSeparator
-			PATH_NAME_SEPARATOR
-		end
-
-		def self.pathSeparator
-			PATH_SEPARATOR
-		end
+end # module Recls
 
-		def self.wildcardsAll
-			WILDCARDS_ALL
-		end
-
-		class FileSearch
-
-			alias_method :searchRoot, :search_root
-			alias_method :pattern, :patterns
-		end
-
-		class Entry
-
-			alias_method :uncDrive, :drive
-			alias_method :directoryPath, :directory_path
-			alias_method :directoryParts, :directory_parts
-			alias_method :file, :file_full_name
-			alias_method :shortFile, :file_short_name
-			alias_method :fileBaseName, :file_name_only
-			alias_method :fileName, :file_name_only
-			alias_method :fileExt, :file_extension
-			alias_method :searchDirectory, :search_directory
-			alias_method :searchRelativePath, :search_relative_path
-
-			alias_method :isDirectory, :directory?
-			alias_method :isFile, :file?
-			#alias_method :isLink, :link?
-			alias_method :isReadOnly, :readonly?
-			def isUNC
-
-				d = drive
-
-				d and d.size > 2
-			end
-
-			alias_method :creationTime, :modification_time
-		end
-	end
-end
+require 'recls/obsolete'
 
 # ############################## end of file ############################# #
 
+