TextFile

TextFile

TextFile class is used for accessing & modifying an existing text file OR creating a new one in the file system from QJS scripts.

Table of Contents

• Constructor
• Properties
• Functions
  • Open
  • OpenAs
  • Close
  • AtEnd
  • Seek
  • Read
  • ReadLine
  • Write
  • WriteLine
  • SetEncoding

Constructor

A TextFile instance can be constructed using 1 of 3 syntaxes as shown below.

Syntax:

new TextFile([enc])
new TextFile(path, [mode])
new TextFile(path, enc, [mode])

Argument	Description
path	The file to be opened. Any relative paths will be relative to the WARP folder.
enc	The Encoding to use for the file. If not provided UTF-8 is used.
mode	Optional mode in which the file should be opened. Valid values are: r = read only w = write only rw = read/write a = append r is the default mode.

Once the object is created, the following properties & functions become available.

Properties

Property name	Description
<obj>.Path	The opened file's path
<obj>.Size	Size of currently open file
<obj>.Pos	Current file position offset
<obj>.Valid	Boolean indicating there is a valid file currently open

Functions

Open

Used for opening a file with an existing TextFile instance .

If the instance already has a file opened, it will be closed automatically.

Syntax:

<obj>.Open(path, mode)

Argument	Description
path	The file to be opened. Any relative paths will be relative to the WARP folder.
mode	Optional mode in which the file should be opened. Valid values are: r = read only w = write only rw = read/write a = append r is the default mode.

Returns: true if successfully opened else false

OpenAs

Same as Open but with the option to specify the Encoding.

Syntax:

<obj>.OpenAs(path, enc, mode)

Argument	Description
path	The file to be opened. Any relative paths will be relative to the WARP folder.
enc	The Encoding to use for the file. If not provided UTF-8 is used.
mode	Optional mode in which the file should be opened. Valid values are: r = read only w = write only rw = read/write a = append r is the default mode.

Returns: true if successfully opened else false

Close

Closes the currently open file (if any)

Syntax:

<obj>.Close()

AtEnd

Checks whether the internal position has reached the End Of File.

Syntax:

<obj>.AtEnd()

Returns: true if it is at EOF else false

Seek

Changes the internal position to specified value (only if it is valid one).

Syntax:

<obj>.Seek(pos)

Argument	Description
pos	The new position requested. Only works if the value is within the file limits.

Returns: true if position set successfully else false

Read

Reads a specific number of characters from the file.

Syntax:

<obj>.Read([size], [from])

Argument	Description
size	No of characters to be read. If omitted or negative, all the remaining characters are read until NULL termination
from	Address from where the characters need to be read. If omitted or negative, then the characters are read from <obj>.Pos, which is then incremented.

Returns: the retrieved text string if successful otherwise an empty string.

ReadLine

Reads a line of text from the file.

Syntax:

<obj>.ReadLine([from])

Argument	Description
from	Address from where the characters need to be read. If omitted or negative, then the characters are read from <obj>.Pos, which is then incremented.

Returns: the retrieved text string if successful otherwise an empty string.

Write

Writes a text string to the file.

Syntax:

<obj>.Write(text, [to])

Argument	Description
text	The text string to be written.
to	The address at which the string should be written. If omitted or negative, then the data is written at <obj>.Pos, which is then incremented.

Returns: true if successful else false.

WriteLine

Writes a text string as a new line to the file (i.e. a new line character is added at the end).

Syntax:

<obj>.WriteLine(text, [to])

Argument	Description
text	The text string to be written.
to	The address at which the string should be written. If omitted or negative, then the data is written at <obj>.Pos, which is then incremented.

Returns: true if successful else false.

SetEncoding

Unless explicitly changed, all files are treated as UTF-8 encoded by default.

If you need to switch the Encoding before or after opening a file, then you can use this function.

Syntax:

<obj>.SetEncoding(enc)

Argument	Description
enc	The new Encoding to use

Return to top

Further reading

• BinFile
• Inbuilt API
• Scripted API
• Writing scripts