File

Read and write files on the computer ARCx runs on. Writing adds to the end of a file and creates it if needed. Reading can take the whole file at once, or a line, a character or a byte at a time from a read position that moves forward as you read. Use full paths, such as C:\Robot\log.txt on Windows.

Where to find it: type File. in a JavaScript script, or open the ARCx API view of the script editor and expand File

Commands

Command	What it does
File.append	Adds one byte to the end of a file, creating the file if it does not exist.
File.appendString	Adds text to the end of a file without a line ending, creating the file if it does not exist.
File.appendStringLine	Adds text followed by a line ending to the end of a file, creating the file if it does not exist.
File.delete	Deletes a file, closing it first if it is open for reading.
File.exists	Checks whether a file exists.
File.getLength	Returns the size of a file in bytes.
File.getReadPosition	Returns how far into a file the next read will start, in bytes from the beginning.
File.isFileOpenForReading	Checks whether a file is open from an earlier read command.
File.isReadEnd	Checks whether the read position has reached the end of a file.
File.readAllText	Returns the rest of a file as text, from the current read position to the end, opening it if needed (an error is raised if it does not exist).
File.readByte	Reads the next byte from a file, opening it on first use (an error is raised if it does not exist).
File.readChar	Reads the next character from a file, opening it on first use (an error is raised if it does not exist).
File.readClose	Closes a file that was opened by a read command, so the next read starts from the beginning and other programs can change or delete it.
File.readLine	Reads the next line of text from a file, opening it on first use (an error is raised if it does not exist).
File.readRandomLine	Returns a random line from a text file, trying not to pick the same line twice in a row.
File.readReset	Closes a file that is open for reading, so the next read starts again from the beginning.
File.setReadPosition	Moves the point in a file where the next read will start, in bytes from the beginning.

Details

File.append

Adds one byte to the end of a file, creating the file if it does not exist.

File.append(filename, @byte)
File.append(filename, byteArray)

Value	Type	What it is
`filename`	string	The path and name of the file.
`byteArray`	number[]	Only in some forms. The bytes to add, each 0 to 255.
`@byte`	number	Only in some forms.

File.append(filename, @byte): Adds one byte to the end of a file, creating the file if it does not exist.
File.append(filename, byteArray): Adds a list of bytes to the end of a file, creating the file if it does not exist.

File.appendString

Adds text to the end of a file without a line ending, creating the file if it does not exist. The text is saved as UTF-8.

File.appendString(filename, str)

Value	Type	What it is
`filename`	string	The path and name of the file.
`str`	string	The text to add.

File.appendStringLine

Adds text followed by a line ending to the end of a file, creating the file if it does not exist. The text is saved as UTF-8.

File.appendStringLine(filename, str)

Value	Type	What it is
`filename`	string	The path and name of the file.
`str`	string	The text to add.

File.delete

Deletes a file, closing it first if it is open for reading. Nothing happens if the file does not exist.

File.delete(filename)

Value	Type	What it is
`filename`	string	The path and name of the file.

File.exists

Checks whether a file exists. Folders do not count.

File.exists(filename)

Value	Type	What it is
`filename`	string	The path and name of the file.

Gives back: boolean. Whether the file exists.

File.getLength

Returns the size of a file in bytes. The file is opened for reading if needed, and an error is raised if it does not exist.

File.getLength(filename)

Value	Type	What it is
`filename`	string	The path and name of the file.

Gives back: number. The file size in bytes.

File.getReadPosition

Returns how far into a file the next read will start, in bytes from the beginning. The file is opened for reading if needed, and an error is raised if it does not exist.

File.getReadPosition(filename)

Value	Type	What it is
`filename`	string	The path and name of the file.

Gives back: number. The read position in bytes, 0 being the start of the file.

File.isFileOpenForReading

Checks whether a file is open from an earlier read command. Open files and their read positions are shared by every script.

File.isFileOpenForReading(filename)

Value	Type	What it is
`filename`	string	The path and name of the file.

Gives back: boolean. Whether the file is open for reading.

File.isReadEnd

Checks whether the read position has reached the end of a file. The file is opened for reading if needed, and an error is raised if it does not exist.

File.isReadEnd(filename)

Value	Type	What it is
`filename`	string	The path and name of the file.

Gives back: boolean. Whether there is nothing left to read.

File.readAllText

Returns the rest of a file as text, from the current read position to the end, opening it if needed (an error is raised if it does not exist). The file stays open with the read position at the end, so use readReset or setReadPosition to read it again from the start.

File.readAllText(filename)

Value	Type	What it is
`filename`	string	The path and name of the file.

Gives back: string. The text that was read.

File.readByte

Reads the next byte from a file, opening it on first use (an error is raised if it does not exist). Returns 0 once the end of the file has been reached.

File.readByte(filename)

Value	Type	What it is
`filename`	string	The path and name of the file.

Gives back: number. The byte, 0 to 255.

File.readChar

Reads the next character from a file, opening it on first use (an error is raised if it does not exist). Each byte is read as one character, so plain ASCII text works best. Returns an empty string once the end of the file has been reached.

File.readChar(filename)

Value	Type	What it is
`filename`	string	The path and name of the file.

Gives back: string. The character as a one-character string, or an empty string at the end of the file.

File.readClose

Closes a file that was opened by a read command, so the next read starts from the beginning and other programs can change or delete it. The filename is matched without regard to case. Nothing happens if the file is not open.

File.readClose(filename)

Value	Type	What it is
`filename`	string	The path and name of the file.

File.readLine

Reads the next line of text from a file, opening it on first use (an error is raised if it does not exist). Raises an error when the end of the file has already been reached; plain ASCII text works best because each byte is read as one character.

File.readLine(filename)

Value	Type	What it is
`filename`	string	The path and name of the file.

Gives back: string. The line, without its line ending.

File.readRandomLine

Returns a random line from a text file, trying not to pick the same line twice in a row. Any line, including the last one, can be picked. It reads the whole file on its own without changing the read position, and raises an error if the file does not exist or is empty.

File.readRandomLine(filename)

Value	Type	What it is
`filename`	string	The path and name of the file.

Gives back: string. The chosen line of text.

File.readReset

Closes a file that is open for reading, so the next read starts again from the beginning. The filename is matched without regard to case. Nothing happens if the file is not open.

File.readReset(filename)

Value	Type	What it is
`filename`	string	The path and name of the file.

File.setReadPosition

Moves the point in a file where the next read will start, in bytes from the beginning. The file is opened for reading if needed, and an error is raised if it does not exist.

File.setReadPosition(filename, position)

Value	Type	What it is
`filename`	string	The path and name of the file.
`position`	number	The new read position in bytes, 0 being the start of the file.