Mask
[Class_wrapper]
Masks are used to build custom string matching rules by which libdar will select and exclude both file names and directory paths.
More...Data Structures | |
| struct | dar_mask |
| Incomplete struct for use as mask reference pointer. More... | |
Functions | |
| NAMESPACE_LIBDAR_START dar_mask * | dar_mask_create_same_path (char *path, bool case_sensit) |
| Matches if string is exactly the given mask (without wildcard expressions). | |
| dar_mask * | dar_mask_create_bool (bool always) |
| Always matches or never matches. | |
| dar_mask * | dar_mask_create_and () |
| Evaluates the logical and between two or more masks. | |
| dar_mask * | dar_mask_create_or () |
| Evaluates the logical or between two or more masks. | |
| dar_mask * | dar_mask_create_exclude_dir (char *path, bool case_sensit) |
| Matches any file and it's children. | |
| dar_mask * | dar_mask_create_not (dar_mask *mask) |
| Negation of another mask. | |
| dar_mask * | dar_mask_create_regular (char *expr, bool case_sensit) |
| Full regular expression matching. | |
| dar_mask * | dar_mask_create_simple (char *expr, bool case_sensit) |
| Simple text matching similiar to that done on the command line. | |
| dar_mask * | dar_mask_create_simple_path (char *path, bool case_sensit) |
| Matches any path and it's children plus any parents of that given path. | |
| void | dar_mask_destroy (dar_mask *mask) |
| Frees memory used by mask object. | |
| void | dar_mask_and_add (dar_mask *ref, dar_mask *new_mask) |
| Expands a union by adding another mask to an and mask. | |
| void | dar_mask_and_clear (dar_mask *ref) |
| Clears all entries from an and mask. | |
| U_I | dar_mask_and_size (dar_mask *ref) |
| Gets the number of elements in a union. | |
| void | dar_mask_or_add (dar_mask *ref, dar_mask *new_mask) |
| Narrows an intersection by adding another mask to an or mask. | |
| void | dar_mask_or_clear (dar_mask *ref) |
| Clears all entries from an or mask. | |
| U_I | dar_mask_or_size (dar_mask *ref) |
| Gets the number of elements in an intersection. | |
Detailed Description
Masks are used to build custom string matching rules by which libdar will select and exclude both file names and directory paths.Masks may concentrate on individual names, absolute, and relative paths. Masks may be combined in multiple layers recursively.
In the C bindings path classes are controlled by a set of functions; some type specific, some more general. Function names are organized starting with dar_mask. All constructor functions are grouped together are dar_mask_create followed by the name of the C++ library class minus the "mask". For example, the libdar::simple_path_mask constructor is dar_mask_create_simple_path. There are a few exceptions where the french names were translated into english (et and ou).
Almost all masks are treated as immutable in the C bindings. The exceptions are the union and intersection masks (and and or). Each of these masks has an additional set of functions for adding elements, clearing the set, and querying the amount of elements contained in the set. Each of these functions takes a reference to the element in question and any additional arguments required. Their names are organized as dar_mask_TYPE_FUNCTION. There are memory considerations when using these functions. More on that later.
Because all mask types end up as the same pointer type the system is obviously not very typesafe. This isn't a big deal for the most part and is useful because all mask types inherit from the same parent class. However, it is extremely important not to use a non-boolean combination mask as a reference in said operations. Such usage will not be fatal, but will not result in any useful results. See the functions which operate on the and and or masks for more information.
The last function is a wrapper for the destructor function. All mask classes override the same destructor, which will be called using the delete method when the destructor wrapper is invoked. This functions is called dar_mask_destroy.
The memory consideration is thus: The responsibility of invoking the destructor is in the users hands. The union and intersection masks copy all data passed in, leaving the original pointers untouched. Thus, if you want to avoid memory leaks this is a bad idea:
dar_mask* result = dar_mask_create_or();
dar_mask_or_add( result, dar_mask_create_simple("/f*", TRUE) );
dar_mask_or_add( result, dar_mask_create_simple("/t*", TRUE) );
The pointer passed in will not be deleted. You need to call the destroy method after passing mask objects to other objects. The following is better.
dar_mask* result = dar_mask_create_or();
dar_mask* m1 = dar_mask_create_simple("/f*", TRUE);
dar_mask* m2 = dar_mask_create_simple("/t*", TRUE);
dar_mask_or_add(result, m1);
dar_mask_or_add(result, m2);
dar_mask_destroy(m1);
dar_mask_destroy(m2);
// later...
dar_mask_destroy(result);
That's what you have to do for every mask you make. Sorry.
Remember to delete your own c strings too.
Function Documentation
|
||||||||||||
|
Expands a union by adding another mask to an and mask.
|
|
|
Clears all entries from an and mask.
|
|
|
Gets the number of elements in a union.
|
|
|
Evaluates the logical and between two or more masks. Given the paths:
dar_mask* result = dar_mask_create_and();
dar_mask* m1 = dar_mask_create_simple("/f*", TRUE);
dar_mask* m2 = dar_mask_create_simple("*bar", TRUE);
dar_mask_and_add( m1 );
dar_mask_and_add( m2 );
dar_mask_destroy( m1 );
dar_mask_destroy( m2 );
The resulting match will be:
|
|
||||||||||||
|
Matches any file and it's children. Despite the name, this mask does not implicitly exclude. Wrap in a not mask to implement exclusion. Given the paths:
dar_mask* result = dar_mask_create_exclude_dir( "/foo/bar", TRUE ); The resulting matches will be:
To fix this problem, you must (if you really want to save the absolute path) use a simple path mask or save only the relative path information. In such a case: Given the paths:
NOTE FURTHER that if you use a relative path a simple mask will often be easier. Really, the exclude directory mask is meant for excluding specific paths within a hierarchy. When wrapped in a not mask the combination will provide the expected behavior.
dar_mask* m = dar_mask_create_exclude_dir( "/foo/bar", TRUE ); dar_mask* result = dar_mask_create_not( m ); dar_mask_destroy( m ); Given the original paths, the above code will produce the following matches:
|
|
|
Negation of another mask. Useful for selective exclusion. Given the paths:
dar_mask* m = dar_mask_create_simple("/this", TRUE);
dar_mask* result = dar_mask_create_not( m );
dar_mask_destroy( m );
The resulting matches will be:
|
|
|
Evaluates the logical or between two or more masks. Given the paths:
dar_mask* result = dar_mask_create_or();
dar_mask* m1 = dar_mask_create_simple("/f*", TRUE);
dar_mask* m2 = dar_mask_create_simple("/t*", TRUE);
dar_mask_or_add( m1 );
dar_mask_or_add( m2 );
dar_mask_destroy( m1 );
dar_mask_destroy( m2 );
The resulting matches will be:
|
|
||||||||||||
|
Full regular expression matching.
See |
|
||||||||||||
|
Matches if string is exactly the given mask (without wildcard expressions). Remember to destroy your input path when finished with it! |
|
||||||||||||
|
Simple text matching similiar to that done on the command line.
See |
|
||||||||||||
|
Matches any path and it's children plus any parents of that given path. Given the paths:
dar_mask* result = dar_mask_create_simple_path( "/foo/bar", TRUE ); The resulting matches will be:
|
|
|
Frees memory used by mask object. Works for all mask types. Definition at line 104 of file mask.cpp. Referenced by dar_sup_spec_destroy(), and dar_sup_storage_destroy(). |
|
||||||||||||
|
Narrows an intersection by adding another mask to an or mask.
|
|
|
Clears all entries from an or mask.
|
|
|
Gets the number of elements in an intersection.
|