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

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

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

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