1 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
7 ------------- Copyright (C) 2004 Jon S. Berndt (jsb@hal-pc.org) -------------
9 This program is free software; you can redistribute it and/or modify it under
10 the terms of the GNU General Public License as published by the Free Software
11 Foundation; either version 2 of the License, or (at your option) any later
14 This program is distributed in the hope that it will be useful, but WITHOUT
15 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
16 FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
19 You should have received a copy of the GNU General Public License along with
20 this program; if not, write to the Free Software Foundation, Inc., 59 Temple
21 Place - Suite 330, Boston, MA 02111-1307, USA.
23 Further information about the GNU General Public License can also be found on
24 the world wide web at http://www.gnu.org.
26 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
28 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
33 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
35 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
38 # include <simgear/compiler.h>
39 # ifdef SG_HAVE_STD_INCLUDES
47 # include <iostream.h>
67 #include <math/FGColumnVector3.h>
69 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
71 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
73 #define ID_XMLELEMENT "$Id$"
75 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
77 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
81 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
83 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
85 /** Encapsulates an XML element.
86 This class handles the creation, storage, and manipulation of XML elements.
87 This class also can convert supplied values as follows:
89 convert ["from"]["to"] = factor, so: from * factor = to
90 - convert["M"]["FT"] = 3.2808399;
91 - convert["FT"]["M"] = 1.0/convert["M"]["FT"];
92 - convert["M2"]["FT2"] = convert["M"]["FT"]*convert["M"]["FT"];
93 - convert["FT2"]["M2"] = 1.0/convert["M2"]["FT2"];
94 - convert["FT"]["IN"] = 12.0;
95 - convert["IN"]["FT"] = 1.0/convert["FT"]["IN"];
96 - convert["LBS"]["KG"] = 0.45359237;
97 - convert["KG"]["LBS"] = 1.0/convert["LBS"]["KG"];
98 - convert["SLUG*FT2"]["KG*M2"] = 1.35594;
99 - convert["KG*M2"]["SLUG*FT2"] = 1.0/convert["SLUG*FT2"]["KG*M2"];
100 - convert["RAD"]["DEG"] = 360.0/(2.0*3.1415926);
101 - convert["DEG"]["RAD"] = 1.0/convert["RAD"]["DEG"];
102 - convert["LBS/FT"]["N/M"] = 14.5939;
103 - convert["LBS/FT/SEC"]["N/M/SEC"] = 14.5939;
104 - convert["N/M"]["LBS/FT"] = 1.0/convert["LBS/FT"]["N/M"];
105 - convert["N/M/SEC"]["LBS/FT/SEC"] = 1.0/convert["LBS/FT/SEC"]["N/M/SEC"];
106 - convert["WATTS"]["HP"] = 0.001341022;
107 - convert["HP"]["WATTS"] = 1.0/convert["WATTS"]["HP"];
108 - convert["N"]["LBS"] = 0.22482;
109 - convert["LBS"]["N"] = 1.0/convert["N"]["LBS"];
110 - convert["KTS"]["FT/SEC"] = ktstofps;
112 - convert["M"]["M"] = 1.00;
113 - convert["FT"]["FT"] = 1.00;
114 - convert["IN"]["IN"] = 1.00;
115 - convert["DEG"]["DEG"] = 1.00;
116 - convert["RAD"]["RAD"] = 1.00;
117 - convert["M2"]["M2"] = 1.00;
118 - convert["FT2"]["FT2"] = 1.00;
119 - convert["KG*M2"]["KG*M2"] = 1.00;
120 - convert["SLUG*FT2"]["SLUG*FT2"] = 1.00;
121 - convert["KG"]["KG"] = 1.00;
122 - convert["LBS"]["LBS"] = 1.00;
123 - convert["LBS/FT"]["LBS/FT"] = 1.00;
124 - convert["N/M"]["N/M"] = 1.00;
125 - convert["LBS/FT/SEC"]["LBS/FT/SEC"] = 1.00;
126 - convert["N/M/SEC"]["N/M/SEC"] = 1.00;
127 - convert["PSI"]["PSI"] = 1.00;
128 - convert["INHG"]["INHG"] = 1.00;
129 - convert["HP"]["HP"] = 1.00;
130 - convert["N"]["N"] = 1.00;
131 - convert["WATTS"]["WATTS"] = 1.00;
132 - convert["KTS"]["KTS"] = 1.0;
133 - convert["FT/SEC"]["FT/SEC"] = 1.0;
138 - M2 = meters squared
149 @author Jon S. Berndt
153 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
155 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
160 @param nm the name of this element (if given)
166 /** Retrieves an attribute.
167 @param key specifies the attribute key to retrieve the value of.
168 @return the key value (as a string), or the empty string if no such
170 string GetAttributeValue(string key);
172 /** Retrieves an attribute value as a double precision real number.
173 @param key specifies the attribute key to retrieve the value of.
174 @return the key value (as a number), or the HUGE_VAL if no such
176 double GetAttributeValueAsNumber(string key);
178 /** Retrieves the element name.
179 @return the element name, or the empty string if no name has been set.*/
180 string GetName(void) {return name;}
182 /** Gets a line of data belonging to an element.
183 @param i the index of the data line to return (0 by default).
184 @return a string representing the data line requested, or the empty string
186 string GetDataLine(int i=0);
188 /// Returns the number of lines of data stored
189 int GetNumDataLines(void) {return data_lines.size();}
191 /// Returns the number of child elements for this element.
192 int GetNumElements(void) {return children.size();}
194 /// Returns the number of named child elements for this element.
195 int GetNumElements(string);
197 /** Converts the element data to a number.
198 This function attempts to convert the first (and presumably only) line of
199 data "owned" by the element into a real number. If there is not exactly one
200 line of data owned by the element, then HUGE_VAL is returned.
201 @return the numeric value of the data owned by the element.*/
202 double GetDataAsNumber(void);
204 /** Returns a pointer to the element requested by index.
205 This function also resets an internal counter to the index, so that
206 subsequent calls to GetNextElement() will return the following
207 elements sequentially, until the last element is reached. At that point,
208 GetNextElement() will return NULL.
209 @param el the index of the requested element (0 by default)
210 @return a pointer to the Element, or 0 if no valid element exists. */
211 Element* GetElement(int el=0);
213 /** Returns a pointer to the next element in the list.
214 The function GetElement() must be called first to be sure that this
215 function will return the correct element. The call to GetElement() resets
216 the internal counter to zero. Subsequent calls to GetNextElement() return
217 a pointer to subsequent elements in the list. When the final element is
218 reached, 0 is returned.
219 @return a pointer to the next Element in the sequence, or 0 if no valid
220 Element is present. */
221 Element* GetNextElement(void);
223 /** Returns a pointer to the parent of an element.
224 @return a pointer to the parent Element, or 0 if this is the top level Element. */
225 Element* GetParent(void) {return parent;}
227 /** Searches for a specified element.
228 Finds the first element that matches the supplied string, or simply the first
229 element if no search string is supplied. This function call resets the internal
230 element counter to the first element.
231 @param el the search string (empty string by default).
232 @return a pointer to the first element that matches the supplied search string. */
233 Element* FindElement(string el="");
235 /** Searches for the next element as specified.
236 This function would be called after FindElement() is first called (in order to
237 reset the internal counter). If no argument is supplied (or the empty string)
238 a pointer to the very next element is returned. Otherwise, the next occurence
239 of the named element is returned. If the end of the list is reached, 0 is
241 @param el the name of the next element to find.
242 @return the pointer to the found element, or 0 if no appropriate element us
244 Element* FindNextElement(string el="");
246 /** Searches for the named element and returns the string data belonging to it.
247 This function allows the data belonging to a named element to be returned
248 as a string. If no element is found, the empty string is returned. If no
249 argument is supplied, the data string for the first element is returned.
250 @param el the name of the element being searched for (the empty string by
252 @return the data value for the named element as a string, or the empty
253 string if the element cannot be found. */
254 string FindElementValue(string el="");
256 /** Searches for the named element and returns the data belonging to it as a number.
257 This function allows the data belonging to a named element to be returned
258 as a double. If no element is found, HUGE_VAL is returned. If no
259 argument is supplied, the data for the first element is returned.
260 @param el the name of the element being searched for (the empty string by
262 @return the data value for the named element as a double, or HUGE_VAL if the
264 double FindElementValueAsNumber(string el="");
266 /** Searches for the named element and converts and returns the data belonging to it.
267 This function allows the data belonging to a named element to be returned
268 as a double. If no element is found, HUGE_VAL is returned. If no
269 argument is supplied, the data for the first element is returned. Additionally,
270 this function converts the value from the units specified in the config file (via
271 the UNITS="" attribute in the element definition) to the native units used by
272 JSBSim itself, as specified by the target_units parameter. The currently
273 allowable unit conversions are seen in the source file FGXMLElement.cpp.
274 Also, see above in the main documentation for this class.
275 @param el the name of the element being searched for (the empty string by
277 @param target_units the string representing the native units used by JSBSim
278 to which the value returned will be converted.
279 @return the unit-converted data value for the named element as a double,
280 or HUGE_VAL if the data is missing. */
281 double FindElementValueAsNumberConvertTo(string el, string target_units);
283 /** Searches for the named element and converts and returns the data belonging to it.
284 This function allows the data belonging to a named element to be returned
285 as a double. If no element is found, HUGE_VAL is returned. If no
286 argument is supplied, the data for the first element is returned. Additionally,
287 this function converts the value from the units specified in the supplied_units
288 parameter to the units specified in the target_units parameter. JSBSim itself,
289 as specified by the target_units parameter. The currently allowable unit
290 conversions are seen in the source file FGXMLElement.cpp. Also, see above
291 in the main documentation for this class.
292 @param el the name of the element being searched for (the empty string by
294 @param supplied_units the string representing the units of the value as
295 supplied by the config file.
296 @param target_units the string representing the native units used by JSBSim
297 to which the value returned will be converted.
298 @return the unit-converted data value for the named element as a double,
299 or HUGE_VAL if the data is missing. */
300 double FindElementValueAsNumberConvertFromTo( string el,
301 string supplied_units,
302 string target_units);
304 /** Composes a 3-element column vector for the supplied location or orientation.
305 This function processes a LOCATION or ORIENTATION construct, returning a
306 filled-out 3-element column vector containing the X, Y, Z or ROLL, PITCH,
307 YAW elements found in the supplied element. If one of the mentioned components
308 is not found, that component is set to zero and a warning message is printed.
309 All three elements should be supplied.
310 @param target_units the string representing the native units used by JSBSim
311 to which the value returned will be converted.
312 @return a column vector object built from the LOCATION or ORIENT components. */
313 FGColumnVector3 FindElementTripletConvertTo( string target_units);
315 /** This function sets the value of the parent class attribute to the supplied
317 @param p pointer to the parent Element. */
318 void SetParent(Element* p) {parent = p;}
320 /** Adds a child element to the list of children stored for this element.
321 * @param el Child element to add. */
322 void AddChildElement(Element* el) {children.push_back(el);}
324 /** Stores an attribute belonging to this element.
325 * @param name The string name of the attribute.
326 * @param value The string value of the attribute. */
327 void AddAttribute(string name, string value);
329 /** Stores data belonging to this element.
330 * @param d the data to store. */
331 void AddData(string d);
333 /** Prints the element.
334 * Prints this element and calls the Print routine for child elements.
335 * @param d The tab level. A level corresponds to a single space. */
336 void Print(int level=0);
340 map <string, string> attributes;
341 vector <string> data_lines;
342 vector <Element*> children;
343 vector <string> attribute_key;
346 typedef map <string, map <string, double> > tMapConvert;
350 } // namespace JSBSim
352 //%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%