module Recls
The recls module
Significant Components¶ ↑
Constants
- DETAILS_LATER
Causes operations (such as
Recls::stat()
) to obtain a result even when no corresponding file-system entity does not exist- DEVICES
Specifies that devices are to be listed
- DIRECTORIES
Specifies that directories are to be listed
- 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
- DIR_PROGRESS
- IGNORED
-
This for compatibility with recls libraries written in other languages
- FILES
Specifies that files are to be listed
- LINKS
Specifies that links are to be listed (and not followed)
- LINK_COUNT
- IGNORED
-
This for compatibility with recls libraries written in other languages
- MARK_DIRECTORIES
Causes the
Recls::Entry#path
andRecls::Entry#search_relative_path
attributes to contain a trailing path-name-separator for directory entries- NODE_INDEX
- IGNORED
-
This for compatibility with recls libraries written in other languages
- PATH_NAME_SEPARATOR
The string sequence used to separate names in paths, e.g. “/” on UNIX
- PATH_SEPARATOR
The string sequence used to separate paths, e.g. “:” on UNIX
- RECURSIVE
Causes search to operate recursively
- SEARCH_THROUGH_LINKS
Causes sub-directories that are links to be searched; default is not to search through links
- SHOW_HIDDEN
Specifies that hidden items are to be shown and hidden directories are to be searched
- STOP_ON_ACCESS_FAILURE
Causes search to terminate if a directory cannot be entered or an entry's information cannot be stat()'d
- TYPEMASK
Type mask (combination of
Recls::FILES
,Recls::DIRECTORIES
,Recls::LINKS
,Recls::DEVICES
)- VERSION
Current version of the recls.Ruby library
- WILDCARDS_ALL
Represents the “all” wildcards string for the ambient operating system
Public Class Methods
- DEPRECATED
# File lib/recls/api.rb, line 50 def self.FileSearch(search_root, patterns, options = {}) Recls::FileSearch.new(search_root, patterns, options) 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
# 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
Indicates whether the given path is absolute
Signature¶ ↑
-
Parameters:
-
path
(String, Recls::Entry) The path
-
Return¶ ↑
(boolean) true
if path
is absolute; false
otherwise
# 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
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
# 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
Combines paths
Signature¶ ↑
-
Parameters:
-
paths
([ (::String, ::Recls::Entry) ]) Array of 1 or more path elements to be combined
-
Return¶ ↑
(String) The combined path
# 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
Derives a given path relative to an origin, unless the path is absolute
Signature¶ ↑
-
Parameters:
-
origin
(String, Recls::Entry) The path against whichpath
will be evaluated -
path
(String, Recls::Entry) The path to evaluate
-
Return¶ ↑
(String) The relative form of the path
# File lib/recls/util.rb, line 94 def self.derive_relative_path(origin, path) Recls::Ximpl.derive_relative_path origin, path 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
# 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
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
# File lib/recls/util.rb, line 120 def self.exist?(path) return nil if path.nil? Recls.stat(path) 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
# 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
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 benil
, in which case the current directory is assumed -
patterns
(String, Array) The pattern(s) for which to search. May benil
, in which caseRecls::WILDCARDS_ALL
is assumed -
options
(Hash, Integer) Combination of flags (with behaviour as described below for theflags
option), or an options hash
-
-
Options:
-
flags
(Integer) Combination of flags -FILES
,DIRECTORIES
, etc. If the value moduloTYPEMASK
is 0, thenFILES
is assumed. The valueRECURSIVE
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
# 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
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 benil
, in which case the current directory is assumed -
patterns
(String, Array) The pattern(s) for which to search. May benil
, in which caseRecls::WILDCARDS_ALL
is assumed -
options
(Hash, Integer) Combination of flags (with behaviour as described below for theflags
option), or an options hash
-
-
Options:
-
flags
(Integer) Combination of flags -FILES
,DIRECTORIES
,RECURSIVE
, etc. If the value moduloTYPEMASK
is 0, thenFILES
is assumed
-
Return¶ ↑
An instance of a class implementing ::Enumerable whose value type is Recls::Entry
# File lib/recls/api.rb, line 110 def self.file_search(search_root, patterns, options = {}) Recls::FileSearch.new(search_root, patterns, options) end
Performs a recursive search and enumerates the lines of all files found
Signature¶ ↑
-
Parameters:
-
searchable
A searchable instance obtained fromRecls::file_search()
orRecls::file_rsearch()
-
search_root
(String, Recls::Entry) The root directory of the search. May benil
, in which case the current directory is assumed -
patterns
(String, Array) The pattern(s) for which to search. May benil
, in which caseRecls::WILDCARDS_ALL
is assumed -
options
(Hash) An options hash -
flags
(Integer) Combination of flags (with behaviour as described below for theflags
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¶ ↑
# 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
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 benil
-
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 asRecls::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
# 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
Indicates whether the operating system is a variant of Windows
# File lib/recls/recls.rb, line 82 def self.windows? Recls::Ximpl::OS::OS_IS_WINDOWS end