Site Tools


perlcall
no way to compare when less than two revisions

Differences

This shows you the differences between two versions of the page.


perlcall [2007/03/02 02:32] (current) – created - external edit 127.0.0.1
Line 1: Line 1:
 +# $EPIC: perlcall.txt,v 1.3 2007/03/02 02:32:04 jnelson Exp $
 +======Synopsis:======
 +$__perlcall__(<subroutine> [<text>])
 +
 +======Technical:======
 +The <subroutine> argument is a [[what is a word|dword]] 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.
 +   * The subroutine is called in scalar context and the scalar value of the return value of the subroutine is returned.
 +
 +The [[perlxcall]] function gives you much more control.
 +
 +======Practical:======
 +These functions are much faster and less dangerous than the [[perl]]
 +function 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 the [[perl]] function 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 the [[perl]] function 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]].  See
 +                      [[Arrays]]
 +</file>
 +
 +You could then [[msg]] or [[notice]] 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.
  
perlcall.txt · Last modified: 2007/03/02 02:32 by 127.0.0.1