# Jaxer.File : Jaxer.Filesystem
Return to: Jaxer Framework index

Utility object for simple filesystem access.

## Platform Support

Jaxer Server Framework | Jaxer Client Framework
--- | ---
1.0 | no

## Constructors

Constructor | Action | Jaxer Server Framework | Jaxer Client Framework
--- | --- | --- | ---
Jaxer.File Constructor(String aPath) : Jaxer.File Creates a new File handle for performing filesystem file operations. | Show Details | 1.0 | no

### Jaxer.File(String aPath) : Jaxer.File

Creates a new File handle for performing filesystem file operations.

Parameters

String | aPath | an argument of string local file path

Returns

Jaxer.File | Returns an instance of File.

Throws
    Throws a Exception containing the error code upon failure.

## Properties

Property | Action | Jaxer Server Framework | Jaxer Client Framework
--- | --- | --- | ---
EOF : Boolean Checks 'end of file' status and returns boolean to indicate whether the end of file has been reached. This function takes no arguments but needs an open read mode filehandle. | Show Details | 1.0 | no

Examples

       var p='/tmp/foo.dat'; var f=new Jaxer.File(p); f.open(); while(!f.EOF) dump("line: "+f.readline()+"\n");

ext : String Returns the extension of the file object | Show Details | 1.0 | no

Examples

       var p='/tmp/foo.dat'; var f=new Jaxer.File(p); alert(f.ext);

  outputs: dat

pos : Number Returns the current byte position in the referenced file. This method is only applicable when using the File.read() method. If used with the File.readline() method it will return the internal read ahead buffer position, which is unlikely to be what was expected. | Show Details | 1.0 | no

Examples

       var p='/tmp/foo.dat'; var f=new Jaxer.File(p); f.open(); while(!f.EOF) { dump("pos: "+f.pos+"\n"); dump("line: "+f.readline()+"\n");
                              }

size : Number Returns the size in bytes of the referenced file system object as reported by the OS. | Show Details | 1.0 | no

Examples

       var p='/tmp/foo.dat'; var f=new Jaxer.File(p); f.size;

  outputs: int 16

## Inherited Properties

Property | Action | Jaxer Server Framework | Jaxer Client Framework
--- | --- | --- | ---
dateModified : Object The last modified timestamp as reported by the OS. | No Details | 1.0 | no

exists : Boolean A boolean indicator of whether the referenced object physically exists on the filesystem. | No Details | 1.0 | no

isDir : Boolean A boolean indicator of whether the referenced object is a folder/directory | No Details | 1.0 | no

isExec : Boolean A boolean indicator of whether the referenced object is an executable | No Details | 1.0 | no

isFile : Boolean A boolean indicator of whether the referenced object is a file | No Details | 1.0 | no

isFolder : Boolean A boolean indicator of whether the referenced object is a folder/directory an alias of as isDir | No Details | 1.0 | no

isHidden : Boolean A boolean indicator of whether the referenced object is hidden | No Details | 1.0 | no

isReadable : Boolean A boolean indicator of whether the referenced object is readable | No Details | 1.0 | no

isSpecial : Boolean A boolean indicator of whether the referenced object is special. NOTE: Not implemented on Mac and possibly other systems. | No Details | 1.0 | no

isSymlink : Boolean A boolean indicator of whether the referenced object is a symlink | No Details | 1.0 | no

isWritable : Boolean A boolean indicator of whether the referenced object is writable | No Details | 1.0 | no

leaf : String Get/Set the leaf (filename + extension) portion of the file path. | No Details | 1.0 | no

nsIFile : Object Returns a clone of the underlying nsIFile object. | No Details | 1.0 | no

path : String Returns the path of the refererenced filesystem object. | No Details | 1.0 | no

permissions : String
Get/Set the file permissions for the File object. this may be ignored/misreported by some versions of windows. on Windows, you can only set the Read/Write bits of a file. And User/Group/Other will have the SAME settings based on the most-relaxed setting (Read 04, 040, 0400, Write 02, 020, 0200). When a file is created, by default it has both Read and Write permissions. Also, you cannot set the file permission to WRITE-ONLY, doing so would set it to read-write

No Details

1.0

no

URL : String Return the path of the referenced object as a file URL | No Details | 1.0 | no

## Functions

Method | Action | Jaxer Server Framework | Jaxer Client Framework
--- | --- | --- | ---
clone() : Jaxer.File Return a new instance of a JSLib File object referencing the same path | Show Details | 1.0 | no

Returns

Jaxer.File | A File object created from the path of the original file

Throws
    Throws a Exception containing the error code.

close(Object exception) : void Closes an open file stream, takes a single parameter Object which will be thrown as a Exception after the close and cleanup of the file stream. | Show Details | 1.0 | no

Parameters

Object | exception | the object to raise as an exception.

Examples

       var p='/tmp/foo.dat'; var f=new Jaxer.File(p); f.open(); f.close();

copy(String aDest) : void Copy to file to another location. | Show Details | 1.0 | no

Parameters

String | aDest | the path to copy the file to.

Examples

       var p='/tmp/foo.dat'; var f=new Jaxer.File(p); f.copy("/tmp/foo_copy.dat");

create() : void Creates a new file under the referenced path of the object | Show Details | 1.0 | no

Throws
    Throws a Exception containing the error code.

createUnique() : void Creates a new unique file under the referenced path of the object. | Show Details | 1.0 | no

Throws
    Throws a Exception containing the error code.

open(String aMode, Number aPermissions) : void Opens the file for reading or writing. The provided file mode can be one or two characters the using 'rb','ab','wb' will cause the file to be opened in binary safe mode. NOTE: This implementation doesn't support file locking so will allow multiple open handles to the same file. | Show Details | 1.0 | no

Parameters

String | aMode | an argument of string 'w', 'a', 'r', 'b'
Number | aPermissions | a number containing the unix style chmod value for the permissions

Examples

       var p='/tmp/foo.dat'; var f=new Jaxer.File(p); f.open();

Throws
    Throws a Exception containing the error code.

read(Number aSize) : String Reads a file, if the file is binary it will return type ex: ELF takes no arguments but needs an open read mode filehandle returns data read from file as a string on success, or a null value on failure | Show Details | 1.0 | no

Parameters

Number | aSize | the number of bytes to read from the file. If it is omitted the read will return the entire contents of the file.

Returns

String | <string contents of foo.dat>

Examples

       var p='/tmp/foo.dat'; var f=new Jaxer.File(p); f.open(); myContent = f.read();

Throws
    Throws a Exception containing the error code.

readAllLines() : String Returns an array of individual lines read from the file on success, throws an Exception on failure | Show Details | 1.0 | no

Returns

String | <string array of foo.dat>

Examples

       var p='/tmp/foo.dat'; var f=new Jaxer.File(p); var lines = f.readAllLines();

Throws
    Throws a Exception containing the error code.

readline() : String Reads a single line from an open file, takes no arguments but needs an open read mode filehandle returns string containing the data read on success, null on failure | Show Details | 1.0 | no

Returns

String | <string line of foo.dat>

Examples

       var p='/tmp/foo.dat'; var f=new Jaxer.File(p); f.open(); while(!f.EOF) dump("line: "+f.readline()+"\n");

Throws
    Throws a Exception containing the error code.

remove() : void Removes the referenced file object from the file system. Throws an exception is the action fails. | Show Details | 1.0 | no

Throws
    Throws a Exception containing the error code.

truncate() : void Truncates the file. Throws an exception if the action fails. | Show Details | 1.0 | no

Throws
    Throws a Exception containing the error code.

write(String a) : void Write provided data to a file. | Show Details | 1.0 | no

Parameters

String | a | Buffer to be written to a file, if the file is Binary then the buffer should be an array.

Examples

       var p='/tmp/foo.dat'; var f=new Jaxer.File(p); f.open("w"); f.write("some data to be written");

Throws
    Throws a Exception containing the error code.

static absolutePath(String path) : String Extracts the absolute path of the file referenced by the provided path | Show Details | 1.0 | no

Parameters

String | path | The full or partial (to be resolved) path of the file

Returns

String | The absolute path of the file referenced by the provided path

static append(String path, String text) : void Add the provided text to the end of an existing file. | Show Details | 1.0 | no

Parameters

String | path | The full or partial (to be resolved) path to append to
String | text | The text to append

static appendLine(String path, String text) : void Add a line to the end of an existing file. | Show Details | 1.0 | no

Parameters

String | path | The full or partial (to be resolved) path to append to
String | text | The text to append, as a new line

static backup(String sourcePath) : String Create a uniquely named backup copy of the file referenced by the provided path | Show Details | 1.0 | no

Parameters

String | sourcePath | The full or partial (to be resolved) path of the original file

Returns

String | The path to the backup copy of the file

static checksum(String path) : String return a crc32 checksum calculated from the file referenced by the provided path | Show Details | 1.0 | no

Parameters

String | path | The full or partial (to be resolved) path of the file

Returns

String | The checksum of the file referenced by the provided path

static chmod(String path, String permissions) : Number
Get/Set the file permissions for the File object If the optional permissions parameter is provided chmod will set the permissions of the object to those provided. this may be ignored/misreported by some versions of windows. on Windows, you can only set the Read/Write bits of a file. And User/Group/Other will have the SAME settings based on the most-relaxed setting (Read 04, 040, 0400, Write 02, 020, 0200). When a file is created, by default it has both Read and Write permissions. Also, you cannot set the file permission to WRITE-ONLY, doing so would set it to read-write

Show Details

1.0

no

Parameters

String | path | The full or partial (to be resolved) path of the original file
String | permissions | The file permissions to apply to the file referenced by the provided path, this number is an OCTAL representation of the permissions. to indicate a number is in octal format in javascript the first digit must be a 0

Returns

Number | The file permissions from the file referenced by the provided path

static copy(String sourcePath, String destinationPath) : void Copies the file from sourcePath to destinationPath. If the destination file exists it will be overwritten. | Show Details | 1.0 | no

Parameters

String | sourcePath | The full or partial (to be resolved) path of the original file
String | destinationPath | The full or partial (to be resolved) path to the new file

static dateModified(String path) : String Return the dateModified for the file referenced by the provided path | Show Details | 1.0 | no

Parameters

String | path | The full or partial (to be resolved) path of the file

Returns

String | The last modified date of file referenced by the provided path

static exists(String path) : Boolean Does the file (or folder) exist on disk? | Show Details | 1.0 | no

Parameters

String | path | The full or partial (to be resolved) path to test

Returns

Boolean | true if exists, false otherwise

static extension(String path) : String Return the file extension for the file referenced by the provided path | Show Details | 1.0 | no

Parameters

String | path | The full or partial (to be resolved) path of the file

Returns

String | The extension of the file referenced by the provided path

static filename(String filename) : String Extracts the filename for the file referenced by the provided path | Show Details | 1.0 | no

Parameters

String | filename | The full or partial (to be resolved) of the path

Returns

String | The filename from the file referenced by the provided path

static getOrCreate(String path) : Jaxer.File Get a file object, and if the object doesn't exist then automagically create it. | Show Details | 1.0 | no

Parameters

String | path | The full or partial (to be resolved) path to get or create

Returns

Jaxer.File | The file, possibly newly-created

static move(String sourcePath, String destinationPath) : void Moves the file from sourcePath to destinationPath, the orginal file is deleted from the file system. If the destination file exists it will be overwritten. | Show Details | 1.0 | no

Parameters

String | sourcePath | The full or partial (to be resolved) path of the original file
String | destinationPath | The full or partial (to be resolved) path to the new file

static parentPath(String parentPath) : String Extracts the path of the containing folder for the file referenced by the provided path | Show Details | 1.0 | no

Parameters

String | parentPath | The full or partial (to be resolved) path of the file

Returns

String | The path to the parent folder of file referenced by the provided path

static read(String path) : null|String Read the contents of a file on local disk. If the file does not exist, returns a null | Show Details | 1.0 | no

Parameters

String | path | The full or partial (to be resolved) path to read

Returns

null | The contents of the file as a string, or null if the file does not exist
String | The contents of the file as a string, or null if the file does not exist

static readLines(String path, [String sep]) : Array|null|String Read the contents of a textfile on local disk, return an array of lines. When the optional sep parameter is not provided return a string with the lines concatenated by the provided parameter. If the file does not exist, returns a null | Show Details | 1.0 | no

Parameters

String | path | The full or partial (to be resolved) path to read
String | sep | (optional)An optional separator to use between lines. If none is specified, returns an array of lines.

Returns

Array | The contents of the file as a string or array of lines, or null if the file does not exist
null | The contents of the file as a string or array of lines, or null if the file does not exist
String | The contents of the file as a string or array of lines, or null if the file does not exist

static remove(String path) : void Delete a file (only if it already exists). | Show Details | 1.0 | no

Parameters

String | path | The full or partial (to be resolved) path to delete

static size(String path) : Number Returns the size of the file in bytes. | Show Details | 1.0 | no

Parameters

String | path | The full or partial (to be resolved) path to truncated

Returns

Number | The size of the file in bytes

static touch(String path) : void Creates a file if required, if the file already exists it will set the last modified timestamp to the current time. | Show Details | 1.0 | no

Parameters

String | path | The full or partial (to be resolved) path to touched

static truncate(String path) : void Truncates a file if the file already exists otherwise it will create an empty file. | Show Details | 1.0 | no

Parameters

String | path | The full or partial (to be resolved) path to truncated

static write(String path, String text) : void Writes the provided text to file specified by the path. WARNING - destructive! This will overwrite an existing file so use File.append if you want to add the data to the end of an existing file. | Show Details | 1.0 | no

Parameters

String | path | The full or partial (to be resolved) path to read
String | text | The text to write to the file

## Inherited Functions

Method | Action | Jaxer Server Framework | Jaxer Client Framework
--- | --- | --- | ---
append(String leafname) : String Changes the path of the filesystem object by appending the provided leaf value. | Show Details | 1.0 | no

Parameters

String | leafname | The leafname to be appended

Returns

String | The appended directory and leafname

Throws
    Throws a Exception containing the error code.

appendRelativePath(String relative) : void This method is used for appending a relative path to the current filesystem object | Show Details | 1.0 | no

Parameters

String | relative | path

Throws
    Throws a Exception containing the error code.

equals(Object a) : Boolean Evaluates whether the current filesystem object refers to the same file as the one provided as a parameter | Show Details | 1.0 | no

Parameters

Object | a | file system object to be compared

Returns

Boolean | true if object refers to same filesystem object, false otherwise

Throws
    Throws a Exception containing the error code.

initPath(Array a) : String This method will initialize the file system object with the provided path information (or will attempt to derive the path if an object is provided). An existing File object can be 'repointed' to a new physical file sytem object by invoking this method. | Show Details | 1.0 | no

Parameters

Array | a | set of arguments

Returns

String | the file extension of the referenced filesystem object

Throws
    Throws a Exception containing the error code.

move(String destination) : void Move the referenced file to a new filesystem location provided as a parameter NOTE: after a move, 'this' will be reinitialized to reference the moved file! | Show Details | 1.0 | no

Parameters

String | destination | path

Throws
    Throws a Exception containing the error code.

normalize() : void As of Mozilla 1.7, the underlying XPCOM method is only implemented under UNIX builds (except for Mac OSX). This method will fail if the path does not exist. | Show Details | 1.0 | no

Throws
    Throws a Exception containing the error code.

resetCache() : Boolean Truncates the file referenced by the filesystem object. | Show Details | 1.0 | no

Returns

Boolean | true indicates success

Throws
    Throws a Exception containing the error code.

## Examples

     var p = '/tmp/foo.dat'; var f = new Jaxer.File(p);

aptana_docs