Difference between revisions of "Fs.open"
From ComputerCraft Wiki
m (Fixed up some parts that weren't clear. fixed links to nil) |
|||
| Line 2: | Line 2: | ||
{{Function | {{Function | ||
|name=fs.open | |name=fs.open | ||
| − | |args=[[string (type)|string]] path, [[string (type)|string]] | + | |args=[[string (type)|string]] path, [[string (type)|string]] mode |
| − | + | ||
|api=fs | |api=fs | ||
| − | |returns=[[Table_(type)|Table]] the file handle, or | + | |returns=[[Table_(type)|Table]] the file handle, or [[Nil|nil]] if the mode was read-only and the file did not exist |
| − | |desc=Opens a file; <var>mode</var> consists of a first character which is one of | + | |desc= |
| + | '''Supported File Modes''' | ||
| + | Opens a file; <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, or | + | "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, plus optionally the second character | "a" to open for writing but keep existing data and append any writes to the end of the file, plus optionally the second character | ||
| Line 15: | Line 16: | ||
"b" to open the file for binary access instead of text access | "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) | (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. | ||
|examples= | |examples= | ||
{{Example | {{Example | ||
| − | |desc=Creates the file "abcd" and holds a file handle to it | + | |desc=Creates the file "abcd" for writing, and holds a file handle to it |
|code=h = fs.open("abcd", "w") | |code=h = fs.open("abcd", "w") | ||
}} | }} | ||
| Line 25: | Line 28: | ||
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 (<em>not</em> 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 <var>h</var>. | 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 (<em>not</em> 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 <var>h</var>. | ||
| + | |||
| + | === 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. | ||
| + | {{Function | ||
| + | |name=<var>h</var>.close | ||
| + | |api=fs | ||
| + | |desc=Closes the file handle, after which it can no longer be used | ||
| + | }} | ||
=== Files opened in text read mode === | === Files opened in text read mode === | ||
| Line 40: | Line 52: | ||
|api=fs | |api=fs | ||
|returns=[[string]] the entire rest of the file, with the end-of-line character on the very last line (if present) stripped | |returns=[[string]] the entire rest of the file, with the end-of-line character on the very last line (if present) stripped | ||
| − | |desc=Reads the | + | |desc=Reads the all the text in the file |
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
}} | }} | ||
| Line 63: | Line 70: | ||
|api=fs | |api=fs | ||
|desc=Writes a string of characters to the file, then appends an end-of-line character | |desc=Writes a string of characters to the file, then appends an end-of-line character | ||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
}} | }} | ||
| Line 77: | Line 79: | ||
|name=<var>h</var>.read | |name=<var>h</var>.read | ||
|api=fs | |api=fs | ||
| − | |returns=[[int (type)|int]] the byte read from the file, or | + | |returns=[[int (type)|int]] the byte read from the file, or [[Nil|nil]] if there are no more bytes |
|desc=Reads a single byte from the file and returns it | |desc=Reads a single byte from the file and returns it | ||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
}} | }} | ||
| Line 95: | Line 92: | ||
|api=fs | |api=fs | ||
|desc=Writes a single byte into the file | |desc=Writes a single byte into the file | ||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
}} | }} | ||
[[Category:Lua_Core_Functions]] | [[Category:Lua_Core_Functions]] | ||
Revision as of 11:58, 20 January 2013
 Function fs.open | |
| Supported File Modes
Opens a file; 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, plus optionally the second character "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 if the mode was read-only and the file did not exist |
| Part of | ComputerCraft |
| API | fs |
Contents
Examples
 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.
| 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.
| 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 |
| 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:
| 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 |
| 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:
| 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:
| Function h.write | |
| Writes a single byte into the file | |
| Syntax | h.write(int byte) |
| Returns | nil |
| Part of | ComputerCraft |
| API | fs |
