Create a new command.

Arguments:

name

The name to give the function.

/flags

Zero or more flag names, each one preceded by a '/' character. These appear as boolean variables inside the command. If the user calls the command with these flags, the corresponding boolean variables are assigned the value "true". Otherwise they have the value "false". See below for an example.

type name

The datatype and name of an argument of the command.

[type name,...]

The datatypes and names of any optional arguments. Such arguments can only be used to give values to the optional arguments of other commands (ie. ultimately to the optional arguments of builtin commands). See below for an example.

Note that arguments are passed by reference. This means that if a variable is passed as an argument to a command, and the value of this argument is changed within the command, then the value of the original variable will be changed. This provides a way for commands to return values to their callers.

Examples:

A trivial example:

The following example creates a command that, when invoked, delays the execution of the script for a given interval. It then shows how one would call it to delay script execution for 10 minutes.

 command delay(Double dt) {
   until $elapsed >= $dt
 }

 delay 0:10:0

An example of using flags:

The following is an example of the definition of a command with flags.

 command track_source/wait/warn(Source src) {
 
   # If the source is currently below the horizon, and the
   # caller has asked to be told about this, output a warning.
 
   if($warn & $el($src) < 0.0) {
     print "Source ", $src, " is currently below the horizon."
   }
 
   # Tell the control system to track the source.
 
   track $src
 
   # If the caller wants us to wait until the source is acquired before
   # returning, do so here.
 
   if($wait) {
     until $acquired(source)
   }
 }

This command can then be called like:

  track_source/warn mars

in which case $warn would be true and $wait would be false, or

  track_source/warn/wait moon

to make both $warn and $wait true, or

  track_source mercury

to make both $warn and $wait false.

An example of using optional arguments:

The following is an example of the definition of a command that has optional arguments.

  command offset_track(Source src, [Double az, Double el, Double dk]) {
    offset az=$az, el=$el, dk=$dk
    track $src
  }

This command has one mandatory argument, followed by 3 optional arguments. The optional arguments are passed to the builtin "offset" command, where only the arguments that are presented to the offset_track command actually become arguments of the offset command. To be more precise, if the optional $az argument is omitted when calling offset_track, the corresponding optional $az argument of the offset command will be assigned a nul value. For example:

 offset_track moon, az=0:0:5, el=0:0:10

would result in the offset command installing new tracking offsets for azimuth and elevation, but would leave the deck angle offset unchanged.

An example of returning values via arguments:

The following example makes use of the fact that if the value of a command argument is changed within the command, the variable that was passed to that argument by the caller is likewise changed.

The example defines a command that returns, via its arguments, the current azimuth and elevation tracking offsets. When it is called, at the end of the example, the values of the az_offset and el_offset variables, which were passed to the command, end up containing the azimuth and elevation offsets that were queried within the command.

  command azel_offsets(Double az, Double el) {
    TrackingOffsets offsets = $tracking_offsets()
    az = $offsets.az
    el = $offsets.el
  }
  ...
  Double az_offset = 0
  Double el_offset = 0
  azel_offsets($az_offset, $y_offset)

Context:

Once a new command has been defined like this it can be used exactly as though it were a builtin command.