SEnC Client Commands

In order to provide possibilities for even more powerful Enif scripting, SEnC also supports its own set of client commands, i.e. commands which are not sent to the Enif server, but which are processed locally by the SEnC program.

Client commands are easily recognizable since they all start with an exclamation mark. If such a line is detected in the input stream, instead of being sent to the Enif server, it passed to a SEnC's local command parser.

The current version of SEnC supports the following client commands:

!include filename

 
This command causes SEnC to open the specified file and process the commands it contains before continuing with the next command. The !include command can be used to read in header files containing required function libraries (as an alternative to specifying the required header files directly in the command line). Also, the !include command is convenient in interactive mode for telling SEnC to process an input file.

!print anytext

 
This command prints the given text to the standard output, after having passed it through SEnC's variable substitution (if any), but without passing it on to the Enif server. Thus, if the text does not contain any Enif parameter substitutions %<...>%, the print command produces the same output as a corresponding echo server command, but is much more efficient, since it is handled locally.

!wait seconds

 
Pauses for the specified number of seconds (which can be specified with decimals if small delays are required) before the next command is processed. This command may be useful for automated demonstrations in which each image should stay on the screen for some specific amount of time.

!prompt message

 
Prompt the user with the specified messages and wait for the user to enter an answer. The typed in answer will be written to the special variable ANSWER which can be accessed via variable substitution by putting the string ``{ANSWER}'' as a place holder. This command may be useful in situations where the user should be given time to take some action (e.g. interacting directly with Enif) before the processing of the commands should be continued.

!exit status

 
Terminate SEnC immediately, without processing the remaining commands. If an integer value is specified as argument, it is used passed to the operating system as exit status code.

!new variable = value

 
Create a new variable or, if the variable already exists, create a new instance of this variable and set it to the specified value.

!set variable = value

 
Set the topmost instance of the specified variable to the given value. If the variable does not yet exists, create it.

!delete variable [variable ...]

 
Delete the topmost instance of the specified variables.

!replace variable regexp [newstring]

 
In the specified variable all occurrences of the regular expression regexp are placed by the string newstring. If newstring is not specified, a single blank is used by default.

!begin

...

commands

...

!end

 
Command enclosed between a !begin and an !end command constitute a command block which can be used instead of a single command in composed commands that are described below.

!function fctname [argname ...]

 
The !function client command defines the function with the given function name to consist of the line or the following block of lines that is included between !begin and !end commands. Optional function arguments can be defined after the function name. Any occurrence of one of the function arguments enclosed in braces, {argname}, will be replaced by the corresponding argument value with which the function is called via the !call client command. Note that !function commands are not allowed within function definitions.

!call fctname [argvalue ...]

 
Call the function fctname using the argument values which are specified after the function name to substitute the function arguments.

!return

 
The !return command can be used in function definitions to return from the function before having reached the end of the function. Note that before returning from the function, it is up to the programmer to delete any private instance of variables which have been created with !new client commands within the function body.

!if value

!if val1 compop val2

 
The !if command cause the execution of following command or command block to be conditional to the specified test. If the first form is used, i.e. if only one value is specified, the condition is only met when the specified value is either a non-zero numerical value or the string ``yes''. If the second form is used, the two values val1 and val2 are compared using the comparison operator compop, as shown in the following table:

String comparisons:
==	equal
!=	not equal

Numeric comparisons:
=	equal	<>	not equal
>	larger than	<	less than
>=	larger or equal	<=	less or equal

 

Note that the comparison operator must always be separated by at least one blank from values which are compared, i.e. the command ``!if {X} > 1'' will work as expected, whereas the command ``!if {X}>1'' will not!

!iferror

 
This command is similar to the !if command described above. But instead of testing the given argument values, its condition is the acknowledgment received in response to the last server command. If the preceding server command was successful (OK reply), the following command or command block is skipped, whereas if it returned with an error (KO reply), the following command or command block is executed.

!else

 
The !else command can optionally follow just after the conditional command or command block of any !if or !iferror command. Only if the condition of the preceding if-command was not satisfied, the command or command block following the !else command will be executed. The following example illustrates the implementation of an if-then-else test:

!if 0 <= {OFFSET}
   !begin
      !print positive offset -> shifting to the right
      !call rightshift 0 {OFFSET}
   !end
!else
   !begin
      !print negative offset -> shifting to the left
      !call leftshift {OFFSET} 0
   !end

!for variable startval endval [increment]

 
The !for command implements a for loop by iterating the loop variable specified as the first argument from a start value up to and not exceeding a end value using, if specified, the given increment or else the value 1. The command or command block immediately following the !for command is executed for each of the values assigned to the loop variable.

E.g. the sequence
!for scenario 1000 5000 1000
  !call generateStandardPlots {scenario}
will call the function generateStandardPlots for each of the loop value, i.e. it is equivalent to the following commands:
!call generateStandardPlots 1000
!call generateStandardPlots 2000
!call generateStandardPlots 3000
!call generateStandardPlots 4000
!call generateStandardPlots 5000

The specified specified start, end and increment values can contain decimals. If the increment value is zero or has a different sign than the difference between end and start value, the command or command block following the !for command is not executed at all.

!foreach variable val1 val2 val3 ...

 
The !foreach command command executes the following command or command block once for each of the values valX as arguments. For each given value, the specified variable is first set to this value and then the line following the !foreach is executed.

E.g. the sequence
!foreach scenario 2000 2001 2002 3001 1000
  !call generateStandardPlots {scenario}
will call the function generateStandardPlots for each of the loop value, i.e. it is equivalent to the following commands:
!call generateStandardPlots 2000
!call generateStandardPlots 2001
!call generateStandardPlots 2002
!call generateStandardPlots 3001
!call generateStandardPlots 1000

!while value

!while val1 compop val2

 
The syntax of the !while client command corresponds to the !if client command. The command or command block following immediately the !while command will be executed for as long as the specified condition is true.

In addition to the client commands which are described above, SEnC also recognizes any input line which starts with # as a comment line and does not process it any further.