script sections

Following information is not required to edit snippets but might help to understand limitations, features and conventions.

ot-snippet is a bash shell script, snippets are simply named array-variables.

The script consists of three sections

• header - internal variables and helper
• snippets section
• footer - callback and parameter evaluation

Although you shouldn't edit the header or footer section, it wont hurt to know some internals at least.

support files

ot-snippet creates/uses some support files, where the basename of the called application link is used derive the file names by adding file extensions as needed. A file extension - like .sh - will be stripped from a given basename.

This allows to use several symbolic links pointing at the same ~/bin/ot-snippet-002.sh while being able to thus use a different custom file for each symbolic link.

According dependent files of ~/bin/ot-snippet-strm would be:

... or for some other purpose ~/bin/ot-snippet-strm-dvuan would be:

# workarounds for known issues -----------------------------------------

common helper functions

The header includes some helper funtions to be used with snippets as needed.

# snippet-helper: merge args to query-string using +
# to be used with combined search-queries
# $@ - word-list
# output via echo
function QS
{
vmerge="${@}"
echo "${vmerge// /\+}"  
}

# snippet-helper: merge args to query-string using %20 to replace blank
# to be used with quoted search terms containing blanks
# $@ - word-list
# output via echo
function WS
{
vmerge="${@}"
echo "${vmerge// /\%20}"  
}

The helper functions can be used to build valid html queries, replacing whitespace with according escapes.

A usage sample is:

# this one is special: - uses QS-function to chain $3..$n with + for search query
search=("
$2> using some alternative search-engine does often help to get answers (instead of advertisement)
$2> https://www.startpage.com/do/dsearch?query=$(QS ${@:3}) $open_htm")

You are accordingly able to add your own helper functions. Helper functions have to be defined at the header section of the custom file to be callable/usable with the snippets.

stream input to arglist

Handling stream input is done at a single location. Reading from the stream is done using a predefined timeout.

After successful reading stream arguments they are used to replace the current call stack arguments of ot-snippet itself.

This allows to keep up with the parameter mode logic of V001 snippets, to use simple bash style variables for expected arguments like: $2 ${@:3:} ${@:2:2}

A usage sample is:

# this one is special: - uses QS-function to chain $3..$n with + for search query
search=("
$2> using some alternative search-engine does often help to get answers (instead of advertisement)
$2> https://www.startpage.com/do/dsearch?query=$(QS ${@:3}) $open_htm")

... where additional arguments are combined to build a useful search query, which can be shared.

stream timeout, errors

If expected arguments cant be read from the stream within the current timeout, a warning message will be added to the log and ot-snippet terminates without any further output (intentionally).

If any runtime error happens while reading from the stream an according error message is added to the log and ot-snippet terminates without any further output (intentionally).

To test ot-snippet in stream mode, either pipe expected input to it, or define a longer timeout, to be able to enter expected parameters manually in time. Using some 30 seconds should be enough for most case: ot-snippet-strm --timeout=30

filters

Last part of the header addresses support for login features like filters.

Filters can be used to handle selected log messages to suppress common 'noise' at the logfile.

Details and predefined suppress-statements - see: suppress log entries