param mode (vs stream mode)
Using the deprecated param mode of ot-snippet has some restrictions and side effects like any other shell application and has been the major reason for the new/prefered V002 stream mode - details: param mode
IRC clients are typically using a shell call to run external applications like ot-snippet via exec. Arguments are handed over as given and are just used via their bash call argument variable, where $1 contains the name of the snippet to be used as convention.
Although you are free to use $2 in any way you like, you should stick to using it for nicknames, as this is needed for the new ${P} ( dynamic prompt ) variable to work reasonable the same way its needed with
To use some single extra argument needs only to place an according parameter variable at the snippet text.
More complex snippets - like building a sharable search engine url - can use variable ranges with some custom helper function to create the final snippet text.
# this one is special: - uses QS-function to chain $3..$n with + for search query
search=("
${P}using some alternative search-engine does often help to get answers (instead of advertisement)
${P}https://www.startpage.com/do/dsearch?query=$(QS ${@:3})
${P}https://html.duckduckgo.com/html?q=$(QS ${@:3}) $open_htm")
ot-snippet-para search guest7562 linux haveged
guest7562: using some alternative search-engine does often help to get answers (instead of advertisement) guest7562: https://www.startpage.com/do/dsearch?query=linux+haveged guest7562: https://html.duckduckgo.com/html?q=linux+haveged (<- click onto link(s) to open)
Using ${@:3} selects any extra given paramaters past an expected nickname to call a helper function QS to chain arguments using + characters as needed.
stream mode
In stream mode ot-snippets expects and reads arguments from stdin. Arguments read from the stream are used to replace the argument list of the ot-snippet instance itself.
It doesn't matter for a snippet if it gets called in parameter or in stream mode as it will always get available arguments via the regular bash variables $1,$2,..,$n .
To avoiding hanging ot-snippet instances due to missing arguments (either missing or failure on performing the write call from an IRC client) implements ot-snippet a 2 seconds default timeout. If ot-snippet aborts with a timeout it writes an entry to the log and just quits silently to avoid disturing IRC channels with unwanted noise.
dynamic prompt
With V002 an additional global prompt variable $P is available, which can be used instead of hardcoded nickname prompts at snippet definitions.
This is an optional feature: There is no technical need to use the dynamic prompt with a V001 style custom file.
If a nickname parameter ( $2 ) is available, the dynamic prompt defaults to: "$2: " including 1 trailing blank.
If no nickname parameter is available, the dynamic prompt defaults to an empty string; this will remove the complete prompt(s) from an expanded snippet without leaving stray characters behind.
An updated snippet definition looks like:
ask=("
${P}If you need support - describe your issue, giving some (more) details + version used: mint 19.x,20.x, lmde4 ? + DE: cinnamon, mate, xfce? - if anybody has an answer she/he will reply.
${P}Stay connected afterwards == people need some time to answer....$important")
Using the snippet with a nickname, renders a the nickname and an according prompt:
ot-snippet-para ask guest7235 guest7235: If you need support - describe your issue, giving some (more) details + version used: mint 19.x,20.x, lmde4 ? + DE: cinnamon, mate, xfce? - if anybody has an answer she/he will reply. guest7235: Stay connected afterwards == people need some time to answer....$important")
Using the snippet now without a nickname renders a text without any stray prompt elements:
ot-snippet-para ask If you need support - describe your issue, giving some (more) details + version used: mint 19.x,20.x, lmde4 ? + DE: cinnamon, mate, xfce? - if anybody has an answer she/he will reply. Stay connected afterwards == people need some time to answer....$important")
Where using the older V001 format leaves parts of the prompt behind:
ot-snippet-para ask > If you need support - describe your issue, giving some (more) details + version used: mint 19.x,20.x, lmde4 ? + DE: cinnamon, mate, xfce? - if anybody has an answer she/he will reply. > Stay connected afterwards == people need some time to answer....$important")
custom variables
Note: Its perfectly fine to not add or use any private/custom variables - its just an option and personal preference.
snippets are free to use variables which hold common text fragments. The according variables have to be defined before usage and are typically placed at the start of the custom file (snippet section within ot-snippet itself) ahead of snippet definitions. In the above sample used $libera_info and $open_irc variables are defined as:
libera_info="$2> NOTE: at some more libera-channels, only registered users are able to write/ask or even join => read: https://libera.chat/guides/registration" open_irc="(using hexchat: right-click onto link(s) and select 'Connect')"
If you notice that you are reusing slightly different versions of common text with your snippets, it might make sense to just define one version of that and reuse a consistent version with your snippets.
Good candidates are external services/links being used more often with snippets, where successors services might be used someday; so one only needs to adjust a single definition instead adjusting all affected snippets.
Note: snippet internal string array variables of the form var=("...") shall not be listed and may not use the convention for snippet definition naming. To avoid being listed by internal helpers its enough to:
- use no line break after =("
- indent variable declaration
- use white space with declarations like = (" or =( "
custom functions
Note: Its perfectly fine to not add and use any custom functions - its just an option and personal preference.
As you are effectively running a bash script when using ot-snippet, you are able to not just use call parameters - like $1..$n - and/or custom variables but to call you own custom functions too. A typical use case is to transform given parameters into some different format, like building a valid search query for search machine urls.
The predefined search snippet uses the internal helper function QS to create a search engine compatible query string.
# snippet-helper: merge args to query-string using +
# to be used with search-queries
# $@ - word-list
# output via echo
function QS
{
vmerge="${@}"
echo "${vmerge// /\+}"
}
Using helper functions allows to focus on messages and hiding some additional formatting requirements.
# 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")
Note: to get a list of all optional parameters after the nickname ${@:3} expands is used.
This allows to run the command with a nickname and a wordlist of any length:
/s search guest7235 install chrome linux mint
... which gets expanded at runtime to:
guest7235> using some alternative search-engine does often help to get answers (instead of advertisement)
guest7235> https://www.startpage.com/do/dsearch?query=install+chrome+linux+mint (<- click onto link(s) to open)
Malicious nicknames
Note: Be aware that you might need to do some cleanup using external input like a current nickname. Even if the stream mode is used with ot-snippet, this will only protect the call to ot-snippet itself and the internal representation of arguments is exactly as given.
If you are using given arguments with your own functions, you have to care about malicious arguments. A nickname may containinig backticks for example (seemingly allowed with more IRC networks). If you are feeding such variables into function calls or expand them as part of concatening strings you could run unintended statements this way.
Besides using cleartext, parts of statements can be given as encoded characters to bypass nickname character restrictions.
The main limit for usable commands is the available/supported nick name length (still enough to cause trouble) and the user seeing a fishy nickname - or just use the stream mode of ot-snippet and avoid using nicknames as parameters to your own internal functions.