Codice: [ Link visibile solo agli utenti registrati ]
alias
Synopsis:
alias [ [-]<alias name> [<commands>] ]
Description:
alias is one of TekNap's most powerful user interfaces.
It allows the user to execute an arbitrary series of commands with one single command.
It actually serves a dual purpose. The primary usage is as described, a convenient mechanism for issuing multiple commands in succession.
It may also be used to define custom functions that can be used in conditional or assignment statements.
The real power of aliases comes from the fact that the client allows aliases to overload built-in commands (but not built-in functions).
Usage
Aliases are used just like normal commands (and functions). They may be called from the input line by prepending the command character (see cmdchars) to them, or may be used in a script. Likewise, scripted functions may be called using the normal $name( ) notation. Aliases have no functional differences between built-in commands and functions.
Syntax
Alias definitions with multiple commands may delimit the commands with semicolons, or the commands may span multiple lines if surrounded with curly braces. Users familiar with C/C++ or Perl programming will note numerous similarities in the command syntax. Like those languages, routines and functions are distinguished by whether the alias has a return value; functions do, routines don't. Aliases of both types may also accept arbitrary parameters, called expandos. They are used just like variables, and are numbered sequentially, starting with 0 (zero). Current aliases may be displayed by only giving the alias name in the command; all aliases matching the name are returned (such that "foo" might return aliases "foo" and "foobar"). If no alias name is given, all aliases are displayed. An alias may be removed by prepending its name with a hyphen (-). As mentioned previously, the client's builtin commands may be overloaded by aliases. This naturally poses a problem when one needs to use the real command, and needs to be sure it isn't some alias. The simple answer is to use the "//command" form. That is, the client will skip alias expansion for any command when it is preceded by the any command character twice. Other methods include stack, or avoiding command overloading in the first place.
Examples:
To create an alias that overloads a command, and calls it too:
alias lusers {
..echo ======= User Information for ${ [$*] ? [$*] : S}
..//lusers $* echo ======= End User Information
}
To create a function that returns the sum of two inputs:
alias sum {
..@ function_return = [$0] + [$1]
}
To create an alias that uses the new function:
alias showsum {
..echo *** The sum of $0 and $1 is $sum($0 $1)
}
An alternate way of definite the same alias:
alias showsum echo The sum of $0 and $1 is $sum($0 $1)
To use the new /showsum command to compute a sum:
/showsum 4 5
Using the alias as in the previous example will display the following:
*** The sum of 4 and 5 is 9
See Also:
assign
say
send
set cmdchars
stack
Restrictions:
As mentioned above, aliases can overload commands, but not functions. Alias names can consist of any character that isn't already a meta character for TekNap (the @ symbol, square brackets, curly braces, semi-colons, parenthesis, etc.). Note, however, that functions will not when the name contains certain characters. A good rule of thumb is to limit alias names to alphanumeric characters (and the underscore).
Bugs:
The exact syntax rules for alias structures (see assign for information about structures) is somewhat ambiguous. Structures can be represented as either name.sub or name[sub], but neither notation is guaranteed to work in all instances. Functions, for instance, do not work with the latter. This isn't necessarily a bug, but a feature of the syntax that may produce some unexpected results.
Other Notes:
Like C, whitespace in scripts is generally not significant (there are exceptions, such as with literal text to be echoed). An alias can literally be defined on one line, or on as many lines as desired. Code indentation is not required, though is done by convention, as with most structured languages. Braces in multiline aliases may be placed anywhere, as in C.
assign
Synopsis:
assign [ [-] <variable name> [<value>] ]
Description:
assign is the general-purpose interface for creating and manipulating variables. Just about any value can be assigned, whether it be a string or a number. Internally, TekNap treats the contents of all variables as strings, though it is smart enough to distinguish between strings and numerical values for mathematical purposes.
The rules for variable names are similar to those of the C language; they may consist of any letter, digit, or the underscore (_) character, and they must begin with a letter. Unlike C, variable names are not case-sensitive (nor are their contents, though they are case-preserving).
assign is primarily used for string assignments. It can be used for mathematical purposes as well, using the ${ } construct, but it can very quickly become awkward and cumbersome. Mathematical operations are better suited to the @ modifier (see Expressions).
Examples:
To assign a text string to the variable $foo:
assign foo this is some text string
To compute the sum of two integers:
assign foo ${4 + 5}
To delete a variable:
assign -foo
See Also:
Expressions
Special_Vars
alias
eval
set input_aliases
Other Notes:
The default behavior of the client is to not treat variables specially on the command line; they are passed as literal text. Variables normally are only expanded when used inside an alias. This naturally poses a problem for using assign with the ${ } construct from the input line. To force $ expansion on the input line, set input_aliases to on, or use eval. This is not a bug, it is a general feature of all commands.
break
Synopsis:
break
Description:
break, like its C counterpart, breaks out of a loop.
Examples:
@ loop = 0
while (0==0) {
/* endless loop? */
..@ loop++
..if (loop==20) break
}
/* loop only made 20 iterations */
See Also:
alias
continue
return
for
while, until
comment
Synopsis:
comment [<anything>]
Description:
This is exactly what it says, a comment. It does nothing. It is useful in scripts for explaining bits of code, adding disclaimers or copyright notices, etc.
There are also several symbolic comments. Both the # and : characters may be used to designate comments. There is no functional difference between any of them. Additionally, TekNap supports C /* */ multiline comments.
Examples:
These are some comments:
comment this was the first comment
# this is a newer comment
: this is a new comment too, but it isn't used much
/* this is an elite comment unique to TekNap */
See Also:
set comment_hack
Restrictions:
There is no restriction on where the closing '*/' may appear. Also, unlike C, a command may not begin before a comment, and end after it; the /* */ effectively acts like a line terminator.
Other Notes:
Executing an alias whose name begins with a '*' by calling it as '/*' will lose, as it will be interpreted as a comment. The solution here is to limit alias names to alphanumeric characters.
continue
Synopsis:
continue
Description:
continue skips certain loops. In a for( ) or while( ), continue will jump to the end of the current loop and continue to the next iteration.
Examples:
for (@ loop=0,loop<=10,@ loop++) {
..if (loop==4) continue
..echo $loop of 10, skipping 4.
}
See Also:
alias
break
return
for
while, until
do
Synopsis:
do <commands>
do { <commands> } [while (<condition>) ]
Description:
In its base form, do behaves much like eval. It evaluates its input once, then executes it. It is superior in some respects, however. For instance, it can cope with complex commands (multiple commands within curly braces). Furthermore, do has the ability to mimic the while command. While the operation is not identical, it is similar. It only differs in that the condition is evaluated after each loop iteration, so the loop is guaranteed to run for at least one iteration.
See Also:
To force expansion of some variable $foo:
/do echo the variable $$foo expands to $foo
To run the same command in indefinite number of times, but at least once:
assign blah 2
do {
..echo $blah is lower than 3
} while ( blah = rand(5) < 3 )
See Also:
eval
while
Other Notes:
This command is mostly supported for compatibility with irc clients. Internally, it uses more resources than eval, so it isn't of much practical use, save for its looping ability.
dump
Synopsis:
dump [all | alias | variables | on]
Description:
This purges all aliases, variables, and/or hooks in the client's current memory. This is useful if a script is not behaving as expected, letting the use dump everything and reload the script without restarting the client. It is also useful for dumping any scripts that the client loads automatically upon startup.
If no specific data type is specified, 'all' is used as the default.
Options:
alias purges all aliases in memory
variables purges all variables in memory
on purges all hooks in memory
all all of the above
Bugs:
The client will not return an error message if an invalid type is given. In fact, it will report that the given type was indeed dumped!
Other Notes:
This command does not affect the teknap.rc or any other file in any way. It only affects the client's current state.
echo
Synopsis:
echo [<anything>]
Description:
This command prints its arguments back to the screen. That's it. It is useful for printing status messages from inside scripts, or inside hooks for redefining server messages. The echo command is also the only command (one of two, actually; see xecho) that can write to the screen when display is off. echo now has no length limitation, it can display any string within the confines of memory.
See Also:
eval
set display
input_aliases
xecho
Other Notes:
echo will not normally expand variables unless it is used inside an alias. To force expansion, use eval or set input_aliases on. This is not a bug, it is an intentional feature common to all commands.
local
Synopsis:
local [ [-] <variable name> [,<variable name>] [<value>] ]
Description:
local creates "local" variables. Local variables are the same as assign variables, except they're primarily for inside one specific alias. Local variables cannot be removed. There are several reasons for this, which are mostly advantages for scripts. A local variable is specific to the alias it was defined in, causing less confusion with multiple variables in multiple aliases. They are less cpu-intensive, making them optimal for recursive functions like for. Arrays may also be defined with local.
Examples:
To give the local variable $blah a value of "this is a test":
local blah this is a test
To give both $blah and $foo a value:
local blah,foo local vars are neat
See Also:
Expressions
Special_Vars
alias
assign
eval
set input_aliases
exec
Synopsis:
exec [<shell commands>]
exec -direct <commands>
exec -name <name> <shell commands>
exec -out <process id | shell commands>
exec -msg <nickname | channel> <process id | shell commands>
exec -notice <nickname | channel> <process id | shell commands>
exec -in <process id> <text to send to process>
exec -window <process id | shell commands>
exec -<signal> <process id>
exec -close <process id>
Description:
exec allows you to spawn other processes from within your client, which are naturally treated as child processes. For example, if you wished to check your email without suspending your client (or quitting TekNap), you could simply exec your favorite mail program.
Processes can be given unique names, allowing them to be referred to more intuitively than trying to figure out its process id number. Processes can also accept any signal normally available through use of the Unix "kill" command (letting you kill, suspend, etc. any process that accepts such a signal). Process identifiers begin with a "%". Thus, a process named "mail" with pid 0 could be referred to as either "%mail" or "%0".
exec can take several different flags, each of which allow you to manipulate the subprocess in different ways. At the most basic level, the only argument you really need to give is the external program to run. If no arguments are given at all, a list of any currently running processes is returned.
When using the -out, -msg, or -notice flags, output can be sent to the target upon startup of the subprocess, or redirected to it after it's already running by using its process id.
Another flag of note, -close, can be used to shut down renegade subprocesses that simply won't go away (i.e. with their own quit command, with the kill signal, etc.). This actually just severs the link between the subprocess and the client, so it will die on its own the next time it tries to send data to the client.
Something to remember when worried about a shell processing arguments is the -direct flag, which executes the commands without spawning a shell. This can cut down on security risks, and save some memory.
Options:
-direct executes commands without spawning a shell
-name give the subprocess a logical name
-out send subprocess output to your current channel
-msg send subprocess output to a nick or channel with msg
-notice send subprocess output to a nick or channel with notice
-in send a text string to the specified subprocess
-window redirect subprocess output to another window
-<signal> send sig<signal> to the subprocess
-close forcibly kill the subprocess and its children
Examples (assume that the process used with these examples is the Unix mail program):
To start a process:
/exec mail
To start a process without a shell interfering:
/exec -direct mail
To start a process and give it a human-readable name:
/exec -name mail mail
To send the output of a new subprocess to your current channel:
/exec -out mail
To send the output of a running subprocess to JoeBob with a msg:
/exec -msg joebob %mail
To send the output of a new subprocess to #blah with a notice:
/exec -notice #blah mail
To send a text string (command) to a running subprocess:
/exec -in %mail ?
To send a running subprocess the kill signal:
/exec -kill %mail
To forcibly close down a stubborn subprocess that just won't die:
/exec -close %mail
Aliases:
When using exec with the -in flag, the functionality is identical to using msg to send a message to a process. See msg for more information.
See Also:
msg
set exec_protection
set notify_on_termination
set security
set shell
set shell_flags
set shell_limit
Restrictions:
Use of external programs from within TekNap can sometimes be dangerous if you don't know what you're doing. The danger doesn't necessarily lie in the external programs themselves, but rather in any lack of knowledge about them you may have. When all else fails, don't use a command if you don't know what it does. You can explicitly limit your ability to use exec in several ways.
Other Notes:
The available signals that may be sent to a process will vary from system
to system.
fe, fec
Synopsis:
fe (<list>) <variable> [<variable>...] {<actions>}
fec (<list>) <variable> [<variable>...] {<actions>}
Description:
fe is one of several loop types available in TekNap. This loop takes a list of items, and for each one, it performs the specified action.
It may act on more than one item at a time. The list may be a plain text list, a variable, a function, or any combination. As with aliases and other control structures, the braces surrounding the action may appear anywhere. List items are whitespace-delimited. Extended words (those with spaces in them) are honored when they are surrounded in double quotes (").
For instance, fe might be used to loop through a list of nicknames that the user wishes to invite to a channel (or kick from it!).
Any looping mechanism can run through a list one by one. The real power of fe is its ability to act on multiple list items at once. One could perform an action on 3 at a time, for instance, such as setting a +o channel mode on other users. Other loops, such as for, can do this as well, but fe offers a more elegant solution.
Examples:
A simple mode +o script to cluster mode changes 3 at a time:
fe ($friends) xx yy zz {
..if (zz) {
....mode #blah +ooo $xx $yy $zz
..} {
....if (yy) {
......mode #blah +oo $xx $yy
....} {
......mode +o $xx
....}
..}
}
A script to check for upper-case letters in a line of input:
@ caps = 0
fec ($*) xx {
..if (ascii($xx) >= 65 || ascii($xx) <= 90) {
....@ caps++
..}
}
echo *** Found $caps upper-case letters
Aliases:
fec works the same as fe, except it loops through each character in the list, not each word. Whitespace is only valid if it is between two other non-whitespace characters. Whitespace that follows the opening parenthesis, and that leads up to the closing one, is ignored.
See Also:
for
foreach
while, until
Other Notes:
The loop doesn't necessarily have to have an action inside the curly braces. It doesn't make much sense to omit it, though.
for
Synopsis:
for ([<pre>],[<condition>],[<post>]) {<action>}
Description:
for is a general purpose loop. It is modeled on the C for statement, and works in a very similar manner. Aside from the action, there are three parts to a for loop:
* The "pre" part is executed before the loop begins iterating. This is often used for initializing counters and other variables that will be used in the loop.
* Before each loop iteration, the "condition" is checked. Most often, this is used to see if the counter has exceeded a certain limit. The condition may contain any expression legal in the if command. Because of this, the loop does not necessarily have to iterate at all.
* The "post" part is executed after the condition, if the condition returns true. This is generally used to increment a counter that gets checked by the condition statement.
Multiple commands may be used in each part; they must be separated by semicolons (giving it something of a reverse-C syntax). Note that there does not necessarily need to be any commands in any part. The action is optional as well.
Examples:
To display a warning message 3 times:
for (@ xx = 3, xx > 0, @ xx--) {
..echo WARNING! This ship will self destruct in $xx seconds!
}
A infinite loop that behaves like the Unix 'yes' command:
for ( ,, ) {
..echo yes
}
See Also:
fe, fec
foreach
while, until
foreach
Synopsis:
foreach [-] <structure> <variable> {<action>}
Description:
The foreach command is a loop type that iterates through the items in a variable (or alias, see below) structure. This is often useful for purging an entire structure, or for searching through it for a certain piece of data.
Variables in the action field are normally not expanded until actual execution of the action. They can be forced to expand early by quoting the opening curly brace with a backslash: \{
If a hyphen (-) is prepended to the structure name, the foreach loop will try to iterate through an alias structure instead of a variable structure. This is primarily useful for purging alias structures.
Examples:
Simple usage of foreach, assuming $blah is a structure two levels deep:
foreach blah xx {
..foreach blah.${xx} yy {
....echo $blah[$xx] [$yy]
..}
}
To purge an alias structure called booya:
foreach -booya xx {
..alias -booya[$xx]
}
See Also:
fe, fec
while, until
Restrictions:
Structures may be referenced as either $var.${subvar}.${subvar} or $var [$subvar] [$subvar] (with any number structure levels, of course). The notation $var.$subvar.$subvar parses as $var [${subvar.$subvar}], which of course is incorrect, and should not be used.
Other Notes:
The action portion does not necessarily need to do anything, though there isn't much point in using the command without it.
if, unless
Synopsis:
if (<condition>) <then>
if (<condition>) { <then> } [{ <else> }]
if (<condition>) { <else> } elsif (<condition>) { <then> } else { <then> }
Description:
if is the general purpose control statement for testing the truth/false value of a given condition. If the condition is true, it performs some action; if false, some alternate action. The condition does not necessarily need to be a numeric comparison. It may be a function whose return value is evaluated for truth or falsity, or compared against some other value (which might also be a function return value). Expressions are generally of the following forms:
( exp ) tests for existence of exp (usually a variable)
( !exp ) tests for non-existence of exp
( exp1 == exp2 ) tests whether exp1 equals exp2
( exp1 != exp2 ) tests whether exp1 does not equal exp2
( exp1 && exp2 ) tests for existence of exp1 and exp2
( exp1 || exp2 ) tests for existence of exp1 or exp2 or both
( exp1 ^^ exp2 ) tests for existence of exp1 or exp2, not both
( exp1 < exp2 ) tests whether exp1 is less than exp2
( exp1 > exp2 ) tests whether exp1 is more than exp2
( exp1 <= exp2 ) tests whether exp1 is less than or equal to exp2
( exp1 >= exp2 ) tests whether exp1 is more than or equal to exp2
The "else" portion of an if statement is not required. Additionally, if the "then" portion is only a single statement, the curly braces are not required either. The expression (exp) is evaluated as though it were within a ${ } construct, such that
if ( blah ) ...
would expand "blah" to $blah, then test the value of $blah. Variables can also be placed inside the expression parser, such that
if ( [$blah] ) ...
is equivalent to the previous statement (though it isn't as efficient). Both forms may be combined in the same expression. Numbers are treated as constants, so in order to expand numeric expandos, such as $0, you must use the expression parser, as above. Strings must also be passed through the expression parser (otherwise they are interpreted as variables), and are compared case-insensitively. As in C, assignment operators may be used inside if statements. This is generally not recommended, if only because it can make the code rather confusing, but there are times when it can prove to be useful. The following:
if ( foo = 3 > bar ) ...
would first set the value of $foo to 3, and then compare it with $bar. Note that the @ operator is not needed (and in fact is not even allowed). Gratuitous use of parenthesis is recommended with this notation. Finally, as with other TekNap control statements, the curly braces may be placed anywhere.
Examples:
The following two statements are functionally equivalent:
if ( foo == bar ) echo foo and bar are the same
if ( foo == bar ) {
..echo foo and bar are the same
}
These are also equivalent:
if ( !foo ) ...
unless ( foo ) ...
Braces are required for a multi-line then portion:
if ( foo == bar ) {
..echo foo and bar are the same
..echo that's so cool!
}
Like other control statements, ifs may be embedded:
if ( foo ) {
..if ( bar ) {
....echo foo and bar are the same echo that's so cool!
..}
}
Function return values can be evaluated too:
if ( rmatch(foobar *blah* *bar) ) {
..echo it matched
}
Aliases:
unless is the exact opposite of if. It is essentially the same applying the negation operator (!) to the entire if condition.
Other Notes:
The "then" and "else" portions aren't required to contain anything. Use of the negation operator and unless obsolete this practice, however.
input, input_char
Synopsis:
input "<prompt>" <command> [<arguments>]
input_char "<prompt" <command> [<arguments>]
Description:
This command is primarily for use inside scripts. It allows the client to present the user with a visible prompt for specific commands. This can be used for interactive commands, for command confirmation, etc. Multiple commands may be specified if surrounded with curly braces. The variant input_char words the same as input, except it only takes a single character. The primary difference is that it does not require that a carriage return be entered before executing the command; the first keystroke will trigger it.
Options:
-noecho stops the echoing of characters as they are typed
Examples:
To let a command ask for confirmation:
input "Are you REALLY sure you want to do this? (y/n) " {
..if ( [$0] == [y] ) exec rm -rf *
}
The basis for a simple paging mechanism:
input_char "Press 'q' to quit, any other key to continue: " {
..unless ( [$0] == [q] ) {
..../* do whatever */
..}
}
Aliases:
These commands are functionally equivalent to the $"..." expando. In truth, they supersedes $"...".
See Also:
Special_Vars
input, input_char
Synopsis:
input "<prompt>" <command> [<arguments>]
input_char "<prompt" <command> [<arguments>]
Description:
This command is primarily for use inside scripts. It allows the client to present the user with a visible prompt for specific commands. This can be used for interactive commands, for command confirmation, etc. Multiple commands may be specified if surrounded with curly braces. The variant input_char words the same as input, except it only takes a single character. The primary difference is that it does not require that a carriage return be entered before executing the command; the first keystroke will trigger it.
Options:
-noecho stops the echoing of characters as they are typed
Examples:
To let a command ask for confirmation:
input "Are you REALLY sure you want to do this? (y/n) " {
..if ( [$0] == [y] ) exec rm -rf *
}
The basis for a simple paging mechanism:
input_char "Press 'q' to quit, any other key to continue: " {
..unless ( [$0] == [q] ) {
..../* do whatever */
..}
}
Aliases:
These commands are functionally equivalent to the $"..." expando. In truth, they supersedes $"...".
See Also:
Special_Vars
load
Synopsis:
load [-args] <file> [<file> ...]
Description:
load allows for commands contained in external files to be executed. This has the obvious use of setting up aliases and hooks without having to type each one in individually. The .teknaprc file, for example, it automatically loaded when the client is started (assuming the -q switch isn't used). When attempting to load a script, the client will first search the directories in the load_path for the desired file. The client will also accept an absolute pathname. The syntax of an TekNap script file is rather relaxed. It mostly resembles C code, aesthetically. As with C, whitespace is usually not significant, except in literal text. Curly braces used for complex commands may be placed anywhere. As with the input line, commands issued directly in a loaded script are, by default, not evaluated. This means that aliases and functions will not be expanded, and semicolons are not honored. This can be overridden script-wide with the -args switch, or by turning the input_aliases setting on inside the script. eval should be used if only select lines need to be evaluated.
Options:
-args This switch causes the script to be loaded with input_aliases turned on. In addition, commands may use the special numeric expandos ($*, $2, etc.), which will expand to the arguments passed to load.
See Also:
cd
set input_aliases
set load_path
stub
which
local
Synopsis:
local [ [-] <variable name> [,<variable name>] [<value>] ]
Description:
local creates "local" variables. Local variables are the same as assign variables, except they're primarily for inside one specific alias. Local variables cannot be removed. There are several reasons for this, which are mostly advantages for scripts. A local variable is specific to the alias it was defined in, causing less confusion with multiple variables in multiple aliases. They are less cpu-intensive, making them optimal for recursive functions like for. Arrays may also be defined with local.
Examples:
To give the local variable $blah a value of "this is a test":
local blah this is a test
To give both $blah and $foo a value:
local blah,foo local vars are neat
See Also:
Expressions
Special_Vars
alias
assign
eval
set input_aliases
parsekey
Synopsis:
parsekey <key function>
Description:
This command allows direct access to the functions normally bound to special keys via the bind command. It is useful for using rarely-used key functions that are not bound to a particular key. Any of the functions that may be bound to a key may be used.
See Also:
bind
pause
Synopsis:
pause [<time>]
Description:
This command will pause the client until a key is pressed. Or if a time period is specified then the client will pause until that time has passed.
Examples:
/pause
/pause 4
See Also:
sleep
usleep
purge
Synopsis:
purge [<alias>] <alias>
Description:
This command will remove the specified aliases from the clients memory.
Examples:
/purge flood flood1
See Also:
dump
push, pop
Synopsis:
push <variable name> <word>
pop <variable name>
Description:
push appends the given word (or words) to the given variable, padded with a single space. The variable name itself may not contain a leading '$'; the command uses the variable itself, not the expanded contents. If the variable does not exist, it is created containing the given word(s) (just as if assign were used).
Aliases:
pop is the exact opposite of push, in that it pops off the last word in the variable. If there is only one word in the variable, the variable is deleted. Both push and pop are functionally equivalent to the $push() and $pop() functions, respectively.
See Also:
assign
shift, unshift
setenv
Synopsis:
setenv
Description:
setenv sets the environment variable for TekNap's current process and all processes /exec'd under it. It isn't extremely useful, but is provided for completeness.
See Also:
assign
Environment
Expressions
return
Synopsis:
return [<arguments>]
Description:
return ends processing of a block such as an alias, scripted function, or an on hook, optionally giving it a return value.
Examples:
alias square return ${ [$0]*[$0] }
eval echo $square(5) /* returns 25 */
See Also:
alias
break
continue
for
while, until
save
Synopsis:
save [<options>] [<filename>]
Description:
save is used to record the client's current configuration to an external file; if none is specified, the ~/.TekNap/TekNap.sav is used, or the name of the file specified on the command line. The command does not save some information.
Examples:
To save everything:
/save
See Also:
Command_Line_Args
load
stub
send
Synopsis:
send <text>
Description:
This command provides a convenient mechanism for scripts, aliases, key bindings, etc. to send a line of text to the current channel or query. It is also useful for chatting while command_mode is off. Other than the ability to send a message to a query, send is identical to say.
See Also:
msg
say
set command_mode
sendline
Synopsis:
sendline
Description:
sendline sends a line of text to the client exactly as it is typed. It is similar to type (and thus xtype), except that it does not actually display the text on the input line as it is sent. The primary use of sendline is inside the input hook, which grabs the current input to the client before it is actually parsed or sent to a server. sendline can be used as a preprocessor of sorts. Extreme caution is recommended with this practice, as an improper input hook can effectively render the client unusable.
See Also:
on input
set input_protection
type
xtype setenv
Synopsis:
setenv
Description:
setenv sets the environment variable for TekNap's current process and all processes /exec'd under it. It isn't extremely useful, but is provided for completeness.
See Also:
assign
Environment
Expressions
shift, unshift
Synopsis:
unshift <variable name> <word>
shift <variable name>
Description:
unshift prepends the given word (or words) to the given variable, padded with a single space. The variable name itself may not contain a leading '$'; the command uses the variable itself, not the expanded contents. If the variable does not exist, it is created containing the given word(s) (just as if assign were used).
Aliases:
shift is the exact opposite of unshift, in that it chops off the first word in the variable. If there is only one word in the variable, the variable is deleted. Both unshift and shift are functionally equivalent to the $unshift() and $shift() functions, respectively.
See Also:
assign
pop, push sleep, pause
Synopsis:
sleep <seconds>
pause <seconds>
Description:
This suspends the client for the specified number of seconds. During this time, the client does absolutely nothing; it quite literally goes to sleep. In general, it is most useful in non-interactive automated scripts, and even these cases are fairly rare. The only external difference between sleep and pause is that sleep blocks. The client stops everything until it is done sleeping. pause, however, only pauses execution of the current code block. This allows the client to stop processing an alias temporarily without locking the whole client up. There are other commands more suited to the tasks that sleep is often used for. To wait a specified period of time before executing a command, use timer. To wait indefinitely for a command or server query to complete, use wait.
See Also:
timer
wait
usleep
stack
Synopsis:
stack push | pop | list alias | assign | on | set [<item>]
Description:
stack is a convenient mechanism for storing current aliases, variables, and hooks in a stack. New aliases, variables, or hooks with the same names or scopes can be created without disturbing the stacked ones. Those that are stacked can be restored at any time (clobbering any current settings in favor of the saved ones). There are three commands currently available to stack. The first, push, pushes an item onto a stack bearing its name. The second, pop, removes the most recent pushed item off its stack. The last, list, shows the contents of the named stack.
Examples:
To push the current who hook onto the stack:
stack push on who
To pop the most recently pushed $foo variable off its stack:
stack pop assign foo
To list the current alias stack:
stack list alias
See Also:
alias
assign
on
Bugs:
stack list works, but not quite as one would expect. Instead of listing each individual alias, variable, or hook separately, all are clumped together. Their order is correct, but the output may be confusing.
stub
Synopsis:
stub alias | assign <alias/var> [,<alias/var>] <filename> [<filename> ...]
Description:
The stub command allows for a sort of dynamic script loading. Any alias or variable name may be associated with a file; that alias or variable effectively becomes a stub for that file, a placeholder. When that alias/variable is accessed, the file is loaded. Stubs are always cleared when the alias or variable associated with them is accessed. That is, calling the variable again will not reload the same file. Stubs are also cleared any time a stubbed file is loaded. The file that is loaded does not necessarily need to contain to redefine the alias or variable associated with it. Finally, Stubs may load more than one file at a time.
Examples:
To load the file foobar.nap when the /foo command is issued:
stub alias foo foobar.nap
To load footoo.nap when $foo and $bar are accessed:
stub assign foo,bar foonap.irc
See Also:
alias
assign
load
Other Notes:
stub is not a memory management tool. Its purpose is to minimize the client's overhead at it initially starts up. Files that are loaded with stub are not automatically unloaded later.
switch
Synopsis:
switch (<control text>) { (<switch>) {<body>} }
Description:
switch is similar to C's switch statement. It allows for multiple alternatives to a given "control" statement where more than two possible values exist. It is functionally similar to if except it doesn't require excessive nesting for multiple alternatives.
Whitespace is not significant any any part of switch. Braces may appear anywhere, and multiple switches may appear on the same line or on individual lines. No logic takes place inside the switch, only string comparisons. For this reason, the expression parser is not needed (nor allowed), as everything is assumed to be a string, and variables are expanded.
Examples:
A simple switch that checks the value of an arbitrary input:
switch ($0) {
..(foo) {
....<do action for "foo">
..}
..(bar) (blah) {
....<do action for "bar" or "blah">
..}
..(*) {
....<do action for everything else>
..}
}
See Also:
if
fe, fec
timer
Synopsis:
timer [-refnum <num | name> ] [-repeat <times>] <seconds> [<action>]
timer -delete [all] | [<num | name>]
Description:
This command allows the client to store arbitrary commands scheduled for execution at some specified number of seconds in the future. Any number of timers may be set, and any number of commands may be used in a timer. Timers with multiple commands must have those commands surrounded by curly braces.
All timers are assigned a reference number to distinguish them from each other. A specific reference number may be specified, though the number may not be one that is already in use, and it must be either a non-negative integer or a string of no more than 10 characters (longer strings will be silently truncated). The reference number or name is also used to delete a timer. Using the timer command with no arguments will display the list of pending timers. When used with -repeat, the timer will only expire after running through number of times.
Options:
-delete <num> | all delete the numbered timer, or all timers
-list same as using no arguments; lists all timers
-refnum <num | name> set a timer with the given reference number or name
-repeat cycle through the timer times before expiring
-update re-assign the timer with new values
-window specifies in which window the timer should go off
Examples:
To create a reminder that X Files will be on in 10 minutes:
timer 600 {
..beep echo *** X Files is on!
..echo *** Why are you still on napster?!
}
To assign a specific refnum to that timer:
timer -ref 103 600 { ... }
timer -ref foo 600 { ... }
This timer's reference name will be truncated to "foobarbooy":
timer -ref foobarbooya 45 { ... }
To delete all pending timers:
timer -d all
Other Notes:
TekNap attempts to keep track of which server and window each timer was started from. Each timer will be reverted back to that window and server when it expires.
type
Synopsis:
type <keystroke>
Description:
type is used to simulate user keystrokes. The arguments given to it are literally "typed" out in the input line, as though the user had typed them in. Variables and bound keys are usually expanded, so xtype must be used to force literal display of the keys.
Examples:
This will type out a "template" for the kick command that allows a user to be kicked with a normal reason, plus a generic message appended to the kick reason (where ^[ is the ESC key; ^[b moves the cursor back by one word):
type /kick FooScript C1996^[b^[b
See Also:
xtype
if, unless
Synopsis:
if (<condition>) <then>
if (<condition>) { <then> } [{ <else> }]
if (<condition>) { <else> } elsif (<condition>) { <then> } else { <then> }
Description:
if is the general purpose control statement for testing the truth/false value of a given condition. If the condition is true, it performs some action; if false, some alternate action. The condition does not necessarily need to be a numeric comparison. It may be a function whose return value is evaluated for truth or falsity, or compared against some other value (which might also be a function return value). Expressions are generally of the following forms:
( exp ) tests for existence of exp (usually a variable)
( !exp ) tests for non-existence of exp
( exp1 == exp2 ) tests whether exp1 equals exp2
( exp1 != exp2 ) tests whether exp1 does not equal exp2
( exp1 && exp2 ) tests for existence of exp1 and exp2
( exp1 || exp2 ) tests for existence of exp1 or exp2 or both
( exp1 ^^ exp2 ) tests for existence of exp1 or exp2, not both
( exp1 < exp2 ) tests whether exp1 is less than exp2
( exp1 > exp2 ) tests whether exp1 is more than exp2
( exp1 <= exp2 ) tests whether exp1 is less than or equal to exp2
( exp1 >= exp2 ) tests whether exp1 is more than or equal to exp2
The "else" portion of an if statement is not required. Additionally, if the "then" portion is only a single statement, the curly braces are not required either. The expression (exp) is evaluated as though it were within a ${ } construct, such that
if ( blah ) ...
would expand "blah" to $blah, then test the value of $blah. Variables can also be placed inside the expression parser, such that
if ( [$blah] ) ...
is equivalent to the previous statement (though it isn't as efficient). Both forms may be combined in the same expression. Numbers are treated as constants, so in order to expand numeric expandos, such as $0, you must use the expression parser, as above. Strings must also be passed through the expression parser (otherwise they are interpreted as variables), and are compared case-insensitively. As in C, assignment operators may be used inside if statements. This is generally not recommended, if only because it can make the code rather confusing, but there are times when it can prove to be useful. The following:
if ( foo = 3 > bar ) ...
would first set the value of $foo to 3, and then compare it with $bar. Note that the @ operator is not needed (and in fact is not even allowed). Gratuitous use of parenthesis is recommended with this notation. Finally, as with other TekNap control statements, the curly braces may be placed anywhere.
Examples:
The following two statements are functionally equivalent:
if ( foo == bar ) echo foo and bar are the same
if ( foo == bar ) {
..echo foo and bar are the same
}
These are also equivalent:
if ( !foo ) ...
unless ( foo ) ...
Braces are required for a multi-line then portion:
if ( foo == bar ) {
..echo foo and bar are the same
..echo that's so cool!
}
Like other control statements, ifs may be embedded:
if ( foo ) {
..if ( bar ) {
....echo foo and bar are the same echo that's so cool!
..}
}
Function return values can be evaluated too:
if ( rmatch(foobar *blah* *bar) ) {
..echo it matched
}
Aliases:
unless is the exact opposite of if. It is essentially the same applying the negation operator (!) to the entire if condition.
Other Notes:
The "then" and "else" portions aren't required to contain anything. Use of the negation operator and unless obsolete this practice, however.
shift, unshift
Synopsis:
unshift <variable name> <word>
shift <variable name>
Description:
unshift prepends the given word (or words) to the given variable, padded with a single space. The variable name itself may not contain a leading '$'; the command uses the variable itself, not the expanded contents. If the variable does not exist, it is created containing the given word(s) (just as if assign were used).
Aliases:
shift is the exact opposite of unshift, in that it chops off the first word in the variable. If there is only one word in the variable, the variable is deleted. Both unshift and shift are functionally equivalent to the $unshift() and $shift() functions, respectively.
See Also:
assign
pop, usleep
Synopsis:
usleep
Description:
This suspends the client for the specified number of microseconds. During this time, the client does absolutely nothing; it quite literally goes to sleep. In general, it is most useful in non-interactive automated scripts, and even these cases are fairly rare.
See Also:
sleep
pause
timer
wait
push
wait
Synopsis:
wait [for] [%<process>] | [-cmd <command>]
Description:
wait is a convenient means for executing a series of commands and ensuring that those commands are run in the desired sequence. The command can make the client wait for the completion of server or subprocess output. The simplest form is wait with no arguments. When run after a server query, the client will not execute further commands (within an alias; does not apply to the input line) until all server output has been received. If used as /wait for, it will execute the command, and halt until a server reply is detected. When waiting on an execed subprocess, the client will block until the subprocess has completed. This effectively disables the the entire client (and can even cause it to ping timeout from the server). The last form allows for a series of commands to be executed in no particular order. This is most useful when a particular command needs to be issued, but subsequent commands don't rely on its contents or timing.
Options:
-cmd execute the given commands at the end of the alias
Examples:
To add a header and footer to a channel's ban list:
alias banlist {
..echo *** Begin ban list for #blah (generated $stime($time()))
..mode #blah +b
..wait
..echo *** End ban list for #blah
}
To run a subprocess, and wait before doing anything else:
alias localusers {
..echo *** Getting list of local users...
..exec -name who who
..wait %who
..echo *** Finished subshell `who' listing
}
The second command will actually finish before the first:
alias backwards {
..wait -cmd echo this appears last
..cho this appears first
}
Other Notes:
If multiple waits are pending at once, they will all return once the last one is completed, to ensure that no data is lost. Using wait for server queries is useful. However, there are often times then it is not the most efficient way to do something. When possible, hooking server numerics that marks the end of a message is preferred, as it is generally more reliable. Using wait or wait for and /redirect is a Bad Thing(tm), so don't do it.
while, until
Synopsis:
while (<condition>) <action>
while (<condition) [{ <action> }]
Description:
The while loop is a sort of hybrid between the for loop and the if control statement. It allows for repetitive action, as with for, but the loop iterates (performs the action) only if a specific condition is met, as with if. The "condition" portion may contain any comparison or assignment allowed in an if statement.
Examples:
To display a warning message 3 times:
@ xx = 3
while ( xx > 0 ) {
..echo WARNING! This ship will self destruct in $xx seconds!
..@ xx--
}
A infinite loop that behaves like the Unix 'yes' command:
while ( 1 ) echo yes
Aliases:
until is the exact opposite of while. It is essentially the same applying the negation operator (!) to the entire while condition.
See Also:
fe, fec
for
foreach
Other Notes:
while has all of the capabilities of for, only in a different syntax. The distinction between the two is not great enough to warrant a recommendation of one over the other. If anything, for tends to be more concise than while; however, this is not always the case.
xecho
Synopsis:
xecho [<switch> [<arg>] [<switch> [<arg>] ...] ] [--] <text>
Description:
xecho works just like echo, except that it may also accept certain switches to give more control over where the text is send. Currently, text can be sent explicitly to the current window, to any arbitrary window, and can be set to only be displayed in windows with a certain level set.
Options:
-banner display the $banner in front of the text
-current send text to current window
-level only echo text if target window has specified level
-raw send raw text to the screen, no formatting whatsoever
-window send text to specified window (name or number)
-nolog do not allow the text to be logged
-say do not output text if called as ^xecho
-- literal; disabled argument parsing for all text to the right of the double hyphens
Examples:
To echo text to the current window:
xecho -c This text will appear in the current window
To send only crap and server notices to a window called misc:
xecho -l snotice,crap -w misc This appears in the misc window
To change the titlebar of an xterm:
eval xecho -r $chr(27)]2\;Your titlebar has been changed.$chr(7)
To output text beginning with a hyphen:
xecho -- -= This text is treated literal =-
outputs:
-= This text is treated literal =-
See Also:
echo
set level
window level
xtype
Synopsis:
xtype [-literal] <type>
Description:
xtype works just like type, except that it may also take certain switches. Currently, there is only one switch for xtype.
Options:
-literal do not expand key bindings
Examples:
To literally insert a control-a instead of having its meaning expanded:
xtype -l now inserting a ^A is easy!
See Also:
bind
type
:: me l'ha passata Dede ieri..ho accorpato tutti i files htm e li ho riportati qui pronti per la stampa ;-) ::
