recls-ruby 2.6.4

data/lib/recls/stat.rb

@@ -0,0 +1,104 @@
+# ######################################################################### #
+# File:         recls/stat.rb
+#
+# Purpose:      Defines the Recls.stat() method for the recls.Ruby library.
+#
+# Created:      24th July 2012
+# Updated:      28th December 2015
+#
+# Author:       Matthew Wilson
+#
+# Copyright (c) 2012-2015, 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.
+#
+# ######################################################################### #
+
+
+require 'recls/entry'
+require 'recls/flags'
+
+module Recls
+
+	# USAGE:
+	#
+	#  - stat(path)
+	#  - stat(path, flags)
+	#  - stat(path, search_root)
+	#  - stat(path, search_root, flags)
+	#  - stat(path, flags, search_root)
+	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
+
+		begin
+			Recls::Entry.new(path, Recls::Ximpl::FileStat.stat(path), search_root, flags)
+		rescue Errno::ENOENT => x
+
+			if 0 != (flags & Recls::DETAILS_LATER)
+
+				Recls::Entry.new(path, nil, search_root, flags)
+			else
+
+				nil
+			end
+		end
+	end 
+end
+
+# ############################## end of file ############################# #
+

data/lib/recls/util.rb

@@ -0,0 +1,73 @@
+# ######################################################################### #
+# File:         recls/util.rb
+#
+# Purpose:      Utility module functions for recls library
+#
+# Created:      17th February 2014
+# Updated:      27th August 2015
+#
+# Author:       Matthew Wilson
+#
+# Copyright (c) 2012-2015, 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.
+#
+# ######################################################################### #
+
+
+require 'recls/ximpl/util'
+require 'recls/ximpl/os'
+
+module Recls
+
+	# Obtains the absolute form of the given path
+	def self.absolute_path(path)
+
+		return Recls::Ximpl.absolute_path path
+	end
+
+	# Canonicalises the given path, by removing dots ('.' and '..')
+	# directories
+	def self.canonicalise_path(path)
+
+		return Recls::Ximpl.canonicalise_path path
+	end
+
+	# Derives a given path relative to an origin, unless the path is
+	# absolute
+	def self.derive_relative_path(origin, path)
+
+		return Recls::Ximpl.derive_relative_path origin, path
+	end
+
+	# Combines paths, optionally canonicalising them
+	#
+	def self.combine_paths(origin, path, options={})
+
+		return Recls::Ximpl.combine_paths origin, path, options
+	end
+end
+
+# ############################## end of file ############################# #
+

data/lib/recls/version.rb

@@ -0,0 +1,53 @@
+# ######################################################################### #
+# File:         recls/version.rb
+#
+# Purpose:      Version for recls library
+#
+# Created:      14th February 2014
+# Updated:      31st May 2016
+#
+# Author:       Matthew Wilson
+#
+# Copyright (c) 2012-2016, 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.
+#
+# ######################################################################### #
+
+
+module Recls
+
+	# Current version of the recls.Ruby library
+	VERSION				=	'2.6.4'
+
+	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
+
+# ############################## end of file ############################# #
+

data/lib/recls/ximpl/os.rb

@@ -0,0 +1,85 @@
+# ######################################################################### #
+# File:        recls/ximpl/os.rb
+#
+# Purpose:     Operating system internal implementation constructs for the
+#              recls library.
+#
+# Created:     16th February 2014
+# Updated:     27th August 2015
+#
+# Author:      Matthew Wilson
+#
+# Copyright (c) 2012-2015, 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.
+#
+# ######################################################################### #
+
+
+module Recls
+
+	module Ximpl
+
+		module OS
+
+			OS_IS_WINDOWS = (RUBY_PLATFORM =~ /(mswin|mingw|bccwin|wince)/i) ? true : false
+
+			PATH_NAME_SEPARATOR = OS_IS_WINDOWS ? '\\' : '/'
+
+			PATH_SEPARATOR = OS_IS_WINDOWS ? ';' : ':'
+
+			WILDCARDS_ALL = OS_IS_WINDOWS ? '*' : '*'
+
+			def OS.get_number_of_dots_dir_(p)
+
+				if p
+					if ?. == p[0]
+						return 1 if 1 == p.size
+						return 1 if ?/ == p[1]
+						return 1 if OS_IS_WINDOWS and ?\\ == p[1]
+						if ?. == p[1]
+							return 2 if 2 == p.size
+							return 2 if ?/ == p[2]
+							return 2 if OS_IS_WINDOWS and ?\\ == p[2]
+						end
+					end
+				end
+
+				return 0
+			end
+
+			def OS.is_root_dir_(p)
+
+				return nil if not p
+				return true if '/' == p
+				return true if OS_IS_WINDOWS and '\\' == p
+
+				return false
+			end
+		end
+	end
+end
+
+# ############################## end of file ############################# #
+

data/lib/recls/ximpl/unix.rb

@@ -0,0 +1,81 @@
+# ######################################################################### #
+# File:        recls/ximpl/unix.rb
+#
+# Purpose:     UNIX-specific constructs for the recls library.
+#
+# Created:     19th February 2014
+# Updated:     27th August 2015
+#
+# Author:      Matthew Wilson
+#
+# Copyright (c) 2012-2015, 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.
+#
+# ######################################################################### #
+
+
+require 'recls/ximpl/util'
+
+module Recls
+
+	module Ximpl
+
+		class FileStat < File::Stat
+
+			private
+			def initialize(path)
+
+				@path = path
+
+				super(path)
+			end
+
+			public
+			attr_reader :path
+
+			def hidden?
+
+				basename = File.basename @path
+
+				return false if basename.empty?
+				return false if '.' == basename
+				return false if '..' == basename
+				return false if ?. != basename[0]
+
+				return true
+			end
+
+			public
+			def FileStat.stat(path)
+
+				Recls::Ximpl::FileStat.new(path)
+
+			end
+		end
+	end
+end
+
+# ############################## end of file ############################# #
+

data/lib/recls/ximpl/util.rb

@@ -0,0 +1,650 @@
+# ######################################################################### #
+# File:        recls/ximpl/util.rb
+#
+# Purpose:     Internal implementation constructs for the recls library.
+#
+# Created:     24th July 2012
+# Updated:     20th December 2015
+#
+# Author:      Matthew Wilson
+#
+# Copyright (c) 2012-2015, 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.
+#
+# ######################################################################### #
+
+
+require 'recls/ximpl/os'
+require 'recls/flags'
+
+require 'pathname'
+
+module Recls
+
+	module Ximpl
+
+		module Util
+
+			def self.is_path_name_separator(c)
+
+				return true if ?/ == c
+
+				if Recls::Ximpl::OS::OS_IS_WINDOWS
+					return true if ?\\ == c
+				end
+
+				return false
+			end
+
+			# Indicates whether a trailing slash is on the given path
+			#
+			# dependencies: none
+			def self.has_trailing_slash(p)
+
+				return p if p.nil? or p.empty?
+
+				return self.is_path_name_separator(p[-1])
+			end
+
+			# returns the trailing slash, or nil if none present
+			#
+			# dependencies: none
+			def self.get_trailing_slash(p, args = {})
+
+				return nil if p.nil?
+				return nil if p.empty?
+
+				return self.is_path_name_separator(p[-1]) ? p[-1] : nil
+			end
+
+			# appends trailing slash to a path if not already
+			# present
+			#
+			# dependencies: none
+			def self.append_trailing_slash(p, slash = nil)
+
+				return p if not p or p.empty?
+
+				return p if self.is_path_name_separator(p[-1])
+
+				slash = '/' if not slash
+
+				"#{p}#{slash}"
+			end
+
+			# trims trailing slash from a path, unless it is the
+			# root
+			#
+			# dependencies: none
+			def self.trim_trailing_slash(p)
+
+				return p if not p or p.empty?
+
+				p = p[0 ... -1] if self.is_path_name_separator(p[-1])
+
+				return p
+			end
+
+			# From path p, returns a tuple containing either:
+			#
+			#  [ nil, p ] if p does not contain a Windows root, or
+			#
+			#  [ wroot, remainder ] if p does contain a Windows root, or
+			#
+			#  [ nil, nil ] if p is nil
+			#
+			# dependencies: none
+			def self.get_windows_root(p)
+
+				return [ nil, nil ] if not p
+
+				if Recls::Ximpl::OS::OS_IS_WINDOWS
+
+					# Windows local drive (e.g. 'H:')
+					#
+					# NOTE: this works for both rooted and unrooted paths
+					if p =~ /^([a-zA-Z]:)/
+						return [ $1, $' ]
+					end
+
+					# UNC network drive
+					#
+					# NOTE: there are several permutations ...
+					if p =~ /^(\\\\[^\\\/:*?<>|]+\\[^\\\/:*?<>|]+)([\\\/].*)$/
+						# \\server\share{\{... rest of path}}
+						return [ $1, $2 ]
+					end
+					if p =~ /^(\\\\[^\\\/:*?<>|]+\\[^\\\/:*?<>|]+)$/
+						# \\server\share
+						return [ $1, nil ]
+					end
+					if p =~ /^(\\\\[^\\\/:*?<>|]+\\)$/
+						# \\server\
+						return [ $1, nil ]
+					end
+					if p =~ /^(\\\\[^\\\/:*?<>|]+)$/
+						# \\server
+						return [ $1, nil ]
+					end
+				end
+
+				return [ nil, p ]
+			end
+
+			# obtains the parts from a path, including any Windows root and
+			# the file basename
+			def self.path_parts(path)
+
+				return nil if path.nil?
+				return [] if path.empty?
+
+				parts = []
+
+				wr, rem =  self.get_windows_root(path)
+
+				parts << wr if wr
+
+				until rem.nil? || rem.empty?
+					if rem =~ /^([^\\\/]*[\\\/])/
+						parts << $1
+						rem = $'
+					else
+						parts << rem
+						rem = ''
+					end
+				end
+
+				parts
+			end
+
+			# Returns a tuple consisting of the following
+			# elements (or nil, for any element that is not)
+			# present
+			#
+			# f1. Windows root, or nil
+			# f2. directory, or nil
+			# f3. basename, or nil
+			# f4. basename-minus-extension, or nil
+			# f5. extension, or nil
+			# f6. array of directory path parts, which may be empty (not nil)
+			# f7. array of all path parts, which may be empty (not nil)
+			#
+			# dependencies: Util.path_parts, Util.get_windows_root
+			def self.split_path(p)
+
+				f1_windows_root, remainder = self.get_windows_root p
+				f1_windows_root = nil if not f1_windows_root or f1_windows_root.empty?
+				remainder = nil if not remainder or remainder.empty?
+
+				if not remainder or remainder.empty?
+					f2_directory = nil
+					f3_basename = nil
+					f4_nameonly = nil
+					f5_extension = nil
+				else
+					if remainder =~ /^(.*[\\\/])([^\\\/]*)$/
+						f2_directory = $1
+						f3_basename = $2
+					else
+						f2_directory = nil
+						f3_basename = remainder
+						f4_nameonly = nil
+						f5_extension = nil
+					end
+
+					f2_directory = nil if not f2_directory or f2_directory.empty?
+					f3_basename = nil if not f3_basename or f3_basename.empty?
+
+					if f3_basename
+						# special case: treat '.' and '..' as file-name only
+						if '.' == f3_basename or '..' == f3_basename
+							f4_nameonly = f3_basename
+							f5_extension = nil
+						elsif f3_basename =~ /^(.*)(\.[^.]*)$/
+							f4_nameonly = $1
+							f5_extension = $2
+						else
+							f4_nameonly = f3_basename
+							f5_extension = nil
+						end
+					else
+						f4_nameonly = nil
+						f5_extension = nil
+					end
+				end
+
+				f4_nameonly = nil if not f4_nameonly or f4_nameonly.empty?
+				f5_extension = nil if not f5_extension or f5_extension.empty?
+				f6_directory_parts = self.path_parts(f2_directory)
+				f7_path_parts = self.path_parts(p)
+
+				return [ f1_windows_root, f2_directory, f3_basename, f4_nameonly, f5_extension, f6_directory_parts, f7_path_parts ]
+			end
+
+			# Returns a tuple consisting of:
+			#
+			# f1. The canonicalised array of parts
+			# f2. A boolean indicating whether to 'consume' the basename
+			#
+			# dependencies: OS.is_root_dir_, OS.get_number_of_dots_dir_,
+			def self.canonicalise_parts(parts, basename = nil)
+
+				newParts = []
+
+				trailing_slash = parts.empty? ? nil : self.get_trailing_slash(parts[-1])
+
+				lastSingleDots = nil
+
+				path_is_rooted = nil
+
+				index = -1
+				parts.each do |part|
+
+					index += 1
+
+					next if not part
+					next if part.empty?
+
+					if path_is_rooted.nil?
+						path_is_rooted = self.is_path_name_separator(part[0])
+					end
+
+					if ?. == part[0]
+						if self.is_path_name_separator(part[1])
+							# single dots, so ...
+
+							# ... remember the last instance, and ...
+							lastSingleDots = part
+
+							# ... skip to leave this out of the result
+							next
+						elsif ?. == part[1]
+							if self.is_path_name_separator(part[2])
+								# double dots, so ...
+								# ... skip this and pop prior from the new list iff:
+								#
+								# 1. there is a prior elements in the new list (size > 1); AND
+								# 2. the last element in the new list is not the root directory; AND
+								# 3. the last element in the list is not a dots directory
+								if not newParts.empty? # 1.
+									priorPart = newParts[-1]
+									if 1 == newParts.size and OS.is_root_dir_(priorPart)
+										# 2.
+										next
+									else
+										dirtype = OS.get_number_of_dots_dir_(priorPart)
+										if 0 == dirtype # 3.
+											if newParts.pop
+												next
+											end
+										end
+									end
+								end
+							else
+								# it's a ..X part
+							end
+						else
+							# it's a .X part
+						end
+					else
+						# it's a non-dots part
+					end
+
+					newParts << part
+				end
+
+				consume_basename = false
+
+				if basename
+					if ?. == basename[0]
+						if 1 == basename.size
+							# single dots
+							if newParts.empty?
+								lastSingleDots = false
+							else
+								consume_basename = true
+							end
+						elsif ?. == basename[1] and 2 == basename.size
+							# double dots, so ...
+							#
+							# ... pop unless we already have some outstanding double dots
+							if newParts.empty?
+								newParts << '..'
+								consume_basename = true
+							elsif 1 == newParts.size && 1 == newParts[0].size && Util.is_path_name_separator(newParts[0][0])
+								consume_basename = true
+							else
+								if 2 != OS.get_number_of_dots_dir_(newParts[-1])
+									newParts.pop
+									consume_basename = true
+								end
+							end
+						end
+					end
+				end
+
+				# push lastSingleDots (which may contain a trailing slash) if
+				# exists and newParts is empty
+				newParts << lastSingleDots if lastSingleDots and newParts.empty?
+
+				if not newParts.empty?
+					if 2 == OS.get_number_of_dots_dir_(newParts[-1])
+						# the last element is the double-dots directory, but
+						# need to determine whether to ensure/remote a
+						# trailing slash
+						if basename and not basename.empty?
+							if not consume_basename
+								# leave as is
+							else
+								# 
+								newParts[-1] = '..'
+							end
+						end
+					end
+				else
+					# handle case where all (double)-dots have eliminated
+					# all regular directories
+					if not basename or basename.empty? or consume_basename
+						newParts << '.'
+					end
+				end
+
+				[ newParts.join(''), consume_basename ]
+			end
+		end
+
+		# Canonicalises a path
+		#
+		# Note: contains a trailing slash if, in the context of the given
+		# path, the last element of the canonicalised path is a directory
+		# unequivocally
+		def self.canonicalise_path(path)
+
+			return nil if not path
+			return '' if path.empty?
+
+			f1_windows_root, f2_directory, f3_basename, dummy1, dummy2, directory_parts, dummy3 = Util.split_path(path)
+
+			if not f2_directory
+				canonicalised_directory = nil
+			else
+				canonicalised_directory, consume_basename = Util.canonicalise_parts(directory_parts, f3_basename)
+				f3_basename = nil if consume_basename
+			end
+
+			return "#{f1_windows_root}#{canonicalised_directory}#{f3_basename}"
+		end
+
+		# determines the absolute path of a given path
+		def self.absolute_path(path, refdir = nil)
+
+			case path
+			when ::NilClass
+				return nil
+			when ::String
+			when ::Recls::Entry
+				path = path.to_s
+			else
+				raise TypeError, "parameter path ('#{path}') is of type #{path.class} must be an instance of #{::String} or #{::Recls::Entry}"
+			end
+
+			return '' if path.empty?
+
+			f1_windows_root, f2_directory, f3_basename, dummy1, dummy2, dummy3, dummy4 = Util.split_path(path)
+
+			if f2_directory =~ /^[\\\/]/
+				return path
+			end
+
+			cwd = refdir ? refdir : Dir.getwd
+
+			trailing_slash = Util.get_trailing_slash(path)
+
+			if '.' == path
+				return Util.trim_trailing_slash cwd
+			elsif 2 == path.size and trailing_slash
+				return Util.append_trailing_slash(cwd, path[1..1])
+			end
+
+			cwd = Util.append_trailing_slash(cwd)
+
+			path = "#{cwd}#{path}"
+
+			path = canonicalise_path path
+
+			if trailing_slash
+				path = Util.append_trailing_slash path, trailing_slash
+			else
+				path = Util.trim_trailing_slash path
+			end
+
+			path
+		end
+
+		# obtains the basename of a path, e.g.
+		# the basename of
+		#  abc/def/ghi.jkl
+		# or (on Windows)
+		#  C:\abc\def\ghi.jkl
+		# is
+		#  ghi.jkl
+		#
+		def self.basename(path)
+
+			return nil if not path
+
+			# NOTE: we don't implement in terms of split_path
+			# because all but the UNC case work with just
+			# detecting the last (back)slash
+
+			if Recls::Ximpl::OS::OS_IS_WINDOWS
+				wr, rem = Util.get_windows_root(path)
+
+				if not rem
+					return ''
+				else
+					path = rem
+				end
+			end
+
+			if not path.is_a? String
+				path = path.to_s
+			end
+
+			if path =~ /^.*[\/\\](.*)/
+				$1
+			else
+				path
+			end
+		end
+
+		# obtains the file extension of a basename, e.g.
+		# the file_ext of
+		#  ghi.jkl
+		# is
+		#  .jkl
+		def self.file_ext(path)
+
+			return nil if not path
+
+			use_split_path = false
+
+			if Recls::Ximpl::OS::OS_IS_WINDOWS
+				if path.include? ?\\
+					use_split_path = true
+				end
+			end
+
+			if path.include? ?/
+				use_split_path = true
+			end
+
+			if use_split_path
+				ext = Util.split_path(path)[4]
+			else
+				if path =~ /^.*(\.[^.]*)$/
+					ext = $1
+				else
+					ext = nil
+				end
+			end
+
+			return ext ? ext : ''
+		end
+
+		# obtains the directory from the directory path
+		#
+		def self.directory_from_directory_path(directory_path)
+
+			wr, rem =  Util.get_windows_root(directory_path)
+
+			rem
+		end
+
+		# obtains the directory parts from a directory
+		def self.directory_parts_from_directory(directory)
+
+			return nil if not directory
+
+			directory_parts = []
+
+			until directory.empty?
+				if directory =~ /^([^\\\/]*[\\\/])/
+					directory_parts << $1
+					directory = $'
+				else
+					directory_parts << directory
+					directory = ''
+				end
+			end
+
+			directory_parts
+		end
+
+		# obtains the relative path of a given path and
+		# a reference directory
+		def self.derive_relative_path(origin, path)
+
+			return nil if path.nil?
+			return nil if path.empty?
+			return path if origin.nil?
+			return path if origin.empty?
+
+			path			=	self.canonicalise_path path
+			origin			=	self.canonicalise_path origin
+
+			path_splits		=	Util.split_path(path)
+			origin_splits	=	Util.split_path(origin)
+
+			# if different windows root, then cannot provide relative
+			if path_splits[0] and origin_splits[0]
+				return path if path_splits[0] != origin_splits[0]
+			end
+
+			trailing_slash	=	Util.get_trailing_slash(path)
+
+			path_parts		=	path_splits[6]
+			origin_parts	=	origin_splits[6]
+
+			while true
+
+				break if path_parts.empty?
+				break if origin_parts.empty?
+
+				path_part	=	path_parts[0]
+				origin_part	=	origin_parts[0]
+
+				if 1 == path_parts.size || 1 == origin_parts.size
+					path_part	=	Util.append_trailing_slash(path_part)
+					origin_part	=	Util.append_trailing_slash(origin_part)
+				end
+
+				if path_part == origin_part
+					path_parts.shift
+					origin_parts.shift
+				else
+					break
+				end
+			end
+
+			return ".#{trailing_slash}" if path_parts.empty? and origin_parts.empty?
+
+			# at this point, all reference parts should be converted into '..'
+
+			return origin_parts.map { |rp| '..' }.join('/') if path_parts.empty?
+
+			return '../' * origin_parts.size + path_parts.join('')
+		end
+
+
+		def self.combine_paths(origin, path, options)
+
+			f1_windows_root, f2_directory, f3_basename, dummy1, dummy2, dummy3, dummy4 = Util.split_path(path)
+
+#			return path if f1_windows_root
+			return path if f2_directory && Util.is_path_name_separator(f2_directory[0])
+
+			r	=	File.join origin, path
+
+			if options[:clean_path]
+
+				r = Pathname.new(r).cleanpath
+			end
+
+			r
+		end
+
+
+		# Elicits the contents of the given directory, or, if the flag
+		# STOP_ON_ACCESS_FAILURE is specified throws an exception if the
+		# directory does not exist
+		#
+		# Some known conditions:
+		#
+		# * (Mac OSX) /dev/fd/<N> - some of these stat() as directories but
+		#    Dir.new fails with ENOTDIR
+		#
+		def self.dir_entries_maybe(dir, flags)
+
+			begin
+
+				Dir.new(dir).to_a
+
+			rescue SystemCallError => x
+
+				# TODO this should be filtered up and/or logged
+
+				if(0 != (STOP_ON_ACCESS_FAILURE & flags))
+					raise
+				end
+
+				return []
+			end
+		end
+	end
+end
+
+# ############################## end of file ############################# #
+