PropertyList XML files: Difference between revisions

Jump to navigation Jump to search

PropertyList XML files (view source)

Revision as of 02:58, 20 May 2013

24 bytes added ,  20 May 2013
m
no edit summary
(http://www.mail-archive.com/flightgear-devel@flightgear.org/msg09626.html)
mNo edit summary
Line 6: Line 6:


Most configuration files in FlightGear are XML-encoded property lists. PropertyList-encoded XML files use a subset of XML to map the property tree to XML space and vice versa. PropertyList-XML files are the main mechanism to populate the FlightGear property tree (or a sub branch of it) from XML files, but also to serialize (save) property tree/branch state to an XML file. XML attributes are mainly used as meta-directives for the property tree.
Most configuration files in FlightGear are XML-encoded property lists. PropertyList-encoded XML files use a subset of XML to map the property tree to XML space and vice versa. PropertyList-XML files are the main mechanism to populate the FlightGear property tree (or a sub branch of it) from XML files, but also to serialize (save) property tree/branch state to an XML file. XML attributes are mainly used as meta-directives for the property tree.
Right now, we use attributes for meta-information (data type, read/write flags, aliasing, and tracing).  As long as we use attributes for meta-information and elements for data, we'll have a clean upgrade path; otherwise, we'll end up with lots of reserved names (you cannot have a property named "alias", for example, because it might conflict with the attribute), and versioning problems (there's a new attribute named "foo", so any existing "foo" properties have to be renamed).
The current practice is a little verbose compared with a custom-designed, single-purpose XML format, but it generalizes nicely.  Another alternative would be to use XML Namespaces, but (while I support them) those have their detractors even in the hard-core XML community, and I'm worried that they'll confuse people a bit in FlightGear.
A custom-designed XML format for panels, sound, animations, FDMs, etc. could be *much* less verbose, but then we'd be managing n different XML-based formats and parsing libraries.


One advantage of the XML representation is its conceptual simplicity. Every element except for the root PropertyList container represents exactly one property, and every attribute represents metadata for the property associated with its element.  
One advantage of the XML representation is its conceptual simplicity. Every element except for the root PropertyList container represents exactly one property, and every attribute represents metadata for the property associated with its element.  


Not everything that is read from an XML file resides in the main property tree; some subsystems also use XML files for initial configuration information. There are different kinds of data. The property tree is meant to represent the shared state of the program; when a subsystem happens to use an XML file to set up its internal state -- information that is of no use to the rest of the program and that cannot be changed without a reinit. Temporary trees are usually deleted as soon as the subsystem is set up (i.e. they exist for perhaps 0.1 sec).  We could just as easily use another format for internal initialization, but since the XML support is already available, it was the easiest route.
Not everything that is read from an XML file resides in the main property tree; some subsystems also use XML files for initial configuration information and are read into a temporary tree and subsequently discarded. The main property tree is meant to represent the shared state of the program, but when a subsystem happens to use an XML file to set up its internal state that information is often of no use to the rest of the program and thus does not need to continually be in the main tree. Temporary trees are usually deleted as soon as the subsystem is set up (i.e. they exist for perhaps 0.1 sec).  We could just as easily use another format for internal initialization, but since the XML support is already available, it was the easiest route.
 
FlightGear is getting more sophisticated -- there's more to learn if you want to customize things, but that's only because there's so much more that
you can customize.


The config files serve many different purposes; using the XML-based property-list format for all of them helps a lot, since it allows some common structure and reusable code among all the formats.  Imagine if we had one file format for preferences, a different one for panels (say, with fixed-length fields), a different one for saving a flight (perhaps a binary format), another one for sound configuration (perhaps an INI file), a different one for top-level aircraft configuration (perhaps CSV), yet another one for configuring 3D models (perhaps embedded data strings in the 3D files themselves), etc. etc.
The config files serve many different purposes; using the XML-based property-list format for all of them helps a lot, since it allows some common structure and reusable code among all the formats.  Imagine if we had one file format for preferences, a different one for panels (say, with fixed-length fields), a different one for saving a flight (perhaps a binary format), another one for sound configuration (perhaps an INI file), a different one for top-level aircraft configuration (perhaps CSV), yet another one for configuring 3D models (perhaps embedded data strings in the 3D files themselves), etc. etc.
Line 38: Line 29:
* Aircraft/*/Instruments/*.xml - configuration files for individual instruments included by the 2D panels.
* Aircraft/*/Instruments/*.xml - configuration files for individual instruments included by the 2D panels.
* Aircraft/Instruments/*.xml - ditto
* Aircraft/Instruments/*.xml - ditto
* Aircraft/*/Models/*.xml - animation files for a .ac file, oodles of <animation> nodes!


We also use some XML-based formats that do not (yet?) follow the property-list conventions, including the following:
We also use some XML-based formats that do not (yet?) follow the property-list conventions, including the following:
Line 49: Line 41:
The one advantage of Yasim's approach is efficiency -- Andy copies from the XML straight into the YASim data structures, without building up and tearing down an in-memory property tree first.  For large-scale XML implementations, we *have* to do things that way -- the DOM and XSLT tend to break down catastrophically for large XML documents or high volume.  That's why we designed the Simple API for XML (SAX).
The one advantage of Yasim's approach is efficiency -- Andy copies from the XML straight into the YASim data structures, without building up and tearing down an in-memory property tree first.  For large-scale XML implementations, we *have* to do things that way -- the DOM and XSLT tend to break down catastrophically for large XML documents or high volume.  That's why we designed the Simple API for XML (SAX).


Efficiency doesn't matter much for YASim, since we're a short file, and we're reading it only once.  If we're ever processing a lot of XML in the main loop, say, over a network connection or from large GIS databases, we'll need to go with a streaming approach like Andy used.
Efficiency doesn't matter much for YASim, since it's a short file and we're reading it only once.  If we're ever processing a lot of XML in the main loop, say, over a network connection or from large GIS databases, we'll need to go with a streaming approach like Andy used.


To work with PropertyList-XML files, you can use various means, such as:
To work with PropertyList-XML files, you can use various means, such as:
Line 56: Line 48:
* C++ APIs (see links at the end of the navigation sidebar)
* C++ APIs (see links at the end of the navigation sidebar)


There are several places to look for properties; one is in the aircraft files, another is all Nasal files, and the last place (and often most useful!) is grepping (searching) through the C++ code. To determine how a property works and what it does often requires looking through any code that uses it. This is a part of FlightGear that we could certainly document better .
There are several places to look for properties; one is in the aircraft files, another is all Nasal files, and the last place (and often most useful!) is grepping (searching) through the C++ code. To determine how a property works and what it does often requires looking through any code that uses it. This is a part of FlightGear that we could certainly document better.


As for the relationship between XML and the Property Tree, in some cases in FG (most notably preferences.xml and each AIRCRAFT-set.xml file), the <PropertyList> format directly defines properties in FlightGear's global property tree. In other cases, like the animation files given by /sim/model/path, those do not define properties but the <PropertyList> format is used as a matter of convenience so that FG can parse all of its XML files using the same mechanism and to keep the fundamental structure the same. XML has a lot of different dialects, and having only one for FlightGear really makes it easier, especially since it is very intuitive
As for the relationship between XML and the Property Tree, in some cases in FG (most notably preferences.xml and each AIRCRAFT-set.xml file), the <PropertyList> format directly defines properties in FlightGear's global property tree. In other cases, like the animation files given by /sim/model/path, those do not define properties but the <PropertyList> format is used as a matter of convenience so that FG can parse all of its XML files using the same mechanism and to keep the fundamental structure the same. XML has a lot of different dialects, and having only one for FlightGear really makes it easier, especially since it is very intuitive
Line 96: Line 88:




You can also use explicit indexing by setting the '''n'' attribute of each tag:
You can also use explicit indexing by setting the '''n''' attribute of each tag:


<syntaxhighlight lang="xml">
<syntaxhighlight lang="xml">
Line 141: Line 133:


For further information please refer to [[$FG_ROOT]]/Docs/README.introduction and [[$FG_ROOT]]/Docs/README.properties.
For further information please refer to [[$FG_ROOT]]/Docs/README.introduction and [[$FG_ROOT]]/Docs/README.properties.
== Pros for the current implementation ==
Right now, we use attributes for meta-information (data type, read/write flags, aliasing, and tracing). As long as we use attributes for meta-information and elements for data, we'll have a clean upgrade path; otherwise, we could end up with lots of reserved names (like you could not have a property named "alias", for example, because it would conflict with the attribute), and versioning problems (there's a new attribute named "foo", so any existing "foo" properties have to be renamed).
The current practice is a little verbose compared with a custom-designed, single-purpose XML format, but it generalizes nicely. Another alternative would be to use XML Namespaces, but (while I support them) those have their detractors even in the hard-core XML community, and I'm worried that they'll confuse people a bit in FlightGear.
A custom-designed XML format for panels, sound, animations, FDMs, etc. could be *much* less verbose, but then we'd be managing n different XML-based formats and parsing libraries.


== Also see ==
== Also see ==
Philosopher
395

edits

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

Navigation menu