src/FDM/JSBSim/input_output/FGXMLElement.h

   1 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   2
   3  File:         FGXMLElement.h
   4  Author:       Jon S. Berndt
   5  Date started: 9/28/04
   6
   7  ------------- Copyright (C) 2004  Jon S. Berndt (jsb@hal-pc.org) -------------
   8
   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
  12  version.
  13
  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
  17  details.
  18
  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.
  22
  23  Further information about the GNU General Public License can also be found on
  24  the world wide web at http://www.gnu.org.
  25
  26 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  27 SENTRY
  28 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  29
  30 #ifndef XMLELEMENT_H
  31 #define XMLELEMENT_H
  32
  33 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  34 INCLUDES
  35 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  36
  37 #ifdef FGFS
  38 #  include <simgear/compiler.h>
  39 #  ifdef SG_HAVE_STD_INCLUDES
  40 #    include <string>
  41 #    include <vector>
  42 #    include <iostream>
  43 #    include <map>
  44 #  else
  45 #    include <vector.h>
  46 #    include <string>
  47 #    include <iostream.h>
  48 #    include <map.h>
  49 #  endif
  50 #else
  51 #  include <string>
  52 #  include <map>
  53 #  include <iostream>
  54 #  include <vector>
  55    using std::string;
  56    using std::map;
  57    using std::vector;
  58    using std::cout;
  59    using std::endl;
  60 #endif
  61    using std::string;
  62    using std::map;
  63    using std::vector;
  64    using std::cout;
  65    using std::endl;
  66
  67 #include <math/FGColumnVector3.h>
  68
  69 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  70 DEFINITIONS
  71 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  72
  73 #define ID_XMLELEMENT "$Id$"
  74
  75 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  76 FORWARD DECLARATIONS
  77 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  78
  79 namespace JSBSim {
  80
  81 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  82 CLASS DOCUMENTATION
  83 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  84
  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:
  88
  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;
 111
 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;
 134
 135     Where:
 136     - N = newtons
 137     - M = meters
 138     - M2 = meters squared
 139     - KG = kilograms
 140     - LBS = pounds force
 141     - FT = feet
 142     - FT2 = feet squared
 143     - SEC = seconds
 144     - SLUG = slug
 145     - DEG = degrees
 146     - RAD = radians
 147     - WATTS = watts
 148
 149     @author Jon S. Berndt
 150     @version $Id$
 151 */
 152
 153 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 154 CLASS DECLARATION
 155 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
 156
 157 class Element {
 158 public:
 159   /** Constructor
 160       @param nm the name of this element (if given)
 161       */
 162   Element(string nm);
 163   /// Destructor
 164   ~Element(void);
 165
 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
 169               attribute exists. */
 170   string GetAttributeValue(string key);
 171
 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
 175               attribute exists. */
 176   double GetAttributeValueAsNumber(string key);
 177
 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;}
 181
 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
 185               if none exists.*/
 186   string GetDataLine(int i=0);
 187
 188   /// Returns the number of lines of data stored
 189   int GetNumDataLines(void) {return data_lines.size();}
 190
 191   /// Returns the number of child elements for this element.
 192   int GetNumElements(void) {return children.size();}
 193
 194   /// Returns the number of named child elements for this element.
 195   int GetNumElements(string);
 196
 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);
 203
 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);
 212
 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);
 222
 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;}
 226
 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="");
 234
 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
 240       returned.
 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
 243               found.*/
 244   Element* FindNextElement(string el="");
 245
 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
 251       default)
 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="");
 255
 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
 261       default)
 262       @return the data value for the named element as a double, or HUGE_VAL if the
 263               data is missing. */
 264   double FindElementValueAsNumber(string el="");
 265
 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
 276       default)
 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);
 282
 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
 293       default)
 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);
 303
 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);
 314
 315   /** This function sets the value of the parent class attribute to the supplied
 316       Element pointer.
 317       @param p pointer to the parent Element. */
 318   void SetParent(Element* p) {parent = p;}
 319
 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);}
 323
 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);
 328
 329   /** Stores data belonging to this element.
 330   *   @param d the data to store. */
 331   void AddData(string d);
 332
 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);
 337
 338 private:
 339   string name;
 340   map <string, string> attributes;
 341   vector <string> data_lines;
 342   vector <Element*> children;
 343   vector <string> attribute_key;
 344   Element *parent;
 345   int element_index;
 346   typedef map <string, map <string, double> > tMapConvert;
 347   tMapConvert convert;
 348 };
 349
 350 } // namespace JSBSim
 351
 352 //%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 353
 354 #endif