2,732
edits
Nasal library/io: Difference between revisions
Update {{func link}} form
Red Leader (talk | contribs) (nocat and navbox) |
Red Leader (talk | contribs) (Update {{func link}} form) |
||
| Line 22: | Line 22: | ||
|text = Flushes and closes the specified file. Returns <code>'''nil'''</code>. | |text = Flushes and closes the specified file. Returns <code>'''nil'''</code>. | ||
|param1 = file | |param1 = file | ||
|param1text = File object as returned by {{func link|open()}}. | |param1text = File object as returned by {{func link|open()|page=this}}. | ||
|example1 = var path = getprop("/sim/fg-root") ~ '/keyboard.xml'; | |example1 = var path = getprop("/sim/fg-root") ~ '/keyboard.xml'; | ||
var file = io.open(path); | var file = io.open(path); | ||
| Line 46: | Line 46: | ||
{{Nasal doc | {{Nasal doc | ||
|syntax = io.flush(file); | |syntax = io.flush(file); | ||
|text = Flushes the file's buffer. This means that the contents of the buffer (a kind of temporary storage) are written to the actual file on the hard disk. Note that the buffer is also flushed when {{func link|close()}} is called. | |text = Flushes the file's buffer. This means that the contents of the buffer (a kind of temporary storage) are written to the actual file on the hard disk. Note that the buffer is also flushed when {{func link|close()|page=this}} is called. | ||
|param1 = file | |param1 = file | ||
|param1text = File object as returned by {{func link|open()}}. | |param1text = File object as returned by {{func link|open()|page=this}}. | ||
|example1 = var path = getprop("/sim/fg-home") ~ '/Export/demo.txt'; | |example1 = var path = getprop("/sim/fg-home") ~ '/Export/demo.txt'; | ||
var file = io.open(path, "w"); # create and open file | var file = io.open(path, "w"); # create and open file | ||
| Line 125: | Line 125: | ||
{{!-}} | {{!-}} | ||
{{!}} <code>a+</code> | {{!}} <code>a+</code> | ||
{{!}} Opens a file for input and output operations. Output operations will append data to the end of the file. Input operations are affected by {{func link|seek()}}, but output operations will move the position back to the end of the file. The file is created if it does not exist. | {{!}} Opens a file for input and output operations. Output operations will append data to the end of the file. Input operations are affected by {{func link|seek()|page=this}}, but output operations will move the position back to the end of the file. The file is created if it does not exist. | ||
{{!-}} | {{!-}} | ||
{{!}} <code>rb</code> | {{!}} <code>rb</code> | ||
| Line 143: | Line 143: | ||
{{!-}} | {{!-}} | ||
{{!}} <code>a+b</code> ''or'' <code>ab+</code> | {{!}} <code>a+b</code> ''or'' <code>ab+</code> | ||
{{!}} Opens a file for input and output operations, treating it as a binary file. Output operations will append data to the end of the file. Input operations are affected by {{func link|seek()}}, but output operations will move the position back to the end of the file. The file is created if it does not exist. | {{!}} Opens a file for input and output operations, treating it as a binary file. Output operations will append data to the end of the file. Input operations are affected by {{func link|seek()|page=this}}, but output operations will move the position back to the end of the file. The file is created if it does not exist. | ||
{{!}}} | {{!}}} | ||
|param1 = path | |param1 = path | ||
| Line 169: | Line 169: | ||
{{Nasal doc | {{Nasal doc | ||
|syntax = io.read(file, buf, len); | |syntax = io.read(file, buf, len); | ||
|text = Reads a given number of bytes from the given file and places those bytes into the given buffer. The bytes will be read from the position of the position indicator (this can be changed using {{func link|seek()}}). Failures are thrown as runtime errors. Returns the number of bytes successfully read. | |text = Reads a given number of bytes from the given file and places those bytes into the given buffer. The bytes will be read from the position of the position indicator (this can be changed using {{func link|seek()|page=this}}). Failures are thrown as runtime errors. Returns the number of bytes successfully read. | ||
|param1 = file | |param1 = file | ||
|param1text = File object as returned by {{func link|open()}}. | |param1text = File object as returned by {{func link|open()|page=this}}. | ||
|param2 = buf | |param2 = buf | ||
|param2text = Buffer to read bytes into. A new buffer can be created using <code>bits.buf(size)</code>. Must not be smaller than '''len'''. | |param2text = Buffer to read bytes into. A new buffer can be created using <code>bits.buf(size)</code>. Must not be smaller than '''len'''. | ||
| Line 246: | Line 246: | ||
|text = Reads and returns a single line from the file, advancing the position indicator. Accepts different {{wikipedia|newline}} types, including {{abbr|LF|line feed}}, {{abbr|CR|carriage return}}, and CR+LF. Does not include the EOL character(s) in the returned string. End of file or an error is signaled by returning <code>'''nil'''</code>. | |text = Reads and returns a single line from the file, advancing the position indicator. Accepts different {{wikipedia|newline}} types, including {{abbr|LF|line feed}}, {{abbr|CR|carriage return}}, and CR+LF. Does not include the EOL character(s) in the returned string. End of file or an error is signaled by returning <code>'''nil'''</code>. | ||
|param1 = file | |param1 = file | ||
|param1text = File object as returned by {{func link|open}}. | |param1text = File object as returned by {{func link|open()|page=this}}. | ||
|example1 = var path = getprop("/sim/fg-root") ~ '/Nasal/bits.nas'; | |example1 = var path = getprop("/sim/fg-root") ~ '/Nasal/bits.nas'; | ||
var file = io.open(path); | var file = io.open(path); | ||
| Line 282: | Line 282: | ||
|text = Moves the pointer position to a specified place. | |text = Moves the pointer position to a specified place. | ||
|param1 = file | |param1 = file | ||
|param1text = File object as returned by {{func link|open()}}. | |param1text = File object as returned by {{func link|open()|page=this}}. | ||
|param2 = position | |param2 = position | ||
|param2text = Number of bytes offset from '''whence''' as an integer. If '''whence''' is {{func link|SEEK_SET}}, this cannot be negative. | |param2text = Number of bytes offset from '''whence''' as an integer. If '''whence''' is {{func link|SEEK_SET|page=this}}, this cannot be negative. | ||
|param3 = whence | |param3 = whence | ||
|param3text = Specifies position to set the offset from. Must be one of {{func link|SEEK_SET}} (beginning of file), {{func link|SEEK_END}} (end of file), or {{func link|SEEK_CUR}} (current pointer position). | |param3text = Specifies position to set the offset from. Must be one of {{func link|SEEK_SET|page=this}} (beginning of file), {{func link|SEEK_END|page=this}} (end of file), or {{func link|SEEK_CUR|page=this}} (current pointer position). | ||
|example1 = var path = getprop("/sim/fg-root") ~ '/Nasal/geo.nas'; | |example1 = var path = getprop("/sim/fg-root") ~ '/Nasal/geo.nas'; | ||
var file = io.open(path, "r"); # open file | var file = io.open(path, "r"); # open file | ||
| Line 340: | Line 340: | ||
|text = Returns the current pointer position of the file. | |text = Returns the current pointer position of the file. | ||
|param1 = file | |param1 = file | ||
|param1text = File object as returned by {{func link|open()}}. | |param1text = File object as returned by {{func link|open()|page=this}}. | ||
|example1 = var path = getprop("/sim/fg-root") ~ '/Nasal/geo.nas'; | |example1 = var path = getprop("/sim/fg-root") ~ '/Nasal/geo.nas'; | ||
var file = io.open(path); | var file = io.open(path); | ||
| Line 353: | Line 353: | ||
|text = Writes a string to a given file and returns the number of bytes successfully written. | |text = Writes a string to a given file and returns the number of bytes successfully written. | ||
|param1 = file | |param1 = file | ||
|param1text = File object as returned by {{func link|open()}}. | |param1text = File object as returned by {{func link|open()|page=this}}. | ||
|param2 = string | |param2 = string | ||
|param2text = String to write to the file. | |param2text = String to write to the file. | ||
{{tip|It is good practice to make sure that all lines, including the last one, end in a newline (<code>\n</code>). This will especially help if you will be calling {{func link|readln()}} on the file later.}} | {{tip|It is good practice to make sure that all lines, including the last one, end in a newline (<code>\n</code>). This will especially help if you will be calling {{func link|readln()|page=this}} on the file later.}} | ||
|example1 = var path = getprop("/sim/fg-home") ~ '/Export/demo.txt'; | |example1 = var path = getprop("/sim/fg-home") ~ '/Export/demo.txt'; | ||
var file = io.open(path, "wb"); # open in write mode | var file = io.open(path, "wb"); # open in write mode | ||
| Line 397: | Line 397: | ||
|param1text = Path of the file to write to as a string. If it does not have a <tt>.xml</tt> extension, <tt>.xml</tt> will be added to it. | |param1text = Path of the file to write to as a string. If it does not have a <tt>.xml</tt> extension, <tt>.xml</tt> will be added to it. | ||
|param2 = node | |param2 = node | ||
|param2text = <code>props.Node</code> object containing the data to write to the file. Attributes should be included as child nodes with a certain '''prefix'''. See also {{func link|readxml()}}. It must also have just one root node. | |param2text = <code>props.Node</code> object containing the data to write to the file. Attributes should be included as child nodes with a certain '''prefix'''. See also {{func link|readxml()|page=this}}. It must also have just one root node. | ||
|param3 = indent | |param3 = indent | ||
|param3text = Optional string specifying what characters should be used to indent lines. Defaults to one horizontal tab character (<tt>\t</tt>). | |param3text = Optional string specifying what characters should be used to indent lines. Defaults to one horizontal tab character (<tt>\t</tt>). | ||
| Line 436: | Line 436: | ||
{{Nasal doc | {{Nasal doc | ||
|syntax = io.SEEK_CUR; | |syntax = io.SEEK_CUR; | ||
|text = Used with {{func link|seek()}}. Means the offset will be counted from the current pointer postion. | |text = Used with {{func link|seek()|page=this}}. Means the offset will be counted from the current pointer postion. | ||
}} | }} | ||
=== SEEK_END === | === SEEK_END === | ||
{{Nasal doc | {{Nasal doc | ||
|syntax = io.SEEK_END; | |syntax = io.SEEK_END; | ||
|text = Used with {{func link|seek()}}. Means the offset will be counted from the end of the file. | |text = Used with {{func link|seek()|page=this}}. Means the offset will be counted from the end of the file. | ||
}} | }} | ||
=== SEEK_SET === | === SEEK_SET === | ||
{{Nasal doc | {{Nasal doc | ||
|syntax = io.SEEK_SET; | |syntax = io.SEEK_SET; | ||
|text = Used with {{func link|seek()}}. Means the offset will be counted from the beginning of the file. | |text = Used with {{func link|seek()|page=this}}. Means the offset will be counted from the beginning of the file. | ||
}} | }} | ||
{{Nasal namespaces}} | {{Nasal namespaces}} | ||