src/FDM/JSBSim/FGScript.h

   1 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   2  Header:       FGScript.h
   3  Author:       Jon Berndt
   4  Date started: 12/21/2001
   5
   6  ------------- Copyright (C) 2001  Jon S. Berndt (jsb@hal-pc.org) -------------
   7
   8  This program is free software; you can redistribute it and/or modify it under
   9  the terms of the GNU General Public License as published by the Free Software
  10  Foundation; either version 2 of the License, or (at your option) any later
  11  version.
  12
  13  This program is distributed in the hope that it will be useful, but WITHOUT
  14  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
  15  FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
  16  details.
  17
  18  You should have received a copy of the GNU General Public License along with
  19  this program; if not, write to the Free Software Foundation, Inc., 59 Temple
  20  Place - Suite 330, Boston, MA  02111-1307, USA.
  21
  22  Further information about the GNU General Public License can also be found on
  23  the world wide web at http://www.gnu.org.
  24
  25 HISTORY
  26 --------------------------------------------------------------------------------
  27 12/21/01   JSB   Created
  28
  29 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  30 SENTRY
  31 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  32
  33 #ifndef FGSCRIPT_HEADER_H
  34 #define FGSCRIPT_HEADER_H
  35
  36 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  37 INCLUDES
  38 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  39
  40 #include "FGJSBBase.h"
  41 #include "FGState.h"
  42 #include "FGFDMExec.h"
  43 #include <vector>
  44
  45 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  46 DEFINITIONS
  47 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  48
  49 #define ID_FGSCRIPT "$Id$"
  50
  51 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  52 FORWARD DECLARATIONS
  53 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  54
  55 namespace JSBSim {
  56
  57 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  58 COMMENTS, REFERENCES, and NOTES [use "class documentation" below for API docs]
  59 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  60
  61 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  62 CLASS DOCUMENTATION
  63 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
  64
  65 /** Encapsulates the JSBSim scripting capability.
  66     @author Jon S. Berndt
  67     @version $Id$
  68     @see <a href="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/jsbsim/JSBSim/FGScript.h?rev=HEAD&content-type=text/vnd.viewcvs-markup">
  69          Header File </a>
  70     @see <a href="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/jsbsim/JSBSim/FGScript.cpp?rev=HEAD&content-type=text/vnd.viewcvs-markup">
  71          Source File </a>
  72
  73     <h4>Scripting support provided via FGScript.</h4>
  74
  75     <p>There is simple scripting support provided in the FGScript
  76     class. Commands are specified using the <u>Simple Scripting
  77     Directives for JSBSim</u> (SSDJ). The script file is in XML
  78     format. A test condition (or conditions) can be set up in the
  79     script and when the condition evaluates to true, the specified
  80     action[s] is/are taken. A test condition can be <em>persistent</em>,
  81     meaning that if a test condition evaluates to true, then passes
  82     and evaluates to false, the condition is reset and may again be
  83     triggered. When the set of tests evaluates to true for a given
  84     condition, an item may be set to another value. This value might
  85     be a boolean, a value, or a delta value, and the change from the
  86     current value to the new value can be either via a step function,
  87     a ramp, or an exponential approach. The speed of a ramp or
  88     approach is specified via the time constant. Here is the format
  89     of the script file:</p>
  90
  91     <pre><strong>&lt;?xml version=&quot;1.0&quot;?&gt;
  92     &lt;runscript name=&quot;C172-01A&quot;&gt;
  93
  94     &lt;!--
  95     This run is for testing C172 runs
  96     --&gt;
  97
  98     &lt;use aircraft=&quot;c172&quot;&gt;
  99     &lt;use initialize=&quot;reset00&quot;&gt;
 100
 101     &lt;run start=&quot;0.0&quot; end=&quot;4.5&quot; dt=&quot;0.05&quot;&gt;
 102       &lt;when&gt;
 103         &lt;parameter name=&quot;FG_TIME&quot; comparison=&quot;ge&quot; value=&quot;0.25&quot;&gt;
 104         &lt;parameter name=&quot;FG_TIME&quot; comparison=&quot;le&quot; value=&quot;0.50&quot;&gt;
 105         &lt;set name=&quot;FG_AILERON_CMD&quot; type=&quot;FG_VALUE&quot; value=&quot;0.25&quot;
 106         action=&quot;FG_STEP&quot; persistent=&quot;false&quot; tc =&quot;0.25&quot;&gt;
 107       &lt;/when&gt;
 108       &lt;when&gt;
 109         &lt;parameter name=&quot;FG_TIME&quot; comparison=&quot;ge&quot; value=&quot;0.5&quot;&gt;
 110         &lt;parameter name=&quot;FG_TIME&quot; comparison=&quot;le&quot; value=&quot;1.5&quot;&gt;
 111         &lt;set name=&quot;FG_AILERON_CMD&quot; type=&quot;FG_DELTA&quot; value=&quot;0.5&quot;
 112         action=&quot;FG_EXP&quot; persistent=&quot;false&quot; tc =&quot;0.5&quot;&gt;
 113       &lt;/when&gt;
 114       &lt;when&gt;
 115         &lt;parameter name=&quot;FG_TIME&quot; comparison=&quot;ge&quot; value=&quot;1.5&quot;&gt;
 116         &lt;parameter name=&quot;FG_TIME&quot; comparison=&quot;le&quot; value=&quot;2.5&quot;&gt;
 117         &lt;set name=&quot;FG_RUDDER_CMD&quot; type=&quot;FG_DELTA&quot; value=&quot;0.5&quot;
 118         action=&quot;FG_RAMP&quot; persistent=&quot;false&quot; tc =&quot;0.5&quot;&gt;
 119       &lt;/when&gt;
 120     &lt;/run&gt;
 121
 122     &lt;/runscript&gt;</strong></pre>
 123
 124     <p>The first line must always be present. The second line
 125     identifies this file as a script file, and gives a descriptive
 126     name to the script file. Comments are next, delineated by the
 127     &lt;!-- and --&gt; symbols. The aircraft and initialization files
 128     to be used are specified in the &quot;use&quot; lines. Next,
 129     comes the &quot;run&quot; section, where the conditions are
 130     described in &quot;when&quot; clauses.</p>
 131
 132 */
 133
 134 /*%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 135 CLASS DECLARATION
 136 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%*/
 137
 138 class FGScript : public FGJSBBase
 139 {
 140 public:
 141   /// Default constructor
 142   FGScript(FGFDMExec* exec);
 143
 144   /// Default destructor
 145   ~FGScript();
 146
 147   /** Loads a script to drive JSBSim (usually in standalone mode).
 148       The language is the Simple Script Directives for JSBSim (SSDJ).
 149       @param script the filename (including path name, if any) for the script.
 150       @return true if successful */
 151   bool LoadScript( string script );
 152
 153   /** This function is called each pass through the executive Run() method IF
 154       scripting is enabled.
 155       @return false if script should exit (i.e. if time limits are violated */
 156   bool RunScript(void);
 157
 158 private:
 159   enum eAction {
 160     FG_RAMP  = 1,
 161     FG_STEP  = 2,
 162     FG_EXP   = 3
 163   };
 164
 165   enum eType {
 166     FG_VALUE = 1,
 167     FG_DELTA = 2,
 168     FG_BOOL  = 3
 169   };
 170
 171   struct condition {
 172     vector <FGPropertyManager*>  TestParam;
 173     vector <FGPropertyManager*>  SetParam;
 174     vector <double>  TestValue;
 175     vector <double>  SetValue;
 176     vector <string>  Comparison;
 177     vector <double>  TC;
 178     vector <bool>    Persistent;
 179     vector <eAction> Action;
 180     vector <eType>   Type;
 181     vector <bool>    Triggered;
 182     vector <double>  newValue;
 183     vector <double>  OriginalValue;
 184     vector <double>  StartTime;
 185     vector <double>  EndTime;
 186
 187     condition() {
 188     }
 189   };
 190
 191   bool Scripted;
 192
 193   string  ScriptName;
 194   double  StartTime;
 195   double  EndTime;
 196   vector <struct condition> Conditions;
 197
 198   FGFDMExec* FDMExec;
 199   FGState* State;
 200   FGPropertyManager* PropertyManager;
 201   void Debug(int from);
 202 };
 203 }
 204 //%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 205 #endif
 206