Path

Moduleejs.io
Definition class Path
InheritancePath inherit Object
Specifiedejscript-1.1
StabilityEvolving.

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

QualifiersPropertyTypeDescription
public get absolutePathAn absolute path equivalent for the current path. The path is normalized.
public get accessedDateGet when the file was last accessed. Set to null if the file does not exist.
public get basenamePathBase of portion of the path. The base portion is the trailing portion without any directory elements.
public get componentsArrayPath 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 createdDateWhen was the file was created. Set to null if the file does not exist.
public get dirnamePathThe 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 existsBooleanDoes a file exist for this path.
public get extensionStringFile extension portion of the path. The file extension is the portion after (and not including) the last ".".
public get hasDriveBooleanDoes the file path have a drive spec (C:) in it's name. Only relevant on Windows like systems.
public get isAbsoluteBooleanIs the path absolute, i.e. Beginning at the file system's root.
public get isDirBooleanIs the path a directory.
public get isLinkBooleanIs the path is a symbolic link. Not available on some platforms (such as Windows and VxWorks).
public get isRegularBooleanIs the path a regular file.
public get isRelativeBooleanIs the path is relative and not absolute.
public get linkTargetPathThe 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 mimeTypeStringGet the mime type for a path or extension string. The path's extension is used to lookup the corresponding mime type.
public get modifiedDateWhen the file was created or last modified. Set to null the file does not exist.
public get nameStringName of the Path as a string. This is the same as toString().
public get naturalPathNatural (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 normalizePathNormalized 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 parentPathThe parent directory of path. This may be an absolute path if there are no parent directories in the path.
public get setpermsNumberThe 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 portablePathThe path in a portable (like Unix) representation. This uses "/" separators. The value is is normalized and the separators are mapped to "/".
public get relativePathThat path in a form relative to the application's current working directory. The value is normalized.
public get separatorStringThe 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 sizeNumberSize 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

QualifiersMethod
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

public contains(pattern: String): Boolean

Test if the path name contains a substring.

Parameters
pattern: String String pattern to search for.
Returns
Boolean True if found.

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

Copy a file.

Parameters
target: Object New file location.
options: Object Object hash. [default: null]
Options
permissionsSet to a numeric Posix permissions mask. Not implemented.

public endsWith(suffix: String): Boolean

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.

public files(enumDirs: Boolean = false): Array

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.

public find(glob: String = * , recurse: Boolean = true): Array

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.

override iterator get(): 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.
Returns
An iterator object.
Example
for (f in Path("."))

override iterator getValues(): 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.
Returns
An iterator object.
Example
for each (f in Path("."))

public join(other: Array): 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.

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.

public makeDir(options: Object = null): 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 [default: null]
options: Object [default: null]
Options
permissionsSet to a numeric Posix permissions mask.
ownerString representing the file owner (Not implemented).
groupString representing the file group (Not implemented).
Throws
IOError: if the directory cannot be created.

public makeLink(existing: Path, hard: Boolean = false): Void

Create a link to a file.

Description
Links are not supported on all platforms (such as Windows and VxWORKS).
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]

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.

public map(separator: String): Path

Get a path after mapping the path directory separator.

Parameters
separator: String Path directory separator to use.
Returns
A new Path after mapping separators.

public open(options: Object = null): File

Open a path and return a File object.

Parameters
options: Object [default: null]
options: Object [default: null]
Options
modeOptional file access mode string. Use "r" for read, "w" for write, "a" for append to existing content, "+" never truncate.
permissionsOptional Posix permissions number mask. Defaults to 0664.
ownerString representing the file owner (Not implemented).
groupString 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 = null): BinaryStream

Open a file and return a BinaryStream object.

Parameters
options: Object Optional options object. [default: null]
Options
permissionsOptional Posix permissions number mask. Defaults to 0664.
ownerString representing the file owner (Not implemented).
groupString 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 = null): TextStream

Open a file and return a TextStream object.

Parameters
options: Object Optional options object. [default: null]
Options
modeOptional file access mode string. Use "r" for read, "w" for write, "a" for append to existing content, "+" never truncate.
encodingText encoding format.
permissionsOptional Posix permissions number mask. Defaults to 0664.
ownerString representing the file owner (Not implemented).
groupString 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.

public Path(path: String)

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

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

public readBytes(): ByteArray

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()

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.
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.
Returns
A string.
Throws
IOError: if the file cannot be read
Example
data = 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.
Returns
An XML object.
Throws
IOError: if the file cannot be read

public remove(): Void

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.

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.

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.

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.

public replaceExt(ext: String): Path

Replace the path extension and return a new path.

Returns
A new path with joined extension.

public resolve(otherPaths: Array): Path

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.

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.

public startsWith(prefix: String): Boolean

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.

override public toJSON(): String

Convert the path to a JSON string.

Returns
A JSON string representing the path.

public toLower(): Path

Convert the path to lower case.

Returns
A new Path mapped to lower case.

override public toString(): String

Return the path as a string.

Description
The path is not translated.
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