\chapter{References\label{chap:ref}}

% ====================================================================== 

\section{Introduction} 

We have covered the use of scalars in the first few chapters of this tutorial. However, we haven't 
covered a very important type of scalar yet --- \term{references}. Perl references are prevalently used nowadays, 
thanks to the official support of object-oriented programming starting from Perl 5. You need to have
a good command of references before heading towards the topic of object-oriented programming. \\

References look cryptic from the start. It resembles the concept of ``pointers'' in C/C++, and ``hard
links'' in Unix filesystems (you may flip to Appendix~\ref{chap:unixprimer} for a crash course on basic
Unix). The use of references is in some sense a peculiar concept in programming. However, it turns
out to be very useful in parameter passing and serves as the basis for constructing complex data structures
in Perl (and therefore, it is central to object-oriented programming in Perl). Towards the end you will also learn 
to use typeglobs in your programs. Typeglobs were used to pass data structures to and from subroutines
when references were not yet available in earlier versions of Perl. Today, they have been largely superseded
by references, and the section on typeglobs is merely presented for your information only. \\

%fundamental importance to object-oriented programming. In Chapter~\ref{chap:oop} we would build a traffic
%light simulator program which uses references to demonstrate a listener mechanism. \\

% ====================================================================== 

%\section{References Primer}

A reference is a special form of scalar variable that stores the location (address) of a data structure. 
Fundamentally, when something needs to be stored in the memory, a memory address is required. It is only with
the knowledge of the address of the object that we can access it. This is synonymous with your postal address
in mail delivery, or your IP address for packet routing on the Internet. \\

%In more technical parlance, the rvalue of a reference variable is the lvalue of some other variables (or even references - because a reference is just simply a scalar variable). 
%An lvalue is simply a memory address where the value of the variable is stored.

\section{Creating a Reference}

To create a reference, prefix the \textbackslash\ operator to the data object. For example, \\

\begin{verbatim}
$a = \100;	
\end{verbatim}

This creates a reference variable \mono{\$a} that points to a newly created data object which holds the literal 100. 
If the memory address of the data object is stored is at location \mono{0x8101B8C}, the 
reference \mono{\$a} would have an rvalue of \mono{0x8101B8C}. The following diagram is a pictorial 
representation of the situation. Note that the memory address varies from system to system, and 
because of the relocatable nature of processes, the address may probably vary on every execution. I just 
made it up here for the purpose of illustration. \\

\image{!hbt}{!}{!}{images/scalarref.eps}{Scalar Reference}{fig:scalarref}

In the diagram, the association is represented by a solid arrow. The real data object is represented 
by a cloud shape while the reference by a rectangle. You can further create a reference \mono{\$b} 
which points to \mono{\$a}, by \\

\begin{verbatimtab}[4]
$b = \$a;				# scalar reference
\end{verbatimtab}

\image{!hbt}{!}{!}{images/scalarref2.eps}{A Chain of Scalar References}{fig:scalarref2}

Apart from references of scalars, you can also create references of hashes, arrays, 
subroutines and typeglobs. Subroutine reference (or code reference/anonymous subroutines) 
and typeglob reference will be revisited afterwards. \\

\begin{verbatimtab}[4]
$arrayref = \@array;		# array reference
$hashref = \%hash;			# hash reference
$coderef = \&subroutine;	# subroutine reference
$globref = \*typeglob;		# typeglob reference
\end{verbatimtab}

Though appearing awkward to do so, you may create a chain of references in one go without involving
intermediate variables by prefixing multiple backslashes to the data object. For example, the above 
two statements are functionally equivalent to: \\

\begin{verbatim}
$b = \\100;
\end{verbatim}

Be careful of enumerated lists as a special case! As indicated on the perlref manpage,
taking a reference of an enumerated 
list evaluates to a list of references of the list elements: \\

\begin{verbatimtab}[4]
@list = \($a, $b, $c);		# Actually (\$a, \$b, \$c)
@list2 = \($a, @b);			# Actually (\$a, \$b[0], \$b[1], ...)
# Actually \$c. Remember list operator in scalar context?
$scalarref = \($a, $b, $c);	
\end{verbatimtab}

Recall that in an enumerated list all arrays or hashes are expanded to the constituent
elements to form a single list. To create a reference to an enumerated list directly 
without creating an intermediate array first, which is
called an \term{anonymous array}, enclose the list in [ ] instead: \\

\begin{verbatim}
$listref = [$a, $b, $c];
\end{verbatim}

Similarly, to construct an \term{anonymous hash}, enclose the key-value pairs in \{ \} 
instead: \\

\begin{verbatimtab}[4]
$hashref = {
	'key1' => 'value1', 
	'key2' => 'value2', 
	'key3' => 'value3',
};
\end{verbatimtab}

Because a reference is simply a scalar value, elements of an anonymous array (or values of
anonymous hash) can also be a hash reference or array reference. In this way, we will be able
to implement some complex data structures easily, which we shall explore later in this chapter as 
well as in the next chapter when I introduce object-oriented programming. For example, \\

\begin{verbatimtab}[4]
$hashref = {
	'values' => [
		'a',
		'b',
		'c',
	], 
	'device' => 'screen', 
	'options' => {
		'indent' => TRUE,
		'color' => '0xFFFF00',
	},
};
\end{verbatimtab}

which creates an anonymous hash containing three key-value pairs. The \mono{values} key maps
to an anonymous array, while the \mono{options} key maps to an anonymous hash. The \mono{device}
key maps to a simple scalar string. \\

References to subroutines behave like functors in C. They can be created in two ways. The first way is
to prepend \mono{\textbackslash\&} to the name of the subroutine. The \mono{\&} is required when you 
are referring to the name of a subroutine. For example,
if you have a subroutine named \mono{somesub()} you can take a reference to it by \mono{\textbackslash\&somesub}. \\

%\begin{verbatimtab}[4]
%\&somesub
%\end{verbatimtab}
 
You can also create an anonymous subroutine directly, by using \mono{sub} without specifying the name
of the subroutine: \\


\begin{verbatimtab}[4]
$subref = sub {
	# This is a subroutine
};
\end{verbatimtab}

\section{Using References}

If you try to \mono{print()} a reference variable, the type as well as the memory location will be displayed, for
example \mono{CODE(0x814f3a0)} for an anonymous subroutine. \\

Once you have the reference variables, you may \term{dereference} them to access the underlying data objects. To
dereference a reference variable, simply put a pair of curly braces around the reference variable and prepend it 
with the symbol which stands for the 
underlying type. For example, to dereference the reference variable \mono{\$a} in our earlier examples, we can write \mono{\$\{\$a\}}. Other examples: \\

\begin{verbatimtab}[4]
@array = @{$arrayref};			# array
$scalar = ${$arrayref}[0];		# Return the first element of array above
%hash = %{$hashref};			# hash
$scalar = ${$hashref}{'KEY'};	# Return the value whose key is 'KEY' of hash above
&{$coderef}('a', 'b');			# subroutine invocation
\end{verbatimtab}

In general, you can omit the curly braces around the reference variables in dereferencing operations. Situations
that require them will be described at a later time. \\ 

You can also dereference multiple levels deep. For example, consider the chain of references \mono{\$b} we saw
at the beginning of this chapter, we can access the data object which holds the literal 100 by dereferencing it
two times, by \\

\begin{verbatimtab}[4]
$a = \100;
$b = \$a;
print $$$b; 		# prints 100
\end{verbatimtab}

%\begin{lstlisting}[numbers=none,backgroundcolor=\color{CodeBackground}]
%\end{lstlisting}
%\addvspace{\baselineskip}


However, creating a reference to a literal makes it read-only. For example, trying to modify its value in dereferencing
is a runtime error: \\

\begin{verbatimtab}[4]
$a = \100;
$b = \$a;
$$$b = 90;		# same as $$a = 90

Modification of a read-only value attempted at test.pl line 3.
\end{verbatimtab}

Because the value pointed to by \mono{\$a} is read-only, we can only change it by creating a new literal of the 
desired value, and point \mono{\$a} to it instead. 
\mono{\$b} would now reflect the new value when dereferenced: \\

\begin{verbatim}
print "Before reference \$a changes: $$$b\n";
$a = \200;
print "After reference \$a changes: $$$b\n";
\end{verbatim}

The output is \\

\begin{verbatim}
Before reference $a changes: 100
After reference $a changes: 200
\end{verbatim}

\image{!hbt}{!}{!}{images/scalarref3.eps}{Change in Reference Chain}{fig:scalarref3}

This is different from the case below, which you may change the underlying value because
because the reference is taken on a scalar variable, not a literal: \\

\begin{verbatimtab}[4]
$a = 100;
$b = \$a;
$$b = 90;
\end{verbatimtab}

Note that subroutine prototypes are ignored when you invoke a subroutine through its reference, because prototypes are
only used during compile time, at which point perl cannot yet resolve the subroutine to which the reference variable 
points. \\

Recall that to dereference a reference variable we put a pair of curly braces around it and prepend a backslash to it.
I then told you that the braces are customarily omitted. The fact is, the curly braces may contain anything, provided
it returns a reference matching the expected type. For example, \\

\begin{verbatim}
${ $$ref{'KEY'} }
\end{verbatim}

dereferences the hash reference \mono{\$ref}, take the value associated with key \mono{KEY} which is presumably a scalar
reference, and  dereference it. Note that this is not the same as \mono{\$\$\$ref\{'KEY'\}}, which is actually
identical to \\

\begin{verbatimtab}[4]
${${$ref}}{'KEY'}		# $$ref->{'KEY'}  (see below)
\end{verbatimtab}

which dereferences the scalar reference \mono{\$ref} to get the underlying hash reference, dereference
it and then access the value associated with the key \mono{KEY}. In other words, when the curly braces 
are omitted, access of array or hash is performed at last. As the reference chain gets more complicated 
the dereferencing expression can get very confusing. Therefore, Perl also supports a special syntax resembling
the C pointer-to-member (arrow) operator. Table~\ref{tab:dereference} summarizes the alternative forms.  \\

\begin{table}[htbp]
\begin{center}
\begin{tabular}{ll}
\hline
\textbf{Operation}	& \textbf{Alternative Method} \\
\hline 
	\mono{\$\$arrayref[\$index]} &	\mono{\$arrayref->[\$index]}	\br \\
	\mono{\$\$hashref\{\$key\}} &	\mono{\$hashref->\{\$key\}}	\br \\
	\mono{\&\$coderef(@args)} &	\mono{\$coderef->(@args)}	\br \\
\hline 
\end{tabular}
\\[\baselineskip]
\end{center}
\caption{Alternative Syntax for Dereferencing}\label{tab:dereference}
\end{table}

The arrow operator can be cascaded, for example, \\

\begin{verbatimtab}[4]
$hashref->{'files'}->[0] = 'index.html';
\end{verbatimtab}

presumably \mono{\$hashref} is a hash reference, and \mono{\$hashref->\{'files'\}} yields an array reference. 
However, Perl is smart in that by executing the above statement it will automatically create all the necessary
data structures and references to fulfill this statement if they do not yet exist. This is known as 
\term{autovivification}. In other words, Perl essentially executes the following statement when \mono{\$hashref}
doesn't exist: \\

\begin{verbatimtab}[4]
$hashref = {
	'files' => [
		'index.html',
	],
};
\end{verbatimtab}

\section{Pass By Reference}

Recall that Perl combines the input parameters into a single list. Similarly is the case when a subroutine 
returns a list of scalars to the caller. Therefore, you cannot pass multiple lists to a subroutine as you 
cannot separate them into respective lists. References are useful in this regard because, no matter how complicated
the underlying data object is, they are simply represented by a scalar, and you can pass scalars easily as usual.
Moreover, passing by reference --- even if you copy it to another variable --- allows you to access and possibly
modify the underlying data object. Pass by reference is efficient because only a scalar value is involved in
parameter passing. When used with subroutine prototypes, subroutine invocation can never be more flexible than
ever. \\

Passing a reference is easy. Simply take the reference, and pass it as a parameter and get it back from \mono{@\_}
in the subroutine. With prototypes (and it is not invoked using the \mono{\&} form) the caller does not even need to
take the reference himself/herself if the corresponding symbol in the prototype is prefixed with the backslash \textbackslash\ 
symbol. The following example demonstrates both methods: \\

\begin{verbatimtab}[4]
sub passArgs (\%$) {
	my ($hashref1, $hashref2) = @_;
	# Both variables are now hash references
}

%myhash = ('key1' => 'value1', 'key2' => 'value2');
passArgs(%myhash, \%myhash);
\end{verbatimtab}

However, because prototypes may not be observed, depending on the way the subroutine is invoked, you may wish to
require the caller to take the reference and pass the reference instead of relying on prototypes, which is in my 
opinion the safest way to go at present. \\

Perl does not support named parameter passing, but some programmers may also wish to emulate it as follows, which
is recommended if you have to pass a number of parameters to a subroutine. \\

\begin{verbatimtab}[4]
sub somesub (%) {
	my %params = shift;
	# All parameters now in %params.
	my $filename = $params{'FILE'};
	my @args = @{$params{'ARGS'}};
}

somesub(
	'FILE'	=>	'/bin/ls',
	'ARGS' 	=> 	[
		'-l',
		'-R',
		'/home/cbkihong',
	],
);
\end{verbatimtab}

The advantage is you don't need to remember and follow a predetermined ordering of parameters because there is 
no ordering in a hash. \\

\section{How Everything Fits Together}

Here, let us consolidate the concepts you have learned in this and the previous chapter. This is also an appropriate
opportunity to form a more complete picture as to how they all fit together. \\

By now you should already have a clear separation of the names and their underlying data objects. Data objects
exist independently from variable names as seen in programs. They are linked together by an association, or in
other words, a binding. Bindings of lexical variables are determined and fixed in the compilation phase, before 
a program is even executed. Which data object a lexical variable is bound to is solely determined by the nesting
of environments. Bindings of dynamic variables, including those declared with the \mono{local} modifier are resolved
at runtime from the symbol table, and are dependent on the call stack during program execution. \\

Creating references to a data object actually implies establishing additional access paths to it. In general, you
can access a data object in two ways. The first way is to access it through a variable which is visible and is
bound to the data object. The second way is to access it through dereferencing a reference variable which points
to the data object. Perl maintains the number of associations to every data object to determine when they should
be freed. Simply put, Perl would destroy a data object when the number of associations to a data object drops to 0.
This indicates it cannot be accessed from within the program anymore, and can therefore be safely destroyed. 
Consider this example: \\

\begin{lstlisting}[numbers=none,backgroundcolor=\color{CodeBackground}]
sub createArray () {
	my @array = (1, 2, 3);
	return \@array;
}

{
	my $arrayref = createArray();
	print scalar @$arrayref, "\n";
}
# $arrayref and underlying object destroyed 
\end{lstlisting}
\addvspace{\baselineskip}

In the \mono{createArray()} subroutine, a data structure in the form of an array is created which holds the 
three elements, and a lexical array variable \mono{@array} is created that associates with the array. Before
the \mono{return} function is executed, a reference to the array is created, which adds an association to the
array. By the time the \mono{return} function has been executed, the lexical association to the array has been 
destroyed. However, because a reference to the array still exists, the array is not deallocated. Therefore, 
when the number of elements of the array as accessible through the lexical array reference is \mono{print}ed on line 8
the value displayed is still 3. However, at the end of the block the lexical array reference is destroyed, so
the reference count to the array is now 0, and the array object is also destroyed. \\

% TODO: self-referential structures

\section{Typeglobs}

In the previous chapter we had a brief introduction to typeglobs. A typeglob represents an entry on the symbol
table and stores a list of references to data objects with the same name. In this section, we describe how you
may use typeglobs in your programs. In many cases, you seldom have to mess with typeglobs anymore as references
are more convenient and flexible. \\

Package variables, including those declared with \mono{local} are resolved from symbol tables. You can use 
typeglobs to create symbol table aliases. For example, \mono{*array = *myarray;} causes referencing operations
on the symbol \mono{array} to be resolved through the symbol table entry of \mono{myarray} instead. \\

\image{!hbt}{0.7\textwidth}{!}{images/globalias.eps}{Symbol Table Aliasing}{fig:globalias}

This causes \mono{\$array} to refer to \mono{\$myarray}, \mono{@array} to \mono{@myarray} and \mono{\&array} to
\mono{\&myarray} etc. However, you rarely would like to create an alias for all types in practice. You can actually
assign a reference of the desired type to a typeglob to replace the existing one. In Section~\ref{sec:prototype}
we wrote an \mono{insert()} subroutine that allows you to insert a list into any given array at any arbitrary 
position. You may also rewrite it in this way to make use of typeglobs: \\

\begin{verbatimtab}[4]
sub insert (\@$@) {
	local *myarray = shift;		# not my!!
	my ($pos, @list) = @_;
	return splice(@myarray, $pos, 0, @list);
}
\end{verbatimtab}

Note that, unlike references, accessing through a typeglob does not require any dereferencing. With a typeglob
entry in place you simply replace the \mono{*} symbol with whatever type symbol that is required for the type.
Some people may consider it convenient as a result. \\

Also note that you cannot use a lexical variable, that is one declared with \mono{my}, to represent a typeglob because
a typeglob is a symbol table entry which by nature cannot be lexical. However, this does not prevent you from 
assigning a lexical reference variable to a typeglob, though. \\

Finally I would introduce to you the \mono{*foo\{THING\}} notation, which you have already seen in the previous chapter
in passing using \mono{*INC} as an example. By using this notation you can get the individual references held in
a given typeglob \mono{foo}. Replace \mono{THING} with the name of the type. The table below lists the possible types and their
names: \\

\begin{table}[htbp]
\begin{center}
\begin{tabular}{ll}
\hline
\textbf{\mono{THING}}	& \textbf{Type} \\
\hline 
	\mono{SCALAR} & Scalar reference	(\mono{\textbackslash\$foo})	\br \\
	\mono{ARRAY} & Array Reference	(\mono{\textbackslash@foo})	\br \\
	\mono{HASH} &	Hash reference (\mono{\textbackslash\%foo})	\br \\
	\mono{CODE} &	Subroutine reference (\mono{\textbackslash\&foo})	\br \\
	\mono{GLOB} &	Typeglob reference (\mono{\textbackslash*foo})	\br \\
	\mono{FORMAT} &	Format Variables (Not covered in this tutorial) \br \\
	\mono{IO} &	Filehandle \br \\
\hline 
\end{tabular}
\\[\baselineskip]
\end{center}
%\caption{Alternative Syntax for Dereferencing}\label{tab:dereference}
\end{table}

The notations in parentheses represent an alternative way of accessing them, using references. Because of the
absence of alternative ways to get the reference to a filehandle, \mono{*foo\{IO\}} is most probably the only
one that is more widely used. This is used when a file handle needs to be passed to and from a subroutine. We will
talk about filehandles and the generic input/output mechanism at a later time. \\

While typeglobs are still useful in modern Perl programming, you are generally advised to use them only if you
have good reasons to do so, especially if that purpose can be fulfilled with other means such as references. 
First, typeglobs cannot be lexical variables while reference variables can. Also, typeglobs cannot be used
to create complex data structures that are possible with references. \\

Now you should have the fundamental knowledge to proceed to object-oriented programming. \\

\section*{Summary}

\begin{summary}
\item Reference is a scalar value whose value is the address of a data structure.
\item A reference is created by prefixing the \mono{\bs} symbol to a data object.
\item An anonymous array is an array reference, which can be constructed by a pair of square brackets \mono{[]}.
\item An anonymous hash is a hash reference, which can be constructed by a pair of curly braces \mono{\{\}}.
\item An anonymous subroutine is a subroutine reference, constructed by a subroutine definition without specifying a name.
\item A data structure of arbitrary complexity can be easily implemented in Perl by using hash and array references as building blocks.
\item You may access the underlying data object through a reference by dereferencing it.
\item Pass by reference refers to the practice of passing a reference of a data structure as argument to a subroutine, which is the best way to pass an array or hash to a subroutine while not having its elements merged into \mono{@\_}.
\item Named parameter passing may be emulated by passing all name-value pairs through a hash.
\item Creating references to a data object actually implies establishment of additional access paths to it. Perl maintains a reference count for all data objects and they are not destroyed until the reference count drops to 0.
\item A typeglob represents an entry of the symbol table and stores a list of references to data objects with the same name.
\item References stored in a typeglob may be accessed using the \mono{*FOO\{THING\}} syntax.
\end{summary}
