File functions

Author: FileEX

elements/File/file.yaml

@@ -0,0 +1,3 @@
+name: 'file'
+description: |
+    THIS FUNCTION NEEDS DOCUMENTATION

functions/File/examples/fileClose-1.lua

@@ -0,0 +1,5 @@
+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

functions/File/examples/fileCopy-1.lua

@@ -0,0 +1,9 @@
+addEventHandler("onClientResourceStart", resourceRoot, function(res)
+    local filePath = ":"..getResourceName(res).."/test.txt"
+    fileCreate(filePath) --create the file in this resource and name it 'test.txt'.
+    if fileCopy(filePath,":"..getResourceName(res).."/test1.txt") then
+         outputChatBox("File was successfully copied!", 0, 100, 0)
+    else
+        outputChatBox("File was not successfully copied, probably because it doesn't exist.", 100, 0, 0)
+    end
+end)

functions/File/examples/fileCopy-2.lua

@@ -0,0 +1,9 @@
+addEventHandler("onResourceStart", resourceRoot, function(res)
+    local filePath = ":"..getResourceName(res).."/test.txt"
+    fileCreate(filePath) --create the file in this resource and name it 'test.txt'.
+    if fileCopy(filePath, ":"..getResourceName(res).."/test1.txt") then
+         outputChatBox("File was successfully copied!", root, 0, 100, 0)
+    else
+         outputChatBox("File was not successfully copied, probably because it doesn't exist.", root, 100, 0, 0)
+    end
+end)

functions/File/examples/fileCreate-1.lua

@@ -0,0 +1,5 @@
+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

functions/File/examples/fileDelete-1.lua

@@ -0,0 +1,6 @@
+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
+    fileDelete("test.txt")                            -- delete file
+end

functions/File/examples/fileExists-1.lua

@@ -0,0 +1,22 @@
+function checkExistingFile(player,cmd,filename,resourcename)
+	if not filename then -- if the player didn't include a filename
+		outputChatBox("ERROR: Syntax '/checkfile filename resourcename(optional)'.",player) -- display error
+		return false  -- stop function
+	end
+	if not resourcename then -- if the player didn't specify the resource he wants to check, use current resource
+		resourcename = getResourceName(resource) --every resource has a predefined global variable called resource that contains the resource pointer for that resource, in other words, the value that getThisResource() function returns.
+	else
+		if not getResourceFromName(resourcename) then -- if a resource with that name doesn't exist, output error and stop function
+			outputChatBox("ERROR: Resource "..resourcename.." doesn't exist.",player) -- output error message
+			return false -- stop the function here
+		end
+	end
+	-- as it hasn't stopped anywhere, we have both correct resourcename and filename
+	local exists = fileExists((":%s/%s"):format(resourcename,filename)) -- using shorter format of string.format, see StringLibraryTutorial in lua wiki for that
+	if exists then
+		outputChatBox(("The file %q in resource %q exists"):format(filename,resourcename))
+	else
+		outputChatBox(("The file %q in resource %q doesn't exist"):format(filename,resourcename))
+	end
+end
+addCommandHandler("exists",checkExistingFile)

functions/File/examples/fileFlush-1.lua

@@ -0,0 +1,7 @@
+local fileHandle = fileCreate("test.txt")
+if fileHandle then
+    fileWrite(fileHandle, "Line 1")
+    fileFlush(fileHandle)
+    -- ... further writing operations
+    fileClose(fileHandle)
+end

functions/File/examples/fileGetContents-1.lua

@@ -0,0 +1,7 @@
+local handle = fileOpen("code.lua", true)
+local buffer = fileGetContents(handle) -- code.lua must be listed in meta.xml (for example as <file> for this example)
+fileClose(handle)
+
+if buffer then
+    loadstring(buffer)() -- This is just an example. You should avoid using loadstring. If you are dealing with configuration use json functions instead for security reasons.
+end

functions/File/examples/fileGetPath-1.lua

@@ -0,0 +1,6 @@
+local newFile = fileCreate("test.txt")                -- attempt to create a new file
+if (newFile) then                                       -- check if the creation succeeded
+    local path = fileGetPath(newFile)
+    outputChatBox("New file created at: "..path, root, 0, 255, 0)
+    fileClose(newFile)                                -- close the file once you're done with it
+end

functions/File/examples/fileGetPos-1.lua

@@ -0,0 +1,11 @@
+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.."Current Position: "..fileGetPos(hFile))                  -- ... and output them to the console and outputs the current read position
+    end
+    fileClose(hFile)                           -- close the file once we're done with it
+else
+    outputConsole("Unable to open test.txt")
+end

functions/File/examples/fileGetSize-1.lua

@@ -0,0 +1,9 @@
+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
+	local size = fileGetSize(newFile)              -- get size
+	if size then
+		outputChatBox("Size of test.txt is: "..size, source) -- output size
+        end
+	fileClose(newFile)                                -- close the file once you're done with it
+end

functions/File/examples/fileIsEOF-1.lua

@@ -0,0 +1,11 @@
+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

functions/File/examples/fileOpen-1.lua

@@ -0,0 +1,11 @@
+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

functions/File/examples/fileOpen-2.lua

@@ -0,0 +1,9 @@
+local hFile = fileOpen("test.txt")             -- attempt to open the file (read and write mode)
+if hFile then                                  -- check if it was successfully opened
+    fileSetPos( hFile, fileGetSize( hFile ) )  -- move position to the end of the file
+    fileWrite(hFile, "hello" )                 -- append data
+    fileFlush(hFile)                           -- Flush the appended data into the file.
+    fileClose(hFile)                           -- close the file once we're done with it
+else
+    outputConsole("Unable to open test.txt")
+end

functions/File/examples/fileRead-1.lua

@@ -0,0 +1,14 @@
+function readFile(path)
+    local file = fileOpen(path) -- attempt to open the file
+    if not file then
+        return false -- stop function on failure
+    end
+    local count = fileGetSize(file) -- get file's total size
+    local data = fileRead(file, count) -- read whole file
+    fileClose(file) -- close the file once we're done with it
+    outputConsole(data) -- output code in console
+end
+
+addCommandHandler("readfile",function(cmd,fileName) -- add command to test this function
+    readFile(fileName) -- execute the function
+end)

functions/File/examples/fileRename-1.lua

@@ -0,0 +1,5 @@
+if fileRename( "test1.txt", "test2.txt" ) then
+    outputConsole("File `test1.txt` successfully renamed to `test2.txt`")
+else
+    outputConsole("Unable to rename `test1.txt`")
+end

functions/File/examples/fileRename-2.lua

@@ -0,0 +1,5 @@
+if fileRename( "test1.txt", "myFolder/test1.txt" ) then
+    outputConsole("File `test1.txt` successfuly moved to `myFolder` folder")
+else
+    outputConsole("Unable to move `test1.txt`")
+end

functions/File/examples/fileSetPos-1.lua

@@ -0,0 +1,9 @@
+local hFile = fileOpen("test.dat")          -- attempt to open the file
+if hFile then                               -- check if it succeeded
+    fileSetPos(hFile, 8)                    -- set the read/write position
+    local readByte = fileRead(hFile, 1)     -- read one byte from this position
+    outputConsole("Byte at position 8 = " .. string.byte(readByte))     -- output it
+    fileClose(hFile)                        -- close the file
+else
+    outputConsole("Unable to open test.dat")
+end

functions/File/examples/fileWrite-1.lua

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

functions/File/fileClose.yaml

@@ -1,9 +1,22 @@
-# Scraped from: https://wiki.multitheftauto.com/wiki/fileClose
 shared: &shared
   name: fileClose
-  description: THIS FUNCTION NEEDS DOCUMENTATION
-
-server:
-  <<: *shared
-client:
-  <<: *shared
+  notes:
+    - type: 'important'
+      content: |
+        It is 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.
+  oop:
+    entity: file
+    method: close
+  description: Closes a file handle obtained by [[fileCreate]] or [[fileOpen]].
+  parameters:
+    - name: 'theFile'
+      type: 'file'
+      description: The file handle to close. 
+  returns:
+    description: Returns true if successful, false otherwise.
+    values:
+      - type: bool
+        name: result
+  examples:
+    - path: 'examples/fileClose-1.lua'
+      description: This example creates a text file and writes a string to it.

functions/File/fileCopy.yaml

@@ -1,9 +1,38 @@
-# Scraped from: https://wiki.multitheftauto.com/wiki/fileCopy
 shared: &shared
   name: fileCopy
-  description: THIS FUNCTION NEEDS DOCUMENTATION
+  notes:
+    - type: 'tip'
+      content: |
+        If you do not want to share the content of the created file with other servers, prepend the file path with @ (See [[filepath]] for more information).
+  oop:
+    entity: file
+    method: copy
+  description: This function copies a file.
+  parameters:
+    - name: 'filePath'
+      type: 'string'
+      description: The path of the file you want to copy.
+    - name: 'copyToFilePath'
+      type: 'string'
+      description: Where to copy the specified file to.
+    - name: 'overwrite'
+      type: 'bool'
+      description: If set to true it will overwrite a file that already exists at `copyToFilePath`.
+      default: 'false'
+  returns:
+    description: Return true if the file was copied, else false if the `filePath` doesn't exist.
+    values:
+      - type: bool
+        name: result
+
+client:
+  <<: *shared
+  examples:
+    - path: 'examples/fileCopy-1.lua'
+      description: This example copies a file called `test.txt` and called it `test1.txt`.
 
 server:
   <<: *shared
-client:
-  <<: *shared
+  examples:
+    - path: 'examples/fileCopy-2.lua'
+      description: This example copies a file called `test.txt` and called it `test1.txt`.

functions/File/fileCreate.yaml

@@ -1,9 +1,28 @@
-# Scraped from: https://wiki.multitheftauto.com/wiki/fileCreate
 shared: &shared
   name: fileCreate
-  description: THIS FUNCTION NEEDS DOCUMENTATION
-
-server:
-  <<: *shared
-client:
-  <<: *shared
+  notes:
+    - type: 'important'
+      content: |
+        To prevent memory leaks, ensure each successful call to [[fileCreate]] has a matching call to [[fileClose]].
+    - type: 'tip'
+      content: |
+        If you do not want to share the content of the created file with other servers, prepend the file path with @ (See [[filepath]] for more information).
+    - type: 'important'
+      content: |
+        It is 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.
+  oop:
+    entity: file
+    method: new
+  description: 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.
+  parameters:
+    - name: 'filePath'
+      type: 'string'
+      description: The path of the file you want to copy.
+  returns:
+    description: If successful, returns a [[file]] handle which can be used with other file functions ([[fileWrite]], [[fileClose]] etc.). Returns false if an error occured.
+    values:
+      - type: bool
+        name: result
+  examples:
+    - path: 'examples/fileCreate-1.lua'
+      description: This example creates a text file in the current resource and writes a string to it.

functions/File/fileDelete.yaml

@@ -1,9 +1,21 @@
-# Scraped from: https://wiki.multitheftauto.com/wiki/fileDelete
 shared: &shared
   name: fileDelete
-  description: THIS FUNCTION NEEDS DOCUMENTATION
-
-server:
-  <<: *shared
-client:
-  <<: *shared
+  oop:
+    entity: file
+    method: delete
+  description: Deletes the specified file.
+  parameters:
+    - name: 'filePath'
+      type: 'string'
+      description: |
+        The [filepath](/filepath) of the file to delete 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 delete a file name "myFile.txt" in the resource 'fileres', it can be deleted from another resource this way: `fileDelete(":fileres/myFile.txt")`.
+        If the file is in the current resource, only the file path is necessary, e.g. `fileDelete("myFile.txt")`.
+  returns:
+    description: Returns true if successful, false otherwise (for example if there exists no file with the given name, or it does exist but is in use).
+    values:
+      - type: bool
+        name: result
+  examples:
+    - path: 'examples/fileDelete-1.lua'
+      description: This example will show us how to create a file "text.txt" spell it "This is a test file!", Close the file and delete it.

functions/File/fileExists.yaml

@@ -1,9 +1,21 @@
-# Scraped from: https://wiki.multitheftauto.com/wiki/fileExists
 shared: &shared
   name: fileExists
-  description: THIS FUNCTION NEEDS DOCUMENTATION
-
-server:
-  <<: *shared
-client:
-  <<: *shared
+  oop:
+    entity: file
+    method: exists
+  description: This functions checks whether a specified file exists inside a resource.
+  parameters:
+    - name: 'filePath'
+      type: 'string'
+      description: |
+        The [filepath](/filepath) of the file, whose existence is going to be checked, in the following format: `:resourceName/path`. `resourceName` is the name of the resource the file is checked to be in, and 'path' is the path from the root directory of the resource to the file.
+        For example, if you want to check whether a file named 'myfile.txt' exists in the resource 'mapcreator', it can be done from another resource this way: `fileExists(":mapcreator/myfile.txt")`.
+        If the file, whose existence is going to be checked, is in the current resource, only the file path is necessary, e.g. `fileExists("myfile.txt")`. Note that you must use forward slashes '/' for the folders, backslashes '\' will return false.
+  returns:
+    description: Returns true if the file exists, false otherwise.
+    values:
+      - type: bool
+        name: result
+  examples:
+    - path: 'examples/fileExists-1.lua'
+      description: This example checks if a file exists in a resource directory.