recls-ruby 2.11.0.3 → 2.12.0

data/lib/recls/stat.rb

@@ -1,14 +1,13 @@
-# ######################################################################## #
-# 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:  20th April 2024
+# Created:      24th July 2012
+# Updated:      14th March 2019
 #
-# 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.
 #
@@ -34,149 +33,147 @@
 # 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 ############################# #
 
+

data/lib/recls/util.rb

@@ -1,14 +1,13 @@
-# ######################################################################## #
-# 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:  20th April 2024
+# Created:      17th February 2014
+# Updated:      14th April 2019
 #
-# 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.
 #
@@ -34,118 +33,116 @@
 # 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 ############################# #
 
+

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:  20th April 2024
+# Created:      14th February 2014
+# Updated:      6th April 2021
 #
-# Author:   Matthew Wilson
+# Author:       Matthew Wilson
 #
-# Copyright (c) 2019-2024, Matthew Wilson and Synesis Information Systems
+# Copyright (c) 2019-2020, Matthew Wilson and Synesis Information Systems
 # Copyright (c) 2012-2019, Matthew Wilson and Synesis Software
 # All rights reserved.
 #
@@ -34,32 +34,27 @@
 # 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.11.0.3'
+	# Current version of the recls.Ruby library
+	VERSION				=	'2.12.0'
 
-  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:
+	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:
 end # module Recls
 
-
 # ############################## end of file ############################# #
 
+