recls-ruby 2.9.0 → 2.12.0

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

data/lib/recls/util.rb

@@ -4,7 +4,7 @@
 # Purpose:      Utility module functions for recls library
 #
 # Created:      17th February 2014
-# Updated:      21st March 2019
+# Updated:      14th April 2019
 #
 # Author:       Matthew Wilson
 #
@@ -36,33 +36,64 @@
 # ######################################################################### #
 
 
+require 'recls/stat'
 require 'recls/ximpl/util'
 require 'recls/ximpl/os'
 
+=begin
+=end
+
+class Object; end # :nodoc:
+
 module Recls
 
 	# Obtains the absolute form of the given path
+	#
+	# === Signature
+	#
+	# * *Parameters:*
+	#   - +path+ (String, Recls::Entry) The path
+	#
+	# === Return
+	# (String) The absolute form of the path
 	def self.absolute_path(path)
 
 		return path.path if 'Recls::Entry' === path.class.to_s
 
-		return Recls::Ximpl.absolute_path path
+		Recls::Ximpl.absolute_path path
 	end
 
 	# Canonicalises the given path, by removing dots ('.' and '..')
 	# directories
+	#
+	# === Signature
+	#
+	# * *Parameters:*
+	#   - +path+ (String, Recls::Entry) The path
+	#
+	# === Return
+	# (String) The canonical form of the path
 	def self.canonicalise_path(path)
 
 		path = path.path if 'Recls::Entry' === path.class.to_s
 
-		return Recls::Ximpl.canonicalise_path path
+		Recls::Ximpl.canonicalise_path path
 	end
 
 	# Derives a given path relative to an origin, unless the path is
 	# absolute
+	#
+	# === Signature
+	#
+	# * *Parameters:*
+	#   - +origin+ (String, Recls::Entry) The path against which +path+ will be evaluated
+	#   - +path+ (String, Recls::Entry) The path to evaluate
+	#
+	# === Return
+	# (String) The relative form of the path
 	def self.derive_relative_path(origin, path)
 
-		return Recls::Ximpl.derive_relative_path origin, path
+		Recls::Ximpl.derive_relative_path origin, path
 	end
 end # module Recls
 
@@ -74,6 +105,44 @@ else
 	require 'recls/combine_paths_1'
 end
 
+module Recls
+
+	# Indicates whether the given path exists, obtaining a Recls::Entry
+	# instance if so
+	#
+	# === Signature
+	#
+	# * *Parameters:*
+	#   - +path+ (String, Recls::Entry) The path
+	#
+	# === Return
+	# (Recls::Entry, nil) The entry if +path+ exists; +nil+ otherwise
+	def self.exist?(path)
+
+		return nil if path.nil?
+
+		Recls.stat(path)
+	end
+
+	# Indicates whether the given path is absolute
+	#
+	# === Signature
+	#
+	# * *Parameters:*
+	#   - +path+ (String, Recls::Entry) The path
+	#
+	# === Return
+	# (boolean) +true+ if +path+ is absolute; +false+ otherwise
+	def self.absolute_path?(path)
+
+		return nil if path.nil?
+
+		return true if 'Recls::Entry' === path.class.to_s
+
+		Recls::Ximpl.absolute_path? path
+	end
+end # module Recls
+
 # ############################## end of file ############################# #
 
 

data/lib/recls/version.rb

@@ -4,10 +4,11 @@
 # Purpose:      Version for recls library
 #
 # Created:      14th February 2014
-# Updated:      21st March 2019
+# Updated:      6th April 2021
 #
 # Author:       Matthew Wilson
 #
+# Copyright (c) 2019-2020, Matthew Wilson and Synesis Information Systems
 # Copyright (c) 2012-2019, Matthew Wilson and Synesis Software
 # All rights reserved.
 #
@@ -36,10 +37,15 @@
 # ######################################################################### #
 
 
+=begin
+=end
+
+class Object; end # :nodoc:
+
 module Recls
 
 	# Current version of the recls.Ruby library
-	VERSION				=	'2.9.0'
+	VERSION				=	'2.12.0'
 
 	private
 	VERSION_PARTS_		=	VERSION.split(/[.]/).collect { |n| n.to_i } # :nodoc:
@@ -47,7 +53,7 @@ module Recls
 	VERSION_MAJOR		=	VERSION_PARTS_[0] # :nodoc:
 	VERSION_MINOR		=	VERSION_PARTS_[1] # :nodoc:
 	VERSION_REVISION	=	VERSION_PARTS_[2] # :nodoc:
-end
+end # module Recls
 
 # ############################## end of file ############################# #
 

data/lib/recls/ximpl/os.rb

@@ -1,15 +1,16 @@
 # ######################################################################### #
-# File:        recls/ximpl/os.rb
+# File:         recls/ximpl/os.rb
 #
-# Purpose:     Operating system internal implementation constructs for the
-#              recls library.
+# Purpose:      Operating system internal implementation constructs for the
+#               recls library.
 #
-# Created:     16th February 2014
-# Updated:     27th August 2015
+# Created:      16th February 2014
+# Updated:      6th April 2021
 #
-# Author:      Matthew Wilson
+# Author:       Matthew Wilson
 #
-# Copyright (c) 2012-2015, Matthew Wilson and Synesis Software
+# Copyright (c) 2019-2021, Matthew Wilson and Synesis Information Systems
+# Copyright (c) 2012-2019, Matthew Wilson and Synesis Software
 # All rights reserved.
 #
 # Redistribution and use in source and binary forms, with or without
@@ -37,21 +38,31 @@
 # ######################################################################### #
 
 
-module Recls
+=begin
+=end
 
-	module Ximpl
+module Recls # :nodoc:
 
-		module OS
+# :stopdoc:
 
-			OS_IS_WINDOWS = (RUBY_PLATFORM =~ /(mswin|mingw|bccwin|wince)/i) ? true : false
+	module Ximpl # :nodoc: all
 
+		module OS # :nodoc: all
+
+			# @!visibility private
+			OS_IS_WINDOWS = (RUBY_PLATFORM =~ /(bccwin|cygwin|mingw|mswin|wince)/i) ? true : false
+
+			# @!visibility private
 			PATH_NAME_SEPARATOR = OS_IS_WINDOWS ? '\\' : '/'
 
+			# @!visibility private
 			PATH_SEPARATOR = OS_IS_WINDOWS ? ';' : ':'
 
+			# @!visibility private
 			WILDCARDS_ALL = OS_IS_WINDOWS ? '*' : '*'
 
-			def OS.get_number_of_dots_dir_(p)
+			# @!visibility private
+			def OS.get_number_of_dots_dir_(p) # :nodoc:
 
 				if p
 					if ?. == p[0]
@@ -69,7 +80,8 @@ module Recls
 				return 0
 			end
 
-			def OS.is_root_dir_(p)
+			# @!visibility private
+			def OS.is_root_dir_(p) # :nodoc:
 
 				return nil if not p
 				return true if '/' == p
@@ -77,9 +89,12 @@ module Recls
 
 				return false
 			end
-		end
-	end
-end
+		end # module OS
+	end # module Ximpl
+
+# :startdoc:
+
+end # module Recls
 
 # ############################## end of file ############################# #
 

data/lib/recls/ximpl/unix.rb

@@ -1,14 +1,14 @@
 # ######################################################################### #
-# File:        recls/ximpl/unix.rb
+# File:         recls/ximpl/unix.rb
 #
-# Purpose:     UNIX-specific constructs for the recls library.
+# Purpose:      UNIX-specific constructs for the recls library.
 #
-# Created:     19th February 2014
-# Updated:     27th August 2015
+# Created:      19th February 2014
+# Updated:      14th April 2019
 #
-# Author:      Matthew Wilson
+# 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
@@ -38,14 +38,21 @@
 
 require 'recls/ximpl/util'
 
-module Recls
+=begin
+=end
 
-	module Ximpl
+module Recls # :nodoc:
 
-		class FileStat < File::Stat
+# :stopdoc:
+
+	module Ximpl # :nodoc: all
+
+		# @!visibility private
+		class FileStat < File::Stat # :nodoc:
 
 			private
-			def initialize(path)
+			# @!visibility private
+			def initialize(path) # :nodoc:
 
 				@path = path
 
@@ -53,9 +60,11 @@ module Recls
 			end
 
 			public
-			attr_reader :path
+			# @!visibility private
+			attr_reader :path # :nodoc:
 
-			def hidden?
+			# @!visibility private
+			def hidden? # :nodoc:
 
 				basename = File.basename @path
 
@@ -68,14 +77,18 @@ module Recls
 			end
 
 			public
-			def FileStat.stat(path)
+			# @!visibility private
+			def FileStat.stat(path) # :nodoc:
 
 				Recls::Ximpl::FileStat.new(path)
 
 			end
-		end
-	end
-end
+		end # class FileStat
+	end # module Ximpl
+
+# :startdoc:
+
+end # module Recls
 
 # ############################## end of file ############################# #