MediaWiki has been updated to version 1.35.1. Please report any problems here.

Difference between revisions of "Nasal library/io"

From FlightGear wiki
Jump to navigation Jump to search
(→‎Functions: Doc dirname())
(→‎Functions: Doc flush(), fix doc)
Line 22: Line 22:
 
|syntax = io.close(file);
 
|syntax = io.close(file);
 
|text = Closes the specified file. Returns <code>'''nil'''</code>.
 
|text = Closes the specified file. Returns <code>'''nil'''</code>.
|param1 = path
+
|param1 = file
|param1text = Path as a string.
+
|param1text = File object as returned by {{func link|open()}}.
 
|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 45: Line 45:
  
 
=== flush() ===
 
=== flush() ===
 +
{{Nasal doc
 +
|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.
 +
|param1 = file
 +
|param1text = File object as returned by {{func link|open()}}.
 +
|example1 = var path = getprop("/sim/fg-home") ~ '/Export/demo.txt';
 +
var file = io.open(path, "w+"); # create and open file
 +
io.write(file, "Hello, World!"); # write (to the buffer)
 +
 +
var file2 = io.open(path); # open the file separatly
 +
var b = bits.buf(13); # create a buffer
 +
io.read(file2, b, 13); # read file
 +
print(b); # prints nothing
 +
 +
io.flush(file); # flush buffer to file
 +
io.read(file2, b, 13); # read file again
 +
print(b); # prints "Hello, World!"
 +
 +
io.close(file); # close
 +
io.close(file2);
 +
}}
 +
 
=== include() ===
 
=== include() ===
 
=== load_nasal() ===
 
=== load_nasal() ===

Revision as of 12:42, 19 October 2016

WIP.png Work in progress
This article or section will be worked on in the upcoming hours or days.
See history for the latest developments.

This page contains documentation for the io namespace in Nasal. This namespace provides APIs for input/output (IO) operations on files. The io namespace is sourced from fgdata/Nasal/io.nas and simgear/simgear/nasal/iolib.c.

Functions

basename()

io.basename(path);

Version added: FG 3.0 (commit)

Returns last element of a path as a string.

path
Path as a string.

Examples

var path = '/demo/demo.xml';
print(io.basename(path)); # prints "demo.xml"
var path = 'C:\FlightGear\FlightGear 3.2.0\data';
print(io.basename(path)); # prints "data"

close()

io.close(file);

Closes the specified file. Returns nil.

file
File object as returned by open() .

Example

var path = getprop("/sim/fg-root") ~ '/keyboard.xml';
var file = io.open(path);
print(io.readln(file)); # prints the XML header
io.close(file);

dirname()

io.dirname(path);

Version added: FG 3.0 (commit)

Returns the directory of a path as a string.

path
Path as a string.

Examples

var path = '/demo/demo.xml';
print(io.dirname(path)); # prints "/demo/"
var path = 'C:\FlightGear\FlightGear 3.2.0\data';
print(io.dirname(path)); # prints "C:/FlightGear/FlightGear 3.2.0/"

flush()

io.flush(file);

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 close() is called.

file
File object as returned by open() .

Example

var path = getprop("/sim/fg-home") ~ '/Export/demo.txt';
var file = io.open(path, "w+"); # create and open file
io.write(file, "Hello, World!"); # write (to the buffer)

var file2 = io.open(path); # open the file separatly
var b = bits.buf(13); # create a buffer
io.read(file2, b, 13); # read file
print(b); # prints nothing

io.flush(file); # flush buffer to file
io.read(file2, b, 13); # read file again
print(b); # prints "Hello, World!"

io.close(file); # close
io.close(file2);

include()

load_nasal()

open(filename, mode="r")

Opens the file with the specified mode (as per ANSI fopen()) and returns a ghost object representing the filehandle. Failures are thrown as runtime errors as per die().

read(filehandle, buf, len)

Attempts to read length bytes from the filehandle into the beginning of the mutable string buf. Failures (including overruns when length > size(buf)) are thrown as runtime errors as per die(). Returns the number of bytes successfully read.

read_airport_properties()

Load XML file in FlightGear's native <PropertyList> format. File will be located in the airport-scenery directories according to ICAO and filename, i,e in Airports/I/C/A/ICAO.filename.xml

If the second, optional target parameter is set, then the properties are loaded to this node in the global property tree. Otherwise they are returned as a separate props.Node tree. Returns the data as a props.Node on success or nil on error.

Usage:   io.read_properties(<filename> [, <props.Node or property-path>]);

Example:

var data = io.read_airport_properties("KSFO", "rwyuse");

read_properties()

Load XML file in FlightGear's native <PropertyList> format. If the second, optional target parameter is set, then the properties are loaded to this node in the global property tree. Otherwise they are returned as a separate props.Node tree. Returns the data as a props.Node on success or nil on error.

Usage:   io.read_properties(<filename> [, <props.Node or property-path>]);

Examples:

var target = props.globals.getNode("/sim/model");           
io.read_properties("/tmp/foo.xml", target);                 
                                                            
var data = io.read_properties("/tmp/foo.xml", "/sim/model");
var data = io.read_properties("/tmp/foo.xml");

readfile()

Reads and returns a complete file as a string. Failures are thrown as runtime errors as per die().

io.readfile(file);

readln(filehandle)

Reads and returns a single text line from the filehandle. Interprets both "\n" and "\r\n" as end of line markers, and does not include the "\r" or "\n" bytes in the returned string. End of file or error is signaled by returning nil.

readxml()

Reads an XML file from an absolute path and returns it as property tree. All nodes will be of type STRING. Data are only written to leafs. Attributes are written as regular nodes with the optional prefix prepended to the name. If the prefix is nil, then attributes are ignored. Returns nil on error.

Usage:  io.readxml(path[, prefix = "___"]);
io.readxml(path,prefix);

seek(filehandle, position, whence)

As ANSI fseek(). Attempts to seek to the specified position based on the whence value (which must be one of io.SEEK_SET, io.SEEK_END, or io.SEEK_CUR).

stat(filename)

Calls unix or win32 stat() on the specified file name and returns a seven element array whose contents are, in order: dev, ino, mode, nlink, uid, gid, rdef, size, atime, mtime, ctime. Errors are signaled as exceptions as per die().

tell(filehandle)

Returns the current seek position of the filehandle.

write(filehandle, str)

Attempts to write the entirety of the specified string to the filehandle. Failures are thrown as runtime errors as per die(). Returns the number of bytes successfully written.

write_properties()

Write XML file in FlightGear's native <PropertyList> format. Returns the filename on success or nil on error. If the source is a props.Node that refers to a node in the main tree, then the data are directly written from the tree, yielding a more accurate result. Otherwise the data need to be copied first, which may slightly change node types (FLOAT becomes DOUBLE etc.)

Usage:   io.write_properties(<filename>, <props.Node or property-path>);

Examples:

var data = props.Node.new({ a:1, b:2, c:{ d:3, e:4 } }); 
io.write_properties("/tmp/foo.xml", data);               
io.write_properties("/tmp/foo.xml", "/sim/model");

writexml()

Writes a property tree as returned by readxml() to a file. Children with name starting with <prefix> are again turned into attributes of their parent. <node> must contain exactly one child, which will become the XML file's outermost element.

Usage:  io.writexml(path, node[,indent = "\t"][, prefix = "___"]);
io.writexml(path, node, indent,prefix);

Variables

SEEK_SET

SEEK_CUR

SEEK_END