Nasal library/io: Difference between revisions

From FlightGear wiki
Jump to navigation Jump to search
Line 21: Line 21:
</syntaxhighlight>
</syntaxhighlight>


== XML ==
== Read FG PropertyList XML ==
=== io.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.
<syntaxhighlight lang="nasal">
Usage:  io.read_properties(<filename> [, <props.Node or property-path>]);
</syntaxhighlight>
 
Examples:
<syntaxhighlight lang="nasal">
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");             
</syntaxhighlight>
 
=== io.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.
<syntaxhighlight lang="nasal">
Usage:  io.read_properties(<filename> [, <props.Node or property-path>]);
</syntaxhighlight>
 
Example:
<syntaxhighlight lang="nasal">
var data = io.read_airport_properties("KSFO", "rwyuse");
</syntaxhighlight>
 
== Write FG PropertyList XML ==
=== io.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.)
<syntaxhighlight lang="nasal">
Usage:  io.write_properties(<filename>, <props.Node or property-path>);
</syntaxhighlight>
Examples:
<syntaxhighlight lang="nasal">
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");     
</syntaxhighlight>
 
== Read/Write Plain XML ==
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.
 
=== io.readxml(path[,prefix = "___"]) ===
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.
<syntaxhighlight lang="nasal">
io.readxml(path,prefix);
</syntaxhighlight>
 
=== io.writexml(path, node[,indent = "\t"][, prefix = "___"]) ===
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.                             
<syntaxhighlight lang="nasal">
io.writexml(path, node, indent,prefix);
</syntaxhighlight>
 
== Serializing Nasal types ==
== Serializing Nasal types ==

Revision as of 16:26, 21 May 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.


Creating files

Writing files

Reading files

io.basename()

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

io.basename(<path>);

io.dirname()

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

io.basename(<path>);

io.readfile()

Reads and returns a complete file as a string.

io.readfile(file);

Read FG PropertyList XML

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

io.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 FG PropertyList XML

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

Read/Write Plain XML

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.

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

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.

io.readxml(path,prefix);

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

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.

io.writexml(path, node, indent,prefix);

Serializing Nasal types