Module: Recls

Defined in:
lib/recls/api.rb,
lib/recls/stat.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/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

Defined Under Namespace

Modules: Ximpl Classes: Entry, FileSearch, FileSearchLineEnumerator

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 = 
0x000000ff
SHOW_HIDDEN =

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

0x00000100
DIR_PROGRESS = 
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 = 
0x00008000
RECURSIVE = 
0x00010000
DIRECTORY_PARTS = 
0x00040000
DETAILS_LATER = 
0x00080000
MARK_DIRECTORIES = 
0x00200000

0x00100000
WILDCARDS_ALL =

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

Recls::Ximpl::OS::WILDCARDS_ALL
PATH_NAME_SEPARATOR = 
Recls::Ximpl::OS::PATH_NAME_SEPARATOR
PATH_SEPARATOR = 
Recls::Ximpl::OS::PATH_SEPARATOR
VERSION =

Current version of the recls.Ruby library

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



45
46
47
48
49
50
 
# File 'lib/recls/util.rb', line 45

def self.absolute_path(path)

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

  return Recls::Ximpl.absolute_path path
end

.canonicalise_path(path) ⇒ Object

Canonicalises the given path, by removing dots (‘.’ and ‘..’) directories



54
55
56
57
58
59
 
# File 'lib/recls/util.rb', line 54

def self.canonicalise_path(path)

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

  return 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

The combined path

Raises:

  • (ArgumentError) 


53
54
55
56
57
58
59
60
61
 
# File 'lib/recls/combine_paths_1.rb', line 53

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



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

def self.derive_relative_path(origin, path)

  return Recls::Ximpl.derive_relative_path origin, path
end

.directory?(path, *args) ⇒ Boolean

Performs a stat() but returns nil if an obtained entry is not a directory

Returns:

  • (Boolean) 


46
47
48
49
50
51
52
53
54
55
56
 
# File 'lib/recls/stat.rb', line 46

def self.directory?(path, *args)

  fe = self.stat(path, *args)

  if fe

    return nil unless fe.directory?
  end

  fe
end

.file?(path, *args) ⇒ Boolean

Performs a stat() but returns nil if an obtained entry is not a file

Returns:

  • (Boolean) 


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

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 +::Recls::FileSearch+



78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
 
# File 'lib/recls/api.rb', line 78

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 +::Recls::FileSearch+



125
126
127
128
 
# File 'lib/recls/api.rb', line 125

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

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

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

Deprecated.
DEPRECATED

Use Recls.file_search()



47
48
49
50
 
# File 'lib/recls/api.rb', line 47

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

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

.foreach(*args, &block) ⇒ Object 



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

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

.pathNameSeparator ⇒ Object 



66
67
68
 
# File 'lib/recls/recls.rb', line 66

def self.pathNameSeparator
  PATH_NAME_SEPARATOR
end

.pathSeparator ⇒ Object 



70
71
72
 
# File 'lib/recls/recls.rb', line 70

def self.pathSeparator
  PATH_SEPARATOR
end

.stat(path, *args) ⇒ Object

USAGE:

- stat(path)
- stat(path, flags)
- stat(path, search_root)
- stat(path, search_root, flags)
- stat(path, flags, search_root)

Raises:

  • (ArgumentError) 


79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
 
# File 'lib/recls/stat.rb', line 79

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

  begin

    Recls::Entry.new(path, Recls::Ximpl::FileStat.stat(path), search_root, flags)
  rescue Errno::ENOENT => x

    x = x # suppress warning

    if 0 != (flags & Recls::DETAILS_LATER)

      Recls::Entry.new(path, nil, search_root, flags)
    else

      nil
    end
  end
end

.wildcardsAll ⇒ Object 



74
75
76
 
# File 'lib/recls/recls.rb', line 74

def self.wildcardsAll
  WILDCARDS_ALL
end