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 Lesser 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 Lesser General Public License for more
  17  details.
  18
  19  You should have received a copy of the GNU Lesser 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 Lesser 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 <map>
  43 #  else
  44 #    include <vector.h>
  45 #    include <string>
  46 #    include <map.h>
  47 #  endif
  48 #else
  49 #  include <string>
  50 #  include <map>
  51 #  include <vector>
  52 #endif
  53
  54 #include <math/FGColumnVector3.h>
  55
  56 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  57 DEFINITIONS
  58 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  59
  60 #define ID_XMLELEMENT "$Id$"
  61
  62 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  63 FORWARD DECLARATIONS
  64 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  65
  66 namespace JSBSim {
  67
  68 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  69 CLASS DOCUMENTATION
  70 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  71
  72 /** Encapsulates an XML element.
  73     This class handles the creation, storage, and manipulation of XML elements.
  74     This class also can convert supplied values as follows:
  75
  76     convert ["from"]["to"] = factor, so: from * factor = to
  77     - convert["M"]["FT"] = 3.2808399;
  78     - convert["FT"]["M"] = 1.0/convert["M"]["FT"];
  79     - convert["M2"]["FT2"] = convert["M"]["FT"]*convert["M"]["FT"];
  80     - convert["FT2"]["M2"] = 1.0/convert["M2"]["FT2"];
  81     - convert["FT"]["IN"] = 12.0;
  82     - convert["IN"]["FT"] = 1.0/convert["FT"]["IN"];
  83     - convert["LBS"]["KG"] = 0.45359237;
  84     - convert["KG"]["LBS"] = 1.0/convert["LBS"]["KG"];
  85     - convert["SLUG*FT2"]["KG*M2"] = 1.35594;
  86     - convert["KG*M2"]["SLUG*FT2"] = 1.0/convert["SLUG*FT2"]["KG*M2"];
  87     - convert["RAD"]["DEG"] = 360.0/(2.0*3.1415926);
  88     - convert["DEG"]["RAD"] = 1.0/convert["RAD"]["DEG"];
  89     - convert["LBS/FT"]["N/M"] = 14.5939;
  90     - convert["LBS/FT/SEC"]["N/M/SEC"] = 14.5939;
  91     - convert["N/M"]["LBS/FT"] = 1.0/convert["LBS/FT"]["N/M"];
  92     - convert["N/M/SEC"]["LBS/FT/SEC"] = 1.0/convert["LBS/FT/SEC"]["N/M/SEC"];
  93     - convert["WATTS"]["HP"] = 0.001341022;
  94     - convert["HP"]["WATTS"] = 1.0/convert["WATTS"]["HP"];
  95     - convert["N"]["LBS"] = 0.22482;
  96     - convert["LBS"]["N"] = 1.0/convert["N"]["LBS"];
  97     - convert["KTS"]["FT/SEC"] = ktstofps;
  98
  99     - convert["M"]["M"] = 1.00;
 100     - convert["FT"]["FT"] = 1.00;
 101     - convert["IN"]["IN"] = 1.00;
 102     - convert["DEG"]["DEG"] = 1.00;
 103     - convert["RAD"]["RAD"] = 1.00;
 104     - convert["M2"]["M2"] = 1.00;
 105     - convert["FT2"]["FT2"] = 1.00;
 106     - convert["KG*M2"]["KG*M2"] = 1.00;
 107     - convert["SLUG*FT2"]["SLUG*FT2"] = 1.00;
 108     - convert["KG"]["KG"] = 1.00;
 109     - convert["LBS"]["LBS"] = 1.00;
 110     - convert["LBS/FT"]["LBS/FT"] = 1.00;
 111     - convert["N/M"]["N/M"] = 1.00;
 112     - convert["LBS/FT/SEC"]["LBS/FT/SEC"] = 1.00;
 113     - convert["N/M/SEC"]["N/M/SEC"] = 1.00;
 114     - convert["PSI"]["PSI"] = 1.00;
 115     - convert["INHG"]["INHG"] = 1.00;
 116     - convert["HP"]["HP"] = 1.00;
 117     - convert["N"]["N"] = 1.00;
 118     - convert["WATTS"]["WATTS"] = 1.00;
 119     - convert["KTS"]["KTS"] = 1.0;
 120     - convert["FT/SEC"]["FT/SEC"] = 1.0;
 121
 122     Where:
 123     - N = newtons
 124     - M = meters
 125     - M2 = meters squared
 126     - KG = kilograms
 127     - LBS = pounds force
 128     - FT = feet
 129     - FT2 = feet squared
 130     - SEC = seconds
 131     - SLUG = slug
 132     - DEG = degrees
 133     - RAD = radians
 134     - WATTS = watts
 135
 136     @author Jon S. Berndt
 137     @version $Id$
 138 */
 139
 140 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 141 CLASS DECLARATION
 142 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
 143
 144 class Element {
 145 public:
 146   /** Constructor
 147       @param nm the name of this element (if given)
 148       */
 149   Element(std::string nm);
 150   /// Destructor
 151   ~Element(void);
 152
 153   /** Retrieves an attribute.
 154       @param key specifies the attribute key to retrieve the value of.
 155       @return the key value (as a string), or the empty string if no such
 156               attribute exists. */
 157   std::string GetAttributeValue(std::string key);
 158
 159   /** Retrieves an attribute value as a double precision real number.
 160       @param key specifies the attribute key to retrieve the value of.
 161       @return the key value (as a number), or the HUGE_VAL if no such
 162               attribute exists. */
 163   double GetAttributeValueAsNumber(std::string key);
 164
 165   /** Retrieves the element name.
 166       @return the element name, or the empty string if no name has been set.*/
 167   std::string GetName(void) {return name;}
 168
 169   /** Gets a line of data belonging to an element.
 170       @param i the index of the data line to return (0 by default).
 171       @return a string representing the data line requested, or the empty string
 172               if none exists.*/
 173   std::string GetDataLine(unsigned int i=0);
 174
 175   /// Returns the number of lines of data stored
 176   unsigned int GetNumDataLines(void) {return (unsigned int)data_lines.size();}
 177
 178   /// Returns the number of child elements for this element.
 179   unsigned int GetNumElements(void) {return (unsigned int)children.size();}
 180
 181   /// Returns the number of named child elements for this element.
 182   unsigned int GetNumElements(std::string);
 183
 184   /** Converts the element data to a number.
 185       This function attempts to convert the first (and presumably only) line of
 186       data "owned" by the element into a real number. If there is not exactly one
 187       line of data owned by the element, then HUGE_VAL is returned.
 188       @return the numeric value of the data owned by the element.*/
 189   double GetDataAsNumber(void);
 190
 191   /** Returns a pointer to the element requested by index.
 192       This function also resets an internal counter to the index, so that
 193       subsequent calls to GetNextElement() will return the following
 194       elements sequentially, until the last element is reached. At that point,
 195       GetNextElement() will return NULL.
 196       @param el the index of the requested element (0 by default)
 197       @return a pointer to the Element, or 0 if no valid element exists. */
 198   Element* GetElement(unsigned int el=0);
 199
 200   /** Returns a pointer to the next element in the list.
 201       The function GetElement() must be called first to be sure that this
 202       function will return the correct element. The call to GetElement() resets
 203       the internal counter to zero. Subsequent calls to GetNextElement() return
 204       a pointer to subsequent elements in the list. When the final element is
 205       reached, 0 is returned.
 206       @return a pointer to the next Element in the sequence, or 0 if no valid
 207               Element is present. */
 208   Element* GetNextElement(void);
 209
 210   /** Returns a pointer to the parent of an element.
 211       @return a pointer to the parent Element, or 0 if this is the top level Element. */
 212   Element* GetParent(void) {return parent;}
 213
 214   /** Searches for a specified element.
 215       Finds the first element that matches the supplied std::string, or simply the first
 216       element if no search std::string is supplied. This function call resets the internal
 217       element counter to the first element.
 218       @param el the search std::string (empty std::string by default).
 219       @return a pointer to the first element that matches the supplied search std::string. */
 220   Element* FindElement(std::string el="");
 221
 222   /** Searches for the next element as specified.
 223       This function would be called after FindElement() is first called (in order to
 224       reset the internal counter). If no argument is supplied (or the empty string)
 225       a pointer to the very next element is returned. Otherwise, the next occurence
 226       of the named element is returned. If the end of the list is reached, 0 is
 227       returned.
 228       @param el the name of the next element to find.
 229       @return the pointer to the found element, or 0 if no appropriate element us
 230               found.*/
 231   Element* FindNextElement(std::string el="");
 232
 233   /** Searches for the named element and returns the string data belonging to it.
 234       This function allows the data belonging to a named element to be returned
 235       as a string. If no element is found, the empty string is returned. If no
 236       argument is supplied, the data string for the first element is returned.
 237       @param el the name of the element being searched for (the empty string by
 238       default)
 239       @return the data value for the named element as a string, or the empty
 240               string if the element cannot be found. */
 241   std::string FindElementValue(std::string el="");
 242
 243   /** Searches for the named element and returns the data belonging to it as a number.
 244       This function allows the data belonging to a named element to be returned
 245       as a double. If no element is found, HUGE_VAL is returned. If no
 246       argument is supplied, the data for the first element is returned.
 247       @param el the name of the element being searched for (the empty string by
 248       default)
 249       @return the data value for the named element as a double, or HUGE_VAL if the
 250               data is missing. */
 251   double FindElementValueAsNumber(std::string el="");
 252
 253   /** Searches for the named element and converts and returns the data belonging to it.
 254       This function allows the data belonging to a named element to be returned
 255       as a double. If no element is found, HUGE_VAL is returned. If no
 256       argument is supplied, the data for the first element is returned. Additionally,
 257       this function converts the value from the units specified in the config file (via
 258       the UNITS="" attribute in the element definition) to the native units used by
 259       JSBSim itself, as specified by the target_units parameter. The currently
 260       allowable unit conversions are seen in the source file FGXMLElement.cpp.
 261       Also, see above in the main documentation for this class.
 262       @param el the name of the element being searched for (the empty string by
 263       default)
 264       @param target_units the string representing the native units used by JSBSim
 265              to which the value returned will be converted.
 266       @return the unit-converted data value for the named element as a double,
 267               or HUGE_VAL if the data is missing. */
 268   double FindElementValueAsNumberConvertTo(std::string el, std::string target_units);
 269
 270   /** Searches for the named element and converts and returns the data belonging to it.
 271       This function allows the data belonging to a named element to be returned
 272       as a double. If no element is found, HUGE_VAL is returned. If no
 273       argument is supplied, the data for the first element is returned. Additionally,
 274       this function converts the value from the units specified in the supplied_units
 275       parameter to the units specified in the target_units parameter. JSBSim itself,
 276       as specified by the target_units parameter. The currently allowable unit
 277       conversions are seen in the source file FGXMLElement.cpp. Also, see above
 278       in the main documentation for this class.
 279       @param el the name of the element being searched for (the empty string by
 280       default)
 281       @param supplied_units the string representing the units of the value as
 282              supplied by the config file.
 283       @param target_units the string representing the native units used by JSBSim
 284              to which the value returned will be converted.
 285       @return the unit-converted data value for the named element as a double,
 286               or HUGE_VAL if the data is missing. */
 287   double FindElementValueAsNumberConvertFromTo( std::string el,
 288                                                 std::string supplied_units,
 289                                                 std::string target_units);
 290
 291   /** Composes a 3-element column vector for the supplied location or orientation.
 292       This function processes a LOCATION or ORIENTATION construct, returning a
 293       filled-out 3-element column vector containing the X, Y, Z or ROLL, PITCH,
 294       YAW elements found in the supplied element. If one of the mentioned components
 295       is not found, that component is set to zero and a warning message is printed.
 296       All three elements should be supplied.
 297       @param target_units the string representing the native units used by JSBSim
 298              to which the value returned will be converted.
 299       @return a column vector object built from the LOCATION or ORIENT components. */
 300   FGColumnVector3 FindElementTripletConvertTo( std::string target_units);
 301
 302   /** This function sets the value of the parent class attribute to the supplied
 303       Element pointer.
 304       @param p pointer to the parent Element. */
 305   void SetParent(Element* p) {parent = p;}
 306
 307   /** Adds a child element to the list of children stored for this element.
 308   *   @param el Child element to add. */
 309   void AddChildElement(Element* el) {children.push_back(el);}
 310
 311   /** Stores an attribute belonging to this element.
 312   *   @param name The string name of the attribute.
 313   *   @param value The string value of the attribute. */
 314   void AddAttribute(std::string name, std::string value);
 315
 316   /** Stores data belonging to this element.
 317   *   @param d the data to store. */
 318   void AddData(std::string d);
 319
 320   /** Prints the element.
 321   *   Prints this element and calls the Print routine for child elements.
 322   *   @param d The tab level. A level corresponds to a single space. */
 323   void Print(unsigned int level=0);
 324
 325 private:
 326   std::string name;
 327   std::map <std::string, std::string> attributes;
 328   std::vector <std::string> data_lines;
 329   std::vector <Element*> children;
 330   std::vector <std::string> attribute_key;
 331   Element *parent;
 332   unsigned int element_index;
 333   typedef std::map <std::string, std::map <std::string, double> > tMapConvert;
 334   tMapConvert convert;
 335 };
 336
 337 } // namespace JSBSim
 338
 339 //%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 340
 341 #endif