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

Specifies that links are to be listed (and not followed)

IGNORED

This for compatibility with recls libraries written in other languages

MARK_DIRECTORIES

Causes the Recls::Entry#path and Recls::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

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

FileSearch(search_root, patterns, options = {}) click to toggle source
DEPRECATED

Use Recls::file_search()

# File lib/recls/api.rb, line 50
def self.FileSearch(search_root, patterns, options = {})

        Recls::FileSearch.new(search_root, patterns, options)
end
absolute_path(path) click to toggle source

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
absolute_path?(path) click to toggle source

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
canonicalise_path(path) click to toggle source

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
combine_paths(*paths) click to toggle source

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
derive_relative_path(origin, path) click to toggle source

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

# 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) click to toggle source

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
exist?(path) click to toggle source

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
file?(path, *args) click to toggle source

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
file_rsearch(search_root, patterns, options = {}) click to toggle source

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

# 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
foreach(*args, &block) click to toggle source

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

# 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) click to toggle source

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

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
windows?() click to toggle source

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