Difference between revisions of "FileCreate"

From Multi Theft Auto: Wiki
m
Line 7: Line 7:
  
 
==Syntax==
 
==Syntax==
<syntaxhighlight lang="lua">file fileCreate ( string filename, resource root = getThisResource () )</syntaxhighlight>
+
<syntaxhighlight lang="lua">file fileCreate ( string filePath )</syntaxhighlight>
  
 
===Required Arguments===
 
===Required Arguments===
*'''filename:''' the name of the file you wish to create.
+
*'''filePath:''' the path where the file is to be created 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 you want to create a file named 'myfile.txt' in the resource 'mapcreator', it can be created from another resource this way: ''fileCreate(":mapcreator/myfile.txt")''.
===Optional Arguments===
+
:If the file is in the current resource, only the file path is necessary, e.g. ''fileCreate("myfile.txt")''.
*'''root:''' the resource in which the file should be created. Defaults to the resource calling the function.
 
  
 
===Returns===
 
===Returns===
Line 19: Line 18:
  
 
==Example==
 
==Example==
This example creates a text file and writes a string to it.
+
This example creates a text file in the current resource and writes a string to it.
 
<syntaxhighlight lang="lua">
 
<syntaxhighlight lang="lua">
 
local newFile = fileCreate("test.txt")                -- attempt to create a new file
 
local newFile = fileCreate("test.txt")                -- attempt to create a new file
if newFile then                                      -- check if the creation succeeded
+
if (newFile) then                                      -- check if the creation succeeded
 
     fileWrite(newFile, "This is a test file!")        -- write a text line
 
     fileWrite(newFile, "This is a test file!")        -- write a text line
 
     fileClose(newFile)                                -- close the file once you're done with it
 
     fileClose(newFile)                                -- close the file once you're done with it

Revision as of 03:25, 30 July 2009

Creates a new file in a directory of a resource. If there already exists a file with the specified name, it is overwritten with an empty file.

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 fileCreate ( string filePath )

Required Arguments

  • filePath: the path where the file is to be created 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 you want to create a file named 'myfile.txt' in the resource 'mapcreator', it can be created from another resource this way: fileCreate(":mapcreator/myfile.txt").
If the file is in the current resource, only the file path is necessary, e.g. fileCreate("myfile.txt").

Returns

If successful, returns a file handle which can be used with other file functions (fileWrite, fileClose...). Returns false if an error occured.

Example

This example creates a text file in the current resource and writes a string to it.

local newFile = fileCreate("test.txt")                -- attempt to create a new file
if (newFile) then                                       -- check if the creation succeeded
    fileWrite(newFile, "This is a test file!")        -- write a text line
    fileClose(newFile)                                -- close the file once you're done with it
end

Notice that you can't simply do fileWrite("test.txt", "File content"). Instead, file functions operate on a file handle, which is a special object representing an open file. fileCreate creates a file, opens it, and returns the resulting 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