\chapter{Runtime Evaluation \& Error Trapping\label{chap:eval}}

\section{Warnings and Exceptions}

Man is fallible. So are the programs written. In the course of compilation and execution of a program various kinds
of diagnostic messages are generated. You have for sure encountered a lot of these in your 
learning process. This chapter deals mainly with errors and error handling. Before proceeding
to the rest of the text, it is discreet for us to establish a common terminology first. \\

We may classify an error by the time at which it occurs. They can be either \term{compilation errors} or \term{runtime errors}.
When a Perl source file is being compiled, \term{syntax errors} are being discovered as part of
the parsing process. Every language follows a certain set of syntax, which governs how different parts
of the language can be put together. Syntax errors are thus compilation errors. When a compilation error
occurs, the compilation process will be terminated. 
Errors are also generated when a source file is being executed. We collectively refer to them as runtime
errors. For example, division by zero is a runtime error. \\

We may also classify an error by its severity. Some errors are severe enough that the program should
not be allowed to continue. In Perl manpages, this is customarily called \term{fatal exceptions}. 
For example, division by zero is a fatal exception. 
There are also some kinds of diagnostic messages that are generated, but will not terminate the program. They are called \term{warnings}. 
For example, trying to \mono{print()} the value of an undefined variable if the \mono{-w} switch is in effect
results in a warning. Generation of warnings may not be fatal for your program, but they usually signify
there may be some subtle logical errors in your program. You should try to find out why they occur and
try to eliminate them, or at least you have to ensure that these warnings are expected. \\

Note that all errors and warnings are customarily redirected to the standard error, which is the 
screen by default unless you redirect it to somewhere else, as indicated in Chapter~\ref{chap:files}.
For CGI scripts, these messages are usually recorded in Web server log files that you can examine
to help locate sources of errors. \\

% carp, die, warn ...
\section{Error-Related Functions}

Perl provides you with two builtin functions to generate fatal exceptions and warnings, namely \mono{die()}
and \mono{warn()} respectively. Both of them accept one parameter which is usually the message associated
with the exception or warning. If multiple arguments are given, they are simply concatenated to form a single
error message. If the error message is not terminated with
the newline character, the file name and line number are appended. This is to make debugging easier. \\

Usually you use \mono{die()} to signal occurrences of fatal errors in the sense that the program in question 
should not be allowed to continue. For example, I mentioned in Chapter~\ref{chap:files} that you should check
the return value of \mono{open()} to see if file open is successful before proceeding to other file operations.
Perl programmers customarily do this by a statement like \\

\begin{verbatim}
open FILE, "<file.txt" or die "Cannot open file: $!\n";
\end{verbatim}

It uses the short-circuiting behaviour of the \mono{or} operator. Only if \mono{open()} fails and returns
an \mono{undef} value that \mono{die()} is called. \mono{\$!} is a predefined variable that returns the 
error message returned by the system on the error. Because failure of \mono{open()} does not constitute
a fatal error, for some programs it may be deemed necessary or appropriate to manually terminate it (however, most
sophisticated programs prefer to handle the error and skip the relevant parts of the program instead of abruptly
halting it). The \mono{die()} function serves this purpose. \\

The \mono{warn()} function generates a warning instead of a fatal exception. It merely outputs the message
to the standard error and does not terminate the program. \\

%The \mono{Carp} module contains some functions that are based on \mono{die()} and \mono{warn()} that provide 
%you with some additional goodies. You have to \mono{use()} it before you can use the functions defined. \\

% TODO: carp, confess, croak, cluck, ...

%It is not an object-oriented module.

\section{\mono{eval}}

Consider one day you are asked to
write a command-line application that allows users to input a mathematical expression and the program
will then calculate the result and display it to the user. This seems like an easy task, but it isn't.
You may still manage it if you impose restrictions to allow only simple expressions like \mono{3 + 4} 
and \mono{4 * 6}. But what if the expression is immensely complex? The program has to parse the 
expression. The expression is also checked for syntax errors and evaluated according to the operator
precedence. Parsing a complicated expression is not an easy task without specialized knowledge in
compiler construction. It turns out that you may construct a Perl statement at runtime and evaluate 
it on-the-fly. Therefore, what you need to do is to have the user specify the expression according 
to Perl syntax, and you simply invoke the function \mono{eval()} to evaluate it. This is very 
convenient because Perl checks the syntax and evaluate it for you, so you don't have to. \\

The program can thus be as simple as this: \\

\begin{lstlisting}[backgroundcolor=\color{CodeBackground}]
# WARNING: GRAVE SECURITY HOLE!!!
print "Please enter the expression below:\n";
chomp(my $expr = <STDIN>);
my $result = eval($expr);
print "The return value is $result.\n";
\end{lstlisting}

\mono{eval()} accepts a string as its argument which is parsed as a Perl program. In the above 
example, if the user enters \\

\begin{verbatim}
3*(4+5)
\end{verbatim}

then this is evaluated, so the evaluated result, 27, is returned and assigned to \mono{\$result}.
Note that you may put multiple statements in the argument to \mono{eval()}, delimited by \mono{;}, 
to evaluate multiple statements in one go. The final \mono{;} may be omitted, as illustrated in the
example. \\

In this form, both parsing and evaluation occur at runtime, because the code to be evaluated
are not available until at runtime. \mono{eval} has another form. Instead of passing to it a 
string containing the code, a code block is passed embracing the code (note the final semicolon 
after the code block!). This form is different from the above form in that because 
the code itself is static, it can be parsed at compile time. Therefore, you cannot dynamically
construct a Perl program and evaluate it with this form. For example, \\

\begin{verbatimtab}[4]
eval {
	$result = $a / $b; 
};
\end{verbatimtab}

Then you may wonder what is the use of the second form if the statement(s) inside an \mono{eval\{\}}
block are parsed statically just as if the \mono{eval\{\}} is not in effect. In fact, both forms of
\mono{eval} may be used for error trapping. In the first form, syntax errors as well as 
runtime errors occurred when evaluating the code will be trapped. The error message is sent to the predefined variable \mono{\$@},
and \mono{eval()} returns with the value \mono{undef}. In the second form, compile-time errors
cannot be trapped so they are still displayed and compilation is halted. Runtime errors will be
trapped and redirected to \mono{\$@} similar to the first form. \\ 

Although the first form of \mono{eval()} is very convenient because it can evaluate a string as if
it is a tiny Perl program, it is also highly dangerous if it is cleverly abused. You will see why
shortly after we cover backticks, an equally powerful and dangerous tool. \\

\section{Backticks and \mono{system()}}

You may execute operating system commands in Perl as if you are on the command line of your operating system.
The \mono{system()} function accepts a list of strings as parameters. The first argument is the name of program,
followed by the arguments. For example, \\

\begin{verbatim}
system('notepad.exe', 'myfile.pl');
\end{verbatim}

On a Windows system, this executes the Windows Notepad and opens the file myfile.pl. The \mono{system()}
function doesn't return until the program terminates. \\

Backticks \mono{` `} are more flexible as it simulates the command line. What you need to do is to construct
the command and enclose it in backticks instead of single or double quotes. In US keyboards, the backtick 
is located underneath the Escape key, sharing the key with the tilde ($\sim$). An example is \\

\begin{verbatimtab}[4]
$output = `ls -l`;		# get long directory listing
\end{verbatimtab}

Text that are sent to the standard output are collected and assigned to \mono{\$output}. \\

\section{Why Runtime Evaluation Should Be Restricted}
% Why eval() should be avoided
While \mono{eval()} is an immensely powerful tool for programmers, it is also one of the most dangerous weapon
frequently taken advantage by abusers to crack the system. Sometimes it may even be possible to launch 
catastrophic attacks. When combined with backticks, this is even more dangerous. Consider this example,
which we used to evaluate mathematical expressions on-the-fly: \\

\begin{lstlisting}[backgroundcolor=\color{CodeBackground}]
# WARNING: GRAVE SECURITY HOLE!!!
print "Please enter the expression below:\n";
chomp(my $expr = <STDIN>);
my $result = eval($expr);
print "The return value is $result.\n";
\end{lstlisting}

What an attacker has to enter is \mono{`rm -fR /`}, which is the Unix command for deleting everything in
the root directory. If this script is executed by root, the hard disk will be wiped spick-and-span in a
few minutes; Otherwise, at least the home directory of the user running the program will be deleted. On
Windows, passing a \mono{rmdir} command is equally devastating. Therefore, as you can see, \mono{eval()}
poses a significant security threat if improperly used. \\

\section{Next Generation Exception Handling}

\subsection{Basic Ideas}

While \mono{eval\{\}} is the traditional method of exception handling in Perl, it suffers some
grave drawbacks. The major drawback is that with a deep call stack and the exception is caught
at a deep level, you usually have to put the error message as the return value and \mono{return()}
it multiple times as you exit from each level in order to notify the error to a caller at the
outermost level. Having to always manually check the return value of \mono{eval\{\}} is not 
convenient at all. \\

If you have used certain languages like Java and C++ you may know that exception handling in those
languages are performed differently. The mechanism is called a try/catch.
While the Perl language does not officially support this exception handling mechanism, some wise people
managed to write a Perl module that satisfactorily implemented a similar mechanism from mere Perl code.
The module is on the CPAN, with the name \mono{Error}. The latest version as of this writing is
0.15. It is not in the Perl distribution so you have to install it as described in Appendix~\ref{chap:cpan}.
It is a pure Perl module, so you may easily distribute it with your Perl program if you
use it in your program. 
It is also expected that this exception handling mechanism, possibly with slight adjustments, 
will be officially included in the Perl 6 language. This will not come in the near future, though.
For your convenience, I have bundled the \mono{Error.pm} module together with my code examples. \\

%This module captures exceptions, not warnings. \\ 

As of this writing, the documentation of the latest version of \mono{Error.pm} can be found at
\link{http://search.cpan.org/author/UARUN/Error-0.15/Error.pm}{http://search.cpan.org/author/UARUN/Error-0.15/Error.pm}. \\

To use this module, simply \mono{use()} the module and import the symbol \mono{:try}, i.e. \\

\begin{verbatim}
use Error ':try';
\end{verbatim}

I hereby start my discussion with the \mono{try \{\}} block. Similar to \mono{eval \{\}}, the
code inside the curly braces are executed. In fact, 
internally, \mono{try\{\}} uses \mono{eval\{\}} to handle the exceptions. Therefore, it is compatible with
\mono{eval\{\}}. Let us see how we may use \mono{try \{\}} in place of \mono{eval \{\}} for the following 
simple case: \\

\begin{verbatimtab}[4]
my $retval = eval {
	open FILE, "<file.dat" or die "file.dat cannot be opened: $!";
	while (<FILE>) {
		# Do something 
	}
	close FILE;
};
if (!defined $retval) {
	print "ERROR: $@\n";
}
\end{verbatimtab}

We may transform it into the try/catch way by: \\

\begin{verbatimtab}[4]
use Error ':try';

try {
	open FILE, "<file.dat" or die "file.dat cannot be opened: $!";
	while (<FILE>) {
		# Do something
	}
	close FILE;
} catch Error::Simple with {
	my $err = shift;
	print "ERROR: $err";
};
\end{verbatimtab}

Here, the \mono{try} block is evaluated, and if the file \mono{file.dat} cannot be found, the \mono{die()}
function raises a fatal exception. \mono{try} is actually a subroutine defined in the \mono{Error} package.
When the exception is raised, an error object of class \mono{Error::Simple} will be automatically created
to represent the error. This is known as \term{throwing} the error. \\

After an exception is thrown,
blocks after the \mono{try} block are checked sequentially to search for a \term{handler} to \term{catch} the 
exception. After the \mono{try} block you may place some handlers to handle any exceptions raised. A \mono{catch} 
block is a handler which handles only a certain class of error. In the example above, the only \mono{catch}
block handles only error objects whose class is or inherits \mono{Error::Simple}. Because the error object generated by
\mono{die()} in the \mono{try} block belongs to this class, this handler is executed. The error message is \mono{print}ed
as a result. \textbf{\textit{Note that you have to place a semicolon after the block of the last handler.}} This semicolon
marks the end of the entire try/catch structure. Execution resumes afterwards. \\

What if a matching handler cannot be found in the current environment? The exception is passed immediately to 
the parent environment, if any. The current environment terminates. If the parent environment has a suitable 
handler, that handler is executed. Otherwise, the exception is passed to its parent environment etc. In other
words, the exception travels up the call stack until it finds an appropriate handler, executes it and resumes
execution right after the \mono{try} block. Note that once a handler is complete, other handlers that 
follow will be skipped. Here is an example CGI script which converts the file ``file2html.pl''
(which is the script itself) to HTML for viewing in a browser. It uses try/catch exception handling. You may 
execute this program from the command line. If you would like to view it in a browser, please consult the 
next chapter. \\ 

\head{EXAMPLE}{Text File to HTML Converter}
\lstinputlisting[backgroundcolor=\color{CodeBackground}]{src/eval/file2html.pl}


The script reads the content of itself by default. If you change the filename on line 10 to a non-existing
file, then an error page will be generated instead. \\

In the default case, the \mono{open()} should be successful, and hence the exception is not thrown. In this
case, all handlers are skipped. If the file cannot be \mono{open}ed, the exception is thrown on line 17.
Because the \mono{openFile()} subroutine does not have any handlers defined, the subroutine terminates and
the exception is passed to the parent environment. Note that \mono{openFile()} is invoked inside a \mono{try}
block in the subroutine \mono{toHTML()} (line 28). On receipt of an exception from \mono{openFile()}, the
rest of the \mono{try} block is bypassed and the handlers are searched. Here, we have a matching \mono{catch} 
handler. Therefore, it is executed. Note that handlers internally are also implemented by subroutines, and 
the error object is always passed as the first argument of a handler. In the handler, the error message 
is embedded into the HTML output. Once the handler completes successfully, execution resumes on line 45. \\

This example demonstrates the elegance of the try/catch approach. You do not have to handle an exception 
until you would like to. Traditionally, to notify the caller of a subroutine that an error has occurred
inside the subroutine, the error string or error number has to be passed as the return value. Multiplexing
normal return values and error numbers merely disturbs the program logic, and this is not convenient. It
is even more problematic if you have to propagate the error number of string up the call stack. The 
try/catch mechanism generates and handles errors
through another path so you do not have to mess with return values in order to perform exception handling. \\

If an error object is thrown and no matching handler can be found all the way up the call stack, the program terminates with the exception
message displayed, similar to the behaviour of executing \mono{die()} that is not inside any \mono{eval}. 
In most well-written programs, this should generally not occur because you will usually have a generic 
handler that is executed as the last resort. More on this later on. \\

\subsection{Throwing Different Kinds of Errors}

The power of try/catch does not stop here. The ability to generate different kinds of exception objects
is what that makes this mechanism immensely flexible. You won't need multiple handlers if you simply wish
to handle \mono{Error::Simple} exception objects. Only one handler as illustrated in the above example is
already sufficient for this purpose. \\

All exception objects has to belong to a class that is a subclass of \mono{Error}.
In fact, \mono{Error::Simple} is just a class that is predefined to represent simple errors. 
You can derive your own subclass to add extra functionality or record extra pieces of debugging information. 
You do not have to create an \mono{Error} subclass for each single type of error. The general rule is,
if you are likely to handle some kinds of errors differently than the others (by using different handlers), 
then you should create an exception class for each. \\

Here is an example. Because usually users of CGI applications are not programmers, you may wish to provide
them with additional information other than the regular error messages. For example, in your error message
you may include a suggested method to rectify the problem, tailored to the situation. I will now create an
exception class that records this piece of extra information. \\

\head{EXAMPLE}{Subclassing Error.pm}
\lstinputlisting[backgroundcolor=\color{CodeBackground}]{src/eval/Exception.pm}

Line 9 is an alternative way to say that this class is a subclass of \mono{Error}. You can use the plain 
old \mono{@ISA} method. I just teach you another way to do it. Line 13 actually utilizes \term{operator overloading},
a method of introducing new meanings to existing operators if the operands are objects. Here, this statement
actually means if you place the object variable inside a double-quoted string, the object variable will be 
replaced by the return value of the method \mono{stringify()}, which is also defined in \mono{Error} returning
a simple error message. This statement is added because we would not like 
to break this behaviour. Operator overloading is not covered in this edition of the tutorial. Line 20 
enables the production of \term{stacktrace}. A stacktrace is a textual representation of the current call stack.
From the stacktrace you will find at which point in the program an exception is raised, and the hierarchy
of callers to the point in question. Programmers will find this information useful when debugging a program,
but it may not be useful in production environments at all. Because generation of backtrace is not very efficient, 
this is disabled by default. in this class, we enabled it. Line 24 is placed to ensure that the point at which
the exception is thrown is resolved correctly. I am not explaining it here because it relates to some 
internal mechanisms that are not easy to explain with a few words. As a rule of thumb, just include it
and you are fine. \\ 

The \mono{Error} class is a hash reference. Fields that are carried with the object are stored in the 
hash itself. On line 26 we assign to it two fields. The \mono{-text} field carries the basic error 
message, and \mono{-soln} is the field added by us to hold the suggested solution. We also define a \mono{solution()}
method to get this piece of information from outside of the class. 
At last, we invoke the constructor of the superclass.  \\

You may also wish to read the source code of \mono{Error.pm}. It is not very difficult to read, and it 
is pretty short. You may find out more information about the workings of the module that are absent 
from its documentation. In particular, you may read the source code of \mono{Error::Simple}, which is
in the same file as \mono{Error.pm}. It gives you some hints as to how to write a subclass of \mono{Error}. \\

Now I include a modified version of the text-to-HTML converter program that uses the \mono{Exception} class
we developed above. Apart from the error message, it displays the stacktrace as well as the suggested action
in response to the error. A screenshot showing the generated error page is in Figure~\ref{fig:cgiexception}. \\

\lstinputlisting[backgroundcolor=\color{CodeBackground}]{src/eval/file2html2.pl}
\image{!hbt}{\textwidth}{!}{images/cgiexception.eps}{Web Page Showing Generated Exception}{fig:cgiexception}

Here, you see an example of using multiple handlers, although only the handler of \mono{Exception} is used
in this example. Note that the handler of \mono{Exception} can display more debugging information than
the generic one. In the screenshot we can see a message indicating the course of action that should be 
taken, followed by the stacktrace. \\

Line 21 has been changed from \mono{die()} to \mono{throw()}. The \mono{throw()} function is used to 
generate a new instance of the exception object and throw it. In this example, the package name of the 
exception object is \mono{Exception} and the two parameters, the basic error message and the suggested
action message, are provided, in accordance with the constructor of \mono{Exception} we described earlier. \\

Line 10 declares a \term{named constant}. While Perl does not intrinsically has a mechanism for defining named constants,
the \mono{constant} module provides you with a nice workaround. Here, the constant \mono{FILEIO\_ERR} refers
to the string on the far right. By using constants instead of scalar variables to store immutable data, 
you can avoid inadvertently modifying their contents because
attempts to modify their values result in compile-time error. \\ 

\subsection{Other Handlers}

Now that you have learned the basic knowledge needed to make good use of exception handling. To end up this
topic I will introduce to you the other kinds of handlers you can place to handle exceptions. \\

The \mono{otherwise} handler handles all kinds of exception objects. It is generally used as a generic
exception handler that acts as a last resort to catch the exception if an appropriate handler is missing.
Therefore, you should ensure that this is placed after all \mono{catch} and \mono{except} handlers, if any. 
There can be at most one \mono{otherwise} handler per \mono{try} structure. \\

An \mono{except} handler is rarely used in practice, because its functionality can largely be achieved
using \mono{catch} handlers. Please read the documentation if you are interested in knowing more about it. \\

A \mono{finally} handler is different from the other handlers in that, if one is present, the block is evaluated 
if the \mono{try} block is executed successfully (with no exceptions thrown) or if a handler has completed. \\

You may throw an exception object in a handler. For example, you may have a handler in the current environment
to handle the exception. However, if the caller also has to be informed of this exception, you may simply
\mono{throw()} it again in the handler after you have carried out all necessary processing. For example, \\

\begin{verbatimtab}[4]
...
} catch Error::Simple with {
	my $err = shift;
	# Do some processing here w.r.t. the exception
	$err->throw();		# let caller catch it also
};
\end{verbatimtab}

\section{Other Methods To Catch Programming Errors}

Not all errors are fatal exceptions. More often logical or semantic errors arise because of mistaken
(but syntactically acceptable) use of data values. For example, you may think a certain environment
variable contains valid data, but for unknown reasons it turns out that it is actually \mono{undef}.
You are likely to get unexpected results if you keep on using this value without knowing it is \mono{undef}.
Certain kinds of errors like this may be trapped by using the following methods. \\

\subsection{The \mono{-w} Switch --- Enable Warnings}

You have been using this switch throughout this tutorial. By enabling this switch, warnings on certain dubious
operations are generated. Here, I list some sample situations where warnings will be generated if warnings are
enabled: \\

\begin{itemize}
\item Using the value of a variable without first giving it a value (or the value \mono{undef}); \\ 
\item Applying mathematical operators on an operand which is not a number (e.g. \mono{"30ab" + 4}); \\ 
\item Variables that are mentioned only once. Usually, this signals a typographical error. The rationale is
that in practice a variable is mentioned at least twice, that is when it is given a value (define) and when
it is used. Any variables not adhering to this define-and-use pattern are rather likely misused; \\
\item The use of undefined filehandles. This usually indicates you have not check the return value of 
\mono{open()} to see if the open is successful; \\
\end{itemize}

This is only a selection of the most frequent sources of warnings.
Note that this switch determines whether warnings are generated by Perl internally. Therefore, warnings manually 
generated by \mono{warn()} are not suppressed in the absence of this switch. \\

\subsection{Banning Unsafe Constructs With \mono{strict}}

You can \mono{use strict} to disable some unsafe constructs in Perl. It consists of three kinds of checks,
whose imported symbols are represented by \mono{refs}, \mono{vars} and \mono{subs}, respectively. 
By default, if you insert \mono{use strict;} in your program, all of them are performed by default. You 
may selectively enable some of them but not the others by specifying the corresponding symbols after
\mono{use strict}. For example, \\

\begin{verbatimtab}[4]
use strict 'refs', 'subs';		# Omitting 'vars'
\end{verbatimtab}

If the \mono{refs} check is in effect, it disables the use of so-called \term{symbolic references}. While
it bears the name ``references'', it does not have much to do with references, or ``hard references'' as
are called by some people described in Chapter~\ref{chap:ref}. Symbolic references are generally considered 
undesirable and should be avoided. The idea is quite simple. Consider this example: \\

\begin{verbatimtab}[4]
$b = 10;
$a = \$b;
print ${ $a }, "\n";
\end{verbatimtab}

10 is \mono{print}ed. Recall that anything returning a reference may be placed inside the curly braces.
This is the basis for dereferencing. However, a symbolic reference is just a plain string 
which contains the name of another \textit{non-lexical} variable instead of a reference. Here is an example which uses
symbolic reference that is largely functionally equivalent to the above example: \\

\begin{verbatimtab}[4]
$b = 10;
$a = "b";
print ${ $a }, "\n";
\end{verbatimtab}

% TODO: Why symbolic reference should be avoided? (any more?)

The difference is on line 2, that is, the value held by the lexical variable \mono{\$a}. The first
example is a proper reference, but the second one is not. If \mono{refs} check is in effect, the
second example will be flagged as invalid and a runtime error generated, because you are trying to
dereference a string instead of a real reference. Note that symbolic references always resolve to
non-lexical variables. For instance, in the above example \mono{\$b} is accessed from the symbol
table. If you declare \mono{\$b} as lexical with \mono{my} on line 1, Perl will still resolve it
from the symbol table, which is \mono{undef} unless you have it defined somewhere before. Because
the use of non-lexical variables is discouraged, and you may potentially modify the value of the
Perl predefined variables which hold important runtime data, symbolic reference should be avoided. \\

The \mono{subs} check, despite its name, is used to trap the use of so-called \term{barewords}.
As you may appreciate from your journey through this tutorial, Perl gives you a lot of shorthands
that you may use to make your code more ``compact'', which implies a rather informal way of 
expression that lets you save some keystrokes provided you know exactly what you are doing. \\

A bareword is a standalone word in Perl that does not have any special meaning. For example, \\

\begin{verbatim}
my $word = something;
\end{verbatim}

When parsing the assignment statement during compile time,
Perl first checks if a subroutine of the name \mono{something} has already been declared, 
because a subroutine may be invoked without 
having \mono{\&} and the parentheses. If it is not, then it is assumed to be a string with the
quotes omitted. However, if \\

\begin{verbatimtab}[4]
sub something {
	# something ....
}
my $word = something;
\end{verbatimtab}

Then, \mono{something} is treated as a subroutine invocation as a subroutine of this name exists
when the assignment statement is parsed. If you put the assignment statement above the subroutine
declaration, \mono{something} is treated as a string because at the time of parsing the assignment
statement the subroutine is not declared yet. That is also why it is always a good idea to forward
declare all subroutines early in your program. Apart from giving you the flexibility of defining 
the subroutines in any order you prefer, you also help prevent Perl from interpreting subroutine
invocations as barewords. \\

As you can see, a bareword is always subject to two possible interpretations which you cannot explicitly
tell just by looking at the syntax. That explains why most programming languages today, especially very
structured ones like C and Java, never honour flexibility (or ambiguity) like this. You may rule out
the use of barewords that do not refer to subroutines by carrying out the \mono{subs} check. There a 
a few exceptions, however. Barewords on the left hand side of the \mono{=>} operator is always 
treated as a string as I mentioned very early in the tutorial when you learned about hash initialization.
Also, a bareword appearing inside curly braces \mono{\{\}} is also treated as a string, as in the example below: \\ 

\begin{verbatimtab}[4]
$hash{file}		# $hash{'file'} recommended
\end{verbatimtab}

The \mono{subs} check marks these two exceptional cases as valid use of barewords. However, considering
the use of barewords in most cases does not contribute to a major cut to file size, and you are actually
making the code more confusing, I do not recommend the use of barewords altogether. That's why barewords
are rarely used in this tutorial. \\

The \mono{vars} check is likely to affect you most among the three if you enable it. If you access a scalar variable, an 
array or a hash that is not lexical (declared with \mono{my}) and without qualifying it with the package name
when the \mono{vars} check is in effect, a compile time error is generated. For a long time, we have been
using the shortcut that a package variable without being qualified with the package name refers to the current
package that is in force. Therefore, that implies the package \mono{main} unless you have set up additional
packages. However, when the \mono{vars} check is in effect, you are forced to refer to lexical and package variables 
in different ways. The following summarizes the syntax, which has already been covered earlier in this tutorial: \\

\begin{verbatimtab}[4]
package MyPackage;

my $lexical = 4;
local $MyPackage::pkgVar = 10;		# instead of just $pkgVar
\end{verbatimtab}

Special provisions have been made to allow you to refer to package variables \mono{\$a} and \mono{\$b} without
the package name, because they are used by the \mono{sort()} function to refer to the two arbitrary picked
items for comparison. This also means if you would like to use this \mono{strict} mode, you should refrain 
from using these two variables because they are not checked for \mono{strict}ness. Also note that typeglobs 
are excluded from this check because they cannot be lexical anyway. The rationale behind this \mono{strict}
mode is to cleanly separate the syntax of variable accesses with respect to package variables and lexical variables. 
Without \mono{strict} mode, you are subject to a problem similar to barewords mentioned above, illustrated below: \\

\begin{verbatimtab}[4]
$x = 4;			# package variable
sub proc1 {
	$x;			# package variable
}

my $x = 5;		# lexical
sub proc2 {
	$x;			# lexical
}

print proc1, "\n", proc2, "\n";		# 4, 5
\end{verbatimtab}

A similar example has already been given in Chapter~\ref{chap:scope} to demonstrate how lexical and package
variables are resolved. Without the comments, it is not immediately obvious to distinguish the package
variable from the lexical. Worse still, you can have a package variable and a lexical of exactly the same
name in the same scope. By replacing the above example with a \mono{strict} mode friendly version the whole
picture is easier to identify: \\

\begin{verbatimtab}[4]
$::x = 4;		# package variable
sub proc1 {
	$::x;		# package variable
}

my $x = 5;		# lexical
sub proc2 {
	$x;			# lexical
}

print proc1, "\n", proc2, "\n";		# 4, 5
\end{verbatimtab}


\subsection{The \mono{-T} Switch --- Enable Taint Checking}

Strictly speaking, this is a mechanism to enhance program security rather than one which helps catch 
programming errors. As we have seen above, data passed into your programs from outside can pose 
significant threats if they are fed to backticks or functions like \mono{eval()}.
Although you may honour users of your programs to exercise self-discipline to
specify valid data only, you should not carry this attitude. As demonstrated by the Internet spam
mail problem, you can hardly rely on users to use your programs properly. A programmer who are conscious
of security issues will instead regard all incoming data as if they are malicious, carry out all
necessary validations and accept them only if they are valid. This defensive approach is the 
basic principle behind taint checking in Perl. Perl marks external data passed into the program as tainted.
Before you feed such kind of data to potentially unsafe functions, you are required to manually untaint it.
This forces you to think more carefully about whether every piece of input data is safe. \\

In other words, you have to untaint a piece of data if both of the following conditions are satisfied: \\
\begin{itemize}
\item it originates from outside of the program (and is thus tainted); 
\item it, or its derivative, is going to be involved in a potentially unsafe operation. A potentially unsafe
operation is one which may potentially change the state of the system.
\end{itemize}

Taint checking is more of a concern for CGI scripts and scripts which are executed setuid or setgid
(see Appendix~\ref{chap:unixprimer} for more information about setuid and setgid on Unix systems). In fact,
for Perl scripts executed that has the setuid or setgid file permission bit set, taint mode is performed
automatically and you do not have to enable it. \\

Examples of tainted data include command-line arguments, data read from user input, files or received from network
functions and environment variables. Results of system calls such as \mono{readdir()} and form data received in 
CGI applications are also considered tainted. \\

Examples of potentially unsafe operations are \mono{system()}, backticks, \mono{eval()}, \mono{open}ing a file with writable privilege.
Filesystem functions such as \mono{unlink()} and \mono{rename()} and the low-level system calls that are 
not covered in this tutorial are also unsafe. You may find that all of them have one aspect in common ---
they may be potentially used to alter the state of the system. Note that \mono{print()} itself is \textbf{not} considered
a potentially unsafe operation. If you can \mono{open()} the file with writable permission, then you are allowed 
to write into it even if data written into it are tainted. \\

For example, in a program involving the \mono{open()} function in write or append mode, if the filename derives
from external data (such as input by user) then you are required to untaint it. \\

The only way you may untaint a piece of tainted data is to extract from it by means of backtracking with regular 
expressions. For example, the following example allows you to get the directory listing as generated by the \mono{ls}
command of arbitrary directories inside the current directory, but not outside of it. \\

\begin{lstlisting}[backgroundcolor=\color{CodeBackground}]
#!/usr/bin/perl -Tw

use strict;

my $path = $ARGV[0];
if (defined $path and $path =~ m/^(((\w|\.\w|\.\.[.\w])[.\w]*\/?)+)$/) {
	# $1 contains the path
	$ENV{'PATH'} = '';
	print `/bin/ls -l $1`;
} else {
	print "Invalid or missing relative path!\n";
}
\end{lstlisting}

A list of environment variables available and their corresponding values can be retrieved from the \mono{\%ENV} hash. 
In this example we also demonstrated how to get the command line arguments. Command line arguments are passed
into a Perl program in the \mono{@ARGV} array. Each command line argument becomes an element of this array. For
example, you may try out this program by either of these commands below, depending on your situation: \\

\begin{verbatimtab}[4]
# Directory listing of "images/" subdirectory 

./ls.pl images/				# Unix with executable chmod
perl -Tw ls.pl images/		# Otherwise
\end{verbatimtab}

We used the pattern built at the end of the previous chapter to check if the path is a valid relative path. 
Note that the PATH environment variable is cleared. In taint mode, you are required to set the environment
variable PATH in your program to a known value. This is needed if you are to invoke operations that execute
another program, such as backticks and \mono{system()}. This restriction is mainly set for applications started
from the command line because PATH, just like any other environment variables, can be set by the user who 
executes the program. Therefore, its content cannot be trusted. This environment variable, as introduced 
in the beginning of this tutorial, is used to specify a sequence of directories to be searched for executables,
so that users do not have to always qualify the executable with the absolute path for convenience reasons.
If the attacker prepends to PATH the path of a directory under his or her control, the operating system 
will first search that directory for executables, followed by the system-defined ones. For example, if 
the \mono{ls} program above is not qualified with an absolute path, and a malicious version of \mono{ls}
is placed in that directory, it will be executed instead. Note that this not only affects the program
started from within the Perl program, it affects external applications started by that program as well.
With a PATH that is known to be valid, this attack will not be successful. \\

It is not necessary for PATH to be empty. For example, the following is still valid: \\

\begin{lstlisting}[backgroundcolor=\color{CodeBackground}]
#!/usr/bin/perl -Tw

use strict;

my $path = $ARGV[0];
if (defined $path and $path =~ m/^(((\w|\.\w|\.\.[.\w])[.\w]*\/?)+)$/) {
	# $1 contains the path
	$ENV{'PATH'} = '/bin';
	print `ls -l $1`;
} else {
	print "Invalid or missing relative path!\n";
}
\end{lstlisting}

You don't have to worry about modifying the environment variable. 
In fact this change is local only to the Perl program in question and other programs that get started from there. 
Other parts of your system is not affected. \\

Note that if taint mode is in effect, \mono{@INC} no longer has the ``.'' entry by default. Therefore,
modules in the current directory will not be automatically accessible. This arrangement is mainly introduced to protect
Perl scripts that are executed from the command line. In particular, if your script is written to be 
executed by everyone on the system you are vulnerable to a certain attack if your script has to source
in external files while having a relative path like ``.'' in \mono{@INC}. Say you have the following
program \mono{myprog} in \mono{/usr/local/bin} which can be executed by all users on your server system: \\

\begin{verbatimtab}[4]
#!/usr/bin/perl -w

BEGIN {
	@INC = (@INC, '../lib');
}

use MyModule;	# in /usr/local/lib
# ...
\end{verbatimtab}

A relative path is one which depends on the current directory. ``..'' is still a relative path because 
it denotes the parent directory of the current directory. Using a relative path to locate external modules
suffers two problems. The first being the user has to manually change the directory to the directory of 
the script in order to execute it, for example, \\

\begin{verbatim}
cd /usr/local/bin
\end{verbatim}

before running the script. Most importantly, this leaves a backdoor for a malicious user to replace
the definition of \mono{MyModule} with whatever he or she desires. What he or she needs to do is to
run this program from somewhere in his or her home directory: \\

\begin{verbatim}
cd /home/cracker/bin
/usr/local/bin/myprog
\end{verbatim}

Because the current directory is \mono{/home/cracker/bin}, perl will try to load \mono{MyModule} from
\mono{/home/cracker/lib}. What the attacker has to do is to place his or her own version of \mono{MyModule}
there, very likely containing malicious code which will be duly executed by Perl.
Note that a malicious user does not have to modify the modules placed in \mono{/usr/local/lib}, which 
are not writable for him in order to launch a successful attack. \\

Even if you prefer not to use taint mode, you are advised to replace all relative paths in \mono{@INC}
with absolute paths to avoid the attack outlined in the above example. There are two possible ways to
patch against this security hole. The first way is to replace all relative paths with absolute paths. 
For example, \\

\begin{verbatimtab}[4]
BEGIN {
	$basedir = '/usr/local';
	@INC = (@INC, "$basedir/lib");
}
\end{verbatimtab}

If taint mode is on, and you need to place some modules in the same directory as the script itself,
then do not forget to append its absolute path as well. The second method is to use the \mono{chdir}
function to change the current directory with respect to the script. Then it is still safe to use 
relative paths in the program. For example, \\

\begin{verbatimtab}[4]
BEGIN {
	chdir '/usr/local/bin' or die "Cannot chdir(): $!\n";
	@INC = (@INC, '../lib');
}
\end{verbatimtab}

It is possible that \mono{chdir()} may fail. Therefore, to be discreet you may wish to check the
return value of \mono{chdir()} (a false value if failed) and stop the program if it fails. \\

For CGI scripts, again, because the script is executed by the Web server and the current directory is usually 
set to the directory containing the script itself, it is generally safe to append relative paths to \mono{@INC}
in CGI scripts. It is still a good practice to use absolute paths, however. \\

While taint mode is a means to achieve a higher level of security, it is not the end. There are certain
kinds of attacks that taint mode cannot protect against, such as reading of privacy-sensitive files
(containing password entries, for example), because reading a file does not change the state of the
system, and hence is not considered a potentially unsafe operation.  For example, \\

\begin{verbatimtab}[4]
#!/usr/bin/perl -Tw

my $filename = $ARGV[0];

open FILE, "</usr/local/mywebapp/$filename" or die "Cannot open file!\n";
\end{verbatimtab}

While you may think the script can only access files inside \mono{/usr/local/mywebapp}, what an attacker needs
to do is to pass a string containing ``..''. For example, if \mono{\$filename} is \mono{../../../etc/passwd}
then the attacker will still be able to access \mono{/etc/passwd}. On some Unix systems, especially older installations,
this file contains the encrypted passwords of users on the system. However, security-aware personnel
know that even if passwords are stored encrypted it is still possible to recover them. The algorithm used to 
encrypt these passwords is well known to be easy to break. \\

You may prefer to hide or obfuscate your source code and believe by doing so you can achieve a higher level of security. You don't.
Remember, \textit{security through obscurity} is not an appropriate attitude towards protecting your system.
Once the secret is revealed for whatever reasons, security is gone. The most secure system is one which remains
impenetrable even if all of its internals are presented before the attackers. This goal is frankly not easy 
to achieve, and requires the programmers to stay constantly vigilant over potential ways of abuse. Your level 
of sophistication in security is very often proportional to your experience in this field. You should also
keep an eye on security mailing lists to keep yourself aware of the latest kinds of vulnerabilities and attacks
discovered. \\

% TODO:
% Perl debugger

\section*{Summary}

\begin{summary}
\item Fatal exceptions are severe errors which halt execution unless trapped with \mono{eval\{\}}.
\item Warnings are less severe but usually indicate logical errors in your programs.
\item You may raise fatal exceptions and warnings manually with the \mono{die()} and \mono{warn()} functions respectively.
\item \mono{eval()} can be used for runtime evaluation of a given string as a Perl program.
\item \mono{system()} or backticks can be used to execute external programs or shell commands.
\item The \mono{Error} module on the CPAN can be used for flexible and convenient exception handling.
	\begin{summary}
	\item All exception objects inherit \mono{Error}.
	\item The \mono{try} block contains statements to be checked for exceptions.
	\item The \mono{catch} block is a handler which handles exceptions of a certain class.
	\item The \mono{otherwise} handler is used as a generic handler which handles any kinds of exceptions.
	\item The \mono{finally} block is executed if the corresponding \mono{try} block completes successfully or if a handler has been executed.
	\item If there is no matching handler in the current environment, the exception traverses up the call stack until an appropriate handler is present.
	\item A semicolon is needed after the block of the last handler.
	\item An exception object may be manually thrown using the \mono{throw()} method.
	\end{summary}
\item \mono{-w} switch enables warnings on dubious operations.
\item The \mono{strict} pragma disables some unsafe constructs in your program.
	\begin{summary}
	\item \mono{refs} check disables the use of symbolic references.
	\item \mono{subs} check disables the use of barewords.
	\item \mono{vars} check requires all non-lexical variables to be qualified with package name.
	\end{summary}
\item \mono{@ARGV} contains the command-line arguments.
\item Taint mode serves to enhance program security.
	\begin{summary}
	\item Data originating from outside the program is marked as tainted.
	\item A potentially unsafe operation may change the state of the system.
	\item Tainted data has to be untainted before involving in a potentially unsafe operation.
	\item The only way to untaint is by means of backtracking in pattern matching.
	\item The ``.'' directory is absent in \mono{@INC} in taint mode by default.
	\item The PATH environment variable needs to be set to an untainted value before executing external programs from within your Perl program.
	\end{summary}
\end{summary}

\section*{Web Links}

\begin{list}{\thechapter.\arabic{count}}{\usecounter{count}}
\item {
	\link{http://www.perl.com/pub/a/2002/11/14/exception.html}{perl.com: Object-Oriented Exception Handling in Perl} \\
	\textit{http://www.perl.com/pub/a/2002/11/14/exception.html}
}
\item {
	\link{http://www.perl.com/pub/a/2001/01/begperl6.html}{perl.com: Beginners Intro to Perl --- Part 6} \\
	\textit{http://www.perl.com/pub/a/2001/01/begperl6.html}
}
\item {
	\link{http://gunther.web66.com/FAQS/taintmode.html}{CGI/Perl Taint Mode FAQ} \\
	\textit{http://gunther.web66.com/FAQS/taintmode.html}
}
\item {
	\link{http://www.perldoc.com/perl5.8.0/pod/perlsec.html}{perlsec manpage --- Perl Security} \\
	\textit{http://www.perldoc.com/perl5.8.0/pod/perlsec.html}
}
\end{list}
