FileHandle

Description

FileHandle provides an object instance for working with a file in multiple steps (stat, open, read/write bytes, etc). In JS it is instantiated in the usual object creation method with "new" keyword, eg. var fh = new FileHandle("file.txt"); (the file name can also be set or changed later using the fileName property).

Properties
String	fileName
FS::FileError	error
String	errorString
bool	exists
bool	isReadable
bool	isWritable
bool	isOpen
FS::OpenMode	openMode
int	size
int	length
FS::Permissions	permissions
Date	atime
Date	btime
Date	mtime
bool	atEnd
int	pos
int	bytesAvailable
int	bytesToWrite
bool	isAbs
bool	isExec
String	path
String	name
String	filePath
String	baseName
String	fullBaseName
String	suffix
String	fullSuffix
String	absPath
String	absFilePath
String	normPath
String	normFilePath

Public Member Functions
	FileHandle (String &fileName=String())
bool	setPermissions (::FS::Permissions p)
void	unsetError ()
Date	fileTime (::FS::FileTime time)
bool	setFileTime (Date &newDate, ::FS::FileTime fileTime)
bool	copy (String &newName)
bool	link (String &linkName)
bool	rename (String &newName)
bool	remove ()
bool	resize (int newSize)
bool	open (::FS::OpenMode mode)
bool	open (String &mode)
void	close ()
bool	reset ()
bool	flush ()
bool	seek (int pos)
int	write (ArrayBuffer &data)
ArrayBuffer	peek (int maxSize)
ArrayBuffer	read (int maxSize)
String	readText (int maxSize)
ArrayBuffer	readAll ()
String	readAllText ()
String	readLine (int maxSize=0)
String	readLines (int maxLines, int fromLine=0, bool trimTrailingNewlines=true)

Constructor & Destructor Documentation

FileHandle()

FileHandle ( String &  fileName = String() )

explicit

Creates a new object instance with given fileName. The file name could be empty and specified later by setting the fileName property. The name can have no path, a relative path, or an absolute path. Relative paths are based on current application directory (see Dir.cwd()).
Note that the directory separator "/" works for all operating systems. On Windows backslash ("\") can also be used but must be escaped as "\".

Property Documentation

fileName

String fileName

readwrite

Name of current file, as set in constructor or using this property. This property can also set the name of the file (eg. fh.fileName = "myfile.txt"). The name can have no path, a relative path, or an absolute path. Relative paths are based on current application directory (see Dir.cwd()).

Note

The directory separator "/" works for all operating systems. On Windows the backslash ("\") can also be used but must be escaped in string literals as "\\".

Warning

Do not set this property if the file has already been opened.

error

FS::FileError error

read

Returns the file error status code. For example, if open() returns false, or a read/write operation returns -1, this function can be called to find out the reason why the operation failed.

See also

errorString, unsetError()

errorString

String errorString

read

Returns a human-readable description of the last device error that occurred.

exists

bool exists

read

Returns true if the current file exists, false otherwise.

isReadable

bool isReadable

read

Returns true if data can be read from the current file, false otherwise. This checks that the file has been opened with FS.O_RDONLY flag set.

isWritable

bool isWritable

read

Returns true if data can be written to current the file, false otherwise. This checks that the file has been opened with FS.O_WRONLY flag set.

isOpen

bool isOpen

read

Returns true if the file has been successfully opened, false otherwise.

openMode

FS::OpenMode openMode

read

Returns the current FS.OpenMode of the file handle, or FS.O_NOTOPEN if the file hasn't been opened.

size

int size

read

Size of the current file, in bytes. Same as length.

length

int length

read

Size of the current file, in bytes. Same as size.

permissions

FS::Permissions permissions

read

Returns the complete OR-ed together combination of FS.Permissions for the file.

See also

setPermissions()

atime

Date atime

read

Returns the date and local time when the current file was last accessed. If the file is not available, this function returns an invalid Date object. Same as fileTime(S_ATIME).

btime

Date btime

read

Returns the date and time when the current file was created / born. If the file birth time is not available, this function returns an invalid Date object. Same as fileTime(S_BTIME).

mtime

Date mtime

read

Returns the date and local time when the current file was last modified. If the file is not available, this function returns an invalid Date object. Same as fileTime(S_MTIME).

atEnd

bool atEnd

read

Returns true if current position in file is at the end, false otherwise. Same as if (fh.pos == fh.size - 1);.

pos

int pos

read

Returns the position that data is written to or read from.

bytesAvailable

int bytesAvailable

read

Returns the number of bytes that are available for reading from current position in file.

bytesToWrite

int bytesToWrite

read

For files opened in buffered mode (default), this function returns the number of bytes waiting to be written. For unbuffered writes, this function returns 0.

isAbs

bool isAbs

read

Returns true if the current file path name is absolute, otherwise returns false if the path is relative.

isExec

bool isExec

read

Returns true if the current file is executable; otherwise returns false.

path

String path

read

Returns the current file's path, excluding the file name.

name

String name

read

Returns the name of current file (with suffix), excluding the path.

filePath

String filePath

read

Returns the current file name, including the path (which may be absolute or relative).

baseName

String baseName

read

Returns the base name of the current file without the path. The base name consists of all characters in the file up to (but not including) the first '.' character.

fullBaseName

String fullBaseName

read

Returns the complete base name of the current file without the path. The full base name consists of all characters in the file up to (but not including) the last '.' character.

suffix

String suffix

read

Returns the suffix (extension) of the current file. The suffix consists of all characters in the file after (but not including) the last '.'.

fullSuffix

String fullSuffix

read

Returns the "full" suffix (extension) of the current file. The full suffix consists of all characters in the file after (but not including) the first '.'.

absPath

String absPath

read

Returns the current file's absolute path, excluding the file name.

absFilePath

String absFilePath

read

Returns the current file's absolute path, including the file name (with extension).

normPath

String normPath

read

Returns the current file's path canonical path (excluding the file name), i.e. an absolute path without symbolic links or redundant "." or ".." elements.

normFilePath

String normFilePath

read

Returns the canonical path including the current file name, i.e. an absolute path without symbolic links or redundant "." or ".." elements.

Member Function Documentation

setPermissions()

bool setPermissions

(

::FS::Permissions

p

)

Sets the permissions for the file to the FS.Permissions flags specified in p. Returns true if successful, or false if the permissions cannot be modified.

unsetError()

void unsetError

(

)

Sets the file's error to FS.NoError.

See also

error, errorString

fileTime()

Date fileTime

(

::FS::FileTime

time

)

Returns the file time specified by time. If the time cannot be determined this function returns an invalid Date object.

See also

btime, mtime, atime, FS.FileTime

setFileTime()

bool setFileTime	(	Date &	newDate,
		::FS::FileTime	fileTime
	)

Sets the file time specified by fileTime to newDate on the current file, returning true if successful; otherwise returns false.
Note: The file must be open to use this function.

copy()

bool copy

(

String &

newName

)

Copies the current (fileName) file to a file called newName. Returns true if successful; otherwise returns false. Note that if a file with the name newName already exists, copy() returns false. The source file is closed before it is copied.

link()

bool link

(

String &

linkName

)

Creates a link named linkName that points to the file currently specified by fileName. What a link is depends on the underlying file system. This function will not overwrite an already existing entity in the file system; in this case, link() will return false and set error to return RenameError.

rename()

bool rename

(

String &

newName

)

Copies the current (fileName) file to a file called newName. Returns true if successful; otherwise returns false. Note that if a file with the name newName already exists, rename() returns false. The source file is closed before it is copied.

remove()

bool remove

(

)

Removes the file specified by fileName. Returns true if successful; otherwise returns false. The file is closed before it is removed.

resize()

bool resize

(

int

newSize

)

Sets the current file's size (in bytes) to newSize. Returns true if the resize succeeds; false otherwise. If newSize is larger than the file currently is, the new bytes will be set to 0; if it is smaller, the file is simply truncated.

open() [1/2]

bool open

(

::FS::OpenMode

mode

)

Opens the current file using FS.OpenMode mode flags, returning true if successful; otherwise false.

open() [2/2]

bool open

(

String &

mode

)

Opens the current file using mode text flag(s), returning true if successful; otherwise false. See FS.OpenMode documentation for text equivalents.

close()

void close

(

)

Flushes and closes the current file if it is open and resets error() status. Does nothing if the file is not open. Errors from flush are ignored.

reset()

bool reset

(

)

Seeks to the start of the file. Returns true on success, false otherwise (eg. file is not open).

flush()

bool flush

(

)

Flush any buffered data waiting to be written out to the file. Returns true on success, false otherwise (eg. file is not open in write mode).

seek()

bool seek

(

int

pos

)

Sets the current position to pos, returning true on success, or false if an error occurred. If the position is beyond the end of a file, then seek() will not immediately extend the file. If a write is performed at this position, then the file will be extended.

write()

int write

(

ArrayBuffer &

data

)

Writes the content of data to the file at the current position. Returns the number of bytes that were actually written, or -1 if an error occurred.

peek()

ArrayBuffer peek

(

int

maxSize

)

Returns maxSize bytes from current position in file without moving the position. If maxSize would read past the end, then returns the entire contents.

read()

ArrayBuffer read

(

int

maxSize

)

Returns maxSize bytes as a byte array from current position in file and advances the position. If maxSize would read past the end, then returns the entire contents.

readText()

String readText

(

int

maxSize

)

Returns maxSize bytes from current position in file and advances the position. If maxSize would read past the end, then returns the entire contents. Result is returned as a string, regardless of the file's OpenMode.

readAll()

ArrayBuffer readAll

(

)

Returns all contents of the file from the current position though the end, as a byte array.

readAllText()

String readAllText

(

)

Returns all contents of the file from the current position though the end. Result is returned as a string, regardless of the file's OpenMode.

readLine()

String readLine

(

int

maxSize = 0

)

Tries to read one line from current position in file and advances the position to the next line (if any). The trailing newline is included in the result.
If maxSize is > 0, then at most maxSize or up to the first newline encountered. The newline character is included unless maxSize is exceeded.
If maxSize is 0 (default) then it will return a whole line regardless of size, or the rest of the file if no newline is found.
Result is returned as a string, regardless of the file's OpenMode.

readLines()

String readLines	(	int	maxLines,
		int	fromLine = 0,
		bool	trimTrailingNewlines = true
	)

Reads up to maxLines lines from current position in file and returns the contents as a string. The file position is advanced during the read.
fromLine can be used to skip a number of lines; the default is zero, meaning to start reading from the current position of the file handle. fromLine can be negative, in which case the file will be read backwards from current position. In this case -1 means starting at the current position, -2 means to skip one line ("start at second-to-last line"), and so on.
Set trimTrailingNewlines to true (default) to skip over any empty lines from the end of the file. When searching backwards, setting trimTrailingNewlines to false will count every newline from the end, including any potential newline at end of the last line of the file.
This operation works on all text files regardless of line endings.

Exceptions

Error

is thrown if the file reading fails for any reason.

Note

- The file should be opened in binary (not text) mode, otherwise results are unpredictable depending on line ending type.

- If no newlines are found in the file then the full contents will be returned (a potentially expensive operation).