utl::Directory Class Reference
[Filesystem]

#include <Directory.h>

Inheritance diagram for utl::Directory:

List of all members.

Public Types

enum scan_t {
scan_recursive = 1, scan_recursive_flat = 2, scan_followLinks = 4, scan_excludeDotDirs = 8,
scan_ignoreEx = 16, scan_append = 32
}

Scan flags. More...

Public Member Functions

Directory (const String &path, const Directory *dir=NULL)

Constructor.

virtual int compare (const Object &rhs) const

Compare with another object.

virtual void copy (const Object &rhs)

Copy another instance.

virtual void dump (Stream &os, uint_t level=uint_t_max) const

Dump to a stream by dumping entries.

virtual void serialize (Stream &stream, uint_t io, uint_t mode=ser_default)

Serialize to or from a stream.

virtual void unlink ()

Remove the object from the filesystem.

bool isFlat () const

Determine whether a flat scan was done.

const Collection * entries () const

Get the collection of entries.

Collection * entries ()

Get the collection of entries.

void takeEntries (Directory &rhs)

"Steal" the given directory's entries.

FSobject * find (const Pathname &path, bool relative=true) const

Find an entry matching the given path.

void make (uint_t mode=uint_t_max) const

Create a directory with the given mode.

uint_t scan (uint_t flags=0, Factory *factory=NULL, const Predicate *pred=NULL, bool predVal=true)

Scan the directory to populate the entries collection.

void rescan (uint_t flags=0, Factory *factory=NULL, const Predicate *pred=NULL, bool predVal=true)

This method cannot be used if (isFlat() == true).

Detailed Description

Directory filesystem object.

A directory is a filesystem object that contains references to other filesystem objects. Directories permit files and other objects to be organized in a way that is intuitive for people.

Scanning a directory is a process whereby its entries are discovered by reading the directory from the disk. These entries are translated into instances of FSobject-derived classes and added to the entries collection for the Directory. A recursive scan will scan subdirectories (and their subdirectories, etc.) in order to scan the entire directory tree/branch. The organization of FSobject-derived objects will closely mirror the organization of objects on the disk. For example, suppose that the following directory structure exists:

   /foo/
   /foo/bar.txt
   /foo/bar/
   /foo/bar/foobar.txt
   /foo/bar/foo.bar.gz

If we scan this structure as follows:

   Directory foo("/foo/");
   foo.scan();

Then foo's entries will include a File named bar.txt and a Directory named bar. scan() will be recursively called on bar, and its entries will consist of File objects called foobar.txt and foo.bar.gz. It will look like this:

   Directory("/foo/")
       File("bar.txt")
       Directory("bar/")
           File("foobar.txt")
           File("foo.bar.gz")

Although this organization is often the most intuitive and efficient, an alternative technique for recursive scanning is allowed. In a flat recursive scan, all entries for the entire tree are added to the root Directory object:

   Directory("/foo/")
       File("bar.txt")
       Directory("bar/")
       File("bar/foobar.txt")
       File("bar/foo.bar.gz")

Author:: Adam McKee

Definition at line 78 of file Directory.h.

Member Enumeration Documentation

enum utl::Directory::scan_t

Scan flags.

Enumerator:

scan_recursive	recursive scan
scan_recursive_flat	flat recursive scan
scan_followLinks	follow symbolic links
scan_excludeDotDirs	exclude "." and ".." entries
scan_ignoreEx	ignore exceptions
scan_append	for internal use only

Definition at line 163 of file Directory.h.

Constructor & Destructor Documentation

utl::Directory::Directory	(	const String &	path,
		const Directory *	dir = `NULL`
	)			`[inline]`

Constructor.

Parameters:

	path	directory path
	dir	(optional) parent directory

Definition at line 87 of file Directory.h.

References utl::init().

Member Function Documentation

virtual int utl::Directory::compare ( const Object & rhs ) const [virtual]

Compare with another object.

If no overridden version succeeds in doing the comparison, then an attempt will be made to re-start the comparison process using one or both of the objects' keys. Usually, an override of compare() should call the superclass's compare() if it doesn't know how to compare itself with the rhs object.

See also:: getKey

Returns:: < 0 if self < rhs, 0 if self = rhs, > 0 if self > rhs

Parameters:

rhs

object to compare with

Reimplemented from utl::FSobject.

virtual void utl::Directory::copy ( const Object & rhs ) [virtual]

Copy another instance.

When you override copy(), you should usually call the superclass's copy().

Parameters:

rhs

object to copy

Reimplemented from utl::FSobject.

virtual void utl::Directory::dump	(	Stream &	os,
		uint_t	level = `uint_t_max`
	)			const `[virtual]`

Dump to a stream by dumping entries.

Reimplemented from utl::FSobject.

virtual void utl::Directory::serialize	(	Stream &	stream,
		uint_t	io,
		uint_t	mode = `ser_default`
	)			`[virtual]`

Serialize to or from a stream.

This is the only virtual method for serialization. You must override this in any class that has data to be serialized, and ensure that the superclass's serialize() gets called.

Parameters:

	stream	stream to serialize from/to
	io	see io_t
	mode	see serialize_t

Reimplemented from utl::FSobject.

virtual void utl::Directory::unlink ( ) [virtual]

Remove the object from the filesystem.

Reimplemented from utl::FSobject.

bool utl::Directory::isFlat ( ) const [inline]

Determine whether a flat scan was done.

Definition at line 106 of file Directory.h.

const Collection* utl::Directory::entries ( ) const [inline]

Get the collection of entries.

Definition at line 110 of file Directory.h.

Collection* utl::Directory::entries ( ) [inline]

Get the collection of entries.

Definition at line 114 of file Directory.h.

void utl::Directory::takeEntries ( Directory & rhs )

"Steal" the given directory's entries.

FSobject* utl::Directory::find	(	const Pathname &	path,
		bool	relative = `true`
	)			const

Find an entry matching the given path.

The relative flag indicates whether the given path is relative to the directory's path, or if it includes the directory's path.

Returns:: found object (NULL if none)

Parameters:

	path	pathname
	relative	(optional : true) is path relative to self?

void utl::Directory::make ( uint_t mode = uint_t_max ) const

Create a directory with the given mode.

uint_t utl::Directory::scan	(	uint_t	flags = `0`,
		Factory *	factory = `NULL`,
		const Predicate *	pred = `NULL`,
		bool	predVal = `true`
	)			`[inline]`

Scan the directory to populate the entries collection.

Parameters:

	flags	(optional) scan flags (see scan_t)
	factory	(optional) create Collection-derived object to store entries
	pred	(optional) : predicate : require (pred(fsObject) == predVal)
	predVal	(optional : true) predicate value

Definition at line 141 of file Directory.h.

void utl::Directory::rescan	(	uint_t	flags = `0`,
		Factory *	factory = `NULL`,
		const Predicate *	pred = `NULL`,
		bool	predVal = `true`
	)

This method cannot be used if (isFlat() == true).

Rescan the directory to learn about added and/or removed entries. The advantage of rescan() over scan() is that it retains entry collections for sub-directories, and it retains "stat" information for all entries. Thus, information that could still be useful is not thrown away.

The documentation for this class was generated from the following file:

Directory.h


Public Types
enum	scan_t { scan_recursive = 1, scan_recursive_flat = 2, scan_followLinks = 4, scan_excludeDotDirs = 8, scan_ignoreEx = 16, scan_append = 32 }
	Scan flags. More...
Public Member Functions
	Directory (const String &path, const Directory *dir=NULL)
	Constructor.
virtual int	compare (const Object &rhs) const
	Compare with another object.
virtual void	copy (const Object &rhs)
	Copy another instance.
virtual void	dump (Stream &os, uint_t level=uint_t_max) const
	Dump to a stream by dumping entries.
virtual void	serialize (Stream &stream, uint_t io, uint_t mode=ser_default)
	Serialize to or from a stream.
virtual void	unlink ()
	Remove the object from the filesystem.
bool	isFlat () const
	Determine whether a flat scan was done.
const Collection *	entries () const
	Get the collection of entries.
Collection *	entries ()
	Get the collection of entries.
void	takeEntries (Directory &rhs)
	"Steal" the given directory's entries.
FSobject *	find (const Pathname &path, bool relative=true) const
	Find an entry matching the given path.
void	make (uint_t mode=uint_t_max) const
	Create a directory with the given mode.
uint_t	scan (uint_t flags=0, Factory factory=NULL, const Predicate pred=NULL, bool predVal=true)
	Scan the directory to populate the entries collection.
void	rescan (uint_t flags=0, Factory factory=NULL, const Predicate pred=NULL, bool predVal=true)
	This method cannot be used if (isFlat() == true).

utl::Directory Class Reference [Filesystem]

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

utl::Directory Class Reference
[Filesystem]