13,212
edits
PropertyList XML files: Difference between revisions
Jump to navigation
Jump to search
Copy edit; +link to slightly related devel list thread
No edit summary |
(Copy edit; +link to slightly related devel list thread) |
||
| Line 1: | Line 1: | ||
{{PropertyTree}} | {{PropertyTree}} | ||
Most configuration files in FlightGear are '''PropertyList XML files''' using a subset of XML to encode lists and trees of [[Property Tree Intro|properties]] as XML. 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. | |||
For additional background information, you'll also want to refer to [[$FG_ROOT]]/Docs/README.introduction. | For additional background information, you'll also want to refer to [[$FG_ROOT]]/Docs/README.introduction. | ||
== Advantages == | |||
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. | ||
| Line 15: | Line 14: | ||
* Text editor: manually edit XML files | * Text editor: manually edit XML files | ||
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. | |||
== Read and write access == | |||
{{IO Restrictions}} | {{IO Restrictions}} | ||
== The PropertyList format == | == The PropertyList format == | ||
The root element of each file is always named <PropertyList>. Tags are almost always found in pairs, with the closing tag having a slash prefixing the tag name, i.e </PropertyList>, just like in any other XML dialect. The exception is the tag representing an aliased property. In this case a slash is prepended to the closing angle bracket: | The root element of each file is always named <PropertyList>. Tags are almost always found in pairs, with the closing tag having a slash prefixing the tag name, i.e </PropertyList>, just like in any other XML dialect. The exception is the tag representing an aliased property. In this case a slash is prepended to the closing angle bracket: | ||
<syntaxhighlight lang="xml"> | <syntaxhighlight lang="xml"> | ||
| Line 104: | Line 109: | ||
== CDATA == | == CDATA == | ||
Whenever you need to embed text that isn't valid XML, because it may contain XML tokens, you need to wrap the whole section in a CDATA section, this is typically done with [[Nasal]] code, so that it doesn't need to escape XML entities: | Whenever you need to embed text that isn't valid XML, because it may contain XML tokens, you need to wrap the whole section in a CDATA section, this is typically done with [[Nasal]] code, so that it doesn't need to escape XML entities: | ||
| Line 124: | Line 128: | ||
== PropertyList-based configuration files == | == PropertyList-based configuration files == | ||
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 ofteb 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. | 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 ofteb 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. | ||
| Line 163: | Line 166: | ||
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 | ||
== | == Related content == | ||
* http://forum.flightgear.org/viewtopic.php?f=18&t=19503 | * http://forum.flightgear.org/viewtopic.php?f=18&t=19503 | ||
* {{cite web |url=http://sourceforge.net/p/flightgear/mailman/flightgear-devel/thread/4E79A5CC.80906@t3r.de/ |title=<nowiki>[</nowiki>Flightgear-devel<nowiki>]</nowiki> Property Tree Question: How to save an aircraft specific property between sessions.}} | |||
[[Category:XML]] | [[Category:XML]] | ||
[[Category:Property Tree]] | [[Category:Property Tree]] | ||