User Reference:Operator Module Scripting

Mellinger — Wed, 16 May 2012 11:39:12 GMT

/* Abbreviated commands and synonyms */

Revision as of 11:39, 16 May 2012		Current revision
Line 34:		Line 34:
	=====DO; <loop commands>; UNTIL <condition>=====		=====DO; <loop commands>; UNTIL <condition>=====
	Executes ''loop commands'' until "condition" evaluates to ''true''.		Executes ''loop commands'' until "condition" evaluates to ''true''.
		+	=====FOR <name> IN <item1> <item2> ... ; <loop commands>; END=====
		+	Creates a local variable with the specified name. Then, sequentially assigns each ''item'' to that variable, and executes ''loop commands''. If an ''item'' contains newline characters, it is split up into multiple items, corresponding to the lines contained in the ''item''. E.g.,
		+	FOR i IN top ${LIST FILES} bottom; LOG ${i}; END
		+	will first write a log entry "top". Then, it will create a log entry for each file in the current directory, and finally, it will create a log entry "bottom".

	====Commands operating on Conditions====		====Commands operating on Conditions====
Line 70:		Line 74:
	Clears scripts for the given events. Equivalent to calling SET SCRIPT with an empty script.		Clears scripts for the given events. Equivalent to calling SET SCRIPT with an empty script.

-	=====EXECUTE SCRIPT <file or event>=====	+	=====EXECUTE SCRIPT <file or event> [<Arg1> <Arg2> ... <Arg9>]=====
-	Executes a script contained in a file. To execute a script associated with an event, provide an event name rather than a file.	+	Executes a script contained in a file, and optionally sets the script's local variables ''Arg1'' to ''Arg9'' to the specified values. To execute a script associated with an event, provide an event name rather than a file.

	====Commands operating on Parameters====		====Commands operating on Parameters====
Line 141:		Line 145:
	=====CLEAR EXPRESSION VARIABLE <name>=====		=====CLEAR EXPRESSION VARIABLE <name>=====
	Clears the named expression variable from storage.		Clears the named expression variable from storage.
		+
		+	====Commands operating on Files, Directories, and Paths====
		+	=====EXTRACT DIRECTORY <path>, EXTRACT FILE <path>, EXTRACT FILE BASE <path>=====
		+	Extracts the directory or file portion of a given path. When the path specifies a non-existing directory, the directory name must be followed with a separator ("/") in order to be recognized as a directory. The EXTRACT DIRECTORY command always returns its result with a trailing separator. The EXTRACT FILE BASE command returns the file portion without extension.
		+
		+	=====IS DIRECTORY <path>, IS FILE <path>, IS PATH <path>=====
		+	Determines whether the specified path points to an existing directory, file, or any of the two. The result is returned as one of the strings "true" or "false".
		+	=====PARENT DIRECTORY <path>=====
		+	Returns the parent directory of the specified path, independently of whether the path points to a directory, or to a file.
		+	=====CURRENT DIRECTORY=====
		+	Returns the current working directory.
		+	=====CHANGE DIRECTORY <path>=====
		+	Changes the working directory.
		+	=====MAKE DIRECTORY <path>=====
		+	Creates a new directory with the given path. The directory's parent must exist for the command to succeed.
		+	=====LIST DIRECTORY [<path> or <wildcard expression>]=====
		+	Returns a listing of the specified directory, or the current working directory if no path is specified. The listing is in long form. You may use wildcard expressions in order to restrict the output.
		+	=====LIST FILE <wildcard expression>, LIST FILES [<wildcard expression>]=====
		+	Returns a list of file names relative to the current directory. From LIST FILES, the argument may be omitted, which results in a list of all files.
		+	=====CANONICAL PATH <path>=====
		+	Translates the given path into canonical form, i.e. into an absolute path without symlinks. All directories along the path must exist in order for the command to succeed.

	====Global commands====		====Global commands====
Line 154:		Line 179:
	Waits until the system is in the specified state. This may be one of Unavailable, Idle, Startup, Initialization, Resting, Suspended, ParamsModified, Running, Termination, Busy, or a combination of these, separated with a pipe character: "Resting\|Suspended". When timeout occurs, an error message is returned.		Waits until the system is in the specified state. This may be one of Unavailable, Idle, Startup, Initialization, Resting, Suspended, ParamsModified, Running, Termination, Busy, or a combination of these, separated with a pipe character: "Resting\|Suspended". When timeout occurs, an error message is returned.
	=====SLEEP <time in seconds>=====		=====SLEEP <time in seconds>=====
-	Waits (sleeps) for the given amount of time. Timing resolution depends on the operating system and is typically in the 5ms range. Tends to sleep a little longer than specified, with the error growing with duration.	+	Waits (sleeps) for the given amount of time. Timing resolution is 50ms. Tends to sleep a little longer than specified, with the error growing with duration.

	=====GET SYSTEM VERSION=====		=====GET SYSTEM VERSION=====
Line 179:		Line 204:
	=====START EXECUTABLE <command line>=====		=====START EXECUTABLE <command line>=====
	Starts the specified executable with options. This command returns immediately after the started program has finished initialization.		Starts the specified executable with options. This command returns immediately after the started program has finished initialization.
		+	=====ECHO <arg1> ...=====
		+	Prints its arguments.

	=====LOG <message>=====		=====LOG <message>=====
Line 215:		Line 242:

	===Predefined Variables===		===Predefined Variables===
-	Variables marked with ''local'' are not environment variables, i.e. they are invisible to executables that are launched with SYSTEM or START EXECUTABLE. In script code, they may be used like ordinary variables however.	+	Variables marked with ''local'' are not environment variables, i.e. they are invisible to child processes that are launched using the SYSTEM or START EXECUTABLE commands. In script code, they may be used like ordinary variables however.
	====BCI2000LAUNCHDIR====		====BCI2000LAUNCHDIR====
-	The full absolute path to the working directory when the Operator module was launched. This is also prepended to the PATH environment variable.	+	The full absolute path to the working directory when the Operator module was launched. This is also prepended to the PATH environment variable, such that executables from the current BCI2000 installation will have precedence over any other executable with the same name.
		+
	====BCI2000BINARY====		====BCI2000BINARY====
	The full absolute path to the Operator module.		The full absolute path to the Operator module.
-	====BCI2000SCRIPT (local)====	+	====Arg0, Arg1, ... Arg9 (local)====
-	The full absolute path to the current script file, or the empty string.	+	When a script file is being executed, these variables contain the arguments of the EXECUTE SCRIPT command.
		+	''Arg0'' contains the full absolute path to the current script file. Within scripts, all of the ''Arg'' variables are defined, and those that do not have a matching argument are empty. Outside of scripts, these variables do not exist.
		+
	====YYYYMMDD (local)====		====YYYYMMDD (local)====
	Localtime at execution of the current script, in YYYYMMDD format. In interactive sessions, reflects the time when the session was initiated.		Localtime at execution of the current script, in YYYYMMDD format. In interactive sessions, reflects the time when the session was initiated.
Line 227:		Line 257:
	====HHMMSS (local)====		====HHMMSS (local)====
	Localtime at execution of the current script, in HHMMSS format. In interactive sessions, reflects the time when the session was initiated.		Localtime at execution of the current script, in HHMMSS format. In interactive sessions, reflects the time when the session was initiated.
		+
		+	===Abbreviated commands and synonyms===
		+	To minimize the need of consulting documentation, as well as for backward compatibility, a number of '''synonymous commands''' are provided. E.g., states may be added by INSERT STATE as well as ADD state, and the existence of a file may be queried by IS FILE as well as EXISTS FILE. For an overview over all allowed forms of commands, enter the HELP command.
		+
		+	To simplify operation in interactive sessions, '''abbreviated commands''' exist. Currently, these are:
		+	:'''cd''' for CHANGE DIRECTORY,
		+	:'''pwd''' and '''cd''' without argument for CURRENT DIRECTORY,
		+	:'''ls''' and '''dir''' for LIST DIRECTORY.
		+	For better readability of scripts, it is suggested to use the long forms of these commands.

	===Associating Scripts with Events===		===Associating Scripts with Events===

BCI2000 Wiki - Recent changes [en]

User Reference:Operator Module Scripting