directory_tree Class Reference

#include <directory_tree.h>

Inheritance diagram for directory_tree:

[legend]Collaboration diagram for directory_tree:


Public Types
enum	traversal_types { prefix, infix, postfix }
Public Member Functions
	directory_tree ()
	constructs an empty tree.
	directory_tree (const istring &path, const char pattern="", bool ignore_files=false)
	opens up the "path" specified and scans for files and subdirectories.
	~directory_tree ()
	IMPLEMENT_CLASS_NAME ("directory_tree")
bool	good () const
	returns true if the directory existed and we read its contents.
const istring &	path () const
	returns the root of the directory tree that we manage.
bool	reset (const istring &path, const char pattern="")
	gets rid of any current files and rescans the directory at "path".
filename_tree *	seek (const istring &dir_name, bool ignore_initial) const
	finds the "dir_name" in our tree.
virtual void	pack (byte_array &packed_form) const
	Creates a packed form of the packable object in "packed_form".
virtual bool	unpack (byte_array &packed_form)
	packs the directory_tree into a byte_array.
bool	calculate (bool just_size=false)
	unpacks the directory_tree from a byte_array. visits each file in the directory_tree and calculates its attributes.
bool	calculate (filename_tree *start, bool just_size)
	a calculate method that starts at a specific node rather than the root.
outcome	add_path (const istring &new_item, bool just_size=false)
	adds a "new_item" into the tree.
outcome	remove_path (const istring &zap_item)
	removes the "zap_item" from the tree.
void	text_form (istring &tree_dump, bool show_files=true)
	provides a visual representation of the tree in "tree_dump".
dir_tree_iterator *	start (traversal_types type) const
	starts an iterator on the directory tree.
dir_tree_iterator *	start_at (filename_tree *start, traversal_types type) const
	starts the iterator at a specific "start" node.
Static Public Member Functions
static bool	compare_trees (const directory_tree &source, const directory_tree &target, filename_list &differences, bool compare_size=true, bool compare_checksum=true)
	compares the tree in "source" with the tree in "target".
static bool	compare_trees (const directory_tree &source, const istring &source_start, const directory_tree &target, const istring &target_start, filename_list &differences, bool compare_size=true, bool compare_checksum=true)
static bool	jump_to (dir_tree_iterator &scanning, const istring &sub_path)
	seeks to a "sub_path" below the iterator's current position.
static bool	current_dir (dir_tree_iterator &scanning, filename &dir_name)
	sets "dir_name" to the directory name at the "scanning" location.
static bool	current (dir_tree_iterator &scanning, filename &dir_name, string_array &to_fill)
	retrieves the information for the iterator's current location.
static bool	current (dir_tree_iterator &scanning, filename &dir_name, filename_list &to_fill)
	similar to the above but provides a list of the real underlying type.
static filename_list *	access (dir_tree_iterator &scanning)
	more dangerous operation that lets the actual list be manipulated.
static bool	depth (dir_tree_iterator &scanning, int &depth)
	returns the current depth of the iterator.
static bool	children (dir_tree_iterator &scanning, int &children)
	returns the number of children for the current node.
static bool	next (dir_tree_iterator &scanning)
	goes to the next filename in the "scanning" iterator.
static void	throw_out (dir_tree_iterator *&to_whack)
	cleans up an iterator that was previously opened with start().

Detailed Description

Definition at line 32 of file directory_tree.h.

Member Enumeration Documentation

enum directory_tree::traversal_types

Enumerator:

prefix	prefix means that subnodes are processed after their parent.
infix	infix (for binary trees) goes 1) left, 2) current, 3) right.
postfix	postfix means that subnodes are traversed first (depth first).

Definition at line 131 of file directory_tree.h.

Constructor & Destructor Documentation

directory_tree::directory_tree ( )

constructs an empty tree.

Definition at line 53 of file directory_tree.cpp.

directory_tree::directory_tree	(	const istring &	path,
		const char *	pattern = `"*"`,
		bool	ignore_files = `false`
	)

opens up the "path" specified and scans for files and subdirectories.

if the location was accessible, then the good() method returns true. note that the "path" should just be a bare directory without any wildcards attached. the "pattern" can be specified if you wish to strain out just a subset of the files in the directory. note that unlike the directory object, directory_tree applies the wildcard to filenames only--all sub-directories are included. the pattern must meet the same requirements that the operating system places on wildcard patterns. if "ignore_files" is true, then no files are considered and only the tree of directories is gathered.

Definition at line 63 of file directory_tree.cpp.

References path(), and reset().

directory_tree::~directory_tree ( )

Definition at line 75 of file directory_tree.cpp.

References WHACK().

Member Function Documentation

directory_tree::IMPLEMENT_CLASS_NAME ( "directory_tree" )

bool directory_tree::good ( ) const [inline]

returns true if the directory existed and we read its contents.

Definition at line 54 of file directory_tree.h.

const istring & directory_tree::path ( ) const

returns the root of the directory tree that we manage.

Definition at line 84 of file directory_tree.cpp.

Referenced by compare_trees(), directory_tree(), reset(), and seek().

bool directory_tree::reset	(	const istring &	path,
		const char *	pattern = `"*"`
	)

gets rid of any current files and rescans the directory at "path".

a new "pattern" can be specified at this time also. true is returned if the process was started successfully at "path"; there might be problems with subdirectories, but at least the "path" got validated.

Definition at line 204 of file directory_tree.cpp.

References directory::good(), path(), and WHACK().

Referenced by directory_tree().

filename_tree * directory_tree::seek	(	const istring &	dir_name,
		bool	ignore_initial
	)			const

finds the "dir_name" in our tree.

locates the node that corresponds to the directory name contained in "dir_name" and returns the filename_tree rooted at that node. if the "ignore_initial" flag is true, then dir_name is expected to omit the path() where "this" tree is rooted.

Definition at line 384 of file directory_tree.cpp.

References filename_tree::_dirname, nodes::tree::branch(), nodes::tree::branches(), current(), filename::default_separator(), FUNCDEF, array< contents >::length(), LOG, NIL, path(), and array< contents >::reset().

Referenced by compare_trees().

void directory_tree::pack ( byte_array & packed_form ) const [virtual]

Creates a packed form of the packable object in "packed_form".

This must append to the data in "packed_form" rather than clearing prior contents.

Implements packable.

Definition at line 86 of file directory_tree.cpp.

References basis::attach(), istring::pack(), and nodes::packable_tree::recursive_pack().

Referenced by file_transfer_infoton::package_tree_info().

bool directory_tree::unpack ( byte_array & packed_form ) [virtual]

packs the directory_tree into a byte_array.

Implements packable.

Definition at line 95 of file directory_tree.cpp.

References basis::detach(), istring::unpack(), and WHACK().

bool directory_tree::calculate ( bool just_size = false )

unpacks the directory_tree from a byte_array. visits each file in the directory_tree and calculates its attributes.

the attributes include file size and checksum. if "just_size" is true, then no checksum is computed.

Definition at line 458 of file directory_tree.cpp.

Referenced by add_path(), and recursive_file_copy::copy_hierarchy().

bool directory_tree::calculate	(	filename_tree *	start,
		bool	just_size
	)

a calculate method that starts at a specific node rather than the root.

Definition at line 461 of file directory_tree.cpp.

References access(), current_dir(), depth(), FUNCDEF, LOG, next(), postfix, filename::raw(), start(), start_at(), and throw_out().

outcome directory_tree::add_path	(	const istring &	new_item,
		bool	just_size = `false`
	)

adds a "new_item" into the tree.

this is useful when one knows that new files exist under the directory, but one doesn't want to recalculate the entire tree. the new item will automatically be calculated. the item can be either a file or directory that's under the root. the root directory name should not be included in the "new_item".

Definition at line 754 of file directory_tree.cpp.

References filename_tree::_depth, filename_tree::_dirname, filename_tree::_files, nodes::tree::attach(), common::BAD_INPUT, calculate(), common::FAILURE, filename_list::find(), FUNCDEF, filename::good(), filename::is_directory(), array< contents >::last(), array< contents >::length(), LOG, NIL, common::OKAY, and filename::raw().

outcome directory_tree::remove_path ( const istring & zap_item )

removes the "zap_item" from the tree.

this only works for cases where one knows that an item has been removed in the filesystem. if the item is still really there, then the next rescan will put it back into the tree.

Definition at line 855 of file directory_tree.cpp.

References filename_tree::_dirname, filename_tree::_files, common::BAD_INPUT, FUNCDEF, array< contents >::last(), filename_list::locate(), LOG, filename_list::member(), NIL, common::NOT_FOUND, common::OKAY, common::outcome_name(), nodes::tree::parent(), filename::raw(), WHACK(), and amorph< contents >::zap().

bool directory_tree::compare_trees	(	const directory_tree &	source,
		const directory_tree &	target,
		filename_list &	differences,
		bool	compare_size = `true`,
		bool	compare_checksum = `true`
	)			`[static]`

compares the tree in "source" with the tree in "target".

the two root names may be different, but everything below the root in "source" will be checked against "target". the "differences" between the two trees will be compiled. note that this does not perform any disk access; it merely compares the two trees' current contents. the "differences" list's members will have a primary filename set to the source path and an alternate filename set to the location in the target.

Definition at line 493 of file directory_tree.cpp.

References istring::empty_string().

bool directory_tree::compare_trees	(	const directory_tree &	source,
		const istring &	source_start,
		const directory_tree &	target,
		const istring &	target_start,
		filename_list &	differences,
		bool	compare_size = `true`,
		bool	compare_checksum = `true`
	)			`[static]`

void directory_tree::text_form	(	istring &	tree_dump,
		bool	show_files = `true`
	)

provides a visual representation of the tree in "tree_dump".

if "show_files" is not true, then only the directories will be shown.

Definition at line 114 of file directory_tree.cpp.

References current(), depth(), string_manipulation::indentation(), istring::length(), array< contents >::length(), next(), log_base::platform_ending(), prefix, filename::raw(), string_manipulation::split_lines(), start(), and throw_out().

Referenced by compare_trees().

dir_tree_iterator * directory_tree::start ( traversal_types type ) const

starts an iterator on the directory tree.

Definition at line 235 of file directory_tree.cpp.

References infix, and postfix.

Referenced by calculate(), compare_trees(), start_at(), and text_form().

dir_tree_iterator * directory_tree::start_at	(	filename_tree *	start,
		traversal_types	type
	)			const

starts the iterator at a specific "start" node.

Definition at line 224 of file directory_tree.cpp.

References infix, postfix, and start().

Referenced by calculate().

bool directory_tree::jump_to	(	dir_tree_iterator &	scanning,
		const istring &	sub_path
	)			`[static]`

seeks to a "sub_path" below the iterator's current position.

tries to take the iterator "scanning" down to a "sub_path" that is underneath its current position. true is returned on success.

Definition at line 245 of file directory_tree.cpp.

References filename::default_separator(), FUNCDEF, filename::join(), array< contents >::length(), LOG, filename::raw(), and array< contents >::subarray().

Referenced by compare_trees().

bool directory_tree::current_dir	(	dir_tree_iterator &	scanning,
		filename &	dir_name
	)			`[static]`

sets "dir_name" to the directory name at the "scanning" location.

Definition at line 304 of file directory_tree.cpp.

References filename_tree::_dirname, and istring::empty_string().

Referenced by calculate().

bool directory_tree::current	(	dir_tree_iterator &	scanning,
		filename &	dir_name,
		string_array &	to_fill
	)			`[static]`

retrieves the information for the iterator's current location.

fills the "to_fill" array with filenames that are found at the "scanning" iterator's current position in the tree. the "dir_name" for that location is also set. if the iterator has ended, then false is returned.

Definition at line 314 of file directory_tree.cpp.

References filename_tree::_dirname, filename_tree::_files, istring::empty_string(), filename_list::fill(), and array< contents >::reset().

Referenced by compare_trees(), seek(), and text_form().