Path

Moduleejs.io
Namespace"ejs.io"
Definition class Path
SpecifiedEjs-12.
InheritancePath inherit Object

Path class.

Paths represent files in a file system. The corresponding file or directory for the Path may or may not exist. The representation of a path can be either natural, where the path delimiter is the normal O/S path delimiter. For example, on Windows the path delimiter is "\" and on Unix it is "/". Paths can also be viewed with a unified representation where the delimiter is always "/". Ejscript typically operates in mapped representation to assist creating portable applications. The representaion can be changed via the representation() method.


Properties

QualifiersPropertyTypeDescription
public static const NATIVE  
public static const PORTABLE  

Path Methods

QualifiersMethod
public get absolute(): Path
 Return an absolute path name.
public get accessed(): Date
 Get when the file was last accessed.
public get basename(): Path
 Get the base of portion of the path.
public get components(): Array
 Convert a path to an absolute path and break into components.
public copy(target: Object, options: Object): Void
 Copy a file.
public get created(): Date
 Get when the file was created.
public get dirname(): Path
 Get the directory portion of a file.
public endsWith(suffix: Object): Boolean
 Return true if the path ends with the given suffix.
public get exists(): Boolean
 Test to see if a file for this path exists.
public get extension(): String
 Get the file extension portion of the path.
public files(enumDirs: Boolean): Array
 Get a list of files in a directory.
iterator override get(deep: Boolean): Iterator
 Get iterate over any files contained under this path (assuming it is a directory) "for (v in files)".
iterator override getValues(deep: Boolean): Iterator
 Get an iterator for this file to be used by "for each (v in obj)".
public get hasDrive(): Boolean
 Determine if the file path has a drive spec (C:) in it's name.
public get isAbsolute(): Boolean
 Determine if the path is absolute.
public get isDir(): Boolean
 Determine if the path is a directory.
public get isLink(): Boolean
 Determine if the path is a link file (either symbolic or hard).
public get isRegular(): Boolean
 Determine if the path is a regular file.
public get isRelative(): Boolean
 Determine if the path is absolute.
public get isSymbolic(): Boolean
 Determine if the path is a symbolic link file.
public get join(other: Array): Path
 Join paths.
public get joinExt(ext: String): Path
 Join an extension to a path.
public override get length(): Number
 Get the length of the path name.
public makeDir(options: Object): Void
 Make a new directory and all required intervening directories.
public makeLink(existing: Path, hard: Boolean): Path
 Create a link to a file.
public makeTemp(): Path
 Create a temporary file in the path directory.
public get modified(): Date
 Get when the file was created or last modified.
public get name(): String
 Get the name of the Path as a string in the default representation.
public get natural(): Path
 Get the path in the O/S natural (native) representation.
public get normalize(): Path
 Normalize a path by removing all redundant and invalid path components.
public open(options: Object): File
 Open a path and return a File object.
public openBinaryStream(options: Object): BinaryStream
 Open a file and return a BinaryStream object.
public openTextStream(options: Object): TextStream
 Open a file and return a TextStream object.
public get parent(): Path
 Get the parent directory of path.
Path(path: String)
 Create a new Path object and set the path's location.
public get portable(lower: Boolean): Path
 Get the path in the portable (like Unix) representation.
public readBytes(): ByteArray
 Read the file contents as an array of lines.
public readLines(): Array
 Read the file contents as an array of lines.
public readString(): String
 Read the file contents as a string.
public readXML(): XML
 Read the file contents as an XML object.
public get relative(): Path
 Return a relative path name for the file.
public remove(): Void
 Delete the file associated with the File object.
public removeDir(recursive: Boolean): Void
 Removes a directory.
public rename(target: Object): Void
 Rename a file.
public static set representation(format: Number): Void
 Set the path name representation format.
public static get representation(): Number
 Get the path name representation format.
public same(other: Object): Boolean
 Compare two paths test if they represent the same file.
public get separator(): String
 Return the path separator for this path.
public get size(): Number
 Get the size of the file associated with this Path object.
public startsWith(prefix: Object): Boolean
 Return true if the path starts with the given prefix.
public override toJSON(): String
 Convert the path to a JSON string.
public override toString(): String
 Convert the path to a string.
public trimEnd(pat: String): Path
 Trim a pattern from the end of the path NOTE: this does a case-sensitive match.
public trimExt(): Path
 Trim a file extension from a path.
public trimStart(pat: String): Path
 Trim a pattern from the start of the path NOTE: this does a case-sensitive match.
public truncate(size: Number): Void
 Reduce the size of the file by truncating it.
public write(args: Array): Void
 Write the file contents.

Method Detail

get public absolute(): Path

Return an absolute path name.

Returns
An absolute path equivalent for the current path. The returned path is normalized.

get public accessed(): Date

Get when the file was last accessed.

Returns
A date object with the date and time or null if the method fails.

get public basename(): Path

Get the base of portion of the path.

Description
The base portion is the trailing portion without any directory elements.
Returns
A path containing the base name portion of the current path.

get public components(): Array

Convert a path to an absolute path and break into components.

Returns
An array with an element for each segment of the path. The first element represents the the file system root and will be the empty string or drive spec on a windows like system.

public copy(target: Object, options: Object): Void

Copy a file.

Parameters
target: Object New file location
options: Object Object hash

Options

permissions: Set — to a numeric Posix permissions mask


get public created(): Date

Get when the file was created.

Returns
A date object with the date and time or null if the file does not exist.

get public dirname(): Path

Get the directory portion of a file.

Description
The directory portion is the leading portion including all directory elements and excluding the base name. On some systems, it will include a drive specifier.
Returns
A string containing the directory name portion of the path.

public endsWith(suffix: Object): Boolean

Return true if the path ends with the given suffix.

Parameters
suffix: Object Path or String suffix to compare with the path.
Returns
True if the path does begin with the suffix.

get public exists(): Boolean

Test to see if a file for this path exists.

Returns
True if the file exists.

get public extension(): String

Get the file extension portion of the path.

Returns
String containing the file extension.

public files(enumDirs: Boolean): Array

Get a list of files in a directory.

Description
The returned array contains the base path portion only.
Parameters
enumDirs: Boolean If set to true, then dirList will include sub-directories in the returned list of files. [default: false]
Returns
An Array of strings containing the filenames in the directory.

override iterator get(deep: Boolean): Iterator

Get iterate over any files contained under this path (assuming it is a directory) "for (v in files)".

Description
This operates the same as getValues on a Path object.
Parameters
deep: Boolean Follow the prototype chain [default: false]
Returns
An iterator object.
Example
for (f in Path("."))

override iterator getValues(deep: Boolean): Iterator

Get an iterator for this file to be used by "for each (v in obj)".

Description
Return This operates the same as $get on a Path object.
Parameters
deep: Boolean Follow the prototype chain. Only implemented in ECMA compliance mode.. [default: false]
Returns
An iterator object.
Example
for each (f in Path("."))

get public hasDrive(): Boolean

Determine if the file path has a drive spec (C:) in it's name.

Description
Only relevant on Windows like systems.
Returns
True if the file path has a drive spec.

get public isAbsolute(): Boolean

Determine if the path is absolute.

Returns
True if the path is an absolute path beginning at the file system's root.

get public isDir(): Boolean

Determine if the path is a directory.

Returns
True if the file is a directory.

get public isLink(): Boolean

Determine if the path is a link file (either symbolic or hard).

Returns
True if the file is a link.

get public isRegular(): Boolean

Determine if the path is a regular file.

Returns
True if the file is a regular file and not a directory.

get public isRelative(): Boolean

Determine if the path is absolute.

Returns
True if the path is an absolute path beginning at the file system's root.

get public isSymbolic(): Boolean

Determine if the path is a symbolic link file.

Returns
True if the file is a symbolic link.

get public join(other: Array): Path

Join paths.

Description
Joins one more more paths together. If another path is absolute, return it. Otherwise add a separator, and continue joining.
Returns
A joined, normalized path.

get public joinExt(ext: String): Path

Join an extension to a path.

Description
If the base name of the path already has an extension, this call does nothing.
Returns
A path with extension.

override get public length(): Number

Get the length of the path name.

Returns
The number of characters in the path name.

public makeDir(options: Object): Void

Make a new directory and all required intervening directories.

Description
If the directory already exists, the function returns without throwing an exception.
Parameters
options: Object
options: Object

Options

permissions: Set — to a numeric Posix permissions mask

owner: String — representing the file owner (Not implemented)

group: String — representing the file group (Not implemented)

Throws

IOError: if the directory cannot be created.


public makeLink(existing: Path, hard: Boolean): Path

Create a link to a file.

Parameters
existing: Path Path to an existing file to link to.
hard: Boolean Set to true to create a hard link. Otherwise the default is to create a symbolic link. [default: false]
Returns
This path.

public makeTemp(): Path

Create a temporary file in the path directory.

Description
Creates a new, uniquely named temporary file.
Returns
A new Path object for the temp file.

get public modified(): Date

Get when the file was created or last modified.

Returns
A date object with the date and time or null if the method fails.

get public name(): String

Get the name of the Path as a string in the default representation.

Description
This is the same as $toString.
Returns
The name of the path.

get public natural(): Path

Get the path in the O/S natural (native) representation.

Description
This uses the native O/S separators, this is "\" on windows and "/" on unix.
Returns
The path in the O/S natural representation. The returned path is normalized.

get public normalize(): Path

Normalize a path by removing all redundant and invalid path components.

Description
This removes "/..", "segment/.." and "./" components. It not convert to an absolute path nor will it map the case of the filename.
Returns
A normalized path with all.

public open(options: Object): File

Open a path and return a File object.

Parameters
options: Object
options: Object

Options

mode: optional — file access mode string. Use "r" for read, "w" for write, "a" for append to existing content, "+" never truncate.

permissions: optional — Posix permissions number mask. Defaults to 0664.

owner: String — representing the file owner (Not implemented)

group: String — representing the file group (Not implemented)

Returns
A File object which implements the Stream interface.

Throws

IOError: if the path or file cannot be created.


public openBinaryStream(options: Object): BinaryStream

Open a file and return a BinaryStream object.

Parameters
options: Object Optional options object

Options

permissions: optional — Posix permissions number mask. Defaults to 0664.

owner: String — representing the file owner (Not implemented)

group: String — representing the file group (Not implemented)

Returns
A BinaryStream object which implements the Stream interface.

Throws

IOError: if the path or file cannot be opened or created.


public openTextStream(options: Object): TextStream

Open a file and return a TextStream object.

Parameters
options: Object Optional options object

Options

mode: optional — file access mode string. Use "r" for read, "w" for write, "a" for append to existing content, "+" never truncate.

encoding: Text — encoding format

permissions: optional — Posix permissions number mask. Defaults to 0664.

owner: String — representing the file owner (Not implemented)

group: String — representing the file group (Not implemented)

Returns
A TextStream object which implements the Stream interface.

Throws

IOError: if the path or file cannot be opened or created.


get public parent(): Path

Get the parent directory of path.

Description
This may need to convert to an absolute path if there are no parent directories in a relative path.
Returns
The parent directory as a Path.

Path(path: String)

Create a new Path object and set the path's location.

Parameters
path: String the name of the file to associate with this path object.

get public portable(lower: Boolean): Path

Get the path in the portable (like Unix) representation.

Description
This uses "/" separators.
Parameters
lower: Boolean If set to true, all characters in the path will be mapped to lower case. [default: false]
Returns
The path in a portable representation. The returned path is normalized.

public readBytes(): ByteArray

Read the file contents as an array of lines.

Description
Each line is a string. This method opens the file, reads the contents and closes the file.
Parameters
Returns
An array of strings.

Throws

IOError: if the file cannot be read

Example
for each (byte in Path("/tmp/a.txt").readBytes())

public readLines(): Array

Read the file contents as an array of lines.

Description
Each line is a string. This method opens the file, reads the contents and closes the file.
Parameters
Returns
An array of strings.

Throws

IOError: if the file cannot be read

Example
for each (line in Path("/tmp/a.txt").readLines())

public readString(): String

Read the file contents as a string.

Description
This method opens the file, reads the contents and closes the file.
Parameters
Returns
A string.

Throws

IOError: if the file cannot be read

Example
Path("/tmp/a.txt").readString()

public readXML(): XML

Read the file contents as an XML object.

Description
This method opens the file, reads the contents and closes the file.
Parameters
Returns
An XML object.

Throws

IOError: if the file cannot be read


get public relative(): Path

Return a relative path name for the file.

Returns
A string containing a file path name relative to the application's current working directory.. The returned path is normalized.

public remove(): Void

Delete the file associated with the File object.

Throws

IOError: if the file exists and could not be deleted.


public removeDir(recursive: Boolean): Void

Removes a directory.

Parameters
recursive: Boolean If true, remove all subdirectories with their contents [default: false]

Throws

IOError: if the directory exists and cannot be removed.


public rename(target: Object): Void

Rename a file.

Description
If the new path exists it is removed before the rename.
Parameters
target: Object New name of the path. Can be either a Path or String.

Throws

IOError: if the original file does not exist or cannot be renamed.


static set public representation(format: Number): Void

Set the path name representation format.

Parameters
format: Number Path format. Must be either: NATIVE or PORTABLE.

static get public representation(): Number

Get the path name representation format.

Returns
The Path format. Will return either: NATIVE or PORTABLE.

public same(other: Object): Boolean

Compare two paths test if they represent the same file.

Parameters
other: Object Other path to compare with
Returns
True if the paths represent the same underlying filename.

get public separator(): String

Return the path separator for this path.

Returns
A string. Will typically be either "/" or "\\" depending on the platform and representation.

get public size(): Number

Get the size of the file associated with this Path object.

Returns
The number of bytes in the file or -1 if length determination failed.

public startsWith(prefix: Object): Boolean

Return true if the path starts with the given prefix.

Parameters
prefix: Object Path or String prefix to compare with the path.
Returns
True if the path does begin with the prefix.

override public toJSON(): String

Convert the path to a JSON string.

Returns
A JSON string representing the path.

override public toString(): String

Convert the path to a string.

Description
The format of the string will depend on the defined $representation format.
Returns
A string representing the path.

public trimEnd(pat: String): Path

Trim a pattern from the end of the path NOTE: this does a case-sensitive match.

Returns
A Path containing the trimmed path name.

public trimExt(): Path

Trim a file extension from a path.

Returns
A Path with no extension.

public trimStart(pat: String): Path

Trim a pattern from the start of the path NOTE: this does a case-sensitive match.

Returns
A Path containing the trimmed path name.

public truncate(size: Number): Void

Reduce the size of the file by truncating it.

Parameters
size: Number The new size of the file. If the truncate argument is greater than or equal to the current file size nothing happens.

Throws

IOError: if the truncate failed.


public write(args: Array): Void

Write the file contents.

Description
This method opens the file, writes the contents and closes the file.
Parameters
args: Array The data to write to the file. Data is serialized in before writing. Note that numbers will not be written in a cross platform manner. If that is required, use the BinaryStream class to write Numbers.

Throws

IOError: if the data cannot be written