recls-ruby 2.8.2 → 2.11.0

data/lib/recls/ximpl/util.rb

@@ -1,14 +1,14 @@
 # ######################################################################### #
-# File:        recls/ximpl/util.rb
+# File:         recls/ximpl/util.rb
 #
-# Purpose:     Internal implementation constructs for the recls library.
+# Purpose:      Internal implementation constructs for the recls library.
 #
-# Created:     24th July 2012
-# Updated:     25th January 2018
+# Created:      24th July 2012
+# Updated:      14th April 2019
 #
-# Author:      Matthew Wilson
+# Author:       Matthew Wilson
 #
-# Copyright (c) 2012-2018, 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
@@ -41,13 +41,19 @@ require 'recls/flags'
 
 require 'pathname'
 
-module Recls
+=begin
+=end
+
+module Recls # :nodoc:
 
-	module Ximpl
+# :stopdoc:
 
-		module Util
+	module Ximpl # :nodoc: all
 
-			def self.is_path_name_separator(c)
+		module Util # :nodoc: all
+
+			# @!visibility private
+			def self.is_path_name_separator(c) # :nodoc:
 
 				return true if ?/ == c
 
@@ -62,7 +68,9 @@ module Recls
 			# Indicates whether a trailing slash is on the given path
 			#
 			# dependencies: none
-			def self.has_trailing_slash(p)
+			#
+			# @!visibility private
+			def self.has_trailing_slash(p) # :nodoc:
 
 				return p if p.nil? or p.empty?
 
@@ -72,7 +80,9 @@ module Recls
 			# returns the trailing slash, or nil if none present
 			#
 			# dependencies: none
-			def self.get_trailing_slash(p, args = {})
+			#
+			# @!visibility private
+			def self.get_trailing_slash(p, args = {}) # :nodoc:
 
 				return nil if p.nil?
 				return nil if p.empty?
@@ -84,7 +94,9 @@ module Recls
 			# present
 			#
 			# dependencies: none
-			def self.append_trailing_slash(p, slash = nil)
+			#
+			# @!visibility private
+			def self.append_trailing_slash(p, slash = nil) # :nodoc:
 
 				return p if not p or p.empty?
 
@@ -99,7 +111,9 @@ module Recls
 			# root
 			#
 			# dependencies: none
-			def self.trim_trailing_slash(p)
+			#
+			# @!visibility private
+			def self.trim_trailing_slash(p) # :nodoc:
 
 				return p if not p or p.empty?
 
@@ -117,7 +131,9 @@ module Recls
 			#  [ nil, nil ] if p is nil
 			#
 			# dependencies: none
-			def self.get_windows_root(p)
+			#
+			# @!visibility private
+			def self.get_windows_root(p) # :nodoc:
 
 				return [ nil, nil ] if not p
 
@@ -161,7 +177,9 @@ module Recls
 
 			# obtains the parts from a path, including any Windows root and
 			# the file basename
-			def self.path_parts(path)
+			#
+			# @!visibility private
+			def self.path_parts(path) # :nodoc:
 
 				return nil if path.nil?
 				return [] if path.empty?
@@ -201,7 +219,9 @@ module Recls
 			# 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)
+			#
+			# @!visibility private
+			def self.split_path(p) # :nodoc:
 
 				f1_windows_root, remainder = self.get_windows_root p
 				f1_windows_root = nil if not f1_windows_root or f1_windows_root.empty?
@@ -267,14 +287,12 @@ module Recls
 			# 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)
+			#
+			# @!visibility private
+			def self.canonicalise_parts(parts, basename = nil) # :nodoc:
 
 				newParts = []
 
-=begin
-				trailing_slash = parts.empty? ? nil : self.get_trailing_slash(parts[-1])
-=end
-
 				lastSingleDots = nil
 
 				path_is_rooted = nil
@@ -423,18 +441,22 @@ module Recls
 
 				[ newParts.join(''), consume_basename ]
 			end
-		end
+		end # module Util
 
 		# 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)
+		#
+		# @!visibility private
+		def self.canonicalise_path(path) # :nodoc:
 
 			return nil if not path
 			return '' if path.empty?
 
+			path	=	File.expand_path(path) if '~' == path[0].to_s
+
 			f1_windows_root, f2_directory, f3_basename, dummy1, dummy2, directory_parts, dummy3 = Util.split_path(path)
 
 			# suppress unused warnings
@@ -454,18 +476,58 @@ module Recls
 			return "#{f1_windows_root}#{canonicalised_directory}#{f3_basename}"
 		end
 
+		# @!visibility private
+		def self.absolute_path?(path) # :nodoc:
+
+			case path
+			when nil
+
+				return nil
+			when ::String
+
+				return nil if path.empty?
+
+				path	=	File.expand_path(path) if '~' == path[0]
+			when ::Recls::Entry
+
+				return path
+			else
+
+				raise TypeError, "parameter path ('#{path}') is of type #{path.class} must be nil or an instance of #{::String} or #{::Recls::Entry}"
+			end
+
+			f1_windows_root, f2_directory, dummy1, dummy2, dummy3, dummy4, dummy5 = Util.split_path(path)
+
+			dummy1 = dummy2 = dummy3 = dummy4 = dummy5 = nil
+
+			unless f1_windows_root
+
+				return nil unless f2_directory
+
+				return nil unless Util.is_path_name_separator(f2_directory[0])
+			end
+
+			Recls::Ximpl.stat_prep(path, nil, Recls::DETAILS_LATER)
+		end
+
 		# determines the absolute path of a given path
-		def self.absolute_path(path, refdir = nil)
+		#
+		# @!visibility private
+		def self.absolute_path(path, refdir = nil) # :nodoc:
 
 			case path
 			when ::NilClass
+
 				return nil
 			when ::String
+
+				path	=	File.expand_path(path) if '~' == path[0]
 			when ::Recls::Entry
-				path = path.to_s
+
+				return path.path
 			else
 
-				raise TypeError, "parameter path ('#{path}') is of type #{path.class} must be an instance of #{::String} or #{::Recls::Entry}"
+				raise TypeError, "parameter path ('#{path}') is of type #{path.class} must be an instance of #{::String} or Recls::Entry"
 			end
 
 			return '' if path.empty?
@@ -522,7 +584,8 @@ module Recls
 		# is
 		#  ghi.jkl
 		#
-		def self.basename(path)
+		# @!visibility private
+		def self.basename(path) # :nodoc:
 
 			return nil if not path
 
@@ -565,7 +628,9 @@ module Recls
 		#  ghi.jkl
 		# is
 		#  .jkl
-		def self.file_ext(path)
+		#
+		# @!visibility private
+		def self.file_ext(path) # :nodoc:
 
 			return nil if not path
 
@@ -603,7 +668,8 @@ module Recls
 
 		# obtains the directory from the directory path
 		#
-		def self.directory_from_directory_path(directory_path)
+		# @!visibility private
+		def self.directory_from_directory_path(directory_path) # :nodoc:
 
 			wr, rem =  Util.get_windows_root(directory_path)
 
@@ -614,7 +680,9 @@ module Recls
 		end
 
 		# obtains the directory parts from a directory
-		def self.directory_parts_from_directory(directory)
+		#
+		# @!visibility private
+		def self.directory_parts_from_directory(directory) # :nodoc:
 
 			return nil if not directory
 
@@ -638,7 +706,9 @@ module Recls
 
 		# obtains the relative path of a given path and
 		# a reference directory
-		def self.derive_relative_path(origin, path)
+		#
+		# @!visibility private
+		def self.derive_relative_path(origin, path) # :nodoc:
 
 			return nil if path.nil?
 			return nil if path.empty?
@@ -648,10 +718,16 @@ module Recls
 			path			=	self.canonicalise_path path
 			origin			=	self.canonicalise_path origin
 
+			path			=	self.absolute_path path
+			origin			=	self.absolute_path origin
+
+			return path if /^\.[\\\/]*$/ =~ 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]
@@ -662,7 +738,7 @@ module Recls
 			path_parts		=	path_splits[6]
 			origin_parts	=	origin_splits[6]
 
-			while true
+			loop do
 
 				break if path_parts.empty?
 				break if origin_parts.empty?
@@ -695,12 +771,14 @@ module Recls
 			return '../' * origin_parts.size + path_parts.join('')
 		end
 
-
-		def self.combine_paths(paths, options)
+		# @!visibility private
+		def self.combine_paths(paths, options) # :nodoc:
 
 			paths	=	[ paths ] unless ::Array === paths
 			abs_ix	=	0
 
+			paths	=	paths.map { |path| '~' == path[0].to_s ? File.expand_path(path) : path }
+
 			paths.each_with_index do |path, index|
 
 				dummy1, f2_directory, dummy2, dummy3, dummy4, dummy5, dummy6 = Util.split_path(path)
@@ -721,7 +799,7 @@ module Recls
 
 			paths	=	paths[abs_ix..-1]
 
-			r		=	File.join *paths
+			r		=	File.join(*paths)
 
 			cap	=	options[:canonicalise] || options[:canonicalize]
 
@@ -751,7 +829,8 @@ module Recls
 		# * (Mac OSX) /dev/fd/<N> - some of these stat() as directories but
 		#    Dir.new fails with ENOTDIR
 		#
-		def self.dir_entries_maybe(dir, flags)
+		# @!visibility private
+		def self.dir_entries_maybe(dir, flags) # :nodoc:
 
 			begin
 
@@ -769,8 +848,31 @@ module Recls
 				return []
 			end
 		end
-	end
-end
+
+		# @!visibility private
+		def self.stat_prep(path, search_root, flags) # :nodoc:
+
+			begin
+
+				Recls::Entry.new(path, Recls::Ximpl::FileStat.stat(path), search_root, flags)
+			rescue Errno::ENOENT, Errno::ENXIO => 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 # module Ximpl
+
+# :startdoc:
+
+end # module Recls
 
 # ############################## end of file ############################# #
 

data/lib/recls/ximpl/windows.rb

@@ -1,14 +1,14 @@
 # ######################################################################### #
-# File:        recls/ximpl/windows.rb
+# File:         recls/ximpl/windows.rb
 #
-# Purpose:     Windows-specific constructs for the recls library.
+# Purpose:      Windows-specific constructs for the recls library.
 #
-# Created:     19th February 2014
-# Updated:     18th June 2016
+# Created:      19th February 2014
+# Updated:      14th April 2019
 #
-# Author:      Matthew Wilson
+# 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,11 +38,17 @@
 
 require 'Win32API'
 
-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
 			GetFileAttributes			=	Win32API.new('kernel32', 'GetFileAttributes', [ 'P' ], 'I')
@@ -70,9 +76,11 @@ module Recls
 
 			BHFI_pack_string			=	'LQQQLLLLLL'
 
-			class ByHandleInformation
+			# @!visibility private
+			class ByHandleInformation # :nodoc:
 
-				def initialize(path)
+				# @!visibility private
+				def initialize(path) # :nodoc:
 
 					@volume_id	=	0
 					@file_index	=	0
@@ -101,19 +109,24 @@ module Recls
 					end
 				end
 
+				# @!visibility private
 				attr_reader :volume_id
+				# @!visibility private
 				attr_reader :file_index
+				# @!visibility private
 				attr_reader :num_links
 			end
 
 			private
-			def has_attribute_? (attr)
+			# @!visibility private
+			def has_attribute_? (attr) # :nodoc:
 
 				0 != (attr & @attributes)
 			end
 
 			private
-			def initialize(path)
+			# @!visibility private
+			def initialize(path) # :nodoc:
 
 				@path = path
 
@@ -121,8 +134,10 @@ module Recls
 				attributes = GetFileAttributes.call("#{path}")
 
 				if 0xffffffff == attributes
+
 					@attributes = 0
 				else
+
 					@attributes = attributes
 				end
 
@@ -137,62 +152,78 @@ module Recls
 			end
 
 			public
+			# @!visibility private
 			attr_reader :attributes
+			# @!visibility private
 			attr_reader :path
+			# @!visibility private
 			attr_reader :by_handle_information
+			# @!visibility private
 			attr_reader :short_path
 
-			def hidden?
+			# @!visibility private
+			def hidden? # :nodoc:
 
 				0 != (FILE_ATTRIBUTE_HIDDEN & @attributes)
 			end
 
 			# Windows-specific attributes
 
-			def system?
+			# @!visibility private
+			def system? # :nodoc:
 
 				has_attribute_? FILE_ATTRIBUTE_SYSTEM
 			end
 
-			def archive?
+			# @!visibility private
+			def archive? # :nodoc:
 
 				has_attribute_? FILE_ATTRIBUTE_ARCHIVE
 			end
 
-			def device?
+			# @!visibility private
+			def device? # :nodoc:
 
 				has_attribute_? FILE_ATTRIBUTE_DEVICE
 			end
 
-			def normal?
+			# @!visibility private
+			def normal? # :nodoc:
 
 				has_attribute_? FILE_ATTRIBUTE_NORMAL
 			end
 
-			def temporary?
+			# @!visibility private
+			def temporary? # :nodoc:
 
 				has_attribute_? FILE_ATTRIBUTE_TEMPORARY
 			end
 
-			def compressed?
+			# @!visibility private
+			def compressed? # :nodoc:
 
 				has_attribute_? FILE_ATTRIBUTE_COMPRESSED
 			end
 
-			def encrypted?
+			# @!visibility private
+			def encrypted? # :nodoc:
 
 				has_attribute_? FILE_ATTRIBUTE_ENCRYPTED
 			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 ############################# #