Difference between revisions of "Fs.open"
From ComputerCraft Wiki
m (→Files opened in binary read mode: Correcting link) |
m (More use of Template:Type) |
||
| (5 intermediate revisions by 3 users not shown) | |||
| Line 4: | Line 4: | ||
|args={{Type|string}} path, {{Type|string}} mode | |args={{Type|string}} path, {{Type|string}} mode | ||
|api=fs | |api=fs | ||
| − | |returns={{Type|table}} the file handle, or | + | |returns={{Type|table}} the file handle, or {{Type|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''' | ||
| Line 11: | Line 11: | ||
* "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 | ||
* "a" to open for writing but keep existing data and append any writes to the end of the file | * "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 | + | Any of the three may be optionally followed by "b" to open the file for binary access instead of the default text access (eg, "wb" opens a file for binary output). |
| − | ( | + | |
| − | When you have opened a file you must always close the file handle, or else data | + | Text mode file handles assume UTF-8 encoding for both input and output purposes, and supports all characters within the [https://en.wikipedia.org/wiki/ISO/IEC_8859-1 ISO 8859-1 codepage] (plus a few extras). Prior to ComputerCraft 1.76, instead only [https://en.wikipedia.org/wiki/ASCII#ASCII_printable_characters printable ASCII] characters are supported. In either case, any characters ''not'' supported are translated to 0x3F (representing a question mark). |
| + | |||
| + | When you have opened a file you must always [[#Closing a file handle|close the file handle]], or else data may not be saved. | ||
| + | |||
| + | Append mode and write mode both create a new file if none already exists (and write mode creates a new one even if one does); however, under a few builds of ComputerCraft in the 1.5x range, append mode will fail if an existing file cannot be found. | ||
|examples= | |examples= | ||
{{Example | {{Example | ||
|desc=Creates the file "abcd" for writing, 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=local h = fs.open("abcd", "w") |
| + | }} | ||
| + | {{Example | ||
| + | |desc=Opens "abcd" in either append or write mode, depending on whether it already exists or not. | ||
| + | |code=local h = fs.open("abcd", fs.exists("abcd") and "a" or "w") | ||
}} | }} | ||
}} | }} | ||
| Line 28: | Line 35: | ||
=== Closing a file handle === | === Closing a file handle === | ||
| − | When you open a file you must remember to | + | When you open a file you must remember to close the handle when you've finished with it! The write modes supported by ComputerCraft may not actually output data until this is done. A file opened in any mode exposes the following close function: |
{{Function | {{Function | ||
|name=<var>h</var>.close | |name=<var>h</var>.close | ||
| Line 42: | Line 49: | ||
|name=<var>h</var>.readLine | |name=<var>h</var>.readLine | ||
|api=fs | |api=fs | ||
| − | |returns= | + | |returns={{type|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 |
|desc=Reads the next line from the file | |desc=Reads the next line from the file | ||
}} | }} | ||
| Line 48: | Line 55: | ||
|name=<var>h</var>.readAll | |name=<var>h</var>.readAll | ||
|api=fs | |api=fs | ||
| − | |returns= | + | |returns={{type|string}} the entire rest of the file, with the end-of-line character on the very last line (if present) stripped |
|desc=Reads the all the text in the file | |desc=Reads the all the text in the file | ||
}} | }} | ||
| Line 58: | Line 65: | ||
{{Function | {{Function | ||
|name=<var>h</var>.write | |name=<var>h</var>.write | ||
| − | |args= | + | |args={{type|string}} data |
|api=fs | |api=fs | ||
|desc=Writes a string of characters to the file exactly as they appear in the string <var>data</var> | |desc=Writes a string of characters to the file exactly as they appear in the string <var>data</var> | ||
| Line 64: | Line 71: | ||
{{Function | {{Function | ||
|name=<var>h</var>.writeLine | |name=<var>h</var>.writeLine | ||
| − | |args= | + | |args={{type|string}} data |
|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 | ||
| + | }} | ||
| + | if you just want to save a file, without closing the handle, then you could do a flush. ( this is normally used for logging etc...) | ||
| + | {{Function | ||
| + | |name=<var>h</var>.flush | ||
| + | |api=fs | ||
| + | |desc=Flushes the data to the specified file. (keeps the handle available afterwards) | ||
}} | }} | ||
| Line 76: | Line 89: | ||
|name=<var>h</var>.read | |name=<var>h</var>.read | ||
|api=fs | |api=fs | ||
| − | |returns={{type|number}} the byte read from the file, or | + | |returns={{type|number}} the byte read from the file, or {{type|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 86: | Line 99: | ||
{{Function | {{Function | ||
|name=<var>h</var>.write | |name=<var>h</var>.write | ||
| − | |args= | + | |args={{type|number}} byte |
|api=fs | |api=fs | ||
|desc=Writes a single byte into the file | |desc=Writes a single byte into the file | ||
Latest revision as of 21:08, 9 June 2016
 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:
Any of the three may be optionally followed by "b" to open the file for binary access instead of the default text access (eg, "wb" opens a file for binary output). Text mode file handles assume UTF-8 encoding for both input and output purposes, and supports all characters within the ISO 8859-1 codepage (plus a few extras). Prior to ComputerCraft 1.76, instead only printable ASCII characters are supported. In either case, any characters not supported are translated to 0x3F (representing a question mark). When you have opened a file you must always close the file handle, or else data may not be saved. Append mode and write mode both create a new file if none already exists (and write mode creates a new one even if one does); however, under a few builds of ComputerCraft in the 1.5x range, append mode will fail if an existing file cannot be found. | |
| 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 |
Contents
Examples
 Example | |
| Creates the file "abcd" for writing, and holds a file handle to it | |
| Code |
local h = fs.open("abcd", "w")
|
| Example | |
| Opens "abcd" in either append or write mode, depending on whether it already exists or not. | |
| Code |
local h = fs.open("abcd", fs.exists("abcd") and "a" or "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 close the handle when you've finished with it! The write modes supported by ComputerCraft may not actually output data until this is done. 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 |
if you just want to save a file, without closing the handle, then you could do a flush. ( this is normally used for logging etc...)
| Function h.flush | |
| Flushes the data to the specified file. (keeps the handle available afterwards) | |
| Syntax | h.flush() |
| 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 | number 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(number byte) |
| Returns | nil |
| Part of | ComputerCraft |
| API | fs |
