Path
Module | ejs.io |
Definition | class Path |
Inheritance | Path ![]() |
Specified | ejscript-1.1 |
Stability | Evolving. |
Path class.
Paths are filenames and may or may not represent physical files in a file system. That is, the corresponding file or directory for the Path may or may not exist. Once created, Paths are immutable and their path value cannot be changed.
Properties
Qualifiers | Property | Type | Description |
---|---|---|---|
public get | absolute | Path | An absolute path equivalent for the current path. The path is normalized. |
public get | accessed | Date | Get when the file was last accessed. Set to null if the file does not exist. |
public get | basename | Path | Base of portion of the path. The base portion is the trailing portion without any directory elements. |
public get | components | Array | Path components. This is the path converted to an absolute path and then broken into components for each directory level. It is set to an array object with an element for each segment of the path. The first element represents the file system root and will be the empty string or drive spec on a windows like systems. Array.join("/") can be used to put components back into a complete path. |
public get | created | Date | When was the file was created. Set to null if the file does not exist. |
public get | dirname | Path | The directory portion of a file. 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. |
public get | exists | Boolean | Does a file exist for this path. |
public get | extension | String | File extension portion of the path. The file extension is the portion after (and not including) the last ".". |
public get | hasDrive | Boolean | Does the file path have a drive spec (C:) in it's name. Only relevant on Windows like systems. |
public get | isAbsolute | Boolean | Is the path absolute, i.e. Beginning at the file system's root. |
public get | isDir | Boolean | Is the path a directory. |
public get | isLink | Boolean | Is the path is a symbolic link. Not available on some platforms (such as Windows and VxWorks). |
public get | isRegular | Boolean | Is the path a regular file. |
public get | isRelative | Boolean | Is the path is relative and not absolute. |
public get | linkTarget | Path | The target pointed to if this path is a symbolic link. Not available on some platforms such as Windows and VxWorks. If the path is not a symbolic link, it is set to null. |
public get | mimeType | String | Get the mime type for a path or extension string. The path's extension is used to lookup the corresponding mime type. |
public get | modified | Date | When the file was created or last modified. Set to null the file does not exist. |
public get | name | String | Name of the Path as a string. This is the same as toString(). |
public get | natural | Path | Natural (native) respresentation of the path. This uses the default O/S file system path separator, this is "\" on windows and "/" on unix and is normalized. |
public get | normalize | Path | Normalized representation of the path. This removes "segment/.." and "./" components. Separators are made uniform by converting all separators to be the same as the first separator found in the path. Note: the value is not converted to an absolute path. |
public get | parent | Path | The parent directory of path. This may be an absolute path if there are no parent directories in the path. |
public get set | perms | Number | The file permissions of a path. This number contains the Posix style permissions value or null if the file does not exist. NOTE: this is not a string representation of an octal posix mask. |
public get | portable | Path | The path in a portable (like Unix) representation. This uses "/" separators. The value is is normalized and the separators are mapped to "/". |
public get | relative | Path | That path in a form relative to the application's current working directory. The value is normalized. |
public get | separator | String | The path separator for this path. This will return the first valid path separator used by the path or the default file system path separator if the path has no separators. On Windows, a path may contain "/" and "\" separators. This will be set to a string containing the first separator found in the path. Will typically be either "/" or "/\\" depending on the path, platform and file system. Use natural or portable to create a new path with different path separators. |
public get | size | Number | Size of the file associated with this Path object. Set to number of bytes in the file or -1 if the size determination failed. |
Path Methods
Qualifiers | Method |
---|---|
public | contains(pattern: String): Boolean |
Test if the path name contains a substring. | |
public | copy(target: Object, options: Object = null): Void |
Copy a file. | |
public | endsWith(suffix: String): Boolean |
Return true if the path ends with the given suffix. | |
public | files(enumDirs: Boolean = false): Array |
Get a list of files in a directory. | |
public | find(glob: String = * , recurse: Boolean = true): Array |
Find matching files. | |
iterator override | get(): Iterator |
Get iterate over any files contained under this path (assuming it is a directory) "for (v in files)". | |
iterator override | getValues(): Iterator |
Get an iterator for this file to be used by "for each (v in obj)". | |
public | join(other: Array): Path |
Join paths. | |
public | joinExt(ext: String): Path |
Join an extension to a path. | |
public | makeDir(options: Object = null): Void |
Make a new directory and all required intervening directories. | |
public | makeLink(existing: Path, hard: Boolean = false): Void |
Create a link to a file. | |
public | makeTemp(): Path |
Create a temporary file in the path directory. | |
public | map(separator: String): Path |
Get a path after mapping the path directory separator. | |
public | open(options: Object = null): File |
Open a path and return a File object. | |
public | openBinaryStream(options: Object = null): BinaryStream |
Open a file and return a BinaryStream object. | |
public | openTextStream(options: Object = null): TextStream |
Open a file and return a TextStream object. | |
Path(path: String) | |
Create a new Path object and set the path's location. | |
public | readBytes(): ByteArray |
Read the file contents as a ByteArray. | |
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 | remove(): Void |
Delete the file associated with the Path object. | |
public | removeAll(): Void |
Removes a directory and its contents If the path is a directory, this call will remove all subdirectories and their contents and finally the directory itself. | |
public | rename(target: Object): Void |
Rename a file. | |
public | replaceExt(ext: String): Path |
Replace the path extension and return a new path. | |
public | resolve(otherPaths: Array): Path |
Resolve paths in the neighborhood of this path. | |
public | same(other: Object): Boolean |
Compare two paths test if they represent the same file. | |
public | startsWith(prefix: String): Boolean |
Return true if the path starts with the given prefix. | |
public override | toJSON(): String |
Convert the path to a JSON string. | |
public | toLower(): Path |
Convert the path to lower case. | |
public override | toString(): String |
Return the path as 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
Test if the path name contains a substring.
- Parameters
pattern: String String pattern to search for.
- Returns
- Boolean True if found.
Return true if the path ends with the given suffix.
- Parameters
suffix: String String suffix to compare with the path.
- Returns
- True if the path does begin with the suffix.
Get a list of files in a directory.
- Description
- The returned array contains the base path portion only, relative to the path itself. This routine does not recurse into sub-directories. To get a list of files in sub-directories, use find().
- 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 Path objects for each file in the directory.
Find matching files.
- Description
- Files are listed in depth first order.
- Parameters
glob: String Glob style Pattern that files must match. This is similar to a ls() style pattern. [default: * ] recurse: Boolean Set to true to examine sub-directories. [default: true]
- Returns
- Return a list of matching files.
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.
- 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.
- Returns
- An iterator object.
- Example
for each (f in Path("."))
Join paths.
- Description
- Joins one more more paths together. If the other path is absolute, return it. Otherwise add a separator, and continue joining. The separator is chosen to match the first separator found in either path. If none found, the default file system path separator is used.
- Returns
- A new joined, normalized Path object.
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.
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 a path after mapping the path directory separator.
- Parameters
separator: String Path directory separator to use.
- Returns
- A new Path after mapping separators.
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. [default: null]
- 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. [default: null]
- 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.
Create a new Path object and set the path's location.
- Parameters
path: String Name of the path to associate with this path object.
Read the file contents as a ByteArray.
- Description
- This method opens the file, reads the contents, closes the file and returns a new ByteArray with the contents.
- Returns
- A ByteArray.
- Throws
- IOError: if the file cannot be read
- Example
var b: ByteArray = 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.
- 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.
- Returns
- A string.
- Throws
- IOError: if the file cannot be read
- Example
data = 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.
- Returns
- An XML object.
- Throws
- IOError: if the file cannot be read
Delete the file associated with the Path object.
- Description
- If this is a directory without contents it will be removed.
- Throws
- IOError: if the file exists and could not be deleted.
Removes a directory and its contents If the path is a directory, this call will remove all subdirectories and their contents and finally the directory itself.
- Description
- If the directory does not exist, this call does not error and does nothing.
- Throws
- IOError: if the directory exists and cannot be removed.
Replace the path extension and return a new path.
- Returns
- A new path with joined extension.
Resolve paths in the neighborhood of this path.
- Description
- Resolve operates like join, except that it joins the
given paths to the directory portion of the current ("this") path. For example: if "path" is set to
"/usr/bin/ejs/bin", then path.resolve("lib") will return "/usr/lib/ejs/lib". i.e. it will return the
sibling directory "lib".
Resolve operations by accumulating a virtual current directory, starting with "this" path. It then successively joins the given paths. If the next path is an absolute path, it is used unmodified. The effect is to find the given paths with a virtual current directory set to the directory containing the prior path.
Resolve is useful for creating paths in the region of the current path and gracefully handles both absolute and relative path segments.
- Returns
- A new Path object that is resolved against the prior path.
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 true if the path starts with the given prefix.
- Parameters
prefix: String 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 lower case.
- Returns
- A new Path mapped to lower case.
Return the path as a string.
- Description
- The path is not translated.
- 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