Path
Module | ejs.io |
Namespace | "ejs.io" |
Definition | class Path |
Specified | Ejs-12. |
Inheritance | Path ![]() |
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
Qualifiers | Property | Type | Description |
---|---|---|---|
public static const | NATIVE | ||
public static const | PORTABLE |
Path Methods
Qualifiers | Method |
---|---|
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
Return an absolute path name.
- Returns
- An absolute path equivalent for the current path. The returned path is normalized.
Get when the file was last accessed.
- Returns
- A date object with the date and time or null if the method fails.
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.
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.
Get when the file was created.
- Returns
- A date object with the date and time or null if the file does not exist.
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.
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.
Test to see if a file for this path exists.
- Returns
- True if the file exists.
Get the file extension portion of the path.
- Returns
- String containing the file extension.
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.
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("."))
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("."))
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.
Determine if the path is absolute.
- Returns
- True if the path is an absolute path beginning at the file system's root.
Determine if the path is a directory.
- Returns
- True if the file is a directory.
Determine if the path is a link file (either symbolic or hard).
- Returns
- True if the file is a link.
Determine if the path is a regular file.
- Returns
- True if the file is a regular file and not a directory.
Determine if the path is absolute.
- Returns
- True if the path is an absolute path beginning at the file system's root.
Determine if the path is a symbolic link file.
- Returns
- True if the file is a symbolic link.
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.
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.
Get the length of the path name.
- Returns
- The number of characters in the path name.
Make a new directory and all required intervening directories.
- Description
- If the directory already exists, the function returns without throwing an exception.
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.
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 when the file was created or last modified.
- Returns
- A date object with the date and time or null if the method fails.
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 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.
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.
Open a path and return a File 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.
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.
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 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.
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 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.
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())
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())
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()
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
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.
Delete the file associated with the File object.
Throws
IOError: if the file exists and could not be deleted.
Set the path name representation format.
- Parameters
format: Number Path format. Must be either: NATIVE or PORTABLE.
Get the path name representation format.
- Returns
- The Path format. Will return either: NATIVE or PORTABLE.
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.
Return the path separator for this path.
- Returns
- A string. Will typically be either "/" or "\\" depending on the platform and representation.
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.
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.
Convert the path to a JSON string.
- Returns
- A JSON string representing the path.
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.
Trim a pattern from the end of the path NOTE: this does a case-sensitive match.
- Returns
- A Path containing the trimmed path name.
Trim a file extension from a path.
- Returns
- A Path with no extension.
Trim a pattern from the start of the path NOTE: this does a case-sensitive match.
- Returns
- A Path containing the trimmed path name.
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