Nasal library/io: Difference between revisions

Jump to navigation Jump to search

Nasal library/io (view source)

Revision as of 09:11, 18 October 2016

637 bytes removed ,  18 October 2016
Put in alphabetical order
(Start editing)
(Put in alphabetical order)
Line 4: Line 4:


== Functions ==
== Functions ==
=== open(filename, mode="r") ===
=== basename() ===
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().
Works like standard Unix command basename. Returns the file name from a given path.
<syntaxhighlight lang="nasal">
io.basename(<path>);
</syntaxhighlight>


=== close(filehandle) ===
=== close(filehandle) ===
Closes the specified file as per ANSI fclose().  
Closes the specified file as per ANSI fclose().  


=== read(filehandle, buf, len) ===
=== dirname() ===
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.
Works like standard Unix command dirname. Returns the directory part from a given path.
<syntaxhighlight lang="nasal">
io.basename(<path>);
</syntaxhighlight>


=== write(filehandle, str) ===
=== flush() ===
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.
=== include() ===
=== load_nasal() ===


=== seek(filehandle, position, whence)
=== open(filename, mode="r") ===
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).
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().  
=== tell(filehandle) ===
Returns the current seek position of the filehandle.  


=== readln(filehandle) ===
=== read(filehandle, buf, len) ===
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.  
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.


=== stat(filename) ===
=== read_airport_properties() ===
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().  
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         


=== basename() ===
If the second, optional target parameter is set, then the properties are loaded to this node in the global property tree.
Works like standard Unix command basename. Returns the file name from a given path.
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">
<syntaxhighlight lang="nasal">
io.basename(<path>);
Usage:  io.read_properties(<filename> [, <props.Node or property-path>]);
</syntaxhighlight>
</syntaxhighlight>


=== dirname() ===
Example:
Works like standard Unix command dirname. Returns the directory part from a given path.
<syntaxhighlight lang="nasal">
<syntaxhighlight lang="nasal">
io.basename(<path>);
var data = io.read_airport_properties("KSFO", "rwyuse");
</syntaxhighlight>
 
=== readfile() ===
Reads and returns a complete file as a string. Failures are thrown as runtime errors as per die().
<syntaxhighlight lang="nasal">
io.readfile(file);
</syntaxhighlight>
</syntaxhighlight>


Line 65: Line 65:
</syntaxhighlight>
</syntaxhighlight>


=== read_airport_properties() ===
=== readfile() ===
Load XML file in FlightGear's native <PropertyList> format.        
Reads and returns a complete file as a string. Failures are thrown as runtime errors as per die().
File will be located in the airport-scenery directories according to
<syntaxhighlight lang="nasal">
ICAO and filename, i,e in Airports/I/C/A/ICAO.filename.xml         
io.readfile(file);
</syntaxhighlight>
 
=== 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.


If the second, optional target parameter is set, then the properties are loaded to this node in the global property tree.
=== readxml() ===
Otherwise they are returned as a separate props.Node tree.  
Reads an XML file from an absolute path and returns it as property 
Returns the data as a props.Node on success or nil on error.
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">
<syntaxhighlight lang="nasal">
Usage:   io.read_properties(<filename> [, <props.Node or property-path>]);
Usage: io.readxml(path[, prefix = "___"]);
</syntaxhighlight>
</syntaxhighlight>
Example:
<syntaxhighlight lang="nasal">
<syntaxhighlight lang="nasal">
var data = io.read_airport_properties("KSFO", "rwyuse");
io.readxml(path,prefix);
</syntaxhighlight>
</syntaxhighlight>
=== 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_properties() ===
Line 95: Line 112:
io.write_properties("/tmp/foo.xml", data);               
io.write_properties("/tmp/foo.xml", data);               
io.write_properties("/tmp/foo.xml", "/sim/model");       
io.write_properties("/tmp/foo.xml", "/sim/model");       
</syntaxhighlight>
{{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.
<syntaxhighlight lang="nasal">
Usage:  io.readxml(path[,prefix = "___"]);
</syntaxhighlight>
<syntaxhighlight lang="nasal">
io.readxml(path,prefix);
</syntaxhighlight>
</syntaxhighlight>


Retrieved from "https://wiki.flightgear.org/Special:MobileDiff/105006"

Navigation menu