Bash Shell

KosmicTask Help

Bash Shell

Bash is the default shell on OS X 10.6 and above.

Calling the Task Run Function

Arguments are passed to bash powered tasks as direct parameters rather than through a named entry point function. The task parameters will be forwarded to the task script as command line arguments.

Result Objects

Bash returns results to the client by printing to stdout.

To return structured data, including the contents of files, bash powered tasks should format result data using YAML.

KosmicTask supports both the YAML inline and block formats.

# return a YAML block format array
echo "---"
echo "- Mercury"
echo "- Venus"
echo "- Earth"
echo "- Mars"
echo "- Jupiter"
echo "- Saturn"
echo "- Uranus"
echo "- Neptune"

Inline format:

# we return a YAML inline format dictionary
item1='item 1'
item2='item 2'

echo "--- {key1: $item1, key2: $item2}"

Result File Handling

KosmicTask supports the returning of file contents within task results.

KosmicTask automatically looks for a kosmicFile record containing file paths within a dictionary type result object. If found, KosmicTask will return the contents of the file or files to the client.

For Bash powered tasks files are returned as results using the following YAML dictionary syntax:

echo "---"
echo "{kosmicFile: $FILE}"

A common usage scenario is that a task creates a temporary file (or files) whose contents are then returned to the client. KosmicTask therefore supports automatic temporary file creation and deletion. Temporary files created through KosmicTask are automatically deleted once the parent task has completed.

Bash powered tasks can create temporary files simply by creating files in the current working directory.

# capture screen image to file
# files created in the current directory will be deleted when the task ends

# capture screen
screencapture -t png $FILE

# return a YAML inline format dictionary
echo "---"
echo "{kosmicFile: $FILE , kosmicInfo: file returned}"

Logging and Debugging

Diagnostic and logging information can be written to a task's error stream on /dev/stderr.

# send log value to stderr
echo "Goodbye, kosmos!" >/dev/stderr

An alternate form is.

# send log value to stderr
echo "Goodbye, kosmos!" >&2

In some cases it may be desirable to redirect all or large portions of the script's output to the log. This can be achieved by redirecting stdout to stderr as follows.

# link file descriptor 3 with stdout
exec 3<&1

# redirect stdout to stderr 
exec 1<&2

# echo value to log via redirected stdout
echo "Goodbye, kosmos!" 

# restore stdout and close file descriptor 3
exec 1<&3 3<&-

# send result to stdout
echo "Hello, kosmos!"