Fs.open - Revision history

Randomdude999: More use of Template:Type

2016-06-09T21:08:21Z

More use of Template:Type

Bomb Bloke: CC 1.76

2015-12-27T11:29:42Z

CC 1.76

Bomb Bloke: "Append" mode cannot be trusted to create files.

2014-02-28T13:24:16Z

"Append" mode cannot be trusted to create files.

Alekso56: changed sub cat

2013-10-16T16:18:59Z

changed sub cat

Alekso56: added h.flush

2013-10-16T16:14:46Z

added h.flush

Cranium: /* Files opened in binary write/append mode */ Correcting Link

2013-07-18T11:24:06Z

‎Files opened in binary write/append mode: Correcting Link

Cranium: /* Files opened in binary read mode */ Correcting link

2013-07-18T11:23:43Z

‎Files opened in binary read mode: Correcting link

Cranium: Changing int to number

2013-07-18T11:08:04Z

Changing int to number

Hawk777: Copy description from API page, change return, and use type template

2013-04-22T19:43:34Z

Copy description from API page, change return, and use type template

Hawk777: Tidy up the mode parameter

2013-04-21T19:19:04Z

Tidy up the mode parameter

@@ Line 4: / Line 4: @@
 |args={{Type|string}} path, {{Type|string}} mode
 |api=fs
-|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)
+|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=
 '''Supported File Modes'''
@@ Line 49: / Line 49: @@
 |name=<var>h</var>.readLine
 |api=fs
-|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
+|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
 }}
@@ Line 55: / Line 55: @@
 |name=<var>h</var>.readAll
 |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={{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
 }}
@@ Line 65: / Line 65: @@
 {{Function
 |name=<var>h</var>.write
-|args=[[string (type)|string]] data
+|args={{type|string}} data
 |api=fs
 |desc=Writes a string of characters to the file exactly as they appear in the string <var>data</var>
@@ Line 71: / Line 71: @@
 {{Function
 |name=<var>h</var>.writeLine
-|args=[[string (type)|string]] data
+|args={{type|string}} data
 |api=fs
 |desc=Writes a string of characters to the file, then appends an end-of-line character
@@ Line 89: / Line 89: @@
 |name=<var>h</var>.read
 |api=fs
-|returns={{type|number}} the byte read from the file, or [[Nil|nil]] if there are no more bytes
+|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
 }}

@@ Line 11: / Line 11: @@
 * "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
+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 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.
+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).
-<b>Note:</b> Depending on your version of ComputerCraft, "append" mode may or may not be capable of creating new files (and the function returns "nil" if the file doesn't already exist) - [http://www.computercraft.info/forums2/index.php?/topic/15330-append-mode-to-create-a-file/ most later releases won't]. Even if it works for <i>you</i>, if planning on distributing your code consider using [[Fs.exists|fs.exists()]] to determine when "write" mode is appropriate.
+When you have opened a file you must always [[#Closing a file handle|close the file handle]], or else data may not be saved.
 |examples=
 {{Example
@@ Line 34: / Line 35: @@
 === 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.
+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
 |name=<var>h</var>.close

@@ Line 15: / Line 15: @@
 When you have opened a file you must always close the file handle, or else data will not be saved.
 |examples=
 {{Example
 |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")
 }}
 }}

@@ Line 33: / Line 33: @@
 |api=fs
 |desc=Closes the file handle, after which it can no longer be used
 }}
@@ Line 75: / Line 67: @@
 |api=fs
 |desc=Writes a string of characters to the file, then appends an end-of-line character
 }}

@@ Line 33: / Line 33: @@
 |api=fs
 |desc=Closes the file handle, after which it can no longer be used
 }}

@@ Line 86: / Line 86: @@
 {{Function
 |name=<var>h</var>.write
-|args=[[type|number]] byte
+|args={{type|number}} byte
 |api=fs
 |desc=Writes a single byte into the file

@@ Line 2: / Line 2: @@
 {{Function
 |name=fs.open
-|args=[[string (type)|string]] path, [[string (type)|string]] mode
+|args={{Type|string}} path, {{Type|string}} mode
 |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=
 '''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,
 * "w" to open it for writing and remove any existing data on file open, or