The examples in this section will be using the following folder structure:

c:\rootFolder\
----foo.txt
----bar.txt
----subFolder1\
--------foo1.txt
--------foo2.txt
--------foo3.html (1)
--------ignore.html
----subFolder2\
--------a.js
--------b.js
--------c.js
----subFolder3\
-------subFolder3a\
------------deepFOO1.txt (2)
------------deepFOO2.txt

example paths

(1) c:\rootFolder\subFolder1\foo3.html

(2) c:\rootFolder\subFolder3\subFolder3a\deepFOO1.txt

Using the Jaxer.Dir's readDir() method to search for files and folders.

Using the example folder structure above, we can use the methods contained in the Jaxer.File and Jaxer.Dir namespaces to navigate the filesystem. The samples below use the proprerty value provided in Jaxer 0.9.8 and later, if your are using an earlier release of Jaxer, refer to the annotations in the code samples for guidance. // create a dir object the represents the folder // we want to navigate. var rootDir = new Jaxer.Dir('c:\\rootFolder'); // get an array of Jaxer.Filesystem objects containing the // directory entries returned by readDir var folderEntries = rootDir.readDir(); // loop through the returned directory entries // and take action depending on what we find for (var index = 0; index < folderEntries.length; index++) { var fileSystemObject = folderEntries[index]; //prior to 0.9.8 : if (fileSystemObject.isFile()) if (fileSystemObject.isFile) { // process the file } //prior to 0.9.8 : if (fileSystemObject.isDir) if (fileSystemObject.isDir) { // process the file } }

Programatically navigating the filesystem can result in a lot of scaffolding code. To make this easier, Jaxer provides grep/map methods for scanning the filesystem, which allow you to find sets of files and execute actions on them based on whether the found files match a provided regular expression.

Let's look at some use cases to explain the powerful functionality these provide to the developer.

Jaxer.Dir.grep

The signature of the grep method looks like the following:

var myArrayOfFileObjects = Jaxer.Dir.grep(path,options)

The path parameter is a directory path to the folder you want to search.

The options parameter is a Javascript Object that contains some required properties.

The supported properties are pattern, flags and recursive.
pattern is a string value representing a javascript regular expression,
flags contains any regexp flags you want to provide to govern the behavour of the regular expression provided by the pattern parameter,
recursive is used to indicate whether the search should also scan sub folders.

So given the example folder structure, we can use the simplest form of the grep method specifying only the folder to search in.

var rootFolder = new Jaxer.Dir("c:\\rootFolder"); var myResults = Jaxer.Dir.grep(rootFolder);

which returns an array of file objects representing these files :-

c:\rootFolder\bar.txt
c:\rootFolder\foo.txt

Note that is only files in the specified folder that are returned and no subfolder searching is attempted

The next example provides a pattern parameter that matches a single file in the top level folder.

var myResults = Jaxer.Dir.grep(rootFolder,{pattern:'^.*foo.*$'});

this returns an array containing a single file object representing :-

c:\rootFolder\foo.txt

Now we add the recursive property to the invocation

var myResults = Jaxer.Dir.grep(rootFolder,{pattern:'^.*foo.*$',recursive:true});

and this returns an array of file objects that includes matches from the scanned subfolders :-

c:\rootFolder\foo.txt
c:\rootFolder\subFolder1\foo1.txt,
c:\rootFolder\subFolder1\foo2.txt
c:\rootFolder\subFolder1\foo3.html

Next we add a flag property to the options object to include case insensitive results.

var myResults = Jaxer.Dir.grep(rootFolder,{pattern:'^.*foo.*$',flags:'i',recursive:true});

which returns an array of file objects including some containing 'FOO' :-

c:\rootFolder\foo.txt,
c:\rootFolder\subFolder1\foo1.txt
c:\rootFolder\subFolder1\foo2.txt
c:\rootFolder\subFolder1\foo3.html
c:\rootFolder\subFolder3\subFolder3a\deepFOO1.txt
c:\rootFolder\subFolder3\subFolder3a\deepFOO2.txt

You can also provide a string containing the folder path and use an object literal for your options parameter:

var opt = {pattern:'^.*[12]\..*$',recursive:true}; var myResults = Jaxer.Dir.grep("c:\\rootFolder",opt);

which returns an array of file objects :-

c:\rootFolder\subFolder1\foo1.txt
c:\rootFolder\subFolder1\foo2.txt
c:\rootFolder\subFolder3\subFolder3a\deepFOO1.txt
c:\rootFolder\subFolder3\subFolder3a\deepFOO2.txt

OK, so you get the idea. You can provide an fairly complex query and get a result set of matched values in an array, and you can do it without a whole lot of scaffolding code to navigate the folder tree.

Jaxer.Dir.map

Taking Jaxer.Dir.grep as a given we can now look at the Jaxer.Dir.Map functionality. This has a signature that is extended from the grep method and adds a third parameter of a function to invoke on each matched file object.

var myResults = Jaxer.Dir.map(path,options,fn);

The function can be declared inline or externally and if omitted the map method will behave exactly like the grep method and return an array of Jaxer.File objects.

Let's look at some examples.

var myResults = Jaxer.Dir.map( rootFolder, {pattern:'^.*[12]\..*$',recursive:true }, // prior to 0.9.8 : function(f) { Jaxer.Log.info(f.getPath()); return f })); function(f) { Jaxer.Log.info(f.path); return f }));

will write a log entry out for each of the matched files and return an array of matched Jaxer.File objects

13:55:19 02/20/2008 [  2356] [INFO] [JS Framework] [framework.] c:\rootFolder\subFolder1\foo1.txt
13:55:19 02/20/2008 [  2356] [INFO] [JS Framework] [framework.] c:\rootFolder\subFolder1\foo2.txt
13:55:19 02/20/2008 [  2356] [INFO] [JS Framework] [framework.] c:\rootFolder\subFolder3\subFolder3a\deepFOO1.txt
13:55:19 02/20/2008 [  2356] [INFO] [JS Framework] [framework.] c:\rootFolder\subFolder3\subFolder3a\deepFOO2.txt

The important point to note here is that the function is defined to expect a parameter containing the matching file object being handled.

This code could be rewritten as:

function logMatch(f) { // prior to 0.9.8 : Jaxer.Log.info(f.getPath()); Jaxer.Log.info(f.path); return f }; var opt = { pattern:'^.*[12]\..*$', recursive:true }; var myResults = Jaxer.Dir.map(rootFolder,opt,logMatch));

A more complex example using a decorator function to format the results of the matches:

/** * A decorator function to be used in conjunction with the Jaxer.Dir.map method. * * The function expects a filesystem obj and returns an object with the applied * format/content changes * @param {Object} f, the file object to decorate. */ function fileDecorator(f) { var decoratorOutput = []; // prior to 0.9.8 // decoratorOutput.push(f.getLeaf()); // decoratorOutput.push(f.getSize()); // decoratorOutput.push(f.getExt()); // decoratorOutput.push(f.getDateModified()); // decoratorOutput.push(f.getParentPath()); decoratorOutput.push(f.leaf); decoratorOutput.push(f.size); decoratorOutput.push(f.ext); decoratorOutput.push(f.dateModified); decoratorOutput.push(f.parentPath); return decoratorOutput.join("|") ; } var fileInfo = Jaxer.Dir.map(rootFolder,{pattern:'^.*[12]\..*$',recursive:true}, fileDecorator); fileInfo.map(function(i) {Jaxer.Log.info(i)}); which outputs the following to the log.

15:43:05 02/20/2008 [framework.] foo1.txt|0|txt|Tue Feb 19 2008 19:15:04 GMT-0800 (Pacific Standard Time)|c:\rootFolder\subFolder1
15:43:05 02/20/2008 [framework.] foo2.txt|0|txt|Tue Feb 19 2008 19:15:04 GMT-0800 (Pacific Standard Time)|c:\rootFolder\subFolder1
15:43:05 02/20/2008 [framework.] deepFOO1.txt|0|txt|Tue Feb 19 2008 19:15:04 GMT-0800 (Pacific Standard Time)|c:\rootFolder\subFolder3\subFolder3a
15:43:05 02/20/2008 [framework.] deepFOO2.txt|0|txt|Tue Feb 19 2008 19:15:04 GMT-0800 (Pacific Standard Time)|c:\rootFolder\subFolder3\subFolder3a

So as you can see, the grep and map methods of the Jaxer.Dir namespace provide you with an excellent utility knife to deal with accessing objects on the file system

One final note, as these kind of searches can take some time depending on the depth of the nested searching, take care when invoking through a callback to ensure that a timeout doesn't occur.