recls-ruby 2.9.1 → 2.10.0

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:      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
@@ -38,10 +38,15 @@
 
 require 'recls/file_search'
 
+=begin
+=end
+
+class Object; end # :nodoc:
+
 module Recls
 
 	private
-	class FileSearchLineEnumerator
+	class FileSearchLineEnumerator # :nodoc: all
 
 		include Enumerable
 
@@ -54,7 +59,7 @@ module Recls
 
 			@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,9 +74,36 @@ 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
@@ -97,7 +129,7 @@ module Recls
 			return FileSearchLineEnumerator.new(fs)
 		end
 	end
-end
+end # module Recls
 
 # ############################## end of file ############################# #
 

data/lib/recls/obsolete.rb

@@ -0,0 +1,99 @@
+# ######################################################################### #
+# 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
+
+		def self.pathNameSeparator
+
+			PATH_NAME_SEPARATOR
+		end
+
+		def self.pathSeparator
+
+			PATH_SEPARATOR
+		end
+
+		def self.wildcardsAll
+
+			WILDCARDS_ALL
+		end
+
+		class FileSearch # :nodoc:
+
+			alias_method :searchRoot, :search_root
+			alias_method :pattern, :patterns
+		end
+
+		class Entry # :nodoc:
+
+			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 # 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
-
-		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
+end # module Recls
 
-			alias_method :creationTime, :modification_time
-		end
-	end
-end
+require 'recls/obsolete'
 
 # ############################## end of file ############################# #
 

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:      21st March 2019
+# Updated:      14th March 2019
 #
 # Author:       Matthew Wilson
 #
@@ -39,10 +39,27 @@
 require 'recls/entry'
 require 'recls/flags'
 
+=begin
+=end
+
+class Object; end # :nodoc:
+
 module Recls
 
-	# Performs a +stat()+ but returns +nil+ if an obtained entry is not a
-	# directory
+	# Equivalent to a 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
+	#
+	# === Signature
+	#
+	# * *Parameters:*
+	#   - +path+ (String, Recls::Entry) The path
+	#
+	# === Return
+	# (Recls::Entry, nil) The entry if +path+ exists and is a directory; +nil+ otherwise
 	def self.directory?(path, *args)
 
 		fe = self.stat(path, *args)
@@ -55,8 +72,20 @@ module Recls
 		fe
 	end
 
-	# Performs a +stat()+ but returns +nil+ if an obtained entry is not a
-	# file
+	# Equivalent to a 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
+	#
+	# === Signature
+	#
+	# * *Parameters:*
+	#   - +path+ (String, Recls::Entry) The path
+	#
+	# === Return
+	# (Recls::Entry, nil) The entry if +path+ exists and is a file; +nil+ otherwise
 	def self.file?(path, *args)
 
 		fe = self.stat(path, *args)
@@ -69,13 +98,31 @@ module Recls
 		fe
 	end
 
-	# USAGE:
+	# 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
+	#
+	# === Signature
+	#
+	# * *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)
+	#
+	# ==== Parameter Ordering
 	#
-	#  - stat(path)
-	#  - stat(path, flags)
-	#  - stat(path, search_root)
-	#  - stat(path, search_root, flags)
-	#  - stat(path, flags, search_root)
+	# The parameters may be expressed in any of the following permutations:
+	# - +path+
+	# - +path+, +flags+
+	# - +path+, +search_root+
+	# - +path+, +flags+, +search_root+
+	# - +path+, +search_root+, +flags+
+	#
+	# === Return
+	# (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
+	# regardless of its existence
 	def self.stat(path, *args)
 
 		flags		=	0
@@ -86,50 +133,46 @@ module Recls
 
 		case	args.size
 		when	0
+
 			;
 		when	1
+
 			case	args[0]
 			when	::Integer
+
 				flags = args[0]
 			when	::String
+
 				search_root = args[0]
 			else
+
 				message = "argument '#{args[0]}' (#{args[0].class}) not valid"
 			end
 		when	2
+
 			if false
 			elsif ::Integer === args[0] && ::String === args[1]
+
 				flags		=	args[0]
 				search_root	=	args[1]
 			elsif ::String === args[0] && ::Integer === args[1]
+
 				search_root	=	args[0]
 				flags		=	args[1]
 			else
+
 				message = "invalid combination of arguments"
 			end
 		else
+
 			message = "too many arguments"
 		end
 
 		raise ArgumentError, "#{message}: Recls.stat() takes one (path), two (path+flags or path+search_root), or three (path+search_root+flags) arguments" if message
 
-		begin
-
-			Recls::Entry.new(path, Recls::Ximpl::FileStat.stat(path), search_root, flags)
-		rescue Errno::ENOENT => x
-
-			x = x # suppress warning
-
-			if 0 != (flags & Recls::DETAILS_LATER)
-
-				Recls::Entry.new(path, nil, search_root, flags)
-			else
-
-				nil
-			end
-		end
-	end
-end
+		Recls::Ximpl.stat_prep(path, search_root, flags)
+	end 
+end # module Recls
 
 # ############################## end of file ############################# #