Site Tools


perlcall

Differences

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

Link to this comparison view

perlcall [2007/03/02 02:32] (current)
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 (external edit)