from IRC

After you finished the setup of your IRC client (user-command/alias), you should be ready to test a first snippet. To avoid disturbing some real channel conversations, you should likely create/join a temporary channel first, to play around there with ot-snippet:

/join #testsnippet

Using there:

/s ask guest7235

...should output a message like this:

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....

from a terminal

Instead of testing ot-snippet from an IRC client, you could use ot-snippet from a terminal too, where it will be more straight forward to use the deprecated parameter mode there:

ot-snippet-para ask guest7235

...should output the same message.

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....

If you want to use/test the stream mode from a terminal, it expects the parameters to be feed in via stdin. So either pipe them to ot-snippet-strm - like:

echo "ask guest7235" | ot-snippet-strm

..., or using some here document - like:

ot-snippet-strm <<< "ask guest7235"

To type the expected input manually, you should set a longer timeout to override the default 2 seconds:

ot-snippet-strm --timeout=30
ask guest7235

Parameters, mapping to variables

As ot-snippet is a bash-script, the snippet name is kept at the $1 parameter.

Additional parameters ( $2..$n ) to ot-snippet can be used at the snippets and just expand at the according locations. The result is then returned at stdout and thus shown by the calling application (IRC client or a terminal if being used for testing).

Although you are free to use additional parameters to your liking, most predefined snippetes are using $2 to place a nickname in front of lines to 'tag' an user; using the predefined snippet:

ask=("
$2> 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.
$2> Stay connected afterwards ==  people need some time to answer....$important")

...will typically be used with a nickname as additional parameter:

/s ask guest7235

... and will expand to:

guest7235> If you need support - describe your issue, giving some (more) details + version used: 19.x?, + DE: cinnamon, mate, xfce? - if anybody has an answer she/he will reply.
guest7235> Stay connected afterwards == do not ask and leave after 1 minute.

Note: Read snippet declaration convention about format requirements for snippets first line:

ask=("

superfluous or missing parameters

Superflous parameters not required by the snippet definition are silently ignored.

Expected, but missing parameters will just be replaced by an empty string, as this will often still render some useful text in most cases (only missing some the extra bits); the predefined snippet ask expects normally an extra nickname as parameter and renders like this if being used without that:

/s ask

> If you need support - describe your issue, giving some (more) details + version used: 19.x?, + DE: cinnamon, mate, xfce? - if anybody has an answer she/he will reply.
> Stay connected afterwards == do not ask and leave after 1 minute.

using : or --sel 'snippet'

As you will first struggle to know more rarely used snippet names, ot-snippet offers a feature where you just use : or --sel instead of a snippet name. This will show a dialog with a list of all currently available snippets, where you can select one to be used together with the additional given parameters (nickname).

In the sample one of the numerous libera channels ( li_android ) will be selected:

/s : guest7235

[display fullsize via mouse-click]

... and advertised to the given user:

guest7235> there exist android-related channels at libera.chat-irc (using hexchat: right-click onto link(s) and select 'Connect'):
guest7235> ircs://irc.libera.chat:6697/#android,#android-dev
guest7235> ircs://irc.libera.chat:6697/##java
guest7235> NOTE: at some more libera-channels, only registered users are able to write/ask or even join => read: https://libera.chat/guides/registration

As you might have noticed from the screen shot, instead of scrolling through the snippet list, you can start typing the start of a snippet name to jump to a likely matching entry automatically.

Use the OK button, double-click onto a snippet name or press the Enter key apply a current snippet.

Use the Cancel button, close the dialog window or press the ESC key to abort the dialog (without showing any text).

re-use previous nickname with '+'

Although additional snippet params $2..$n can be used for any purpose, you should stick with using $2 for nicknames to address users.

Most nicknames will differ well enough to use the typical IRC client feature to expand partial given nicknames, using the TAB key. But with some cases this requires more care/effort, like having several users at a channel named like guest* (due to behavior of some IRC servers to sanick certain users/nicknames) or having some more 'mibbit' users around.

So one has to type more than the otherwise only needed 2 to 3 letters and still might get returned an unexpected nickname due to possible collisions (IRC clients often track the activity of users to pick their suggestion based on last seen nicknames).

To address this, the last recently used $2 parameter (the potential nickname of a user) will be saved at ot-snippet*.nick

Calling ot-snippet again, using + as $2 parameter, will instruct ot-snippet to read the last stored nickname from that file and use it instead.

Thus one only has to use the correct nickname of an according user with a snippet once and is able to use + from that on instead of the nickname:

/s 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....

/s libera + wine

guest7235> there exists a specialized channel at libera.chat irc (using hexchat: right-click onto link(s) and select 'Connect'):
guest7235> ircs://irc.libera.chat:6697/#wine
guest7235> NOTE: at some more libera-channels, only registered users are able to write/ask or even join =< read: https://libera.chat/guides/registration

--list

--list or ? displays a list of available snippet keys.

The option greps snippet keys from its internal list, or from an existing custom file (which gets precedence). The option can help while doing larger edits or cleanup of outdated snippets.

To avoid flooding IRC by mistake, no output is returned via stdout but shown at a new terminal window.

[Vergrößern per Mausklick]

--show

--show or _ displays all current/available snippets expanded with dummy parameters [P1]..[P5]

The option greps and formats snippet definitions from its internal list, or from an existing custom file (which gets precedence).

The expanded dummy parametes are highlighted to make it easier to spot according placement within the snippet.

To avoid flooding IRC by mistake, no output is returned via stdout but shown at a new terminal window.

[Vergrößern per Mausklick]

--help

Showing the help page lists some details about your current setup at its header, which might be useful if you are using ot-snippet at some new environment. The remainder of the page gives some minmal help describing parameters, differences in param and stream mode, how to setup hexchat and weechat and a note about using custom files.

Note: you will notice at the sample below that the output contains resolved filenames like /home/demo/bin/ot-snippet-para which will just be different from your install == you will see your according files being named there.

/s --help

will show a new terminal window:

ot-snippet V. 002#199 2022-01-25 - usage (parameter-mode):
setup-info:
term   = /usr/bin/lxterminal  available - used 
	 version: lxterminal 0.4.0
zenity = /usr/bin/zenity available - used 
	 version: 3.41.0
log    = /home/demo/bin/ot-snippet-para.log 463 bytes = warnings/errors available
custom = /home/demo/bin/ot-snippet-para.txt not available - ignored

fixes-info:
dbind-warning : inactive - not used
zenity-38-bug : inactive - not used
log-filters   : active - used:
		GtkDialog mapped without a transient parent
		Allocating size to GtkDialog

usage (parameter-mode):
ot-snippet-002.sh <snippet-name> [additional-parameters]*| {:|--sel} [additional-parameters]* | {_|--show} | {?|--list} | --help | --new-custom

<snippet-name> = a snippet name as defined by /home/demo/bin/ot-snippet-para
                 or an optional /home/demo/bin/ot-snippet-para.txt file;
                 [additional-parameters]* is a list of white space delimited
                 words being placed at existing $1..$5 tags of the
                 snippet; missing (expected) parameters are replace by an
                 empty string.

: or --sel    = show a zenity dialog to select an existing snippet name
                this way instead giving it as parameter;
                using ESC key, clicking onto the Cancel-button or just
                closing the dialog aborts further processing
                using Return key , clicking onto the Ok-button or just
                double-click onto an existing entry uses the according
                snippet name for further processing.
                start typing a snippet name will jump and select to the
                next matching snippet name entry.
                [additional-parameters]* are expanded with the snippet
                like before.

_ or --show   = creates a new terminal window showing all available
                snippets expanded with dummy parameters [P1]..[P5];
                no output is returned via stdout (to avoid flooding IRC).

? or --list   = creates a new terminal window showing a list of all
                available snippet names;
                no output is returned via stdout (to avoid flooding IRC).

--help        = creates a new terminal window showing this help;
                no output is returned via stdout (to avoid flooding IRC).

--new-custom  = creates a new custom file and a terminal window
                showing details about the custom file (location);
                no output is returned via stdout (to avoid flooding IRC).

Although the plain parameter mode is still be usable, its deprecated and
should be avoided - prefer using the stream mode instead (just read on)...

usage (stream-mode):
ot-snippet-strm [--timeout=<seconds>]

--timeout     = <seconds> - define a different/longer timeout other than
                the default 2 seconds;
                is used to test ot-snippet-strm from a terminal, where the
                regular timeout would be too short to enter parameters via
                keyboard

In stream mode arguments are read from stdin and processed internally like
being given as command line arguments of the non-stream version (see above
for available options/parameters).

Using the stream version of ot-snippet avoids that nicknames containing
dangerous commands within backticks (allowed at (all?) irc networks) would
be evaluated by using the /exec command of irc-clients (which is typically
just a call to run the default shell with parameters).

To ensure ot-snippet wont hang waiting for missing input, a 2 seconds
timeout is used.

If no expected data would be written to stdin within the timeout, ot-snippet
will just terminate. As irc-clients often only allow to run a single
application using /exec and further calls would be blocked otherwise.

The predefined timeout can be adjusted using the command line parameter
--timeout=<seconds> giving a different timeout in seconds.
The timeout parameter is the only supported command line option in stream mode
and you will normally only use it to test changes from a terminal, where the
default timeout will just be too short to enter expected parameters in time.

To use ot-snippet in stream mode from irc clients requires to change the call:
1) Rename ot-snippet-002.sh to ot-snippet-strm (or setup an
accordingly named symbolic link pointing to it).
2) Adjust the exec-call of your irc-client to call ot-snippet-strm
and add a second call to stream the expected parameter-data to it.

For hexchat this requires 2 lines of an identically named user-command
- using s like snippet here:
s exec -o ot-snippet-strm
s execwrite &2

Note: there is a glitch with the current implementation of execwrite with
hexchat, which will echo used parameters to the textbuffer (only visible
for you, and not for the channel) - hope the maintainer will address the
according bug-report some time :-).


For weechat one can define an according alias this way:
/alias add s exec -o -name ots -stdin ot-snippet-strm; exec -in ots $1

3) To keep your edits of your previous V001 ot-snippet.sh version
(in case you edited ot-snippet.sh directly):
Run ot-snippet.sh --new-custom to create ot-snippet.txt.
Rename the file to ot-snippet-002-strm.txt - the file has to be located at
the same folder as your V002-copy of ot-snippet.
After being done you can run ot-snippet-strm --timeout=30
and enter --help to show the general help.
Scoll to the top of the page and check that your custom-file is being
used at the custom label of the  setup info section.


press Shift+PgUp to scroll back
press RETURN to close window