Name
OpenFile -- open a file for reading and writing
Synopsis
[id] = OpenFile(id, filename$[, mode, table])
Function
This function attempts to open the file specified by filename$ and assigns id to it. If you pass Nil in id, OpenFile() will automatically choose a vacant identifier and return it. If the file does not exist, this function will fail unless you use the mode argument to open a file for writing. In that case, OpenFile() will create the file for you.

All read and write operations will start at the current file cursor position. You can manually set the file cursor by using the Seek() function but it is also increased if you use other functions which read from or write to the file.

Starting with Hollywood 2.0 you can use the optional argument mode to open the file in read (default) or write mode or in shared mode, which means that you can read from the file and you can also write to it. If a file is opened in read mode, all write operations will fail. If a file is opened in write mode, all read operations will fail.

Starting with Hollywood 6.0 this function accepts an optional table argument which can be used to pass additional parameters. The following table elements are currently recognized:

Adapter:
This tag allows you to specify one or more file adapters that should be asked to open the specified file. This must be set to a string containing the name(s) of one or more adapter(s). Defaults to default. See Loaders and adapters for details. (V6.0)

Encoding:
In case the file is a text file, you can set this tag to the charset used by the file. Hollywood will then handle charset conversions automatically when reading from or writing to the file using functions like ReadLine(), ReadString(), WriteLine() or WriteString(). By default, Hollywood expects text files to be in the UTF-8 charset because that's Hollywood's default charset. If you want to read from or write to a file using the ISO 8859-1 encoding instead, just set Encoding to #ENCODING_ISO8859_1 and Hollywood will handle all conversions to and from ISO 8859-1 automatically. See SetDefaultEncoding for a list of available charsets. (V9.0)

WriteBOM:
Set this tag to True if you want OpenFile() to add the UTF-8 BOM (byte order mark) to the beginning of the file. Obviously, OpenFile() will only do this if the file has been opened in write mode (#MODE_WRITE) and the file's encoding has been set to #ENCODING_UTF8. (V9.0)

Although Hollywood will automatically close all open files when it quits, it is strongly advised that you close an open file when you are done with it using the CloseFile() function so that it becomes available to the operating system again.

Starting with Hollywood 9.0, filename$ may also be one of the special constants #STDIN, #STDOUT, and #STDERR. This is useful for advanced programmers who want to access the stdin, stdout, and stderr file streams associated with each program.

This command is also available from the preprocessor: Use @FILE to preopen files.

Inputs
id
identifier of the file or Nil for auto id selection
filename$
name of the file to open
mode
mode to open the file; can be #MODE_READ, #MODE_WRITE or #MODE_READWRITE (defaults to #MODE_READ) (V2.0)
table
optional: table containing further parameters (V6.0)
Results
id
optional: identifier of the file; will only be returned when you pass Nil as argument 1 (see above)
Example
OpenFile(1, "Highscores.txt")
While Not Eof(1) Do NPrint(ReadLine(1))
CloseFile(1)
This code opens the file "Highscores.txt" as file 1 and prints all of its lines to the screen.

Show TOC