A recent addition to the Jaxer IO capabilities are the grep/map methods, lets look at some use cases to explain the powerful functionality these provide to the developer.

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.

Let's look at some examples of this in practice.

consider 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

Jaxer.Dir.grep

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}, function(f) {Jaxer.Log.info(f.getPath()); 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) { Jaxer.Log.info(f.getPath()); 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 = []; decoratorOutput.push(f.getLeaf()); decoratorOutput.push(f.getSize()); decoratorOutput.push(f.getExt()); decoratorOutput.push(f.getDateModified()); decoratorOutput.push(f.getParentPath()); 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, care needs to be taken when invoking through a callback to ensure that a timeout doesn't occur.