Expecco Scripting API/en: Unterschied zwischen den Versionen
Cg (Diskussion | Beiträge) |
Cg (Diskussion | Beiträge) |
||
| Zeile 33: | Zeile 33: | ||
Having the current directory set to the attachment folder makes it easy for the script to access any attached data files, and also to create output files, which may later be archived in the generated ".elf" file. |
Having the current directory set to the attachment folder makes it easy for the script to access any attached data files, and also to create output files, which may later be archived in the generated ".elf" file. |
||
When finished, the exitCode is written to the "result" pin (if present). |
When finished, the exitCode is written to the "result" pin (if present). Usually, a zero value means "OK", but the details depend on the called script/command (for example, the "diff" unix command will return "1" if there are no differences). |
||
The stdout and stderr are written after the executen iff those pins were defined as buffered pins. |
The stdout and stderr are written after the executen iff those pins were defined as buffered pins. |
||
Version vom 24. Mai 2018, 22:35 Uhr
Inhaltsverzeichnis
Shell and Script Elementary Blocks[Bearbeiten]
Often it is not required to implement an elementary action with Smalltalk, JavaScript or Groovy code: there may be already a program (command line tool), a shell script, or a program/library written in another scripting language available. Expecco provides convenient, flexible and easy to use mechanisms to call those existing functions or programs.
expecco Script API[Bearbeiten]
The way external scripts are called is similar with all supported scripting languages. Depending on the language and script interpreter, there are minor differences in the debug features provided and the format of error messages (these are provided by the called scritp interpreter, and can usually not be enhanced by expecco).
The general mechanism works as follows:
- every script action has a number of input pins to control:
- the standard input to be sent to the script ("stdin" pin)
- a specification of how the output should be handled (all in one, linewise, or in multiple-line chunks)
- an optional execution directory ("execDir" pin)
- an optional set of shell environment variable definitions ("environment" pin)
- an optional list of command line arguments ("args pin)
- additional input pins to further parametrize the executed script (see "Parameters" section below)
- every script action provides at the output:
- the standard output (at the "stdout" pin) either linewise, all-in-one, or chunked, as specified by the "outNLines" input pin
- the standard error ("stderr" pin), also as specified by the "errNLines" input pin
- the program's exit code ("result" pin)
- an optional converted output value ("stdoutValue" pin)
All of those pins and their behavior are described below.
When initially created (via the tree-menu), a script action's definition includes all of the above pins. However, you can remove any unneeded pins in the schema editor, to make your diagrams easier to understand. Of course, any of those pins can be re-added later, via the schema-editor's "Add Special Pin" menu.
Execution[Bearbeiten]
When executed, the script's code is first expanded, using the additional input pin values, and the expanded code is written to a temporary file. Then the external script interpreter is called (with optional command line arguments as provided by the "args" pin), with the current directory set to either the specified exec-directory (via the "execDir" pin), or in the project's attachment folder. Having the current directory set to the attachment folder makes it easy for the script to access any attached data files, and also to create output files, which may later be archived in the generated ".elf" file.
When finished, the exitCode is written to the "result" pin (if present). Usually, a zero value means "OK", but the details depend on the called script/command (for example, the "diff" unix command will return "1" if there are no differences).
The stdout and stderr are written after the executen iff those pins were defined as buffered pins. If unbuffered, the output and error are written as the script generates them (and will be passed to connected steps even if the script later exits with a non-zero exit code).
Finally, the "stdOutValue" pin provides the stdout string converted to its datatype. For example, if this pin has an "Integer" type, the program's stdout will be converted to an integral number and that converted value be generated at the "stdoutValue" pin. A conversion error might be reported, if the program's output does not represent a valid integer number. Be aware, that this automatic conversion is probably only useful for a very limited set of possible types - typically integers, floats and stringCollections.
Shell Scripts[Bearbeiten]
Hello World as Shell Script[Bearbeiten]
The first example is the obligatory "hello world" example:
- create a new shell script action,
- remove all but the stdout pin,
- change the code to:
echo "Hello, World"
execute and see the program's output at the "stdout" pin.
Parameters[Bearbeiten]
The next example demonstrates parameter passing to the script;
- add an additional input pin named "greeting" (with type "String")
- change the script to:
echo "%(greeting)"
- go to the "Test/Demo" page, and freeze the "greeting" input pin with some arbitrary string (for example: "hello foobar"),
- execute the example to see the "greeting" pin's value being echoed.
Accessing Attachment Files[Bearbeiten]
- create an attachment, containing a few lines of text:
line1 line2 line3
- change the filename to "testAttachment". Be careful here: the filename must be "testAttachment" - not the name of the attachment in the tree. Although it does not hurt, if the have the same name.
- change the script to:
ls -l cat testAttachment
- run it to see the attachment folder's name, followed by the lines of the file attachment.
