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: @@
+======Using the inbuilt embedded perl functions======
+Let me start out by saying that it is possible, and still advisable in
+most cases to use the [[exec command|EXEC]] command to do many of the things you want
+from an external scripting language. The external script will run as a
+separate process which will save you performance problems and memory.
+The reason you might want to use the $[[perl function|perl]]*()
+functions are in those situations where you need data to be returned
+from the perl script or if you need it to do something within the epic
+environment from that script. These mechanisms are faster and much more
+stable in these functions than trying to do the same thing with an
+/[[exec command|exec]].
+The perl environment can be used at many levels, from being a helper
+to your irc script to almost entirely driving your script from within
+perl. Most perl modules are available for use from within the perl
+environment, but those that don't return control to your script are
+unlikely to be useful. It is also makes it possible to alter epics
+process environment, such as redefining signals, forking and making
+other random system calls, which is not always a good idea.
+The embedded perl script starts with a call to $[[perl
+function|perl]](expression). When $[[perl function|perl]]() is called,
+the perl environment is initialized and the expression is evaluated.
+Typically what you want is an expression that loads a script or defines
+subroutines for use from your epic environment with the $[[perlcall]]()
+functions.
+At this point, the $[[perlcall]]() and $[[perlxcall]]() functions can be used
+to call whatever subroutines have been defined. $[[perlcall]](sub any text)
+calls the perl subroutine "sub" in scalar context with "any text" as its first
+argument. More complex calls involving Karll [[arrays]](7) are possible with
+$[[perlxcall]]().
+Three new subroutines are available from within the perl environment:
+EPIC::cmd evaluates its arguments as irc commands, returning nothing.
+EPIC::eval evaluates its arguments as if they were applied to /[[eval]],
+also returning nothing. EPIC::expr evaluates its arguments as epic
+[[expressions]](7), returning the results of those expressions.
+The exact difference between cmd and eval is that anything passed to
+eval is subject to Epics parsing rules while anything passed to cmd is
+not. This is not unlike the difference between single and double quoting
+in perl.
+You can use these to "drive" your script from perl, although, if you are
+going to do this with a long running script, it is highly recommended
+that you make calls to EPIC::eval("pause 1") liberally.
+You should not call the EPIC functions from within %SIG signal handlers
+other than $SIG{__WARN__} and $SIG{__DIE__}. Epics internals are likely
+to be unable to handle such behavior.
+From the perl environment, hooks, aliases and other miscellaneous
+settings can be changed via the EPIC functions:
+|EPIC::eval('on hook * @perlcall(sub $*)')  |Sets up a callback from a hook.        |
+|EPIC::eval('alias foo @perlcall(sub $*)')  |Defines an alias with a callback.      |
+|EPIC::eval('echo $foo')                    |Echoes the epic variable $foo.         |
+|EPIC::cmd ('echo $foo')                    |Echoes the text "$foo".                |
+|EPIC::cmd ("echo $foo")                    |Echoes the perl variable $foo.         |
+|EPIC::expr('var')                          |Returns value of variable var.         |
+|EPIC::expr('aliasctl(assign get var)')     |Also returns variable var.             |
+|EPIC::expr('myalias(x)')                   |Calls epic alias myalias().            |
+|EPIC::expr('jot(0 99)')                    |Calls epic function jot(0 99).         |
+|EPIC::expr('1+2*3')                        |How to use epic for math.              |
+|EPIC::expr('perl(EPIC::expr "1+2*3")')     |One last facetious example.  :-)       |
+To fully understand what is possible with EPIC::expr, you should read
+[[Expressions]](7). Briefly, you can retrieve anything from within the
+epic environment with it, and do many things as well. Exceptions to
+this are covered by EPIC::cmd and EPIC::eval, which execute commands,
+for which you should read [[Programming]](7).
+=====Miscellaneous things to be aware of:=====
+By default, perl warnings and errors will be yelled and are trapable
+with the on(5) yell hook or from perl with the $SIG{__DIE__} and
+$SIG{__WARN__} hooks. This is accomplished with EPIC::yell. This you can
+use for your own purposes, but it's better to use EPIC::cmd "echo ...".
+$[[perlcall]]() and $[[perlxcall]]() will return a zero length string if they
+are called while the perl environment is uninitialized or if the sub is
+undefined. You can use this from within an epic script to trigger an autoload
+of a perl subroutine for eg.
+In terms of performance, __perl*call__() are pretty damn fast, but the
+overhead of switching to perlspace takes an order of magnitude longer than
+making the same call from perlspace. To gain performance, you should avoid
+switching universes as much as possible. The EPIC::* functions all take and
+return lists. You will probably find that combining many calls into one makes
+them a lot faster.
+While it is possible to write a script almost entirely in perl, with calls to
+the EPIC functions, the script will need to be loaded with a call to
+$[[perl function|perl]]() from an epic script or with a command.
+The EPIC::* functions will execute within the context that called
+$[[perl function|perl]]*() so it is possible to manipulate epic variables local to that
+context.
+While perl is quite capable of assigning any string of characters to a
+variable, epic is not. Any perl string containing a null character will
+be silently truncated when it is assigned to an epic variable.
+Using perl for non-trivial networking is likely to be trickier than under pure
+perl. Not only does your code have to maintain its sockets, but it has to give
+epic enough cpu time to maintain its own. This can be done by including all of
+epics file descriptors in a perl select() call and calling EPIC::eval "pause 1"
+each time select returns one of them. There currently is no definitive way to
+obtain these descriptors, but they are included in some hooks such as [[on send
+to server|send_to_server]] and [[on dcc raw|dcc_raw]].
+Alternatives to the above are:
+  * Use epic for networking with the raw dcc interface.
+  * Use an external script to handle the request, via the exec interface.
+  * Keep your perl networking code short and sweet.
+"alias perl unless (functioncall()) {@perl($*)}" sets up a /[[perl
+command|PERL]] command. The arguments will be executed within the
+embedded perl environment. You may also want to use this alias for
+calling an external interpreter, which is why there is no inbuilt
+/[[perl command|PERL]] command. The choice is yours.