The stack module 命令堆栈模块

BlueSky gives complete control over the simulation through its own 'scripting language' called TrafScript. The stack is the module that parses these commands. A complete list of built-in stack commands can be found here.

蓝天公司通过自己的 "脚本语言"（TrafScript）对模拟进行完全控制。堆栈是解析这些命令的模块。完整的内置堆栈命令列表可以在这里找到。

Stack commands can come from four sources:

• From scenario files. These consist of a time-stamped list of TrafScript commands, which together can be run as a complete scenario. 来自场景文件。这些文件由带有时间戳的TrafScript命令列表组成，它们可以作为一个完整的场景运行。

• From network communication to/from BlueSky. BlueSky can be connected over TCP to send it simulation commands. See for an example here. 从网络通信到/从BlueSky。BlueSky可以通过TCP连接，向它发送模拟命令。请看这里的一个例子。

• Directly from the interface. The BlueSky interface has a command line, that can be used to interact with the simulation using TrafScript commands. 直接从界面上操作。BlueSky界面有一个命令行，可以使用TrafScript命令与模拟进行交互。

• From inside a plugin, using the stack() function defined below. 从一个插件内部，使用下面定义的stack()函数。

Construction of functions in the stack

By default, the stack contains a large list of functions. In addition, more functions can be added to the stack from BlueSky plugins. All of these functions are stored in a dictionary, following the following format:

默认情况下，堆栈包含一个大的函数列表。此外，更多的函数可以从BlueSky插件中添加到栈中。所有这些函数都存储在一个字典里，格式如下。

NAME : [USAGE_TEXT, ARGUMENT_TYPES, FUNCTION_REFERENCE, HELP_TEXT]

For a simple function such as the ALT command, this becomes:

{
    "ALT": [
        "ALT acid, alt, [vspd]",
        "acid,alt,[vspd]",
        autopilot.select_altitude,
        "Select autopilot altitude (optionally with vertical speed)."
    ]
}

NAME and USAGE_TEXT:

The name and usage text together describe briefly in an understandable form how to use the function. In the ALT example, the name of the function is ALT, and it should be called with at least an aircraft callsign and an altitude, and optionally also a vertical speed (optional because it is indicated between square brackets).

名称和使用文本一起以可理解的形式简要描述了如何使用该函数。在ALT的例子中，函数的名称是ALT，在调用它的时候，至少要有一个飞机呼号和一个高度，还可以选择一个垂直速度（可选，因为它在方括号中表示）。

ARGUMENT_TYPES

In BlueSky, commands that come from scenario files, from the command line, or from the network, are formatted in plain text. The Stack decodes these plain-text arguments into the required function arguments, but of course it needs to know what to expect for each argument. This is indicated for each stack function in the ARGUMENT_TYPES string. This string is a comma-separated list of data types, corresponding to each of the function's expected arguments. In addition, arguments can be made optional when enclosed in square brackets, and alternative types can be indicated with a slash ('/'). In the ALT example above, the first two arguments are mandatory, and the third is optional. The table below describes the argument types recognised by the BlueSky stack.

在BlueSky，来自场景文件、命令行或网络的命令都是纯文本格式。堆栈将这些纯文本参数解码为所需的函数参数，当然它需要知道对每个参数的期待。这在ARGUMENT_TYPES字符串中为每个堆栈函数指出。这个字符串是一个以逗号分隔的数据类型列表，对应于每个函数的预期参数。此外，参数可以用方括号括起来，成为可选项，替代类型可以用斜线（'/'）表示。在上面的ALT例子中，前两个参数是必须的，第三个参数是可选的。下表描述了BlueSky堆栈所识别的参数类型。

Type	Resulting value	description
txt	Upper-case string	The most basic argument type. No parsing is performed.最基本的参数类型。不进行解析。
string	Case-sensitive string of all arguments	Special case: arguments are not parsed separately. Instead the whole argument string is passed as a whole to the function. Used, for instance, for the ECHO command.特殊情况：参数不被单独解析。相反，整个参数字符串被作为一个整体传递给函数。例如，用于ECHO命令。
float	Floating-point value	Basic numerical (floating-point) values.基本数字（浮点）值。
int	Integer value	Basic numerical (integer) values.
bool/onoff	Boolean	Basic boolean (true/false) value. Parses True/False, ON/OFF, Yes/No, 1/0.
acid	Aircraft index	Parses an aircraft callsign, returns its index in the Traffic attribute vectors.解析一个飞机呼号，返回其在交通属性向量中的索引。
wpinroute	string	Looks for a waypoint in the route of the currently addressed aircraft (most often this aircraft is also referenced explicitly in the same function).在当前寻址的飞机的航线中寻找一个航点（最常见的是这个飞机也在同一个函数中被明确引用）。
wpt	string	Returns a formatted waypoint name, based on a number of possible position arguments. See latlon for possible position inputs.根据一些可能的位置参数，返回一个格式化的航点名称。可能的位置输入见latlon。
latlon	(lat,lon) float vector	Parses a number of position arguments.解析若干位置参数。Valid position texts with examples: lat/lon: N52.12,E004.23,N52'14'12',E004'23'10 navaid/fix: SPY,OA,SUGOL airport: EHAM runway: EHAM/RW06 LFPG/RWY23 callsign: KL204
spd	speed in m/s (float)	Parses speed inputs, automatically distinguishing between mach and knots.解析速度输入，自动区分马赫和节数。
vspd	Vertical speed in m/s (float)	Parses vertical speed, and converts from FPM to m/s.解析垂直速度，并从FPM转换为m/s。
alt	Altitude in meters (float)	Parses altitude, accepts feet and flight levels (e.g., FL300).解析高度，接受英尺和飞行等级（如FL300）。
hdg	Heading in degrees (float)	Parses heading. Accepts true (090T) and magnetic (120M).解析航向。接受真实（090T）和磁性（120M）。
time	Time in seconds (float)	Parses time. Accepts seconds, or time notation (12:30:00).解析时间。接受秒，或时间符号（12:30:00）。

If you need to parse an argument whose type is not listed here, either use the 'txt' type and parse it yourself, or propose a new argument type for the stack.

如果你需要解析一个其类型没有在这里列出的参数，要么使用'txt'类型并自己解析它，要么为堆栈提出一个新的参数类型。

FUNCTION_REFERENCE:函数引用

A reference to the function that should be called as a result of the stacked command. This can a top-level function of a module, but also a member function of an object. Remember that in python, functions are also objects, and can be passed around just like regular objects, so in the above ALT example, the following would work:

一个对函数的引用，该函数应作为堆叠命令的结果被调用。这可以是一个模块的顶级函数，但也可以是一个对象的成员函数。记住，在 python 中，函数也是对象，可以像普通对象一样被传递，所以在上面的 ALT 例子中，下面的方法也可以。

class AutoPilot:
   # A lot of initialization and data here

   # The alt function
   def select_altitude(self, idx, alt, vspd=None):
      self.selalt[idx] = alt
      if vspd is not None:
         self.selvs[idx]  = vspd

autopilot = AutoPilot()

# And then connect to the stack as in the above example,
# passing autopilot.select_altitude as target function.

HELP_TEXT:

This is a more elaborate help text to the function.

Stack functions:

get_scenname()

This function returns the name of the currently running scenario. This corresponds either to the name given by the SCEN command, or otherwise the filename of the scenario that was loaded.

该函数返回当前运行的场景的名称。这与SCEN命令给出的名称相对应，或者与被加载的场景的文件名相对应。

stack(cmdline)

Stack a TrafScript command given by cmdline. For example:

叠加一个由cmdline给出的TrafScript命令。比如说。

from bluesky import stack
stack.stack('PAN KLAX;ZOOM 2')

Puts the command on the stack to pan the radarscreen to LA airport, and set the zoom to two. This will be executed the next time the stack is updated.