Difference between revisions of "FileOpen"

From Multi Theft Auto: Wiki
(Syntax)
Line 8: Line 8:
 
==Syntax==
 
==Syntax==
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
file fileOpen ( string filename [, bool readonly = false, resource root = getThisResource ()] )
+
file fileOpen ( string filePath [, bool readOnly = false ])
 
</syntaxhighlight>
 
</syntaxhighlight>
  
 
===Required Arguments===
 
===Required Arguments===
*'''filename''': The name of the file you wish to open.
+
*'''filePath:''' the path of the file in the following format: '''":resourceName/path"'''. 'resourceName' is the name of the resource the file is in, and 'path' is the path from the root directory of the resource to the file.
 +
:For example, if there is a file named 'coolObjects.txt' in the resource 'objectSearch', it can be opened from another resource this way: ''fileOpen(":objectSearch/coolObjects.txt")''.
 +
:If the file is in the current resource, only the file path is necessary, e.g. ''fileOpen("coolObjects.txt")''.
  
 
===Optional Arguments===
 
===Optional Arguments===
*'''readonly:''' By default, the file is opened with reading and writing access. You can specify ''true'' for this parameter if you only need reading access.
+
*'''readOnly:''' By default, the file is opened with reading and writing access. You can specify ''true'' 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===
 
===Returns===
Line 22: Line 23:
  
 
==Example==
 
==Example==
This example opens the file test.txt and outputs its contents to the console.
+
This example opens the file test.txt that is in the root of the current resource, and outputs its contents to the console.
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
 
local hFile = fileOpen("test.txt", true)      -- attempt to open the file (read only)
 
local hFile = fileOpen("test.txt", true)      -- attempt to open the file (read only)

Revision as of 03:45, 30 July 2009

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 filePath [, bool readOnly = false ])

Required Arguments

  • filePath: the path of the file in the following format: ":resourceName/path". 'resourceName' is the name of the resource the file is in, and 'path' is the path from the root directory of the resource to the file.
For example, if there is a file named 'coolObjects.txt' in the resource 'objectSearch', it can be opened from another resource this way: fileOpen(":objectSearch/coolObjects.txt").
If the file is in the current resource, only the file path is necessary, e.g. fileOpen("coolObjects.txt").

Optional Arguments

  • readOnly: By default, the file is opened with reading and writing access. You can specify true for this parameter if you only need reading access.

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 that is in the root of the current resource, 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.

See Also