EPIC
Enhanced
Programmable
IRC-II
Client

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
# $EPIC: perlxcall.txt,v 1.5 2007/03/02 02:32:04 jnelson Exp $
======Synopsis:======
$__perlcall__(<subroutine> [<text>]) \\
$__perlxcall__(<subroutine> [<array-in> [<array-out> [<index> [<text>]]]])

======Technical:======
The <subroutine>, <array-in>, and <array-out> arguments are 
[[what is a word|dwords]] which is different from most function arguments.

These functions call a given subroutine in the embedded perl
interpreter and return the subroutines return value.

   * <subroutine> is the name of a subroutine in perlspace to call.
   * If <text> is given, it forms the first argument to the sub.
   * If <array-in> is given, the entire contents of the named Karll Array are additional arguments, one item per argument.
   * If <array-out> is given, it will be taken as:
        * A cue to call the given subroutine in array context instead of scalar context. Read on..
        * The name of a Karll Array into which the returned list will be dumped.
   * If <index> is given, it is the position in <array-out> at which the returned list will be added.
        * The default value is 0.
        * Negative values refer backwards from the end of the Karll Array. -1 will append to the list, -3 overwrites the last two values, etc.
        * If you actually want $__perlxcall__() to make the call in array context, then you must make sure that <index> is valid for <array-in>.
             * It is valid if $[[setitem]](6) would succeed with <array-in> and <item> (or the ones compliment of <item>) as arguments.
             * Values of 0 and -1 are always valid.
   * If <array-out> and <index> are valid, the perl sub will be called in array context, the returned array will be dumped into <array-out> starting at <index> and the number of elements in the array will be returned.
   * Otherwise, it will be called in scalar context and the scalar value of the value returned will be returned.
   * <array-out> may be lengthened to accommodate extra return values, but it will never be shortened.
   * <array-in> and <array-out> may refer to the same array.

That was the excruciatingly correct way to describe these functions.
The following description of $__perlcall__() may be better.

$__perlcall__() calls the sub in scalar context with one argument,
text, or no arguments, if no text is present, returning the scalar
value (perl term) of the value the sub returns.

======Practical:======
These functions are much faster and less dangerous than $[[perl
function|perl]](6) since the perl interpreter does not have to parse
and/or compile the input. The downside is that you have to define or
load the subroutine with a call to $[[perl function|perl]](6) before
they can be used.

$__perlxcall__() is useful as a prime mover of data between the perl
and epic environments, and in situations where one line of code has
too many or too few consequences to handle at once. In reality, it is
unlikely that you will ever need to make use of all the arguments.

You can't use these functions to call primitive perl functions.

======Returns:======
Nothing will be returned if the perl interpreter hasn't been started
with a call to $[[perl function|perl]](6) or if an error occurred.
Otherwise, the returned scalar (in scalar context), or the number of
items added to the specified array (in list context) are returned.

If the perl sub returns an array when it should return a sub, that
is, if it ignored wantarray, the number of items in the array will be
returned, and the array will be discarded.

======Examples:======
Assume the following (somewhat dangerous) perl sub has been defined:

<file>
# Execute all arguments as shell commands, returning one output line
# per call in scalar context, or all at once in array context. Since
# a local @return always overshadows a global one in perl, you can
# call this sub in any sequence and it will still work as described.
sub system {
    local @return if wantarray;   # @return is global otherwise.
    for (@_) {push @return,`$_`}  # Execute all arguments.
    return wantarray ? @return : shift @return ;
}
</file>

Then, the following will work thusly:

<file>
$perlcall(system ls)  Returns the first line of ls output.
                      Repeated calls will add more data to the
                      return list, but won't be returned until the
                      output from the first one is emptied out.
$perlcall(system)     Returns the next line of ls output.  No
                      commands are actually run.
@delarray(in)         You want to be careful..  :-)
$perlxcall(system in out -1 ls)
                      Dumps the output to out all at once.  out
                      is now a running log of the shell commands.
                      Repeated calls will add to this log.  These
                      can be accessed with __getitem__(6).  See
                      [[Arrays]](7)
</file>

You could then [[msg]](1) or [[notice]](1) somebody with the output of these
functions at a leisurely rate which will not get you flooded off the server.

Of course, you should never ever ever call this particular sub with
text received from the network. There are better ways to do these
things too, so you probably shouldn't have it defined, however, this
does serve as a useful example.