Module: Recls

Defined in:
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/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

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.11.0.3'

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.



62
63
64
65
66
67
 
# File 'lib/recls/util.rb', line 62

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) 


139
140
141
142
143
144
145
146
 
# File 'lib/recls/util.rb', line 139

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.



79
80
81
82
83
84
 
# File 'lib/recls/util.rb', line 79

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) 


60
61
62
63
64
65
66
67
68
 
# File 'lib/recls/combine_paths_1.rb', line 60

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.



97
98
99
100
 
# File 'lib/recls/util.rb', line 97

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) 


66
67
68
69
70
71
72
73
74
75
76
 
# File 'lib/recls/stat.rb', line 66

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) 


123
124
125
126
127
128
 
# File 'lib/recls/util.rb', line 123

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) 


92
93
94
95
96
97
98
99
100
101
102
 
# File 'lib/recls/stat.rb', line 92

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 - Recls::FILES, Recls::DIRECTORIES, etc. If the value modulo Recls::TYPEMASK is 0, then Recls::FILES is assumed. The value Recls::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.



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

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 - Recls::FILES, Recls::DIRECTORIES, Recls::RECURSIVE, etc. If the value modulo Recls::TYPEMASK is 0, then Recls::FILES is assumed

Return

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



113
114
115
116
 
# File 'lib/recls/api.rb', line 113

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()



53
54
55
56
 
# File 'lib/recls/api.rb', line 53

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

nil if a block is given; otherwise, an instance of the FileSearchLineEnumerator.



117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
 
# File 'lib/recls/foreach.rb', line 117

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) 


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
175
176
177
 
# File 'lib/recls/stat.rb', line 129

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