--- /dev/null
+body {
+ font-size: 10pt;
+ margin-left: 8px;
+ margin-right: 8px;
+ margin-top: 6px;
+ margin-bottom: 6px;
+ line-height: 24px;
+ font-family: sans-serif;
+}
+table, td, tr {
+ color: #3c3c3c;
+ font-size: 10pt;
+}
+td {
+ padding: 6px;
+}
+a:link {
+ text-decoration: none;
+ color: #2883e2;
+}
+a:visited {
+ text-decoration: none;
+ color: #6856cc;
+}
+a:hover {
+ text-decoration: underline;
+ color: #186CC4;
+}
+a:active {
+ text-decoration: underline;
+ color: #186CC4;
+}
+.title-table-cell {
+ border-top-left-radius: 3px;
+ border-top-right-radius: 3px;
+ background-color: #F2DFB1;
+}
+.title-text {
+ font-size: 18pt;
+ font-weight: bold;
+ padding-bottom: 3px;
+ color: #404040;
+ text-shadow: 0px 2px 0px rgba(247,247,247,1);
+}
+.title-secondary-text {
+ font-size: 11pt;
+ padding-top: 3px;
+ color: #474747;
+ text-shadow: 0px 2px 0px rgba(247,247,247,1);
+}
+.subtitle-table-cell {
+ background-color: #D6D6D6;
+}
+.subtitle-text {
+ font-size: 11pt;
+ color: #000000;
+ text-shadow: 0px 1px 0px rgba(247,247,247,1);
+}
+.subsubtitle-table-cell {
+ background-color: #E3E3E3;
+}
+.subsubtitle-text {
+ font-size: 10pt;
+ color: #474747;
+}
+.syntax-text {
+ font-family: monospace;
+ font-size: 10pt;
+ font-weight: bold;
+ white-space: pre;
+ color: #800000;
+}
+.note-box {
+ background-color: #F2F2F2;
+ color: #636363;
+ font-size: 9pt;
+}
+.example-box {
+ font-family: monospace;
+ font-size: 10pt;
+ white-space: pre;
+ background-color: #f5f5f5;
+ border: 1px solid #d5d5d5;
+ color: #800000;
+ margin-top: 6px;
+ margin-bottom: 6px;
+ line-height: 16px;
+ padding: 10px;
+}
+.example-box a:link {
+ color: #600030;
+}
+.example-box a:visited {
+ color: #600030;
+}
+.example-box a:hover {
+ color: #FF2B46;
+}
+.example-box a:active {
+ color: #FF2B46;
+}
+.comment-text {
+ color: #578A57;
+}
+.comment-text a:link {
+ color: #578A57;
+}
+.comment-text a:visited {
+ color: #578A57;
+}
+.comment-text a:hover {
+ color: #35BD58;
+}
+.comment-text a:active {
+ color: #35BD58;
+}
+.example-paren {
+ color: #8A7000;
+}
+.example-bracket {
+ color: #9C7914;
+}
+.example-oper {
+ color: #9C7914;
+}
+.example-variable {
+ color: #AB6332;
+}
+.comment-text .example-variable {
+ color: #578A57;
+}
+.comment-text .example-oper {
+ color: #578A57;
+}
+.comment-text .example-paren {
+ color: #578A57;
+}
+.comment-text .example-bracket {
+ color: #578A57;
+}
+.switch-table {
+ width: 100%;
+ border-collapse: collapse;
+}
+.switch-title-table-cell {
+ font-family:"Lucida Console", Monaco, "Courier New", monospace;
+ font-size: 10pt;
+ color: #670000;
+ background-color: #EDEDED;
+}
+.switch-body-table-cell {
+}
+.footer {
+ border-top: 1px solid #a2a2a2;
+ color: #a2a2a2;
+ margin-top: 8px;
+ padding-top: 4px;
+ font-style: italic;
+ font-size: 8pt;
+}
$g_currenttime=gmtime;
$g_currentuser = getlogin || getpwuid($<) || "Unknown";
-$g_notetablebgcolor="#F2F2F2";
-$g_notetextcolor="#636363";
$g_syntaxcolor="#802000";
$g_kvssyntaxcolor="#802000";
$g_filehandle="";
$g_shortsIdx{"keyterms"}=0;
$g_directory = "";
+$g_css = "";
#################################################################################################
# PARSE ARGS
}
$g_version = $ARGV[$i];
$i++;
+ } elsif($ARGV[$i] eq "--css")
+ {
+ $i++;
+ if($ARGV[$i] eq "")
+ {
+ usage();
+ die "Switch --css requires a parameter"
+ }
+ $g_css = $ARGV[$i];
+ $i++;
} else {
$cont = 0; # stop processing
}
{
print $g_filehandle "<html>\n";
print $g_filehandle "<head>\n";
+ print $g_filehandle "<meta http-equiv=\"Content-Type\" content=\"text/html; charset=UTF-8\" >\n";
print $g_filehandle "<title>$_[0]</title>\n";
-
print $g_filehandle "<style type=\"text/css\">\n";
- print $g_filehandle "body {\n";
- print $g_filehandle " font-size: 10pt;\n";
- print $g_filehandle " margin-left: 8px;\n";
- print $g_filehandle " margin-right: 8px;\n";
- print $g_filehandle " margin-top: 6px;\n";
- print $g_filehandle " margin-bottom: 6px;\n";
- print $g_filehandle " font-family:Verdana,Helvetica,Arial,sans-serif;\n";
- print $g_filehandle "}\n";
-
- print $g_filehandle "table, td, tr {\n";
- print $g_filehandle " color: #3c3c3c;\n";
- print $g_filehandle " font-size: 10pt;\n";
- print $g_filehandle "}\n";
-
- print $g_filehandle "td {\n";
- print $g_filehandle " padding: 6px;\n";
- print $g_filehandle "}\n";
-
- print $g_filehandle "a:link {\n";
- print $g_filehandle " text-decoration: none;\n";
- print $g_filehandle " color: #2883e2;\n";
- print $g_filehandle "}\n";
-
- print $g_filehandle "a:visited {\n";
- print $g_filehandle " text-decoration: none;\n";
- print $g_filehandle " color: #6856cc;\n";
- print $g_filehandle "}\n";
-
- print $g_filehandle "a:hover {\n";
- print $g_filehandle " text-decoration: underline;\n";
- print $g_filehandle " color: #186CC4;\n";
- print $g_filehandle "}\n";
-
- print $g_filehandle "a:active {\n";
- print $g_filehandle " text-decoration: underline;\n";
- print $g_filehandle " color: #186CC4;\n";
- print $g_filehandle "}\n";
-
- print $g_filehandle ".title-table-cell {\n";
- print $g_filehandle " border-top-left-radius: 3px;\n";
- print $g_filehandle " border-top-right-radius: 3px;\n";
- print $g_filehandle " background-color: #F2DFB1;\n";
- #print $g_filehandle " background: linear-gradient(#CBE4F2,#4E8ABF);\n";
- print $g_filehandle "}\n";
-
- print $g_filehandle ".title-text {\n";
- print $g_filehandle " font-size: 18pt;\n";
- print $g_filehandle " font-weight: bold;\n";
- print $g_filehandle " padding-bottom: 3px;\n";
- print $g_filehandle " color: #404040;\n";
- print $g_filehandle " text-shadow: 0px 2px 0px rgba(247,247,247,1);\n";
- print $g_filehandle "}\n";
-
- print $g_filehandle ".title-secondary-text {\n";
- print $g_filehandle " font-size: 11pt;\n";
- print $g_filehandle " padding-top: 3px;\n";
- print $g_filehandle " color: #474747;\n";
- print $g_filehandle " text-shadow: 0px 2px 0px rgba(247,247,247,1);\n";
- print $g_filehandle "}\n";
-
- print $g_filehandle ".subtitle-table-cell {\n";
- print $g_filehandle " background-color: #D6D6D6;\n";
- print $g_filehandle "}\n";
-
- print $g_filehandle ".subtitle-text {\n";
- print $g_filehandle " font-size: 11pt;\n";
- print $g_filehandle " color: #000000;\n";
- print $g_filehandle " text-shadow: 0px 1px 0px rgba(247,247,247,1);\n";
- print $g_filehandle "}\n";
-
- print $g_filehandle ".subsubtitle-table-cell {\n";
- print $g_filehandle " background-color: #E3E3E3;\n";
- print $g_filehandle "}\n";
-
- print $g_filehandle ".subsubtitle-text {\n";
- print $g_filehandle " font-size: 10pt;\n";
- print $g_filehandle " color: #474747;\n";
- print $g_filehandle "}\n";
-
- print $g_filehandle ".syntax-text {\n";
- print $g_filehandle " font-family:\"Lucida Console\", Monaco, \"Courier New\", monospace;\n";
- print $g_filehandle " font-size: 10pt;\n";
- print $g_filehandle " font-weight: bold;\n";
- print $g_filehandle " white-space: pre;\n";
- print $g_filehandle " color: #800000;\n";
- print $g_filehandle "}\n";
-
- print $g_filehandle ".example-box {\n";
- print $g_filehandle " font-family:\"Lucida Console\", Monaco, \"Courier New\", monospace;\n";
- print $g_filehandle " font-size: 10pt;\n";
- print $g_filehandle " white-space: pre;\n";
- print $g_filehandle " background-color: #f5f5f5;\n";
- print $g_filehandle " border: 1px solid #d5d5d5;\n";
- print $g_filehandle " color: #800000;\n";
- print $g_filehandle " padding: 10px;\n";
- print $g_filehandle " margin-top: 6px;\n";
- print $g_filehandle " margin-bottom: 6px;\n";
- print $g_filehandle "}\n";
-
- print $g_filehandle ".example-box a:link {\n";
- print $g_filehandle " color: #600030;\n";
- print $g_filehandle "}\n";
-
- print $g_filehandle ".example-box a:visited {\n";
- print $g_filehandle " color: #600030;\n";
- print $g_filehandle "}\n";
-
- print $g_filehandle ".example-box a:hover {\n";
- print $g_filehandle " color: #FF2B46;\n";
- print $g_filehandle "}\n";
-
- print $g_filehandle ".example-box a:active {\n";
- print $g_filehandle " color: #FF2B46;\n";
- print $g_filehandle "}\n";
-
- print $g_filehandle ".comment-text {\n";
- print $g_filehandle " color: #578A57;\n";
- print $g_filehandle "}\n";
-
- print $g_filehandle ".comment-text a:link {\n";
- print $g_filehandle " color: #578A57;\n";
- print $g_filehandle "}\n";
-
- print $g_filehandle ".comment-text a:visited {\n";
- print $g_filehandle " color: #578A57;\n";
- print $g_filehandle "}\n";
-
- print $g_filehandle ".comment-text a:hover {\n";
- print $g_filehandle " color: #35BD58;\n";
- print $g_filehandle "}\n";
-
- print $g_filehandle ".comment-text a:active {\n";
- print $g_filehandle " color: #35BD58;\n";
- print $g_filehandle "}\n";
-
- print $g_filehandle ".example-paren {\n";
- print $g_filehandle " color: #8A7000;\n";
- print $g_filehandle "}\n";
-
- print $g_filehandle ".example-bracket {\n";
- print $g_filehandle " color: #9C7914;\n";
- print $g_filehandle "}\n";
-
- print $g_filehandle ".example-oper {\n";
- print $g_filehandle " color: #9C7914;\n";
- print $g_filehandle "}\n";
-
- print $g_filehandle ".example-variable {\n";
- print $g_filehandle " color: #AB6332;\n";
- print $g_filehandle "}\n";
-
- print $g_filehandle ".comment-text .example-variable {\n";
- print $g_filehandle " color: #578A57;\n";
- print $g_filehandle "}\n";
-
- print $g_filehandle ".comment-text .example-oper {\n";
- print $g_filehandle " color: #578A57;\n";
- print $g_filehandle "}\n";
-
- print $g_filehandle ".comment-text .example-paren {\n";
- print $g_filehandle " color: #578A57;\n";
- print $g_filehandle "}\n";
-
- print $g_filehandle ".comment-text .example-bracket {\n";
- print $g_filehandle " color: #578A57;\n";
- print $g_filehandle "}\n";
-
- print $g_filehandle ".switch-table {\n";
- print $g_filehandle " width: 100%;\n";
- print $g_filehandle " border-collapse: collapse;\n";
- #print $g_filehandle " border: 1px solid #d5d5d5;\n";
- print $g_filehandle "}\n";
-
- print $g_filehandle ".switch-title-table-cell {\n";
- print $g_filehandle " font-family:\"Lucida Console\", Monaco, \"Courier New\", monospace;\n";
- print $g_filehandle " font-size: 10pt;\n";
- print $g_filehandle " color: #670000;\n";
- print $g_filehandle " background-color: #EDEDED;\n";
- print $g_filehandle "}\n";
-
- print $g_filehandle ".switch-body-table-cell {\n";
- #print $g_filehandle " background-color: #EDEDED;\n";
- print $g_filehandle "}\n";
-
- print $g_filehandle ".footer {\n";
- print $g_filehandle " border-top: 1px solid #a2a2a2;\n";
- print $g_filehandle " color: #a2a2a2;\n";
- print $g_filehandle " margin-top: 8px;\n";
- print $g_filehandle " padding-top: 4px;\n";
- print $g_filehandle " font-style: italic;\n";
- print $g_filehandle " font-size: 8pt;\n";
- print $g_filehandle "}\n";
+ if($g_css ne "")
+ {
+ open(INPUT, $g_css) or die "Error opening $g_css: $!";
+ while(<INPUT>)
+ {
+ chomp;
+ print $g_filehandle "$_ ";
+ }
+ close(INPUT);
+ }
print $g_filehandle "</style>\n";
- print $g_filehandle "<meta http-equiv=\"Content-Type\" content=\"text/html; charset=UTF-8\" >\n";
print $g_filehandle "</head>\n";
print $g_filehandle "<body bgcolor=\"$g_bodybgcolor\" text=\"$g_bodytextcolor\">\n";
$_[0] =~ s/\[\/tr\]/\<\/tr\>/g;
$_[0] =~ s/\[td\]/\<td\>/g;
$_[0] =~ s/\[\/td\]/\<\/td\>/g;
- $_[0] =~ s/\[example\][ \n]*/<div class="example-box">/g;
- $_[0] =~ s/\[\/example\]/<\/div>/g;
+ $_[0] =~ s/\[example\][ \n]*/\<\/td\>\<\/tr\>\<tr\>\<td class=\"example-box\"\>/g;
+ $_[0] =~ s/\[\/example\]/\<\/td\>\<\/tr\>\<tr\>\<td bgcolor=\"$g_bodytablebgcolor\"\>/g;
$_[0] =~ s/\[comment\]/<span class="comment-text">/g;
$_[0] =~ s/\[\/comment\]/<\/span>/g;
$_[0] =~ s/\[\/anchorlink\]/\<\/a\>/g;
$_[0] =~ s/\[anchor:([a-zA-Z0-9_]*)\]/\<a name=\"\1"\>/g;
$_[0] =~ s/\[\/anchor\]/\<\/a\>/g;
- $_[0] =~ s/\[note\][ \n]*/<p>\<table width=\"100%\"\ cellpadding=\"2\">\<tr\>\<td\ bgcolor=\"$g_notetablebgcolor\">\<font color=\"$g_notetextcolor\" size=\"-1\"\>/g;
- $_[0] =~ s/\[\/note\]/\<\/font\>\<\/td\>\<\/tr\>\<\/table\><\/p>/g;
+ $_[0] =~ s/\[note\][ \n]*/\<\/td\>\<\/tr\>\<tr\>\<td class=\"note-box\"\>/g;
+ $_[0] =~ s/\[\/note\]/\<\/td\>\<\/tr\>\<tr\>\<td bgcolor=\"$g_bodytablebgcolor\"\>/g;
}
add_custom_command(
OUTPUT ${USERDOCS_OUTPUT_FILE}
COMMENT "Generating user documentation..."
- COMMAND ${PERL_EXECUTABLE} ${PROJECT_SOURCE_DIR}/admin/gendoc.pl -v ${USERDOCS_VERSION} '${CMAKE_CURRENT_BINARY_DIR}/help/en/' ${PROJECT_SOURCE_DIR}/data/doctemplates/ ${PROJECT_SOURCE_DIR}/src/
+ COMMAND ${PERL_EXECUTABLE} ${PROJECT_SOURCE_DIR}/admin/gendoc.pl --css ${PROJECT_SOURCE_DIR}/admin/doc.css -v ${USERDOCS_VERSION} '${CMAKE_CURRENT_BINARY_DIR}/help/en/' ${PROJECT_SOURCE_DIR}/data/doctemplates/ ${PROJECT_SOURCE_DIR}/src/
)
if(APPLE)
install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/help/ DESTINATION ${CMAKE_INSTALL_PREFIX}/Contents/Resources/help)
add_custom_target(
docs
COMMENT "Generating user documentation..."
- COMMAND ${PERL_EXECUTABLE} ${PROJECT_SOURCE_DIR}/admin/gendoc.pl -v ${USERDOCS_VERSION} '${CMAKE_CURRENT_BINARY_DIR}/help/en/' ${PROJECT_SOURCE_DIR}/data/doctemplates/ ${PROJECT_SOURCE_DIR}/src/
+ COMMAND ${PERL_EXECUTABLE} ${PROJECT_SOURCE_DIR}/admin/gendoc.pl --css ${PROJECT_SOURCE_DIR}/admin/doc.css -v ${USERDOCS_VERSION} '${CMAKE_CURRENT_BINARY_DIR}/help/en/' ${PROJECT_SOURCE_DIR}/data/doctemplates/ ${PROJECT_SOURCE_DIR}/src/
)
elseif(WIN32)
add_custom_command(
OUTPUT ${USERDOCS_OUTPUT_FILE}
COMMENT "Generating user documentation..."
- COMMAND ${PERL_EXECUTABLE} ${PROJECT_SOURCE_DIR}/admin/gendoc.pl -v ${USERDOCS_VERSION} ${CMAKE_CURRENT_BINARY_DIR}/help/en/ ${PROJECT_SOURCE_DIR}/data/doctemplates/ ${PROJECT_SOURCE_DIR}/src/
+ COMMAND ${PERL_EXECUTABLE} ${PROJECT_SOURCE_DIR}/admin/gendoc.pl --css ${PROJECT_SOURCE_DIR}/admin/doc.css -v ${USERDOCS_VERSION} ${CMAKE_CURRENT_BINARY_DIR}/help/en/ ${PROJECT_SOURCE_DIR}/data/doctemplates/ ${PROJECT_SOURCE_DIR}/src/
)
install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/help/ DESTINATION ${CMAKE_INSTALL_PREFIX}/help)
add_custom_target(
docs
COMMENT "Generating user documentation..."
- COMMAND ${PERL_EXECUTABLE} ${PROJECT_SOURCE_DIR}/admin/gendoc.pl -v ${USERDOCS_VERSION} ${CMAKE_CURRENT_BINARY_DIR}/help/en/ ${PROJECT_SOURCE_DIR}/data/doctemplates/ ${PROJECT_SOURCE_DIR}/src/
+ COMMAND ${PERL_EXECUTABLE} ${PROJECT_SOURCE_DIR}/admin/gendoc.pl --css ${PROJECT_SOURCE_DIR}/admin/doc.css -v ${USERDOCS_VERSION} ${CMAKE_CURRENT_BINARY_DIR}/help/en/ ${PROJECT_SOURCE_DIR}/data/doctemplates/ ${PROJECT_SOURCE_DIR}/src/
)
endif()
@short:
KVS scripting language introduction
@body:
- [p]
[b]KVS[/b] is the [b]KV[/b]Irc [b]S[/b]cripting language.
It was inspired by C++, sh, Perl, PHP and mIRC scripting language implementations.
It is a compromise between flexibility and speed, a [i]workaround[/i] for many intrinsic
This two-stage approach has been introduced in version 3.0.0, the previous
versions of the language used a single-stage on-the-fly interpreter.
[br]
- KVS allows you to:[br]
+ KVS allows you to:
[ul]
[li]Implement automated reactions to the events generated by an IRC network[/li]
[li]Add new complex commands[/li]
[li]Add interface elements like popups, toolbars, buttons...[/li]
[li]Add advanced interface elements like complete dialogs or even widgets integrated in KVIrc[/li]
[/ul]
- [br]
KVS contains all the common constructs of structured programming.
You will find almost all the C control commands, sh/Perl-like variables, arrays and and functions.
There are also some object-oriented characteristics: you will find C++ like
KVS basic concepts
@body:
[big]Scripts[/big]
- [br]
You use KVS to implement [b]scripts[/b].
A script is basically a finite list of KVS instructions.
When you type a command in the KVIrc input window you in fact
the [i]PrincoScript[/i] or [i]dynamirc[/i] (tough this last one should be categorized as [i]malware[/i] instead).
In KVIrc such a collection of items is called [i]addon[/i], but be prepared
for both usages of the word in this documentation and around the web.[br]
- More about addons in this [doc:addons]document[/doc][br]
+ More about addons in this [doc:addons]document[/doc]
[big]Hello world![/big]
- [br]
This documentation contains a lot of script examples.
They will appear like the following block of code:
[example]
Another alternative for testing scripts is the code tester window.
You can access it by selecting [i]New code tester[/i] from the Scripting menu
at the top of the KVIrc window. You will soon have the opportunity to
- experiment with all the methods. Read on.[br]
+ experiment with all the methods. Read on.
[big]Basic syntax[/big]
- [br]
A script contains a list of instructions separated by newlines or ';' characters.
Placing an instruction per line does not require a terminating character,
placing more instructions in a single line require them to be separated by ';'.
also reflected in KVS).
Another interesting thing is that when you execute the script you
don't see the enclosing quotes around the printed text: more about this
- in the following sections.[br]
+ in the following sections.
[note]
- Cryptic note (you may skip it for now):[br]
- Yes, the command terminator is a problem for those that want to use ';)' at the end
- of IRC commands like [cmd]msg[/cmd]. It is almost unavoidable (read: the cost for
- avoiding it is too high). Note that using '|' or any other character as command terminator
- will [b]not[/b] solve the problem: if the terminator is too difficult to type it will annoy the
- scripters (and me), if it is too easy then there will be always someone that wants to use it
- at the end (or in the middle) of a command with the original meaning.
- The solution is to escape the [b];[/b] character:
+ Cryptic note (you may skip it for now):[br]
+ Yes, the command terminator is a problem for those that want to use ';)' at the end
+ of IRC commands like [cmd]msg[/cmd]. It is almost unavoidable (read: the cost for
+ avoiding it is too high). Note that using '|' or any other character as command terminator
+ will [b]not[/b] solve the problem: if the terminator is too difficult to type it will annoy the
+ scripters (and me), if it is too easy then there will be always someone that wants to use it
+ at the end (or in the middle) of a command with the original meaning.
+ The solution is to escape the [b];[/b] character:
[example]
[cmd]echo[/cmd] You can do it now \;)
[/example]
[/note]
- [br]
[big]Parameter processing[/big]
- [br]
Most of the commands accept (and sometimes require) a list of parameters.
For example, the [cmd]join[/cmd] command (that is used to join an IRC channel)
accepts two parameters: the first one is the channel to join and the second is
optional: if you specify it, then it will be interpreted as the channel password,
if you don't then no password will be used.
[note]
- The syntax is written in a simplified BNF. I say simplified because it is not
- totally strict around the KVIrc documentation. I just prefer the syntax to be
- clear and easy to read instead of being formally perfect.
+ The syntax is written in a simplified BNF. I say simplified because it is not
+ totally strict around the KVIrc documentation. I just prefer the syntax to be
+ clear and easy to read instead of being formally perfect.
[/note]
You can finally join a channel by writing:
[example]
[/example]
In the example above the optional parameter [password] is omitted.
[note]
- In fact it is not really omitted: KVIrc interprets it as an empty string that later
- means [i]do not send the password to the server[/i].
- Empty strings are equivalent to omitted ones.
- [/note][br]
+ In fact it is not really omitted: KVIrc interprets it as an empty string that later
+ means [i]do not send the password to the server[/i].
+ Empty strings are equivalent to omitted ones.
+ [/note]
[big]Parameters, spaces and quotes[/big]
- [br]
From the examples above is obvious that KVS command parameters are separated by spaces.
What is not totally obvious is that multiple spaces are allowed but KVIrc
will automatically reduce them to exactly one (just like HTML parsers or the shell
it is really easier to use than to explain.
There is obviously a method to preserve the quotes too and it is also another
method to preserve the spaces but that leads us to the next paragraph.
- [br]
[big]Escape character[/big]
- [br]
You may have already noticed that KVS treats some characters in a special way.
For example the double-quote characters can be used to enclose strings
and are stripped by the parser.
Later we will discover other common usages of the backslash escape, such
as preventing KVIrc from interpreting a literal percent character as a variable
or separating variable names from the text.
- [br]
[big]Command switches[/big]
- [br]
Many commands accept switch parameters.
[b]A switch modifies the behaviour of a command.[/b]
Any switch can optionally accept a parameter, that must
[example]
[cmd]echo[/cmd] "--- This text has three minus signs on the left"
[/example]
- [br]
[big]Command blocks[/big]
- [br]
Commands can be 'grouped' in blocks by using the classic C++ braces.
Here is a single line example:[br]
[example]
[cmd]echo[/cmd] Third command
[/example]
[note]
- Reminder: copy the example above to a text file
- and then use /[cmd]parse[/cmd] <filename>
+ Reminder: copy the example above to a text file
+ and then use /[cmd]parse[/cmd] <filename>
[/note]
In this case the command block has no special meaning
other than making the code more readable, but command blocks
will be useful later (see [cmd]if[/cmd],[cmd]while[/cmd]...).[br]
[note]
- Unlike in C or C++, the braces do [b]not[/b] automatically define a variable scope
- (with few exceptions to this rule ... just to complicate the things a bit more).
- You will recall this last assertion later, when reading about [doc:data_structures]data structures[/doc].
+ Unlike in C or C++, the braces do [b]not[/b] automatically define a variable scope
+ (with few exceptions to this rule ... just to complicate the things a bit more).
+ You will recall this last assertion later, when reading about [doc:data_structures]data structures[/doc].
[/note]
- [br]
[big]Comments[/big]
[p]
KVIrc supports comments in command sequences.[br]
A comment starts with the character '#' and terminates with a newline.
- You can start a comment anywhere a command can start.[br]
+ You can start a comment anywhere a command can start.
[example]
# This is a comment, it occupies the whole line
[cmd]echo[/cmd] After the comment!; # This is an end-line comment
A C++ comment starts with two slashes [b]//[/b] and terminates with a newline.
A multi-line C comment starts with [b]/ *[/b] and ends at the first [b]* /[/b] encountered.
Since KVIrc has no pre-processor, the C/C++ comments usually can't be placed in the middle of a command:
- they must start where a command would start and end before the begin of another command.[br]
- [br]
+ they must start where a command would start and end before the begin of another command.
[big]Indentation[/big]
- [br]
You [b]should[/b] use spaces or [b]tabs[/b] to [b]indent[/b] your code. Note that the [b]should[/b]
word is written in bold characters: I mean that you really should indent your code.
Indenting helps both you (the script writer) and the reader (any other user that will
read your script). A good indenting practice is the first step to become a great programmer :)
[note]
- Please note that the command parameters should be separated by
- space characters (ASCII 32). Tabs are not granted to work as parameter separators.[br]
+ Please note that the command parameters should be separated by
+ space characters (ASCII 32). Tabs are not granted to work as parameter separators.[br]
[/note]
[example]
{
KVS Functions and aliases
@body:
[big]Introduction[/big]
- [br]
Since you're here, you should already have read about the [doc:kvs_basicconcepts]KVS basic concepts[/doc]
and have visited the [doc:commands]command index[/doc]. If you feel ready to take the next step
then read on.
- [br]
- [big]Functions[/big][br]
- [br]
+ [big]Functions[/big]
KVS has many internal [doc]functions[/doc] that can be used as command parameters.[br]
- [b]All the function names start with a literal [b]$[/b] character.[/b][br]
+ [b]All the function names start with a literal [b]$[/b] character.[/b]
[example]
[cmd]echo[/cmd] This window caption is [fnc]$window.caption[/fnc]
[/example]
The [fnc]$window.caption[/fnc] [doc:functions]function[/doc]
is evaluated before the command executes,
- and it is changed into the current window caption text.[br]
- The [doc]functions[/doc] can be used also as switch parameters.[br]
+ and it is changed into the current window caption text.
+ The [doc]functions[/doc] can be used also as switch parameters.
[example]
[cmd]echo[/cmd] -w = [fnc]$window[/fnc] This text will be surely \
printed in the current window
with the restriction that the first character is not a digit.[br]
Some kind of functions can contain a dot ([b].[/b]) character inside the name
and these are assumed to be module references (see [doc:modules]the modules documentation[/doc]).[br]
- [br]
By now we have seen only simple functions, but there's more...[br]
The functions can accept parameters; the general syntax for a function call is:[br]
[b]$<function name>['('<parameter_list>')'][/b][br]
a string: in this case it can be also interpreted as a number.[br]
When passing an empty list you can avoid the parenthesis.
(And you have found the [i]simple[/i] functions shown above).
- So the following two calls are equal:[br]
+ So the following two calls are equal:
[example]
[cmd]echo[/cmd] [fnc]$window.caption[/fnc]
[cmd]echo[/cmd] [fnc]$window.caption()[/fnc]
[/example]
If you want to pass an [i]empty[/i] string as the first parameter you have to use
- the following syntax:[br]
+ the following syntax:
[example]
[cmd]echo[/cmd] [fnc]$str.len[/fnc]("")
[/example]
- Obviously a function is valid as a function parameter.[br]
+ Obviously a function is valid as a function parameter.
[example]
[cmd]echo[/cmd] [fnc]$str.len[/fnc]([fnc]$window.caption[/fnc])
[/example]
you must escape it.
A special case for when you want to use 'matching' parentheses:
an opened '(' corresponds to a closed ')'.
- In this case you can omit the 'escape' character.[br]
+ In this case you can omit the 'escape' character.
[example]
[cmd]echo[/cmd] The length of '(a+b)' is : [fnc]$str.len[/fnc]( (a+b) )
[/example]
This is useful for algebraic and boolean expressions, like the ones
- accepted by the special function $() (see next paragraphs).[br]
- [br]
- [big]Aliases[/big][br]
+ accepted by the special function $() (see next paragraphs).
+ [big]Aliases[/big]
An alias is a user defined command. It can be used to rename the builtin KVIrc commands or functions,
to automate complex tasks or as a means for structured programming.
Aliases can be created or destroyed by using the scriptcenter (graphic interface)
[example]
[cmd]alias[/cmd](kb){ [cmd]ban[/cmd] $0; [cmd]kick[/cmd] $0-; };
[/example]
- This adds the [b[]kb[/b] alias - it can be called as a normal command:
+ This adds the [b]kb[/b] alias - it can be called as a normal command:
[example]
kb spammer You're not welcome here!
[/example]
If return is not called inside an alias body, the return value will be set to [fnc]$null[/fnc].
[br]
Aliases can accept switches just like any other command. The [fnc]$sw[/fnc] is there
- exactly for that purpose. Check it out.[br]
+ exactly for that purpose. Check it out.
[big]Special functions[/big]
- [br]
We have already seen the positional parameter functions.
The functions of type [b]$N[-[M]][/b] (where N and M are positive
numbers starting from 0 and N < M) evaluate to the sequence of
- [b]positional parameters[/b] from Nth to Mth."[br]
+ [b]positional parameters[/b] from Nth to Mth.[br]
If M is omitted, the function evaluate to the sequence of [b]positional
parameters[/b] from Nth to the last one. If the whole -M block is omitted
the function evaluate to the Nth positional parameter.
We will discover more on the [b]positional parameters[/b] when talking
- of aliases and events.[br]
+ of aliases and events.
[example]
$0 evaluates to the 1st positional parameter
$0-4 evaluates to the parameters from first to 5th
The special function [b]$(<expression>)[/b], called the
[i][doc:expressioneval]Expression evaluation identifier[/doc][/i], returns the result
of the evaluation of the <expression>. In previous versions of KVIrc this
- function was called $calc().[br]
+ function was called $calc().
[example]
[cmd]echo[/cmd] $(2 + (3 ^ 7) <= 1 * (3 && 2))
[/example]
The special function [b]${<command sequence>}[/b] evaluates to the
return value of the <command sequence>.[br]
The special function [b]$$[/b] evaluates to the current object ID,
- but it is too early to explain it here...[br]
+ but it is too early to explain it here...
*/
/*
projects / irc / kvirc / KVIrc.git / commitdiff
