FileOpen: Difference between revisions

Revision as of 10:34, 24 November 2007

Opens an existing file for reading and writing.

Note: The file functions should not be used to implement configuration files. It is encouraged to use the XML functions for this instead.

Syntax

file fileOpen ( string filename, bool readonly = false, resource root = getThisResource () )

Required Arguments

filename: The name of the file you wish to open.

Optional Arguments

readonly: By default, the file is opened with reading and writing access. You can specify false for this parameter if you only need reading access.
root: The resource in whose directory the file is located. Defaults to the resource calling the function.

Returns

If successful, returns a file handle for the file. Otherwise returns false (f.e. if the file doesn't exist).

Example

This example opens the file test.txt and outputs its contents to the console.

local hFile = fileOpen("test.txt", true)       -- attempt to open the file (read only)
if hFile then                                  -- check if it was successfully opened
    local buffer
    while not fileIsEOF(hFile) do              -- as long as we're not at the end of the file...
        buffer = fileRead(hFile, 500)          -- ... read the next 500 bytes...
        outputConsole(buffer)                  -- ... and output them to the console
    end
    fileClose(hFile)                           -- close the file once we're done with it
else
    outputConsole("Unable to open test.txt")
end

Notice that you can't simply do buffer = fileRead("test.txt", 500). Instead, file functions operate on a file handle, which is a special object representing an open file. fileOpen gives us such a handle.

It is also important to remember to close a file after you've finished all your operations on it, especially if you've been writing to the file. If you don't close a file and your resource crashes, all changes to the file may be lost.

@@ Line 11: / Line 11: @@
 </syntaxhighlight>
-===Required arguments===
+===Required Arguments===
 *'''filename''': The name of the file you wish to open.
-===Optional arguments===
+===Optional Arguments===
 *'''readonly:''' By default, the file is opened with reading and writing access. You can specify ''false'' for this parameter if you only need reading access.
 *'''root:''' The resource in whose directory the file is located. Defaults to the resource calling the function.
@@ Line 40: / Line 40: @@
 It is also important to remember to close a file after you've finished all your operations on it, especially if you've been writing to the file. If you don't close a file and your resource crashes, all changes to the file may be lost.
+==See Also==
+{{File functions}}