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.

functions/File/fileFlush.yaml

@@ -1,9 +1,21 @@
-# Scraped from: https://wiki.multitheftauto.com/wiki/fileFlush
 shared: &shared
   name: fileFlush
-  description: THIS FUNCTION NEEDS DOCUMENTATION
-
-server:
-  <<: *shared
-client:
-  <<: *shared
+  notes:
+    - type: 'info'
+      content: '[[fileClose]] automatically flushes the file.'
+  oop:
+    entity: file
+    method: flush
+  description: |
+    Forces pending disk writes to be executed. [[fileWrite]] doesn't directly write to the hard disk but places the data in a temporary buffer; only when there is enough data in the buffer it is actually written to disk. Call this function if you need the data written right now without closing the file. This is useful for log files that might want to be read while the resource is still executing. `fileFlush` can be called after each log entry is written. Without this, the file may appear empty or outdated to the user.
+  parameters:
+    - name: 'theFile'
+      type: 'file'
+      description: The file handle of the file you wish to flush.
+  returns:
+    description: Returns true if succeeded, false in case of failure (e.g. the file handle is invalid).
+    values:
+      - type: bool
+        name: result
+  examples:
+    - path: 'examples/fileFlush-1.lua'

functions/File/fileGetContents.yaml

@@ -1,9 +1,27 @@
-# Scraped from: https://wiki.multitheftauto.com/wiki/fileGetContents
 shared: &shared
   name: fileGetContents
-  description: THIS FUNCTION NEEDS DOCUMENTATION
-
-server:
-  <<: *shared
-client:
-  <<: *shared
+  notes:
+    - type: 'important'
+      content: |
+        Please note that even if you enable SD #22 and #23 on your server, you are not protected from user attacks, which can happen after verification of the file, but before you read the contents of such verified file. This function enables you to safely read the contents of a meta.xml-listed file on both client and server.
+  oop:
+    entity: file
+    method: getContents
+  description: |
+    Reads the entire contents of the file, optionally verifies the read contents by computing and comparing the checksum with the expected one, and returns the content as string. The file cursor position is not modified by calls to this function. File must be added in the [[meta.xml]].
+  parameters:
+    - name: 'theFile'
+      type: 'file'
+      description: A handle to the file you wish to get the contents from. Use [[fileOpen]] to obtain this handle.
+    - name: 'verifyContents'
+      type: 'bool'
+      description: Set to true, to compare the computed and the expected checksum of the file content.
+      default: 'true'
+  returns:
+    description: Returns the bytes that were read from the file, but only if verification was disabled or if the checksum comparison succeeded. On failure, this function returns nil.
+    values:
+      - type: nil|string
+        name: result
+  examples:
+    - path: 'examples/fileGetContents-1.lua'
+      description: This example opens the code.lua file, checks its contents, and then runs it.

functions/File/fileGetPath.yaml

@@ -1,9 +1,18 @@
-# Scraped from: https://wiki.multitheftauto.com/wiki/fileGetPath
 shared: &shared
   name: fileGetPath
-  description: THIS FUNCTION NEEDS DOCUMENTATION
-
-server:
-  <<: *shared
-client:
-  <<: *shared
+  oop:
+    entity: file
+    method: getPath
+    variable: path
+  description: This function retrieves the path of the given file.
+  parameters:
+    - name: 'theFile'
+      type: 'file'
+      description: The file you want to get the path.
+  returns:
+    description: Returns a string representing the file path, false if invalid file was provided.
+    values:
+      - type: string|false
+        name: result
+  examples:
+    - path: 'examples/fileGetPath-1.lua'

functions/File/fileGetPos.yaml

@@ -1,9 +1,20 @@
-# Scraped from: https://wiki.multitheftauto.com/wiki/fileGetPos
 shared: &shared
   name: fileGetPos
-  description: THIS FUNCTION NEEDS DOCUMENTATION
-
-server:
-  <<: *shared
-client:
-  <<: *shared
+  pair: fileSetPos
+  oop:
+    entity: file
+    method: getPos
+    variable: pos
+  description: Returns the current read/write position in the given file.
+  parameters:
+    - name: 'theFile'
+      type: 'file'
+      description: The file handle you wish to get the position of.
+  returns:
+    description: Returns the file position if successful, or false if an error occured (e.g. an invalid handle was passed).
+    values:
+      - type: int|false
+        name: result
+  examples:
+    - path: 'examples/fileGetPos-1.lua'
+      description: This example opens the file test.txt and outputs its contents and current read position to the console.

functions/File/fileGetSize.yaml

@@ -1,9 +1,18 @@
-# Scraped from: https://wiki.multitheftauto.com/wiki/fileGetSize
 shared: &shared
   name: fileGetSize
-  description: THIS FUNCTION NEEDS DOCUMENTATION
-
-server:
-  <<: *shared
-client:
-  <<: *shared
+  oop:
+    entity: file
+    method: getSize
+    variable: size
+  description: Returns the total size in **bytes** of the given file.
+  parameters:
+    - name: 'theFile'
+      type: 'file'
+      description: The file handle you wish to get the size of.
+  returns:
+    description: Returns the file size if successful, or false if an error occured (e.g. an invalid file handle was passed).
+    values:
+      - type: int|false
+        name: result
+  examples:
+    - path: 'examples/fileGetSize-1.lua'

functions/File/fileIsEOF.yaml

@@ -1,9 +1,25 @@
-# Scraped from: https://wiki.multitheftauto.com/wiki/fileIsEOF
 shared: &shared
   name: fileIsEOF
-  description: THIS FUNCTION NEEDS DOCUMENTATION
-
-server:
-  <<: *shared
-client:
-  <<: *shared
+  notes:
+    - type: 'warning'
+      content: Due to underlying C API restrictions this function may return false until an attempt to read further than the end of the file is made.
+    - type: 'info'
+      content: |
+        When you open a file, its file position is set to the beginning of the file. Each call to [[fileRead]] or [[fileWrite]] moves the position ahead by the amount of bytes that were read/written. This way, by using [[fileIsEOF]] you can check if you've passed through the whole file.
+  oop:
+    entity: file
+    method: isEOF
+    variable: eof
+  description: Checks if the file position is at the end of the file.
+  parameters:
+    - name: 'theFile'
+      type: 'file'
+      description: A handle to the file you wish to check.
+  returns:
+    description: Returns true if the file position of the specified file is at the end of the file, false otherwise.
+    values:
+      - type: bool
+        name: result
+  examples:
+    - path: 'examples/fileIsEOF-1.lua'
+      description: This example opens the file test.txt and outputs its contents to the console.

functions/File/fileOpen.yaml

@@ -1,9 +1,29 @@
-# Scraped from: https://wiki.multitheftauto.com/wiki/fileOpen
 shared: &shared
   name: fileOpen
-  description: THIS FUNCTION NEEDS DOCUMENTATION
-
-server:
-  <<: *shared
-client:
-  <<: *shared
+  notes:
+    - type: 'important'
+      content: To prevent memory leaks, ensure each successful call to [[fileOpen]] has a matching call to [[fileClose]].
+  oop:
+    entity: file
+    method: open
+  description: Opens an existing file for reading and writing.
+  parameters:
+    - name: 'filePath'
+      type: 'string'
+      description: |
+        The [filepath](/filepath) 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")`.
+    - name: 'readOnly'
+      type: 'bool'
+      description: 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:
+    description: If successful, returns a file handle for the file. Otherwise returns false (f.e. if the file doesn't exist).
+    values:
+      - type: file|false
+        name: result
+  examples:
+    - path: 'examples/fileOpen-1.lua'
+      description: This example opens the file test.txt that is in the root of the current resource, and outputs its contents to the console.
+    - path: 'examples/fileOpen-2.lua'
+      description: This example show how to append data to an existing file

functions/File/fileRead.yaml

@@ -1,9 +1,27 @@
-# Scraped from: https://wiki.multitheftauto.com/wiki/fileRead
 shared: &shared
   name: fileRead
-  description: THIS FUNCTION NEEDS DOCUMENTATION
+  notes:
+    - type: 'info'
+      content: '[[fileOpen]] sets the read/write position to the beginning of the file. [[fileGetSize]] gets the total size in bytes of given file.'
+  oop:
+    entity: file
+    method: read
+  description: Reads the specified number of bytes from the given file starting at its current read/write position, and returns them as a string.
+  parameters:
+    - name: 'theFile'
+      type: 'file'
+      description: A handle to the file you wish to read from. Use [fileOpen](/fileOpen) to obtain this handle.
+    - name: 'count'
+      type: 'int'
+      description: The number of bytes you wish to read.
+  returns:
+    description: Returns the bytes that were read in a string. Note that this string might not contain as many bytes as you specified if an error occured, i.e. end of file.
+    values:
+      - type: string|false
+        name: result
 
-server:
-  <<: *shared
 client:
-  <<: *shared
+  <<: *shared
+  examples:
+    - path: 'examples/fileRead-1.lua'
+      description: This example opens the file test.txt and outputs its contents to the console.

functions/File/fileRename.yaml

@@ -1,9 +1,28 @@
-# Scraped from: https://wiki.multitheftauto.com/wiki/fileRename
 shared: &shared
   name: fileRename
-  description: THIS FUNCTION NEEDS DOCUMENTATION
-
-server:
-  <<: *shared
-client:
-  <<: *shared
+  notes:
+    - type: 'info'
+      content: |
+        Also with this function you can move specified file to a new location, new folder or even to another resource's folder. But for this action executing resource must have `ModifyOtherObjects` [[ACL]] right set to true.
+  oop:
+    entity: file
+    method: rename
+  description: Renames the specified file.
+  parameters:
+    - name: 'filePath'
+      type: 'string'
+      description: |
+        The filepath of the source 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. If the file is in the current resource, only the file path is necessary.
+    - name: 'newFilePath'
+      type: 'string'
+      description: Destination [filepath](/filepath) for the specified source file in the same format.
+  returns:
+    description: If successful, returns true. Otherwise returns false.
+    values:
+      - type: bool
+        name: result
+  examples:
+    - path: 'examples/fileRename-1.lua'
+      description: This example renames the file test1.txt that is in the root of the current resource to test2.txt.
+    - path: 'examples/fileRename-2.lua'
+      description: This example moves the file test1.txt that is in the root of the current resource to myFolder folder. If this folder is not exists, it will be created before moving the file test1.txt.

functions/File/fileSetPos.yaml

@@ -1,9 +1,22 @@
-# Scraped from: https://wiki.multitheftauto.com/wiki/fileSetPos
 shared: &shared
   name: fileSetPos
-  description: THIS FUNCTION NEEDS DOCUMENTATION
-
-server:
-  <<: *shared
-client:
-  <<: *shared
+  oop:
+    entity: file
+    method: setPos
+    variable: pos
+  description: Sets the current read/write position in the file.
+  parameters:
+    - name: 'theFile'
+      type: 'file'
+      description: The file handle of which you want to change the read/write position.
+    - name: 'offset'
+      type: 'int'
+      description: The new position. This is the number of bytes from the beginning of the file. If this value is larger than the file size, it is limited to `52,428,800` bytes (50 MB).
+  returns:
+    description: Returns where the **offset** was actually set at. I.e. if offset was past the end of the file, it will be set at the end of the file, and this position will be returned. Returns false in case of failure (e.g. the specified file handle is invalid).
+    values:
+      - type: int|false
+        name: result
+  examples:
+    - path: 'examples/fileSetPos-1.lua'
+      description: This example opens a binary file and prints the value of the byte at position 8 to the console.

functions/File/fileWrite.yaml

@@ -1,9 +1,29 @@
-# Scraped from: https://wiki.multitheftauto.com/wiki/fileWrite
 shared: &shared
   name: fileWrite
-  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: write
+  description: Writes one or more strings to a given file, starting at the current read/write position. Advances the position over the number of bytes that were written.
+  parameters:
+    - name: 'theFile'
+      type: 'file'
+      description: A handle to the file you wish to write to. The file must have been opened with write access, i.e. the file handle must be a result of [fileCreate](/fileCreate) or [fileOpen](/fileOpen) with the readonly parameter set to false.
+    - name: 'string1'
+      type: 'string'
+      description: 'The string to write.'
+    - name: 'string2'
+      type: 'string'
+      description: 'You can provide any number of additional strings to write after string1. These will be written in the order in which they are specified.'
+      default: "nil"
+  returns:
+    description: Returns the number of bytes successfully written to the file, returns false if invalid arguments were specified.
+    values:
+      - type: int|false
+        name: result
+  examples:
+    - path: 'examples/fileWrite-1.lua'
+      description: This example creates a text file and writes a string to it.