#$EPIC: perl_command.txt,v 1.3 2006/07/28 04:14:52 jnelson Exp $
======Synopsis:======
[[perl_command|perl]] {//perl statement//}

======Purpose:======
If EPIC was linked with an embedded perl interpreter, the //perl statement//
shall be executed by perl.  If EPIC was not linked against perl, then no
action shall take place.

Although every //perl statement// resolves to a (perl) scalar value, that
(perl) scalar value is discarded when you run it this way.

If the //perl statement// has an error, the result is undefined, but usually
an error message is output to the window.

Remember that the insides of {}s are protected from ircII expansion, so if
you want to pass ircII values into your perl script, you do best to export
the value to perl using the [[perl function]] first.  The insides of the {}
should be a literal segment of perl code.

You can call back to EPIC from perl:
|EPIC::cmd(string)  | Run "string" without $-expansion |
|EPIC::eval(string) | Run "string" with $-expansion |
|EPIC::expr(string) | Return value of epic expression "string" |
|EPIC::call(string) | Call an epic function: string must be of the form "name(args)". $* will expand to the empty string. |
|EPIC::yell(string) | Output something on the epic window. |

You are permitted to register perl END blocks.  They will run when epic
initiates shutdown procedures.

======Examples:======
<file>
	PERL { do script.pl }
Loads and runs script.pl.  See the perl documentation for the "do" function.

	PERL { use Time::localtime }
Loads the standard perl module Time::localtime.

	PERL {
		sub foo {
			reverse(wantarray ? @_ : "@_")
		}
	}
Defines a perl subroutine which returns the reverse of its input, whether 
it is called in scalar or list context.

	PERL {
		push @array, "value with $perlvar"
	}
Pushes a string containing a perl variable into a perl array.

	PERL \{
		push @array, "value with $epicvar"
	\}
Pushes a string containing an EPIC variable into a perl array.
DANGER -- be careful with [[quoting hell]].
</file>

======History:======
The [[perl command]] first appeared in EPIC5-0.3.1.