Module: Recls

Defined in:
lib/recls/recls.rb,
lib/recls/api.rb,
lib/recls/stat.rb,
lib/recls/util.rb,
lib/recls/util.rb,
lib/recls/entry.rb,
lib/recls/flags.rb,
lib/recls/recls.rb,
lib/recls/foreach.rb,
lib/recls/version.rb,
lib/recls/obsolete.rb,
lib/recls/ximpl/os.rb,
lib/recls/ximpl/unix.rb,
lib/recls/ximpl/util.rb,
lib/recls/file_search.rb,
lib/recls/ximpl/windows.rb,
lib/recls/combine_paths_1.rb,
lib/recls/combine_paths_2plus.rb

Overview

:nodoc:

Defined Under Namespace

Modules: Ximpl Classes: Entry, FileSearch

Constant Summary collapse

FILES =

Specifies that files are to be listed

0x00000001
DIRECTORIES =

Specifies that directories are to be listed

0x00000002
0x00000004
DEVICES =

Specifies that devices are to be listed

0x00000008
TYPEMASK =

Type mask (combination of Recls::FILES, Recls::DIRECTORIES, Recls::LINKS, Recls::DEVICES)

0x000000ff
SHOW_HIDDEN =

Specifies that hidden items are to be shown and hidden directories are to be searched

0x00000100
DIR_PROGRESS =
IGNORED

This for compatibility with recls libraries written in other languages

0x00001000
STOP_ON_ACCESS_FAILURE =

Causes search to terminate if a directory cannot be entered or an entry’s information cannot be stat()‘d

0x00002000
0000004000
NODE_INDEX =
IGNORED

This for compatibility with recls libraries written in other languages

0x00008000
RECURSIVE =

Causes search to operate recursively

0x00010000
DIRECTORY_PARTS =
IGNORED

In previous versions the Recls::Entry#directory_parts property was not obtained (for performance reasons) unless this flag was specified. In current version the parts are always obtained

0x00040000
DETAILS_LATER =

Causes operations (such as Recls::stat()) to obtain a result even when no corresponding file-system entity does not exist

0x00080000
MARK_DIRECTORIES =

Causes the Recls::Entry#path and Recls::Entry#search_relative_path attributes to contain a trailing path-name-separator for directory entries

0x00200000
0x00100000
WILDCARDS_ALL =

Represents the “all” wildcards string for the ambient operating system

Recls::Ximpl::OS::WILDCARDS_ALL
PATH_NAME_SEPARATOR =

The string sequence used to separate names in paths, e.g. “/” on UNIX

Recls::Ximpl::OS::PATH_NAME_SEPARATOR
PATH_SEPARATOR =

The string sequence used to separate paths, e.g. “:” on UNIX

Recls::Ximpl::OS::PATH_SEPARATOR
VERSION =

Current version of the recls.Ruby library

'2.12.0'
VERSION_MAJOR =

:nodoc:

VERSION_PARTS_[0]
VERSION_MINOR =

:nodoc:

VERSION_PARTS_[1]
VERSION_REVISION =

:nodoc:

VERSION_PARTS_[2]

Class Method Summary collapse

Class Method Details

.absolute_path(path) ⇒ Object

Obtains the absolute form of the given path

Signature

  • Parameters:

    • path (String, Recls::Entry) The path

Return

(String) The absolute form of the path



59
60
61
62
63
64
 
# File 'lib/recls/util.rb', line 59

def self.absolute_path(path)

	return path.path if 'Recls::Entry' === path.class.to_s

	Recls::Ximpl.absolute_path path
end

.absolute_path?(path) ⇒ Boolean

Indicates whether the given path is absolute

Signature

  • Parameters:

    • path (String, Recls::Entry) The path

Return

(boolean) true if path is absolute; false otherwise

Returns:

  • (Boolean) 


136
137
138
139
140
141
142
143
 
# File 'lib/recls/util.rb', line 136

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

.canonicalise_path(path) ⇒ Object

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



76
77
78
79
80
81
 
# File 'lib/recls/util.rb', line 76

def self.canonicalise_path(path)

	path = path.path if 'Recls::Entry' === path.class.to_s

	Recls::Ximpl.canonicalise_path path
end

.combine_paths(*paths, **options) ⇒ Object

Combines paths, optionally canonicalising them

Signature

  • Parameters:

    • paths ([ (::String, ::Recls::Entry) ]) Array of 1 or more path elements to be combined

    • options (::Hash) Options that moderate the combination

  • Options:

    • :canonicalise (boolean) Causes the evaluated path to be canonicalised - with Recls.canonicalise_path - before it is returned

    • :clean (boolean) Causes the evaluated path to be cleaned (i.e. sent to cleanpath) before it is returned. Ignored if :canonicalise is specified

    • :clean_path (boolean) Equivalent to :clean, but deprecated and may be removed in a future version

Return

(String) The combined path

Raises:

  • (ArgumentError) 


57
58
59
60
61
62
63
64
65
 
# File 'lib/recls/combine_paths_1.rb', line 57

def self.combine_paths(*paths)

	paths	=	paths.reject { |p| p.nil? }
	paths	=	paths.map { |p| 'Recls::Entry' == p.class.to_s ? p.path : p }

	raise ArgumentError, 'must specify one or more path elements' if paths.empty?

	return Recls::Ximpl.combine_paths paths, {}
end

.derive_relative_path(origin, path) ⇒ Object

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



94
95
96
97
 
# File 'lib/recls/util.rb', line 94

def self.derive_relative_path(origin, path)

	Recls::Ximpl.derive_relative_path origin, path
end

.directory?(path, *args) ⇒ Boolean

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

Returns:

  • (Boolean) 


63
64
65
66
67
68
69
70
71
72
73
 
# File 'lib/recls/stat.rb', line 63

def self.directory?(path, *args)

	fe = self.stat(path, *args)

	if fe

		return nil unless fe.directory?
	end

	fe
end

.exist?(path) ⇒ Boolean

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

Returns:

  • (Boolean) 


120
121
122
123
124
125
 
# File 'lib/recls/util.rb', line 120

def self.exist?(path)

	return nil if path.nil?

	Recls.stat(path)
end

.file?(path, *args) ⇒ Boolean

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

Returns:

  • (Boolean) 


89
90
91
92
93
94
95
96
97
98
99
 
# File 'lib/recls/stat.rb', line 89

def self.file?(path, *args)

	fe = self.stat(path, *args)

	if fe

		return nil unless fe.file?
	end

	fe
end

.file_rsearch(search_root, patterns, options = {}) ⇒ Object

Initialises a FileSearch instance, which acts recursively, as an Enumerable of Recls::Entry

Signature

  • Parameters:

    • search_root (String, Recls::Entry) The root directory of the search. May be nil, in which case the current directory is assumed

    • patterns (String, Array) The pattern(s) for which to search. May be nil, in which case Recls::WILDCARDS_ALL is assumed

    • options (Hash, Integer) Combination of flags (with behaviour as described below for the flags option), or an options hash

  • Options:

    • flags (Integer) Combination of flags - FILES, DIRECTORIES, etc. If the value modulo TYPEMASK is 0, then FILES is assumed. The value RECURSIVE is added by the function, and so need not be added by the caller; it cannot be removed

Return

An instance of a class implementing ::Enumerable whose value type is Recls::Entry



71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
 
# File 'lib/recls/api.rb', line 71

def self.file_rsearch(search_root, patterns, options = {})

	case options
	when ::NilClass

		options	=	{ flags: RECURSIVE }
	when ::Integer

		options	|=	RECURSIVE
	when ::Hash

		flags	=	options[:flags] || 0
		flags	|=	RECURSIVE

		options[:flags]	= flags
	else

		# this is handled by the FileSearch initialiser
	end

	Recls::FileSearch.new(search_root, patterns, options)
end

.file_search(search_root, patterns, options = {}) ⇒ Object

Initialises a FileSearch instance, which acts as an Enumerable of Recls::Entry

Signature

  • Parameters:

    • search_root (String, Recls::Entry) The root directory of the search. May be nil, in which case the current directory is assumed

    • patterns (String, Array) The pattern(s) for which to search. May be nil, in which case Recls::WILDCARDS_ALL is assumed

    • options (Hash, Integer) Combination of flags (with behaviour as described below for the flags option), or an options hash

  • Options:

    • flags (Integer) Combination of flags - FILES, DIRECTORIES, RECURSIVE, etc. If the value modulo TYPEMASK is 0, then FILES is assumed

Return

An instance of a class implementing ::Enumerable whose value type is Recls::Entry



110
111
112
113
 
# File 'lib/recls/api.rb', line 110

def self.file_search(search_root, patterns, options = {})

	Recls::FileSearch.new(search_root, patterns, options)
end

.FileSearch(search_root, patterns, options = {}) ⇒ Object

DEPRECATED

Use Recls::file_search()



50
51
52
53
 
# File 'lib/recls/api.rb', line 50

def self.FileSearch(search_root, patterns, options = {})

	Recls::FileSearch.new(search_root, patterns, options)
end

.foreach(*args, &block) ⇒ Object

Performs a recursive search and enumerates the lines of all files found

Signature

  • Parameters:

    • searchable A searchable instance obtained from Recls::file_search() or Recls::file_rsearch()

    • search_root (String, Recls::Entry) The root directory of the search. May be nil, in which case the current directory is assumed

    • patterns (String, Array) The pattern(s) for which to search. May be nil, in which case Recls::WILDCARDS_ALL is assumed

    • options (Hash) An options hash

    • flags (Integer) Combination of flags (with behaviour as described below for the flags option)

  • Block:

An optional block that will be executed once for each line in each file found, where the block must take 1, 2, or 3 parameters, representing the line [ + file-line-index [ + entry ]]. If no block is given, an enumerator is returned.

Parameter Ordering

The parameters may be expressed in any of the following permutations:

  • searchable

  • search_root, patterns, flags

  • search_root, patterns, options

Return



110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
 
# File 'lib/recls/foreach.rb', line 110

def self.foreach(*args, &block)

	fs = nil

	case	args.length
	when	1

		raise ArgumentError "Single argument must be of type #{Recls::FileSearch}" unless args[0].kind_of? Recls::FileSearch

		fs = args[0]
	when	3

		fs = Recls::FileSearch.new(args[0], args[1], args[2])
	else

		raise ArgumentError "Function requires single argument (#{Recls::FileSearch}) or three arguments (directory, patterns, flags)"
	end

	if block_given?

		FileSearchLineEnumerator.new(fs).each(block)

		return nil
	else

		return FileSearchLineEnumerator.new(fs)
	end
end

.stat(path, *args) ⇒ Object

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

Raises:

  • (ArgumentError) 


126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
 
# File 'lib/recls/stat.rb', line 126

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

.windows? ⇒ Boolean

Indicates whether the operating system is a variant of Windows

Returns:

  • (Boolean) 


82
83
84
85
 
# File 'lib/recls/recls.rb', line 82

def self.windows?

	Recls::Ximpl::OS::OS_IS_WINDOWS
end