TSTool / Command / Comment #
Overview
Single-line comments start with #.
Spaces and tabs before the comment character are currently not allowed.
Comments cannot be added after commands - comments must exist on their own command line.
Commands can be converted to and from # comments by right-clicking on a command in TSTool
and selecting Convert selected commands to # comments and
Convert selected commands from # comments from the popup menu.
See also the /* and */
comment block commands, which are used to comment multiple commands.
The following table lists annotation tags that can be placed in comments to provide additional information to software that processes the commands, using notation similar to the following:
#@expectedStatus Failure
Special comments can be added by editing the # comment block or use the Commmands / General - Comments menu.
# Comment Command Annotation Tags
| Annotation Tag | Command/Component That Uses | Description |
|---|---|---|
@enabled False |
TSTool command processor. | Used in automated tests. Used to disable a command file. For example, use this annotation in a test command file when the test is not ready for use in the software release process. |
@expectedStatus Failure@expectedStatus Warning |
RunCommands command |
Used in automated tests. Used to help the test framework know if an error or warning is expected, in which case a passing test can occur even if the command status is not “success”. If the actual status from a command file (most severe status of all commands) does not match the expected status, the user interface will indicate a failure. |
@fixme |
Indicate something to fix, such as a bug in the command file logic. A comment typically has the form #@fixme user date Comment, for example: #@fixme smalers 2021-06-14 Need to fix the following input file. |
|
@os Windows@os UNIX |
CreateRegressionTestCommandFile command |
Used in automated tests. Used to filter out test command files that are not appropriate for the operating system. Linux is included in UNIX. |
@readOnly |
TSTool main interface and command editors | Used to restrict command file editing. Indicates that the command file should not be edited. TSTool will update old command syntax to current syntax when a command file is loaded. However, this tag will cause the software to warn the user when saving the command file, so that they can cancel. This tag is often used with templates to protect the template from mistakenly being edited and saved in TSTool (TSTool does not currently allow editing templates within the interface). |
@require application TSTool version >= NN.NN.NN |
Command processor | Used to ensure compatibility. Indicate that an application version (in this case for TSTool software) is required to run the command file. The operator can be >, >=, =, <, or <=. The version should be specified using Semantic versioning, for example 13.03.00. Each part of the version is checked numerically and leading zeros are ignored; therefore 03 evaluates to 3. If specified for automated tests, a test will only be run if the criteria are met, which allows tests to be developed for specific versions of the software. If the criteria are not met during normal runs, an error is generated. Use multiple @require comments if necessary for multiple criteria checks. |
@require datastore HydroBase version >= YYYYMMDD |
Command processor | Used to ensure compatibility. The syntax after the datastore name depends on the features implemented for a datastore (see the datastore's documenation). Indicate that a datastore version (in this case for datastore named HydroBase) is required to run the command file. The operator can be >, >=, =, <, or <=. The version string must be consistent with what is expected for a datastore. For example, HydroBase versions use the YYYYMMDD syntax, whereas other datastores use semantic versions or other date strings. Refer to the datastore reference documentation for version format information. Not all datastores support version checks. If specified for automated tests, the test will only be run if the criteria are met, which allows tests to be developed for specific versions of the software. If the criteria are not met during normal runs, an error is generated. Use multiple @require comments if necessary for multiple criteria checks. |
@require user User == name@require user User != name |
Command processor | Used to ensure compatibility. Indicate whether the command file is restricted to a certain user. This has mainly been used to ensure that automated tests are run as the correct user. Tests can be grouped by user using a test suite. A user requirement that fails causes command processing to exit. |
@template |
TSTool main interface | Used with template processing. Indicates a template command file that is intended to be expanded with the ExpandTemplateFile command. Currently, a text file editor may need to be used to edit template files because the TSTool user interface checks commands for final syntax and may generate warnings for template files. |
@testSuite ABC |
CreateRegressionTestCommandFile command |
Used in automated tests. Used to filter out test command files that are not appropriate for the operating system. |
@todo |
Indicate something to do, such as a future enhancement to the command file. A comment typically has the form #@todo user date Comment, for example: #@todo smalers 2021-06-14 Need to fill the following time series. |
Command Editor
The following dialog is used to edit the command and illustrates the command syntax.
# Command Editor (see also the full-size image)
Command Syntax
The command syntax is as follows:
# A comment
# Another comment
Examples
See the automated tests.