recls-ruby 2.9.1 → 2.10.0

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,42 @@ 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?
+
+		Recls::Ximpl.absolute_path? path
+	end
+end # module Recls
+
 # ############################## end of file ############################# #
 
 

data/lib/recls/version.rb

@@ -4,7 +4,7 @@
 # Purpose:      Version for recls library
 #
 # Created:      14th February 2014
-# Updated:      10th April 2018
+# Updated:      14th April 2019
 #
 # Author:       Matthew Wilson
 #
@@ -36,10 +36,15 @@
 # ######################################################################### #
 
 
+=begin
+=end
+
+class Object; end # :nodoc:
+
 module Recls
 
 	# Current version of the recls.Ruby library
-	VERSION				=	'2.9.1'
+	VERSION				=	'2.10.0'
 
 	private
 	VERSION_PARTS_		=	VERSION.split(/[.]/).collect { |n| n.to_i } # :nodoc:
@@ -47,7 +52,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,15 @@
 # ######################################################################### #
-# 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:      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
@@ -37,11 +37,14 @@
 # ######################################################################### #
 
 
-module Recls
+=begin
+=end
 
-	module Ximpl
+module Recls # :nodoc:
 
-		module OS
+	module Ximpl # :nodoc: all
+
+		module OS # :nodoc: all
 
 			OS_IS_WINDOWS = (RUBY_PLATFORM =~ /(mswin|mingw|bccwin|wince)/i) ? true : false
 
@@ -77,9 +80,9 @@ module Recls
 
 				return false
 			end
-		end
-	end
-end
+		end # module OS
+	end # module Ximpl
+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,11 +38,14 @@
 
 require 'recls/ximpl/util'
 
-module Recls
+=begin
+=end
 
-	module Ximpl
+module Recls # :nodoc:
 
-		class FileStat < File::Stat
+	module Ximpl # :nodoc: all
+
+		class FileStat < File::Stat # :nodoc:
 
 			private
 			def initialize(path)
@@ -73,9 +76,9 @@ module Recls
 				Recls::Ximpl::FileStat.new(path)
 
 			end
-		end
-	end
-end
+		end # class FileStat
+	end # module Ximpl
+end # module Recls
 
 # ############################## end of file ############################# #
 

data/lib/recls/ximpl/util.rb

@@ -1,12 +1,12 @@
 # ######################################################################### #
-# 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:     21st Jannuary 2019
+# Created:      24th July 2012
+# Updated:      14th April 2019
 #
-# Author:      Matthew Wilson
+# Author:       Matthew Wilson
 #
 # Copyright (c) 2012-2019, Matthew Wilson and Synesis Software
 # All rights reserved.
@@ -41,11 +41,14 @@ require 'recls/flags'
 
 require 'pathname'
 
-module Recls
+=begin
+=end
+
+module Recls # :nodoc:
 
-	module Ximpl
+	module Ximpl # :nodoc: all
 
-		module Util
+		module Util # :nodoc: all
 
 			def self.is_path_name_separator(c)
 
@@ -271,10 +274,6 @@ module Recls
 
 				newParts = []
 
-=begin
-				trailing_slash = parts.empty? ? nil : self.get_trailing_slash(parts[-1])
-=end
-
 				lastSingleDots = nil
 
 				path_is_rooted = nil
@@ -423,7 +422,7 @@ module Recls
 
 				[ newParts.join(''), consume_basename ]
 			end
-		end
+		end # module Util
 
 		# Canonicalises a path
 		#
@@ -435,6 +434,8 @@ module Recls
 			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,6 +455,39 @@ module Recls
 			return "#{f1_windows_root}#{canonicalised_directory}#{f3_basename}"
 		end
 
+		def self.absolute_path?(path)
+
+			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)
 
@@ -463,7 +497,10 @@ module Recls
 				return nil
 			when ::String
 
-				path = path.to_s
+				path	=	File.expand_path(path) if '~' == path[0]
+			when ::Recls::Entry
+
+				return path.path
 			else
 
 				raise TypeError, "parameter path ('#{path}') is of type #{path.class} must be an instance of #{::String} or Recls::Entry"
@@ -649,10 +686,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]
@@ -663,7 +706,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?
@@ -702,6 +745,8 @@ module Recls
 			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)
@@ -770,8 +815,27 @@ module Recls
 				return []
 			end
 		end
-	end
-end
+
+		def self.stat_prep(path, search_root, flags)
+
+			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
+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,14 @@
 
 require 'Win32API'
 
-module Recls
+=begin
+=end
 
-	module Ximpl
+module Recls # :nodoc:
 
-		class FileStat < File::Stat
+	module Ximpl # :nodoc: all
+
+		class FileStat < File::Stat # :nodoc:
 
 			private
 			GetFileAttributes			=	Win32API.new('kernel32', 'GetFileAttributes', [ 'P' ], 'I')
@@ -70,7 +73,7 @@ module Recls
 
 			BHFI_pack_string			=	'LQQQLLLLLL'
 
-			class ByHandleInformation
+			class ByHandleInformation # :nodoc:
 
 				def initialize(path)
 
@@ -121,8 +124,10 @@ module Recls
 				attributes = GetFileAttributes.call("#{path}")
 
 				if 0xffffffff == attributes
+
 					@attributes = 0
 				else
+
 					@attributes = attributes
 				end
 
@@ -190,9 +195,9 @@ module Recls
 
 				Recls::Ximpl::FileStat.new(path)
 			end
-		end
-	end
-end
+		end # class FileStat
+	end # module Ximpl
+end # module Recls
 
 # ############################## end of file ############################# #