The File Tree component interface.

Collaboration diagram for The File Tree component interface.:

Data Structures
struct	file_tree_count_t
Files
file	file_tree.c
file	file_tree.h
Defines
#define	FT_LAST   ((size_t)-1)
Typedefs
typedef struct file_tree *	file_tree_h
typedef struct file_tree const *	file_tree_const_h
typedef void(*	file_tree_callback_t )(file_tree_h ft, char const *name, file_tree_traverse_state_t context)
typedef bool(*	file_filter_t )(char const *leafname)
Enumerations
enum	file_tree_traverse_state_t {   FT_ENTERING_TREE = -2, FT_ENTERING_DIR = -1, FT_AT_FILE = 0, FT_LEAVING_DIR = 1,   FT_LEAVING_TREE = 2 }
enum	file_tree_count_flags { FT_COUNT_FILES = 1, FT_COUNT_DIRS = 2, FT_COUNT_ALL = FT_COUNT_FILES | FT_COUNT_DIRS, FT_COUNT_CHILDREN = 4 }
Functions
heap_str	file_tree_name (file_tree_const_h ft)
file_tree_h	file_tree_new (void)
file_tree_h	file_tree_copy (file_tree_const_h src)
void	file_tree_swap (file_tree_h lhs, file_tree_h rhs)
void	file_tree_assign (file_tree_h dest, file_tree_const_h src)
bool	file_tree_equal (file_tree_const_h lhs, file_tree_const_h rhs)
bool	file_tree_set_filter (file_tree_h ft, file_filter_t filter)
void	file_tree_add (file_tree_h parent, char const *path, file_tree_callback_t callback)
void	file_tree_dispose (file_tree_h ft)
void	file_tree_traverse (file_tree_h ft, file_tree_callback_t callback)
bool	file_tree_is_empty (file_tree_const_h ft)
size_t	file_tree_count (file_tree_const_h ft, unsigned flags, file_tree_count_t *counter)
file_tree_const_h	file_tree_child (file_tree_const_h ft, size_t which)

---

Define Documentation

#define FT_LAST   ((size_t)-1)

Symbolic constant denoting the index of the last child of a file tree.

Definition at line 55 of file file_tree.h.

Referenced by file_tree_child().

---

Typedef Documentation

typedef bool(* file_filter_t)(char const *leafname)

Type of functions for filtering files by leafname. A file tree contains a function pointer of this type that is used to decide the eligibility of files (not directories) for insertion in the file tree. If no such function is assigned to a file tree then the default filter accepts all files.

Parameters:

leafname

The leafname of the file.

Returns:

True iff the leafname satisfies the filter.

Definition at line 118 of file file_tree.h.

typedef void(* file_tree_callback_t)(file_tree_h ft, char const *name, file_tree_traverse_state_t context)

Type of callabck function to be iterated over a file tree.

Parameters:

tree	The current file tree.
name	The pathame of the file or directory
context	Indicator of calling context:- FT_ENTERING_TREE => Starting traversal. name is NULL FT_ENTERING_DIR => Entering directory name FT_AT_FILE => name is a file FT_LEAVING_DIR => Entering directory name FT_LEAVING_TREE => Finished traversal. name is NULL

Definition at line 104 of file file_tree.h.

typedef struct file_tree const* file_tree_const_h

Abstract type of const file tree

Definition at line 80 of file file_tree.h.

typedef struct file_tree* file_tree_h

Abstract type of file tree

Definition at line 77 of file file_tree.h.

---

Enumeration Type Documentation

enum file_tree_count_flags

Bit flags that may be combined in flags passed to file_tree_count() to select the nodes counted.

Enumerator:

FT_COUNT_FILES	Count only files
FT_COUNT_DIRS	Count only directories
FT_COUNT_ALL	Count everything
FT_COUNT_CHILDREN	Only count immediate children.

Definition at line 69 of file file_tree.h.

enum file_tree_traverse_state_t

Enmeration of the states of file tree traversal.

Enumerator:

FT_ENTERING_DIR	Entering file tree Entering directory
FT_AT_FILE	At a file
FT_LEAVING_DIR	Leaving directory

Definition at line 58 of file file_tree.h.

---

Function Documentation

void file_tree_add	(	file_tree_h	parent,
		char const *	path,
		file_tree_callback_t	callback
	)

Add the filtered contents of a path to a file tree.

Parameters:

parent	The file tree to which a path is to be added.
path	The path to be added.
callback	NULL, or file_tree_callback_t to be called on entry and exit for each directory added and for each file added.

Files in path are added to the tree that satisfy the assigned or default filter function of the tree. The default filter accepts all files.

If path is a file, the function adds the file to parent if it satisfies the filter and is not already present, together with all component directories of path that are not already present.

If path is a directory and recursively contains any files that satisfy the filter and are not already present then all these files are added to parent, together with any of the directories recursively containing them that are not already present.

The function populates the file tree grudgingly. A new node will only be added to any parent when the subtree rooted at the new node has been wholly constructed in the same grudging manner and found to contain any wanted files.

Definition at line 822 of file file_tree.c.

References file_tree_add_canon(), file_tree_add_symlink(), fs_file_or_dir(), FS_IS_SLINK, and fs_real_path().

Referenced by dataset_add().

Here is the call graph for this function:

void file_tree_assign	(	file_tree_h	dest,
		file_tree_const_h	src
	)

Assign one file tree to another

Parameters:

dest	The file tree to be assigned.
src	The file tree to be assigned to dest

Definition at line 750 of file file_tree.c.

References file_tree_copy(), file_tree_dispose(), and file_tree_swap().

Here is the call graph for this function:

file_tree_const_h file_tree_child	(	file_tree_const_h	ft,
		size_t	which
	)

Return a child of a file tree.

Parameters:

ft	The file tree from which a child is to be returned.
which	The index of the required child. If which == FT_LAST then the last child, if any, is returned.

Returns:

The child of ft that is indexed by which, if any, else NULL.

Definition at line 909 of file file_tree.c.

References file_tree::children, FT_LAST, IS_DIR, ptr_vector_at(), and ptr_vector_count().

Here is the call graph for this function:

file_tree_h file_tree_copy

(

file_tree_const_h

src

)

Construct a copy of a file tree

Definition at line 729 of file file_tree.c.

References allocate(), and file_tree_copy_init().

Referenced by file_tree_assign(), and file_tree_copy_init().

Here is the call graph for this function:

size_t file_tree_count	(	file_tree_const_h	ft,
		unsigned	flags,
		file_tree_count_t *	counter
	)

Count nodes in a file tree

Parameters:

ft	The file ft to be counted.
flags	A combination of the bitflags in enum file_tree_count_flags controlling which nodes are counted.
counter	NULL, or a pointer to a file_tree_count_t that is filled in with:- Total files counted, for flag FT_COUNT_FILES Total dirs counted, for flag FT_COUNT_FILES Immediate children counted, for flag FT_COUNT_CHILDREN

Definition at line 866 of file file_tree.c.

References file_tree_count_t::children, COUNT_CHILDREN, COUNT_DIRS, COUNT_FILES, file_tree_count_t::dirs, file_tree_count(), file_tree_count_t::files, IS_DIR, IS_ROOT, ptr_vector_begin(), and ptr_vector_end().

Referenced by build_proc(), exit_diagnostics(), file_tree_count(), finish_args(), and node_proc().

Here is the call graph for this function:

void file_tree_dispose

(

file_tree_h

ft

)

Dispose of a file tree, releasing its resources.

Parameters:

ft	The file tree to be destroyed.

Definition at line 813 of file file_tree.c.

References file_tree_finis().

Referenced by deepen(), file_tree_assign(), link_in(), and new_dir_node().

Here is the call graph for this function:

bool file_tree_equal	(	file_tree_const_h	lhs,
		file_tree_const_h	rhs
	)

Say whether two file trees are equal. File trees are equal if they contain identical trees of directories and files, or are both empty.

Definition at line 760 of file file_tree.c.

References eq(), file_tree_equal(), file_tree_name(), IS_ROOT, ptr_vector_begin_const(), ptr_vector_count(), and ptr_vector_end_const().

Referenced by file_tree_equal().

Here is the call graph for this function:

bool file_tree_is_empty

(

file_tree_const_h

ft

)

Say whether a file tree contains any files or directories.

Definition at line 857 of file file_tree.c.

References IS_ROOT, and ptr_vector_count().

Referenced by file_tree_set_filter(), finish_args(), and node_proc().

Here is the call graph for this function:

heap_str file_tree_name

(

file_tree_const_h

ft

)

Compose the full name of a file tree, i.e. the pathname composed from the root name of the file tree and the root names of its recursive parents.

Definition at line 706 of file file_tree.c.

References callocate(), file_tree_name(), fs_compose_filename(), and IS_ROOT.

Referenced by file_tree_equal(), and file_tree_name().

Here is the call graph for this function:

file_tree_h file_tree_new

(

void

)

Construct and return a new file tree. The new file tree is empty and may be populated with file_tree_add(), but this object always represents the root of the file system.

Definition at line 721 of file file_tree.c.

References allocate(), and file_tree_init().

Here is the call graph for this function:

bool file_tree_set_filter	(	file_tree_h	ft,
		file_filter_t	filter
	)

Try to attach a filter function to a file tree, to be used to be used to decide the eligibility of files (not directories) for insertion in the file tree.

Parameters:

ft	The file tree to which the filter will be attached.
filter	Pointer to the filter function to attach.

Returns:

True if the filter function can be attached to the file tree, else false. A filter can only be attached to a file tree when it is empty.

Definition at line 803 of file file_tree.c.

References file_tree_is_empty(), file_tree::filter, and file_tree::var.

Referenced by dataset_filter_filetypes().

Here is the call graph for this function:

void file_tree_swap	(	file_tree_h	lhs,
		file_tree_h	rhs
	)

Exchange two file trees

Definition at line 739 of file file_tree.c.

References file_tree::children, file_tree::files, file_tree::leafname, file_tree::parent, PODSWAP, and file_tree::var.

Referenced by file_tree_assign().

void file_tree_traverse	(	file_tree_h	ft,
		file_tree_callback_t	callback
	)

Iterate a function over a file ft.

Parameters:

ft	The file_tree to be traversed.
callback	NULL, or file_tree_callback_t to be called on entry and exit for each directory added and for each file traversed.

Definition at line 837 of file file_tree.c.

References callocate(), file_tree::children, FS_ROOT_PREFIX, ptr_vector_begin(), ptr_vector_end(), and traverse().

Referenced by process().

Here is the call graph for this function: