no way to compare when less than two revisions

Differences

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

@@ 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.