recls-ruby 2.12.0 → 2.12.0.1

data/lib/recls/stat.rb

@@ -1,13 +1,14 @@
-# ######################################################################### #
-# File:         recls/stat.rb
+# ######################################################################## #
+# File:     recls/stat.rb
 #
-# Purpose:      Defines the Recls.stat() method for the recls.Ruby library.
+# Purpose:  Defines the Recls.stat() method for the recls.Ruby library.
 #
-# Created:      24th July 2012
-# Updated:      14th March 2019
+# Created:  24th July 2012
+# Updated:  20th April 2024
 #
-# Author:       Matthew Wilson
+# Author:   Matthew Wilson
 #
+# Copyright (c) 2019-2024, Matthew Wilson and Synesis Information Systems
 # Copyright (c) 2012-2019, Matthew Wilson and Synesis Software
 # All rights reserved.
 #
@@ -33,147 +34,149 @@
 # ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 # POSSIBILITY OF SUCH DAMAGE.
 #
-# ######################################################################### #
+# ######################################################################## #
 
 
 require 'recls/entry'
 require 'recls/flags'
 
+
 =begin
 =end
 
+# @!visibility private
 class Object; end # :nodoc:
 
 module Recls
 
-	# 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)
-
-		if fe
-
-			return nil unless fe.directory?
-		end
-
-		fe
-	end
-
-	# 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)
-
-		if fe
-
-			return nil unless fe.file?
-		end
-
-		fe
-	end
-
-	# 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
-	#
-	# 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
-		search_root	=	nil
-		message		=	nil
-
-		path		=	File.expand_path(path) if path =~ /^~[\\\/]*/
-
-		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
-
-		Recls::Ximpl.stat_prep(path, search_root, flags)
-	end 
+  # 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)
+
+    if fe
+
+      return nil unless fe.directory?
+    end
+
+    fe
+  end
+
+  # 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)
+
+    if fe
+
+      return nil unless fe.file?
+    end
+
+    fe
+  end
+
+  # 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
+  #
+  # 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
+    search_root = nil
+    message     = nil
+
+    path = File.expand_path(path) if path =~ /^~[\\\/]*/
+
+    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
+
+    Recls::Ximpl.stat_prep(path, search_root, flags)
+  end
 end # module Recls
 
-# ############################## end of file ############################# #
 
+# ############################## end of file ############################# #
 

data/lib/recls/util.rb

@@ -1,13 +1,14 @@
-# ######################################################################### #
-# File:         recls/util.rb
+# ######################################################################## #
+# File:     recls/util.rb
 #
-# Purpose:      Utility module functions for recls library
+# Purpose:  Utility module functions for recls library
 #
-# Created:      17th February 2014
-# Updated:      14th April 2019
+# Created:  17th February 2014
+# Updated:  20th April 2024
 #
-# Author:       Matthew Wilson
+# Author:   Matthew Wilson
 #
+# Copyright (c) 2019-2024, Matthew Wilson and Synesis Information Systems
 # Copyright (c) 2012-2019, Matthew Wilson and Synesis Software
 # All rights reserved.
 #
@@ -33,116 +34,118 @@
 # ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 # POSSIBILITY OF SUCH DAMAGE.
 #
-# ######################################################################### #
+# ######################################################################## #
 
 
 require 'recls/stat'
 require 'recls/ximpl/util'
 require 'recls/ximpl/os'
 
+
 =begin
 =end
 
+# @!visibility private
 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
-
-		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
-
-		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)
-
-		Recls::Ximpl.derive_relative_path origin, path
-	end
+  # 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
+
+    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
+
+    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)
+
+    Recls::Ximpl.derive_relative_path origin, path
+  end
 end # module Recls
 
 if RUBY_VERSION >= '2'
 
-	require 'recls/combine_paths_2plus'
+  require 'recls/combine_paths_2plus'
 else
 
-	require 'recls/combine_paths_1'
+  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
+  # 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 ############################# #
 
+# ############################## end of file ############################# #
 

data/lib/recls/version.rb

@@ -1,14 +1,14 @@
-# ######################################################################### #
-# File:         recls/version.rb
+# ######################################################################## #
+# File:     recls/version.rb
 #
-# Purpose:      Version for recls library
+# Purpose:  Version for recls library
 #
-# Created:      14th February 2014
-# Updated:      6th April 2021
+# Created:  14th February 2014
+# Updated:  20th April 2024
 #
-# Author:       Matthew Wilson
+# Author:   Matthew Wilson
 #
-# Copyright (c) 2019-2020, Matthew Wilson and Synesis Information Systems
+# Copyright (c) 2019-2024, Matthew Wilson and Synesis Information Systems
 # Copyright (c) 2012-2019, Matthew Wilson and Synesis Software
 # All rights reserved.
 #
@@ -34,27 +34,32 @@
 # ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 # POSSIBILITY OF SUCH DAMAGE.
 #
-# ######################################################################### #
+# ######################################################################## #
 
 
 =begin
 =end
 
+# @!visibility private
 class Object; end # :nodoc:
 
 module Recls
 
-	# Current version of the recls.Ruby library
-	VERSION				=	'2.12.0'
+  # Current version of the recls.Ruby library
+  VERSION           = '2.12.0.1'
 
-	private
-	VERSION_PARTS_		=	VERSION.split(/[.]/).collect { |n| n.to_i } # :nodoc:
-	public
-	VERSION_MAJOR		=	VERSION_PARTS_[0] # :nodoc:
-	VERSION_MINOR		=	VERSION_PARTS_[1] # :nodoc:
-	VERSION_REVISION	=	VERSION_PARTS_[2] # :nodoc:
+  private
+  # @!visibility private
+  VERSION_PARTS_    = VERSION.split(/[.]/).collect { |n| n.to_i } # :nodoc:
+  public
+  # @!visibility private
+  VERSION_MAJOR     = VERSION_PARTS_[0] # :nodoc:
+  # @!visibility private
+  VERSION_MINOR     = VERSION_PARTS_[1] # :nodoc:
+  # @!visibility private
+  VERSION_REVISION  = VERSION_PARTS_[2] # :nodoc:
 end # module Recls
 
-# ############################## end of file ############################# #
 
+# ############################## end of file ############################# #