filesystem::directory_tree Class Reference

An object that traverses directory trees and provides a view of all files. More...

#include <directory_tree.h>

Inheritance diagram for filesystem::directory_tree:

[legend]

Collaboration diagram for filesystem::directory_tree:

[legend]

List of all members.

Public Types
enum	traversal_types { prefix, infix, postfix }
Public Member Functions
	directory_tree ()
	constructs an empty tree.
	directory_tree (const basis::astring &path, const char pattern="", bool ignore_files=false)
	opens up the "path" specified and scans for files and subdirectories.
	~directory_tree ()
	DEFINE_CLASS_NAME ("directory_tree")
bool	good () const
	returns true if the directory existed and we read its contents.
const basis::astring &	path () const
	returns the root of the directory tree that we manage.
bool	reset (const basis::astring &path, const char pattern="")
	gets rid of any current files and rescans the directory at "path".
filename_tree *	seek (const basis::astring &dir_name, bool ignore_initial) const
	finds the "dir_name" in our tree.
virtual int	packed_size () const
	reports the size after packing up the tree.
virtual void	pack (basis::byte_array &packed_form) const
	packs the directory_tree into a byte_array.
virtual bool	unpack (basis::byte_array &packed_form)
	unpacks the directory_tree from a byte_array.
bool	calculate (bool just_size)
	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.
basis::outcome	add_path (const basis::astring &new_item, bool just_size=false)
	adds a "new_item" into the tree.
basis::outcome	remove_path (const basis::astring &zap_item)
	removes the "zap_item" from the tree.
void	text_form (basis::astring &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, file_info::file_similarity how_to_compare)
	compares the tree in "source" with the tree in "target".
static bool	compare_trees (const directory_tree &source, const basis::astring &source_start, const directory_tree &target, const basis::astring &target_start, filename_list &differences, file_info::file_similarity how_to_compare)
static bool	jump_to (dir_tree_iterator &scanning, const basis::astring &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, structures::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

An object that traverses directory trees and provides a view of all files.

Definition at line 37 of file directory_tree.h.

Member Enumeration Documentation

enum filesystem::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 139 of file directory_tree.h.

Constructor & Destructor Documentation

filesystem::directory_tree::directory_tree ( )

constructs an empty tree.

Definition at line 58 of file directory_tree.cpp.

filesystem::directory_tree::directory_tree	(	const basis::astring &	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 68 of file directory_tree.cpp.

References reset().

filesystem::directory_tree::~directory_tree ( )

Definition at line 80 of file directory_tree.cpp.

References basis::WHACK().

Member Function Documentation

filename_list * filesystem::directory_tree::access ( dir_tree_iterator & scanning ) [static]

more dangerous operation that lets the actual list be manipulated.

NIL is returned if there was a problem accessing the tree at the iterator position.

Definition at line 365 of file directory_tree.cpp.

References filesystem::filename_tree::_files, and NIL.

Referenced by calculate().

outcome filesystem::directory_tree::add_path	(	const basis::astring &	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 774 of file directory_tree.cpp.

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

bool filesystem::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 478 of file directory_tree.cpp.

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

bool filesystem::directory_tree::calculate ( bool just_size )

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 475 of file directory_tree.cpp.

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

bool filesystem::directory_tree::children	(	dir_tree_iterator &	scanning,
		int &	children
	)			`[static]`

returns the number of children for the current node.

Definition at line 381 of file directory_tree.cpp.

References nodes::tree::branches().

bool filesystem::directory_tree::compare_trees	(	const directory_tree &	source,
		const basis::astring &	source_start,
		const directory_tree &	target,
		const basis::astring &	target_start,
		filename_list &	differences,
		file_info::file_similarity	how_to_compare
	)			`[static]`

bool filesystem::directory_tree::compare_trees	(	const directory_tree &	source,
		const directory_tree &	target,
		filename_list &	differences,
		file_info::file_similarity	how_to_compare
	)			`[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. the "how_to_compare" value will dictate what aspects of file equality are used.

Definition at line 510 of file directory_tree.cpp.

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

similar to the above but provides a list of the real underlying type.

Definition at line 348 of file directory_tree.cpp.

References filesystem::filename_tree::_dirname, filesystem::filename_tree::_files, and structures::amorph< contents >::reset().

bool filesystem::directory_tree::current	(	dir_tree_iterator &	scanning,
		filename &	dir_name,
		structures::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 331 of file directory_tree.cpp.

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

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

bool filesystem::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 321 of file directory_tree.cpp.

References filesystem::filename_tree::_dirname.

Referenced by calculate().

filesystem::directory_tree::DEFINE_CLASS_NAME ( "directory_tree" )

bool filesystem::directory_tree::depth	(	dir_tree_iterator &	scanning,
		int &	depth
	)			`[static]`

returns the current depth of the iterator.

a depth of zero means the iterator is at the root node for the tree.

Definition at line 372 of file directory_tree.cpp.

References filesystem::filename_tree::_depth.

Referenced by calculate(), and text_form().

bool filesystem::directory_tree::good ( ) const [inline]

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

Definition at line 59 of file directory_tree.h.

bool filesystem::directory_tree::jump_to	(	dir_tree_iterator &	scanning,
		const basis::astring &	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 260 of file directory_tree.cpp.

References filesystem::filename_tree::_dirname, nodes::tree::branch(), nodes::tree::branches(), filesystem::filename::compare_prefix(), filesystem::filename::default_separator(), FUNCDEF, filesystem::filename::join(), basis::array< contents >::length(), LOG, filesystem::filename::raw(), and basis::array< contents >::subarray().

Referenced by compare_trees().

bool filesystem::directory_tree::next ( dir_tree_iterator & scanning ) [static]

goes to the next filename in the "scanning" iterator.

true is returned if there is an entry there.

Definition at line 390 of file directory_tree.cpp.

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

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

packs the directory_tree into a byte_array.

Implements basis::packable.

Definition at line 99 of file directory_tree.cpp.

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

Referenced by octopi::file_transfer_infoton::package_tree_info().

int filesystem::directory_tree::packed_size ( ) const [virtual]

reports the size after packing up the tree.

Implements basis::packable.

Definition at line 91 of file directory_tree.cpp.

References basis::astring::packed_size(), structures::PACKED_SIZE_INT32, and nodes::packable_tree::recursive_packed_size().

const astring & filesystem::directory_tree::path ( ) const

returns the root of the directory tree that we manage.

Definition at line 89 of file directory_tree.cpp.

Referenced by compare_trees(), and seek().

outcome filesystem::directory_tree::remove_path ( const basis::astring & 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 875 of file directory_tree.cpp.

References filesystem::filename_tree::_dirname, filesystem::filename_tree::_files, FUNCDEF, basis::array< contents >::last(), filesystem::filename_list::locate(), LOG, filesystem::filename_list::member(), NIL, nodes::tree::parent(), filesystem::filename::raw(), basis::WHACK(), and structures::amorph< contents >::zap().

bool filesystem::directory_tree::reset	(	const basis::astring &	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 219 of file directory_tree.cpp.

References filesystem::directory::good(), and basis::WHACK().

Referenced by directory_tree().

filename_tree * filesystem::directory_tree::seek	(	const basis::astring &	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 401 of file directory_tree.cpp.

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