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
m (Red Leader moved page NAsal to Nasal library/io: Oops, hit enter too early)
(Start editing)
Line 1: Line 1:
 
{{WIP}}
 
{{WIP}}
 
{{Nasal Navigation}}
 
{{Nasal Navigation}}
== Nasal Core functions ==
+
This page contains documentation for the '''<code>io</code> namespace''' in [[Nasal]]. This namespace provides APIs for input/output (IO) operations on files. The <code>io</code> namespace is sourced from {{fgdata file|Nasal/io.nas}} and {{simgear file|simgear/nasal/iolib.c}}.
=== io.open(filename, mode="r") ===
+
 
 +
== Functions ==
 +
=== 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().  
 
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().  
=== io.close(filehandle) ===
+
 
 +
=== close(filehandle) ===
 
Closes the specified file as per ANSI fclose().  
 
Closes the specified file as per ANSI fclose().  
=== io.read(filehandle, buf, len) ===
+
 
 +
=== 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.  
 
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.  
=== io.write(filehandle, str) ===
+
 
 +
=== 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.  
 
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.  
=== io.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).  
+
=== seek(filehandle, position, whence)
=== io.tell(filehandle) ===
+
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).
 +
 +
=== tell(filehandle) ===
 
Returns the current seek position of the filehandle.  
 
Returns the current seek position of the filehandle.  
=== io.readln(filehandle) ===
+
 
 +
=== 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.  
 
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.  
=== io.stat(filename) ===
+
 
 +
=== 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().  
 
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().  
  
== Reading files ==
+
=== basename() ===
The following description of functions refers to "$FG_ROOT\data\Nasal\io.nas".
 
=== io.basename() ===
 
 
Works like standard Unix command basename. Returns the file name from a given path.
 
Works like standard Unix command basename. Returns the file name from a given path.
 
<syntaxhighlight lang="nasal">
 
<syntaxhighlight lang="nasal">
 
io.basename(<path>);
 
io.basename(<path>);
 
</syntaxhighlight>
 
</syntaxhighlight>
=== io.dirname() ===
+
 
 +
=== dirname() ===
 
Works like standard Unix command dirname. Returns the directory part from a given path.
 
Works like standard Unix command dirname. Returns the directory part from a given path.
 
<syntaxhighlight lang="nasal">
 
<syntaxhighlight lang="nasal">
 
io.basename(<path>);
 
io.basename(<path>);
 
</syntaxhighlight>
 
</syntaxhighlight>
=== io.readfile() ===
+
 
 +
=== readfile() ===
 
Reads and returns a complete file as a string. Failures are thrown as runtime errors as per die().
 
Reads and returns a complete file as a string. Failures are thrown as runtime errors as per die().
 
<syntaxhighlight lang="nasal">
 
<syntaxhighlight lang="nasal">
Line 37: Line 46:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
== Read FG PropertyList XML ==
+
=== read_properties() ===
The following description of functions refers to "$FG_ROOT\data\Nasal\io.nas".
 
=== io.read_properties() ===
 
 
Load XML file in FlightGear's native <PropertyList> format.           
 
Load XML file in FlightGear's native <PropertyList> format.           
 
If the second, optional target parameter is set, then the properties  
 
If the second, optional target parameter is set, then the properties  
Line 58: Line 65:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
=== io.read_airport_properties() ===
+
=== read_airport_properties() ===
 
Load XML file in FlightGear's native <PropertyList> format.           
 
Load XML file in FlightGear's native <PropertyList> format.           
 
File will be located in the airport-scenery directories according to  
 
File will be located in the airport-scenery directories according to  
Line 75: Line 82:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
== Write FG PropertyList XML ==
+
=== write_properties() ===
The following description of functions refers to "$FG_ROOT\data\Nasal\io.nas".
 
=== io.write_properties() ===
 
 
Write XML file in FlightGear's native <PropertyList> format.     
 
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,  
 
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,  
Line 92: Line 97:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
== Read/Write Plain XML ==
+
{{Note|The following two functions are for reading generic XML files into     
This description of functions refers to "$FG_ROOT\data\Nasal\io.nas".
 
 
 
The following two functions are for reading generic XML files into     
 
 
the property tree and for writing them from there to the disk. The     
 
the property tree and for writing them from there to the disk. The     
 
built-in fgcommands (load, save, loadxml, savexml) are for FlightGear's
 
built-in fgcommands (load, save, loadxml, savexml) are for FlightGear's
Line 104: Line 106:
 
attributes. The two functions have their own limitations, but can       
 
attributes. The two functions have their own limitations, but can       
 
easily get extended to whichever needs. The underlying parsexml()       
 
easily get extended to whichever needs. The underlying parsexml()       
command will handle any XML file.
+
command will handle any XML file.}}
  
=== io.readxml() ===
+
=== readxml() ===
 
Reads an XML file from an absolute path and returns it as property   
 
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     
 
tree. All nodes will be of type STRING. Data are only written to     
Line 119: Line 121:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
=== io.writexml() ===
+
=== writexml() ===
 
Writes a property tree as returned by readxml() to a file. Children   
 
Writes a property tree as returned by readxml() to a file. Children   
 
with name starting with <prefix> are again turned into attributes of   
 
with name starting with <prefix> are again turned into attributes of   
Line 131: Line 133:
 
</syntaxhighlight>
 
</syntaxhighlight>
  
== Serializing Nasal types ==
+
[[Category:Nasal]]

Revision as of 16:28, 17 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

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().

close(filehandle)

Closes the specified file as per ANSI fclose().

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.

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.

=== 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).

tell(filehandle)

Returns the current seek position of the filehandle.

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.

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().

basename()

Works like standard Unix command basename. Returns the file name from a given path.

io.basename(<path>);

dirname()

Works like standard Unix command dirname. Returns the directory part from a given path.

io.basename(<path>);

readfile()

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

io.readfile(file);

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");

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");

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");
Note  The following two functions are for reading generic XML files into

the property tree and for writing them from there to the disk. The built-in fgcommands (load, save, loadxml, savexml) are for FlightGear's own <PropertyList> XML files only, as they only handle a limited number of very specific attributes. The io.readxml() loader turns attributes into regular children with a configurable prefix prepended to their name, while io.writexml() turns such nodes back into attributes. The two functions have their own limitations, but can easily get extended to whichever needs. The underlying parsexml() command will handle any XML file.

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);

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);