WebReference.com - Part 3 of chapter 5 from Creating Applications with Mozilla. From O'Reilly (4/4).

Currently available JavaScript functions in the JSLib package are divided into different modules that, in turn, are divided into different classes defined in source files such as file.js, dir.js, and fileUtils.js. Table 5-1 describes the basic classes in the JSLib package's I/O module and describes how they are used.

The JSLib File class exposes most local file routines from the nsIFile interface. The File class is part of the JSLib I/O module, and is defined in jslib/io/file.js. Here is how you load the library from xpcshell:

$ ./run-mozilla.sh ./xpcshell -w -s
js> load(`chrome/jslib/jslib.js');
*********************
JS_LIB DEBUG IS ON
*********************
js>

Once JSLib is loaded, you can load the File module with an include statement:

js> include(`chrome://jslib/content/io/file.js');
*** Chrome Registration of package: Checking for contents.rdf at
resource:/chrome/jslib/
*** load: filesystem.js OK
*** load: file.js OK
true
js>

Note that file.js loads filesystem.js in turn. The class FileSystem in filesystem.js is the base class for the File object. You can also load file.js by using the top-level construct JS_LIB_PATH:

js> include(JS_LIB_PATH+'io/file.js');

Once you have the file.js module loaded, you can create an instance of a File object and call methods on it to manipulate the file and path it represents:

js> var f = new File('/tmp/foo');
js> f;
[object Object]
js> f.help; // listing of everything available to the object
. . .
js> f.path;
/tmp/foo
js> f.exists( );   // see if /tmp/foo exists
false
js> f.create( );   // it doesn't, so create it.
js> f.exists( );
true
js> f.isFile( );   // is it a file?
true
js> f.open('w');  // open the file for writing
true
js> f.write('this is line #1\n');
true
js> f.close( );
js> f.open( );     // open the file again and
js> f.read( );     // read back the data
// you can also use default flag 'r' for reading
this is line #1
js> f.close( );

You can also assign the contents of the file to a variable for later use, iterative loops through the file contents, or updates to the data:

js> f.open( );
true
js> var contents = f.read( );
js> f.close( );
js> print(contents);
this is line #1
js>
// rename the file
js> f.move(`/tmp/foo.dat');
foo.dat
filesystem.js:move successful!
js> f.path;
/tmp/foo.dat

These examples show some ways the JSLib File object can manipulate local files. Using these interfaces can make life a lot easier by letting you focus on creating your Mozilla application without having to implement XPCOM nsIFile objects manually from your script.

To create an instance of the FileUtils class, use the FileUtils constructor:

js> var fu = new FileUtils( );
js> fu;
[object Object]

Then look at the object by calling its help method:

js> fu.help;

The difference between using the File and FileUtils interfaces is that methods and properties on the latter are singleton and require a path argument, while the FileUtils utilities are general purpose and not bound to any particular file. The FileUtils interface has several handy I/O utilities for converting, testing, and using URLs, of which this example shows a few:

js> fu.exists('/tmp');
true
// convert a chrome path to a url
js> fu.chromeToPath('chrome://jslib/content/');
/usr/src/mozilla/dist/bin/chrome/jslib/jslib.xul
// convert a file URL path to a local file path
js> fu.urlToPath('file:///tmp/foo.dat');
/tmp/foo.dat

Most methods on the FileUtils objects are identical to the methods found in file.js, except they require a path argument. Another handy method in the FileUtils class is spawn, which spawns an external executable from the operating system. It's used as follows:

js> fu.spawn('/usr/X11R6/bin/Eterm');

This command spawns a new Eterm with no argument. To open an Eterm with vi, you could also use this code:

js> fu.spawn('/usr/X11R6/bin/Eterm', ['-e/usr/bin/vi']);

Checking to see if three different files exist would take several lines when using the File class, but the FileUtils class is optimized for this type of check, as the following listing shows:

js> var fu=new FileUtils( );
js> fu.exists('/tmp');
true
js> fu.exists('/tmp/foo.dat');
true
js> fu.exists('/tmp/foo.baz');
false

You need to initialize the FileUtils class only once to use its members and handle local files robustly.

The Dir class is custom-made for working with directory structures on a local filesystem. To create an instance of the Dir class, call its constructor and then its help method to see the class properties:

js> var d = new Dir('/tmp');
js> d.help;

Dir inherits from the same base class as File, which is why it looks similar, but it implements methods used specifically for directory manipulation:

js> d.path;
/tmp
js> d.exists( );
true
js> d.isDir( );
true

The methods all work like those in the File and FileUtils classes, so you can append a new directory name to the object, see if it exists, and create it if (it does not) by entering:

js> d.append('newDir');
/tmp/newDir
js> d.path;
/tmp/newDir
js> d.exists( );
false
js> d.create( );
js> d.exists( );
true

Note that some methods in the DirUtils class cannot be called from xpcshell and instead must be called from a XUL window into which the proper JSLib source file was imported. The following XUL file provides two buttons that display information in textboxes about the system directories:

<?xml version="1.0"?>
<?xml-stylesheet href="chrome://global/skin" type="text/css"?>
<window xmlns="https://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"
xmlns:html="https://www.w3.org/1999/xhtml"
id="dir-utils-window"
orient="vertical"
autostretch="never">
<script type="application/x-javascript" src="chrome://jslib/content/io/dirUtils.js"/>
<script>
var du = new DirUtils( );
function getChromeDir( ) {
cd = du.getChromeDir( );
textfield1 = document.getElementById("tf1");
textfield1.setAttribute("value", cd);
}
function getMozDir( ) {
md =   du.getMozHomeDir( );
textfield2 = document.getElementById("tf2");
textfield2.setAttribute("value", md);
}
</script>
<box>
<button id="chrome" onclick="getChromeDir( );" label="chrome" />
<textbox id="tf1" value="chrome dir" />
</box>
<box>
<button id="moz" onclick="getMozDir( );" label="mozdir" />
<textbox id="tf2" value="moz dir" />
</box>
</window>

[previous]

Created: October 3, 2002
Revised: October 3, 2002

URL: https://webreference.com/programming/javascript/mozillaapps/chap5/3/4.html