/ 
libsirc-0.03
River stage zero No dependents
/ Sirc::Util

NAME

Sirc::Util - Utility sirc functions

SYNOPSIS

# sirc functions
use Sirc::Util ':sirc';
# overrides:
timer $delay, $code_string_or_ref, [$reference];

# user messages
arg_count_error $name, $want, [@arg];
tell_error $msg;
tell_question $msg;
xtell $msg;

# miscellaneous
eval_this $code, [@arg];
eval_verbose $name, code$, [@arg];
have_ops $channel;
have_ops_q $channel;
ieq $a, $b;
optional_channel;
plausible_channel $channel;
plausible_nick $nick;
xgetarg;
xrestrict;

# /settables
settable name, $var_ref, $validate_ref;
settable_boolean $name, $var_ref;
settable_int $name, $var_ref, [$validate_ref];

# hooks
add_hook_type $name;
add_hook $name, $code;
run_hook $name, [@arg];

DESCRIPTION

This module provides a bunch of utility functions for sirc.

It also allows you to import from it all of the standard sirc API functions, so that you can more simply write your script as a module.

Nothing is exported by default.

STANDARD SIRC FUNCTIONS

You can import the standard SIRC API functions individually or, using the tag :sirc, as a group. The available functions are:

  • accept addcmd addhelp addhook addset connect deltimer describe docommand doset dosplat dostatus eq getarg getuserline getuserpass listen load me msg newfh notice print remhook remsel resolve say sl tell timer userhost yetonearg

Some of these are actually enhanced versions of the routines that sirc provides, see below for information about them.

STANDARD MESSAGE FORMS

These functions provide for a few standard message forms which are shown to the user via main::tell().

arg_count_error name, want, [arg...]

This prints an error appropriate to an incorrect number of arguments. name is the name of the invoking sub, want is how many arguments were desired and the remaining arg arguments are the arguments which were actually received.

tell_error msg

This formats msg as an error message and passes it to main::tell. It's appropriate for errors caused by the system or an invalid invocation of your code.

tell_question msg

This formats msg as an error message for something the user did wrong. The message is passed to main::tell.

xtell msg

This is just main::tell "*** $msg".

MISCELLANEOUS FUNCTIONS

These are some functions which don't fall nicely into groups like those following do.

eval_this code, [arg...]

This evals code with arg as arguments. The code can be either a code reference or a string. In either case the args will be available in @_. The return value is whatever the code returns. $@ will be set if an exception was raised.

eval_verbose name, code, [arg...]

This is like eval_this except that if an exception is raised it is passed along to tell_error (with a message indicating it's from name).

have_ops channel

This function returns true if you have ops on the specified channel. If you don't have ops it prints an error message and returns false.

have_ops_q channel

This is like have_ops except that no message is printed, it just returns true or false depending on whether you have ops on the specified channel.

ieq $a, $b

This sub returns true if its two args are the same, ignoring case.

optional_channel

This sub examines $::args to see if the first word in it looks like a channel. If it doesn't then $::talkchannel is inserted there. If there was no channel present and you're not on a channel then an error message is printed and false is returned, otherwise true is returned.

Here's a replacement for /names which runs /names for your current channel if you don't provide any args.

    sub main::cmd_names {
	optional_channel or return;
	docommand "/names $::args";
    }
    addcmd 'names';
plausible_channel channel

This returns true if channel is syntactically valid as a channel name.

plausible_nick nick

This returns true if nick is syntactically valid as a nick name. Originally I used the RFC 1459 definition here, but that turns out to be no longer valid. I don't know what definition modern IRC servers are using. This sub allows characters in the range [!-~].

timer @args

This is an enhanced version of sirc's timer(). It allows you to use a code reference as the code arg.

xgetarg

This is like main::getarg, but it returns the new argument (in addition to setting $::newarg).

xrestrict

This just returns $::restrict.

/SET COMMANDS

These commands provide a simplified interface to adding /set variables.

settable name, var-ref, validate-ref

This sub adds a user-settable option. name is its name, var-ref is a reference to the place it will be stored, and validate-ref is a reference to code to validate and save new values. The code will be called as $rvalidate-($rvar, $name, $value)>. $name will be in upper case. The code needs to set both $$rvar and $::set{$name}. (The values in %set are user-visible.)

settable_boolean name, var-ref

This adds a /settable boolean called name. var-ref is a reference to the scalar which will store the value.

settable_int name, var-ref, [validate-ref]

This function adds a /settable integer called name var-ref is a reference to the scalar which will store the value.

validate-ref, if provided, will be called to validate the a new value is legal. It will receive both the name and the new value as arguments. Before it is called the new value will have been vetted for number-hood. It should return a boolean to indicate whether the value is okay.

HOOKS

Sirc::Util provides functionality for creating, adding code to and running hooks.

add_hook_type name

This creates a new hook called name.

add_hook name, code

Add code to the name hook. The name must already have been created with add_hook_type(). The code can be either a string or a code reference.

run_hook name, [arg...]

Run the name hook, passing the args to each hook member via @_.

AVAILABILITY

Check CPAN or http://www.argon.org/~roderick/ for the latest version.

AUTHOR

Roderick Schertler <roderick@argon.org>

SEE ALSO

sirc(1), perl(1), Sirc::Chantrack(3pm).