File object

  • Revision slug: SpiderMonkey/File_object
  • Revision title: File object
  • Revision id: 95217
  • Created:
  • Creator: Wesgarland
  • Is current revision? No
  • Comment Summaries for isNative and position properties

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

Static Properties

input a File object that represents the standard input (stdin).

currentDir a File object that represents the standard output (stdout).

currentDir a File object that represents the standard error (stderr).

currentDir a File object referring to the current directory; this property may be set.

separator the system name separator (slash on UNIX).

Instance Properties

length the length of the file in bytes, or the number of entries in the directory. Note: calculating the length of the directory is very expensive.

parent the directory containing the file.

path the canonical path to the file.

name the name of the file.

isDirectory true if the file is a directory.

isFile true if the file is a file.

exists true if the file exists.

canRead true if the file can be read.

canWrite true if the file can be written.

canAppend true if the file is in append mode.

canReplace true if the file is in replace mode.

isOpen true if the file is open.

type a string specifying the type of data or encoding contained in the file. Currently "ascii" (ASCII), "binary" (UTF-8) or "unicode" (UCS-2). (XXX Note -- ASCII might imply ASCIIZ)

mode a string describing the mode used to open the file.

creationTime a Date object representing the time when the file was created.

lastModified a Date object representing the time when the file was last modified.

size the length of the file in bytes; undefined(?) for directories and pipelines.

hasRandomAccess true if random access is supported for this file. Binary (UTF-8) files and pipelines (including File.intput) do not support random access.

hasAutoFlush force a flush on each line break? (readonly)

position The file position. Writing to the property moves the file pointer.

isNative True if the file is backed by a native stdio FILE stream. (i.e. file.input, file.output, file.error or a pipeline)

Methods

open Opens the file, specifying open method and file type.

close Closes the file.

remove Removes the file, provided it is not open.

copyTo Creates a verbatim copy of the file at a new location.

renameTo Removes the file.

flush Flushes the operating system's write buffers for the file and blocks until any pending data has been committed to disk.

seek Moves the file position pointer forward or backwards.

read Read a fixed number of bytes from the file.

readln Read line from the file.

readAll Read the entire file in, returning an array of lines.

write Write bytes to the file.

writeln Write bytes to the file, followed by a line separator, flushing the buffer if file.hasAutoflush.

writeAll Writes an array of lines to the file, obeying the same semantics as writeln.

list Get a list of files, potentially matching a regular expression filter, from the file. Only has meaning when the file is a directory.

mkdir Create a directory. Directory will be created in the same directory as the file, unless the file is a directory, in which case, the directory will be created in that directory. XXX

toString Returns the canonical path to the file.

toURL Returns a file:// URL describing the file relative to the local file system. URL is URI-encoded.

Examples

Example: Hello, world

File.output.writeln("Hello, world");

Example: Writing a new file

var file = new File("myfile.txt");
file.open("write,create", "text");
file.writeln("The quick brown fox jumped over the lazy dogs");
file.close();

Example: Reading from a file

var data; 
var file = new File("myfile.txt");
file.open("read", "text");
data = file.readln();
file.close(); 

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>
<h4 name="Static_Properties"> Static Properties </h4>
<p><a href="en/Spidermonkey/File_object/input">input</a> a File object that represents the standard input (stdin).
</p><p><a href="en/Spidermonkey/File_object/output">currentDir</a> a File object that represents the standard output (stdout).
</p><p><a href="en/Spidermonkey/File_object/error">currentDir</a> a File object that represents the standard error (stderr).
</p><p><a href="en/Spidermonkey/File_object/currentDir">currentDir</a> a File object referring to the current directory; this property may be set.
</p><p><a href="en/Spidermonkey/File_object/separator">separator</a> the system name separator (slash on UNIX).
</p>
<h4 name="Instance_Properties"> Instance Properties </h4>
<p><a href="en/Spidermonkey/File_object/length">length</a> the length of the file in bytes, or the number of entries in the directory. Note: calculating the length of the directory is very expensive.
</p><p><a href="en/Spidermonkey/File_object/parent">parent</a> the directory containing the file.
</p><p><a href="en/Spidermonkey/File_object/path">path</a> the canonical path to the file.
</p><p><a href="en/Spidermonkey/File_object/name">name</a> the name of the file.
</p><p><a href="en/Spidermonkey/File_object/isDirectory">isDirectory</a> true if the file is a directory.
</p><p><a href="en/Spidermonkey/File_object/isFile">isFile</a> true if the file is a file.
</p><p><a href="en/Spidermonkey/File_object/exists">exists</a> true if the file exists.
</p><p><a href="en/Spidermonkey/File_object/canRead">canRead</a> true if the file can be read.
</p><p><a href="en/Spidermonkey/File_object/canWrite">canWrite</a> true if the file can be written.
</p><p><a href="en/Spidermonkey/File_object/canAppend">canAppend</a> true if the file is in append mode.
</p><p><a href="en/Spidermonkey/File_object/canReplace">canReplace</a> true if the file is in replace mode.
</p><p><a href="en/Spidermonkey/File_object/isOpen">isOpen</a> true if the file is open.
</p><p><a href="en/Spidermonkey/File_object/type">type</a> a string specifying the type of data or encoding contained in the file. Currently "ascii" (ASCII), "binary" (UTF-8) or "unicode" (UCS-2).  (XXX Note -- ASCII might imply ASCIIZ)
</p><p><a href="en/Spidermonkey/File_object/mode">mode</a> a string describing the <a href="en/Spidermonkey/File_object/mode">mode</a> used to open the file.
</p><p><a href="en/Spidermonkey/File_object/creationTime">creationTime</a> a <code>Date</code> object representing the time when the file was created.
</p><p><a href="en/Spidermonkey/File_object/lastModified">lastModified</a> a <code>Date</code> object representing the time when the file was last modified.
</p><p><a href="en/Spidermonkey/File_object/size">size</a> the length of the file in bytes; undefined(?) for directories and pipelines.
</p><p><a href="en/Spidermonkey/File_object/hasRandomAccess">hasRandomAccess</a> true if random access is supported for this file. Binary  (UTF-8) files and pipelines (including <code>File.intput</code>) do not support random access.
</p><p><a href="en/Spidermonkey/File_object/hasAutoFlush">hasAutoFlush</a> force a flush on each line break? (readonly)
</p><p><a href="en/Spidermonkey/File_object/position">position</a> The file position. Writing to the property moves the file pointer.
</p><p><a href="en/Spidermonkey/File_object/isNative">isNative</a> True if the file is backed by a native stdio FILE stream. (i.e. file.input, file.output, file.error or a pipeline)
</p>
<h3 name="Methods"> Methods </h3>
<p><a href="en/Spidermonkey/File_object/open">open</a> Opens the file, specifying open method and file type.
</p><p><a href="en/Spidermonkey/File_object/close">close</a> Closes the file.
</p><p><a href="en/Spidermonkey/File_object/remove">remove</a> Removes the file, provided it is not open.
</p><p><a href="en/Spidermonkey/File_object/copyTo">copyTo</a> Creates a verbatim copy of the file at a new location.
</p><p><a href="en/Spidermonkey/File_object/renameTo">renameTo</a> Removes the file.
</p><p><a href="en/Spidermonkey/File_object/flush">flush</a> Flushes the operating system's write buffers for the file and blocks until any pending data has been committed to disk.
</p><p><a href="en/Spidermonkey/File_object/seek">seek</a> Moves the file position pointer forward or backwards.
</p><p><a href="en/Spidermonkey/File_object/read">read</a> Read a fixed number of bytes from the file.
</p><p><a href="en/Spidermonkey/File_object/readln">readln</a> Read line from the file.
</p><p><a href="en/Spidermonkey/File_object/readAll">readAll</a> Read the entire file in, returning an array of lines.
</p><p><a href="en/Spidermonkey/File_object/write">write</a> Write bytes to the file.
</p><p><a href="en/Spidermonkey/File_object/writeln">writeln</a> Write bytes to the file, followed by a line separator, flushing the buffer if file.<code>hasAutoflush</code>.
</p><p><a href="en/Spidermonkey/File_object/writeAll">writeAll</a> Writes an array of lines to the file, obeying the same semantics as <code>writeln</code>.
</p><p><a href="en/Spidermonkey/File_object/list">list</a> Get a list of files, potentially matching a regular expression filter, from the file. Only has meaning when the file is a directory.
</p><p><a href="en/Spidermonkey/File_object/mkdir">mkdir</a> Create a directory. Directory will be created in the same directory as the file, unless the file is a directory, in which case, the directory will be created in that directory. XXX
</p><p><a href="en/Spidermonkey/File_object/toString">toString</a> Returns the canonical path to the file.
</p><p><a href="en/Spidermonkey/File_object/toURL">toURL</a> Returns a file:// URL describing the file relative to the local file system. URL is URI-encoded.
</p>
<h3 name="Examples"> Examples </h3>
<h4 name="Example:_Hello.2C_world"> Example: Hello, world </h4>
<pre class="eval">File.output.writeln("Hello, world");
</pre>
<h4 name="Example:_Writing_a_new_file"> Example: Writing a new file </h4>
<pre class="eval">var file = new File("myfile.txt");
file.open("write,create", "text");
file.writeln("The quick brown fox jumped over the lazy dogs");
file.close();
</pre>
<h4 name="Example:_Reading_from_a_file"> Example: Reading from a file </h4>
<pre class="eval">var data; 
var file = new File("myfile.txt");
file.open("read", "text");
data = file.readln();
file.close(); 
</pre>
<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