One of the less known features of the Xceed FileSystem is its file
filtering capabilities. Not only does it come with built-in support for filtering
files based on name, size, attributes and dates, it also lets you easily combine criterias.
Furthermore, as for all Xceed components, it's fully extensible.
For example, let's say I want to copy files matching the "*.txt" filter that
have the archive attribute on. The following code can be used:
sourceFolder.CopyFilesTo( destFolder, true, true, "*.txt", FileAttributes.Archive );
What is happening beneath the surface? The fouth parameter is "params object[]
filters". This means you can provide any number of any types of parameters. Any
types? Not exactly. What you should see is "params Filter[] filters". The Filter class
is the base class for any type of filter you could think of. The Xceed FileSystem
comes with seven built-in filter classes, divided in two categories:
Operators: AndFilter, OrFilter, NotFilter.
Filters: NameFilter, AttributeFilter, SizeFilter, DateTimeFilter.
So the line of code above can be seen as this:
sourceFolder.CopyFilesTo( destFolder, true, true,
new AndFilter( new NameFilter( "*.txt" ), new AttributeFilter(
FileAttributes.Archive ) ) );
But we've decided that forcing the creation of a new NameFilter everytime
you want to filter on a mask was overkill for such a common operation. That's why
we also accept two other types of parameters. Strings are automatically converted
to a NameFilter, and FileAttributes are automatically converted
to an AttributeFilter. Finally, providing two or more filters as separate
parameters automatically puts them in an AndFilter.
But then, what happens to another common scenario: filtering files based on two name
filters? Passing "*.txt" as the fourth parameter, and "*.doc" as
the fifth would generate an AndFilter around them, thus only matching files
that match the ".txt" and the ".doc" extensions...
Oups!
We support yet another exception: any string filter can contain a pipe character (|)
for providing multiple name filters that will be grouped in an OrFilter,
like this:
sourceFolder.CopyFilesTo( destFolder, true, true, "*.txt|*.doc" );
This will automatically be translated to:
sourceFolder.CopyFilesTo( destFolder, true, true,
new OrFilter( new NameFilter( "*.txt" ), new NameFilter( "*.doc"
) ) );
By the way, most operator-like filters' constructors will accept strings and FileAttributes too,
doing the translation to NameFilter and AttributeFilter instances for
you.
The final "hidden" feature relates to case sensitivity. By default, the FileSystem
is case insensitive, as is the Windows platform. But since archives like zip files
may come from other planets like Linux or Mac OS X, we wanted to support case-sensitive
file matching. If you prepend your string with the "greater than" character (<),
the resulting NameFilter will be case-sensitive. The following code will
only match files which have their extension in upper-case:
sourceFolder.CopyFilesTo( destFolder, true, true, ">*.TXT" );
Since Windows does remember the casing of filenames, this can be very useful even
on the Windows platform. Furthermore, since we released the library, the Mono
project came to life, and our library can now be used on other platforms.
Extending filters
You can easily create custom filters by deriving from the Xceed.FileSystem.Filter class
and overriding the IsItemMatching method. A SearchFilter class,
which searches for a particular text within files could look like this:
class SearchFilter : Filter
{
public SearchFilter( string text )
: base( FilterScope.File )
{
if( text == null )
throw new ArgumentNullException( "text"
);
if( text.Length == 0 )
throw new ArgumentException( "The text
cannot be empty.", "text" );
m_text = text;
}
public override bool IsItemMatching( FileSystemItem item )
{
AbstractFile file = item as AbstractFile;
if( file == null )
return false;
try
{
int bufferSize = ( file.Size < 0x1000000
)
? unchecked( ( int )file.Size
)
: 0x1000000;
byte[] search = System.Text.Encoding.Default.GetBytes(
m_text );
if( search.Length <= bufferSize )
{
byte[] buffer = new byte[ bufferSize
];
int found = 0;
using( BinaryReader reader
= new BinaryReader( file.OpenRead( FileShare.ReadWrite ) ) )
{
int read = 0;
while( ( read =
reader.Read( buffer, 0, bufferSize ) ) > 0 )
{
found
= FindBuffer( buffer, 0, read, search, found );
if(
found == search.Length )
return true;
}
}
}
}
catch {}
return false;
}
private int FindBuffer(
byte[] source,
int sourceStart,
int sourceCount,
byte[] search,
int searchIndex )
{
// TODO: Param check!
for( int i=0; i<sourceCount; i++ )
{
if( source[ sourceStart + i ] == search[
searchIndex ] )
{
if( ++searchIndex == search.Length
)
return searchIndex;
}
else
{
searchIndex = 0;
}
}
return searchIndex;
}
private string m_text; // = null
}
Using this custom filter, you can now copy only files that contain a particular text:
sourceFolder.CopyFilesTo( destFolder, true, true, new SearchFilter( "allo" ) );
Conditionally recursing
One missing feature we had with the filtering will be addressed with today's release.
There were no way to control which subfolders to recurse into or not when calling
methods accepting filters (CopyFilesTo, MoveFilesTo, GetFiles, GetFolders).
The FilterScope.Folder value wasn't preventing recursing into subfolders.
It was only meant to include or exclude folder entries from being copied. But passing
"true" or "false" as the "recurse" parameter was an all or nothing deal.
Today, we introduce a new scope: FilterScope.Recurse. It does not interfere
with the File or Folder socpe, and only determines if we should
continue matching files into each subfolder. Its number one use is for excluding subfolders:
sourceFolder.CopyFilesTo( destFolder, true, true,
"*.txt", new NotFilter( new NameFilter( "Bar", FilterScope.Recurse
) ) );
The way you combine "Recurse" filters and other filters is irrelevant. When
deciding to copy files or folders, the library ignores any filters with the Recurse scope.
When deciding to call itself recursively, the library ignores any filters with the File or Folder scope.
We plan on providing new types of filters. Suggestions welcomed!
