File object

  • Revision slug: SpiderMonkey/File_object
  • Revision title: File object
  • Revision id: 95213
  • Created:
  • Creator: Wesgarland
  • Is current revision? No
  • Comment speling

Revision Content

Warning: This section describes a component of the SpiderMonkey JavaScript interpreter which is non-standard, not generally compiled into distributions, is a potential source of huge security holes, and not well tested.

Getting Started

In order to use the File object from your JavaScript programs, you must enable it by setting the make variable JS_HAS_FILE_OBJECT during the compilation of your Spidermonkey engine.

If you are building a standalone version of Spidermonkey (see: SpiderMonkey Build Documentation), this variable can be added on the make command line, like so:

cd mozilla/js/src
make -f Makefile.ref JS_HAS_FILE_OBJECT=1

Alternatively, if you are building a larger product (such as a browser) and want to include the File object, you may need to perform minor Makefile surgery.

Summary

Non-Standard Server-Side Object

This object lets you work files and directories on the local filesystem, and create OS pipelines. Creating a pipeline involves spawning arbitrary processes; this means that giving a script access to the File object is exactly equivalent to giving the script access to the UNIX shell or DOS command interpreter.

Filesystem access is implemented with NSPR I/O Functions, and as such shares many semantics. Pipelines are implemented with the popen() system call. There is currently no support for p2open()-like semantics.

Here is the original proposal for this object, and a status update from December 1998: http://www.mozilla.org/js/js-file-object.html

Created By

The File constructor:

new File();
new File(filename);

Parameters

filename
Name of the file we want to work with. Directories and pipelines are considered special files. Pipelines either begin or end with the pipe (|) symbol.

Description

Filenames are specified as strings that have an implementation defined format. Use of standard "file:" URLs is encouraged. If no argument is supplied to the constructor, the current working directory is the file object that is returned.

Examples of possible prefix strings are "/" to indicate the Unix root directory, "c:" to specify a Windows drive letter, and "file:" to indicate a file URL.

When a file is constructed, leading and trailing spaces are removed from the filename, so new File(" abc.txt      ") just creates a file called abc.txt. Filenames starting and ending with the pipe symbol (|) are interpreted as pipes. Readable pipelines (i.e. pipe to programs generating output on stdout) begin with the pipe symbol; writeable pipelines end with the pipe symbol. Bi-directional pipelines are not supported.

Properties

length

parent

path

name

input -- stdin

isDirectory

isFile

error -- stderr

exists

canRead

canWrite

canAppend

canReplace

isOpen

type

mode

creationTime

lastModified

size

hasRandomAccess

hasAutoFlush

position

isNative

output -- stdout

Methods

open

close

remove

copyTo

renameTo

flush

seek

read

readln

readAll

write

writeln

writeAll

list

mkdir

toString

toURL

Examples

Example: Sending mail through a pipeline

var mail = new File("|/usr/lib/sendmail foo@bar.com");
mail.writeln("I love JavaScript.\nPipe support is especially good!");
mail.close();

Revision Source

<p>
</p>
<div class="warning"><b>Warning:</b> This section describes a component of the SpiderMonkey JavaScript interpreter which is non-standard, not generally compiled into distributions, is a potential source of huge security holes, and not well tested.</div>
<h3 name="Getting_Started"> Getting Started </h3>
<p>In order to use the File object from your JavaScript programs, you must enable it by setting the make variable JS_HAS_FILE_OBJECT during the compilation of your Spidermonkey engine. 
</p><p>If you are building a standalone version of Spidermonkey (see: <a href="en/SpiderMonkey_Build_Documentation">SpiderMonkey Build Documentation</a>), this variable can be added on the make command line, like so:
</p>
<pre>cd mozilla/js/src
make -f Makefile.ref JS_HAS_FILE_OBJECT=1
</pre>
<p>Alternatively, if you are building a larger product (such as a browser) and want to include the File object, you may need to perform minor Makefile surgery.
</p>
<h3 name="Summary"> Summary </h3>
<p><b><i>Non-Standard</i> Server-Side Object</b>
</p><p>This object lets you work files and directories on the local filesystem, and create OS pipelines. Creating a pipeline involves spawning arbitrary processes; this means that <i>giving a script access to the <code>File</code> object is exactly equivalent to giving the script <b>access to the UNIX shell</b> or DOS command interpreter.</i>
</p><p>Filesystem access is implemented with <a class="external" href="http://www.mozilla.org/projects/nspr/reference/html/priofnc.html">NSPR I/O Functions</a>, and as such shares many semantics. Pipelines are implemented with the <code>popen()</code> system call. There is currently no support for <code>p2open()</code>-like semantics.
</p><p>Here is the original proposal for this object, and a status update from December 1998: http://www.mozilla.org/js/js-file-object.html
</p>
<h3 name="Created_By"> Created By </h3>
<p>The <code>File</code> constructor:
</p>
<pre class="eval">new File();
new File(<i>filename</i>);

</pre>
<h3 name="Parameters"> Parameters </h3>
<dl><dt> <code>filename</code></dt><dd> Name of the file we want to work with. Directories and pipelines are considered special files. Pipelines either begin or end with the pipe (<code>|</code>) symbol. 
</dd></dl>
<h3 name="Description"> Description </h3>
<p>Filenames are specified as strings that have an implementation defined format. Use of standard "file:" URLs is encouraged. If no argument is supplied to the constructor, the current working directory is the file object that is returned.
</p><p>Examples of possible prefix strings are "/" to indicate the Unix root directory, "c:" to specify a Windows drive letter, and "file:" to indicate a file URL.
</p><p>When a file is constructed, leading and trailing spaces are removed from the filename, so <code>new File(" abc.txt      ")</code> just creates a file called abc.txt. Filenames starting and ending with the pipe symbol (<code>|</code>) are interpreted as pipes. Readable pipelines (i.e. pipe to programs generating output on stdout) begin with the pipe symbol; writeable pipelines end with the pipe symbol. Bi-directional pipelines are not supported.
</p>
<h3 name="Properties"> Properties </h3>
<p>length
</p><p>parent
</p><p>path
</p><p>name
</p><p>input -- stdin
</p><p>isDirectory
</p><p>isFile
</p><p>error -- stderr
</p><p>exists
</p><p>canRead
</p><p>canWrite
</p><p>canAppend
</p><p>canReplace
</p><p>isOpen
</p><p>type
</p><p>mode
</p><p>creationTime
</p><p>lastModified
</p><p>size
</p><p>hasRandomAccess
</p><p>hasAutoFlush
</p><p>position
</p><p>isNative
</p><p>output -- stdout
</p>
<h3 name="Methods"> Methods </h3>
<p>open
</p><p>close
</p><p>remove
</p><p>copyTo
</p><p>renameTo
</p><p>flush
</p><p>seek
</p><p>read
</p><p>readln
</p><p>readAll
</p><p>write
</p><p>writeln
</p><p>writeAll
</p><p>list
</p><p>mkdir
</p><p>toString
</p><p>toURL
</p>
<h3 name="Examples"> Examples </h3>
<h4 name="Example:_Sending_mail_through_a_pipeline"> Example: Sending mail through a pipeline </h4>
<pre class="eval">var mail = new File("|/usr/lib/sendmail foo@bar.com");
mail.writeln("I love JavaScript.\nPipe support is especially good!");
mail.close();
</pre>
Revert to this revision