Difference between revisions of "Fs.open"

From ComputerCraft Wiki
Jump to: navigation, search
m (Tidy up the mode parameter)
(Copy description from API page, change return, and use type template)
Line 2: Line 2:
 
{{Function
 
{{Function
 
|name=fs.open
 
|name=fs.open
|args=[[string (type)|string]] path, [[string (type)|string]] mode
+
|args={{Type|string}} path, {{Type|string}} mode
 
|api=fs
 
|api=fs
|returns=[[Table_(type)|Table]] the file handle, or [[Nil|nil]] if the mode was read-only and the file did not exist
+
|returns={{Type|table}} the file handle, or [[nil]] on error (e.g. if <var>mode</var> was "r" and the file did not exist, or if <var>mode</var> was "w" or "a" and the file was in a read-only location)
 
|desc=
 
|desc=
 
'''Supported File Modes'''
 
'''Supported File Modes'''
Opens a file. <var>mode</var> consists of a first character which is one of the following:
+
Opens a file so it can be read or written. <var>mode</var> consists of a first character which is one of the following:
 
* "r" to open the file read-only,  
 
* "r" to open the file read-only,  
 
* "w" to open it for writing and remove any existing data on file open, or  
 
* "w" to open it for writing and remove any existing data on file open, or  

Revision as of 19:43, 22 April 2013


Grid Redstone.png  Function fs.open
Supported File Modes

Opens a file so it can be read or written. mode consists of a first character which is one of the following:

  • "r" to open the file read-only,
  • "w" to open it for writing and remove any existing data on file open, or
  • "a" to open for writing but keep existing data and append any writes to the end of the file

optionally followed by "b" to open the file for binary access instead of text access (text mode will perform end-of-line conversions necessary to move text files between Windows, Linux, and Mac OS systems; binary files should not have these conversions applied as they will be corrupted)

When you have opened a file you must always close the file handle, or else data will not be saved.
Syntax fs.open(string path, string mode)
Returns table the file handle, or nil on error (e.g. if mode was "r" and the file did not exist, or if mode was "w" or "a" and the file was in a read-only location)
Part of ComputerCraft
API fs

Examples

Grid paper.png  Example
Creates the file "abcd" for writing, and holds a file handle to it
Code
h = fs.open("abcd", "w")


File Handles

A file handle allows access to a file. A file handle is a table; the functions within the table are accessed with the dot operator (not the colon operator, as may be more intuitive!). The examples below assume a file has already been opened and the handle stored in the variable h.

Closing a file handle

When you open a file you must remember to then close the handle! With the write modes supported by ComputerCraft all the data that you are writing to a file will not be written into the file until you close the file. A file opened in any mode exposes the following close function.

Grid Redstone.png  Function h.close
Closes the file handle, after which it can no longer be used
Syntax h.close()
Returns nil
Part of ComputerCraft
API fs


Files opened in text read mode

A file opened in mode "r" (text read mode) exposes the following functions.


Grid Redstone.png  Function h.readLine
Reads the next line from the file
Syntax h.readLine()
Returns string the next line read from the file, with the end-of-line character stripped; or nil if there are no more lines in the file
Part of ComputerCraft
API fs


Grid Redstone.png  Function h.readAll
Reads the all the text in the file
Syntax h.readAll()
Returns string the entire rest of the file, with the end-of-line character on the very last line (if present) stripped
Part of ComputerCraft
API fs


Files opened in text write/append mode

A file opened in mode "w" (text write mode) or "a" (text append mode) exposes the following functions:


Grid Redstone.png  Function h.write
Writes a string of characters to the file exactly as they appear in the string data
Syntax h.write(string data)
Returns nil
Part of ComputerCraft
API fs


Grid Redstone.png  Function h.writeLine
Writes a string of characters to the file, then appends an end-of-line character
Syntax h.writeLine(string data)
Returns nil
Part of ComputerCraft
API fs


Files opened in binary read mode

A file opened in mode "rb" (binary read mode) exposes the following functions:


Grid Redstone.png  Function h.read
Reads a single byte from the file and returns it
Syntax h.read()
Returns int the byte read from the file, or nil if there are no more bytes
Part of ComputerCraft
API fs


Files opened in binary write/append mode

A file opened in mode "wb" (binary write mode) or "ab" (binary append mode) exposes the following functions:


Grid Redstone.png  Function h.write
Writes a single byte into the file
Syntax h.write(int byte)
Returns nil
Part of ComputerCraft
API fs