Documento de molib

Idiomas disponible : English français

CLASS

moDirectory

NAME

Contructors - creates a new directory object

VERSION

Version: 1.2.0

SYNOPSIS

moDirectory(void);
moDirectory(const moWCString& path, unsigned long flags = 0);

PARAMETERS

path - the path to the directory to read
flags - whether to read recursively and hidden files

DESCRIPTION

The Directory object can be used to read a directory which is automatically saved in a sorted list of strings.

You can use the same directory object to read multiple directories.

When used with a path and a set of flags, the constructor calls the Read() function. Please, see that function reference for more information.

SEE ALSO

Read, ReadExpand

COPYRIGHTS

This documentation and the code being documented is proprietary and cannot be duplicated without the express and written consent of Made to Order Software Coporation.

Copyright (c) 1999-2007 by Made to Order Software Corporation
All rights reserved.

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moDirectory

NAME

Read - reads a directory
ReadExpand - reads a directory or multiple directories

VERSION

Version: 1.2.0

SYNOPSIS

bool Read(const moWCString& path, unsigned long flags = 0);
bool ReadExpand(const moWCString& path, unsigned long flags = 0);

PARAMETERS

path - the path to the directory to read and a pattern
(without a pattern, the path existance is checked)
flags - a set of bits as defined below:

DIR_FLAG_HIDDEN read the hidden files

DIR_FLAG_RECURSIVE read directories recursively

DIR_FLAG_HIDDEN_CHILDREN
used with the RECURSIVE flag
so hidden files are read
within sub-directories

DESCRIPTION

The Read() function can be used as many times as you need. On each call, it reads the files found in the specified path and these are added to the directory list. Note that if the same path is read twice, new files found in the given directory will be added, but files which were deleted in that disk directory won't be removed from the list.

In order to read a new directory with an empty list, you need to call the Empty() function prior to the Read() or ReadExpand().

Note that the pattern matching is done as in a Unix shell. Thus *.* doesn't match files not including a period (.). A pattern can appear anywhere within the path. We support the asterisk (*), question mark (?) and square brackets ([...]). If no file matches, then nothing is added to the list.

IMPORTANT NOTE: without a pattern within your path nothing will be read, the path will only be checked for existance.

If you want to get support for braces expension, you need to use the ReadExpand() function instead. This function will first call the moWCString::FilenameExpand() and then call the Read() function with all the resulting paths. Note that the existance of the resulting filenames is tested. Non existing files are not included in the directory list.

If there isn't any pattern, then the input path is added to the directory if it exists on the disk.

If the hidden flag is set, then files which start with a period (.) will also be included in the result. Under other systems than Unix, we may use the attributes to know whether or not a file is hidden, which may generate a slowdown reading really large folders.

When the RECURSIVE flag is set, the function reads the directory at the given path. Then it checks each file to determine whether or not there are directories within this directory. If so, these are read. Note that the function is written in such a way that if a top directory is already present in the moDirectory list, then its contents won't be read again. This means new files within sub-directories won't appear in the resulting list unless you call Empty() before you call the Read[Expand]().

The RECURSIVE flag uses the stack and thus it should be used with caution. Only 50 levels of sub-directories will be read. If there are more levels, it is ignored, but the function returns false.

Note that in some cases, it is possible to avoid the RECURSIVE by using patterns such as:

/my/web/pages/??/abc*.html

This will search all the directories with two letters which include HTML files starting with "abc". If you can use such a path instead of recursivity, the function will certainly be much faster.

RETURN VALUE

this function returns true when the entire directory was
read successfully, false otherwise

when the RECURSIVE flag is turned on, then all the directories
that can be read will be read, but the function will return
false if there was an error in any one of these directories

note that a returned value of false doesn't mean nothing
was read; you may check the size of the list to know whether
it grows between calls.

SEE ALSO

Empty

BUGS

at this time the errno is lost when an error occurs

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moDirectory

NAME

Append - append another directory to this one
AppendEmpty - append & empty another directory to this one

VERSION

Version: 1.2.0

SYNOPSIS

void Append(const moListBase *list);
void AppendEmpty(moDirectory& dir);

PARAMETERS

list - another directory
dir - another directory

DESCRIPTION

These functions append a directory to another.

When the AppendEmpty() function is used, then the input directory (dir) entries are used as is and that directory is emptied before the function returns. Note that is why the input dir parameter isn't a constant.

SEE ALSO

Insert

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moDirectory

NAME

Get - get the specified entry
operator [] - get the specified entry

VERSION

Version: 1.2.0

SYNOPSIS

moEntry *Get(position_t position) const;
const moEntry& operator [] (int position) const;

PARAMETERS

position - the item to retrieve

DESCRIPTION

These functions are both overloads of the lower level moList functions. This enables us to have an moEntry object instead of an moBase (to avoid casting all the time).

SEE ALSO

moList

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moDirectory::moEntry

NAME

Constructors - initialize a new directory entry

VERSION

Version: 1.2.0

SYNOPSIS

moEntry(const moWCString& path, const char *name);
moEntry(const moEntry& entry);

PARAMETERS

path - the path where the file was found
name - the new filename in UTF-8
entry - an entry to duplicate

DESCRIPTION

This function initializes a new directory entry or duplicates and existing entry.

SEE ALSO

Read

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moDirectory::moEntry

NAME

FullPath - defines the absolute path starting with /

VERSION

Version: 1.2.0

SYNOPSIS

moWCString FullPath(void) const;

DESCRIPTION

This function determines the full path of the given entry. The full path is the path starting from the root directory up to the given file.

The function will save the path so multiple calls to it will be very fast.

Note that this can very well be equal to the entry string.

If you need the real path (by removing symbolic links), you should use the FullPath() function present in the moFile instead:

full_path = moFile::FullPath(*entry);

RETURN VALUE

the full path of this entry.

SEE ALSO

Stat, LStat

BUGS

This function assumes that the current working directory didn't change from the time the directory was read and this call happens.

The current path can't be mode than 4000 UTF-8 characters.

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moDirectory::moEntry

NAME

Stat - retrieve the statistics about the file

VERSION

Version: 1.2.0

SYNOPSIS

bool Stat(struct stat *st) const;
bool LStat(struct stat *st) const;

PARAMETERS

st - the statistics are copied in this structure

DESCRIPTION

The Stat() function reads the statistics about the file using the low level stat(2) function. Note that the low level stat(2) function will be used only once. This means changes to the file won't be detected.

The LStat() function is similar except it won't follow soft links. This is the function used to read directories recursively. See the low level lstat(2) for more information. Like the stat(2) function, the lstat(2) will be called only the first time the LStat() function is called.

RETURN VALUE

these functions return true unless the statistics
can't be read (file was deleted since read from
the directory, permission denied...)

SEE ALSO

Constructor, FullPath

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

CLASS

moDirectory::moEntry

NAME

IsReg - check whether the file is a regular file
IsDir - check whether the file is a directory
IsChr - check whether the file is a character device
IsBlk - check whether the file is a block device
IsFIFO - check whether the file is a pipe
IsLnk - check whether the file is a link
IsSock - check whether the file is a socket

VERSION

Version: 1.2.0

SYNOPSIS

bool IsReg(void) const;
bool IsDir(void) const;
bool IsChr(void) const;
bool IsBlk(void) const;
bool IsFIFO(void) const;
bool IsLnk(void) const;
bool IsSock(void) const;

DESCRIPTION

All of these functions can be used to know what type of a file this entry points to.

These functions returns true whenever the type corresponds to the name of the function.

RETURN VALUE

true whenever the test succeeds

SEE ALSO

Stat, stat(2)

COPYRIGHTS

AUTHORS

Alexis Wilke, Doug Barbieri

Links:
molib
the sandbox