Title:    Programming CGI Scripts in Perl
Author:   David C. Uhrig
Contact:  E-mail - david@eysle.cruciblegames.com
          ICQ# - 8876126
          AOL IM - Doomduer
Version:  1.0
Released: 6/17/2001

-----------------------------------------------------------

Hello and welcome to this tutorial. Hopefully you will find
it helpful in your programming in Perl. Perl isn't as
difficult of a language as most people make it out to be,
but enough of the chit-chat and lets get to the real reason
you're looking at this document.


First off, a few things that you will need:

1) A text editor, such as Notepad.
2) A place to run and test your Perl scripts. For this, I
recommend Freedom2Surf, http://www.f2s.com, they are a free
web service provider who supply users with Perl, PHP,
mySQL, PostgreSQL, SSI, 20 Mb of space and all without
banners. If you already have a web site in which Perl
scripting is enabled, use that.


Extra things which come in handy is having your own Perl
interpreter to debug your code before you upload it and
test it on the web. To get this, follow these instructions:

1) Go to http://www.perl.com and download the latest STABLE
version of Perl that you can find and unzip it into it's
own directory.
2) Go to http://www.activestate.com and download the latest
FREE version of Active Perl. Install it and allow it to
detect the Perl directory on your hard disk.

Once you have done these things, to test your Perl scripts
you will open up an MS-Dos window, go to the directory your
Perl script is located in, and type in the following at the
command prompt: "Perl <filename>" substituting <filename>
for the name of your script. NOTE: in order for this to
work, your scripts must end in either .cgi, .pl, or .pm.


Now that we have you all setup, onto some of the basics.
We're going to use the typical "Hello World!" script that
has become the standard, it seems, as a starting point for
every programming language.

Open your text editor and copy the code below in and save
it as "hello.cgi":


#!/usr/bin/perl

print "Hello World!";

exit(0);


Open up your MS-Dos prompt and run your script by going to
the directory which it is located in and entering "Perl
hello.cgi" into the command line. The output of the script
should look like this:

C:\David\My Tutorials\perl1.0>perl hello.cgi
Hello World!
C:\David\My Tutorials\perl1.0>

Lets look at that simple 5 lines of code and see what it
is actually doing:

1| #!/usr/bin/perl
2|
3| print "Hello World!";
4|
5| exit(0);

1| This is used on a web server as the path to the server's
   Perl interpreter, such as Apache. #!/usr/bin/perl is the
   most standard.
3| The Perl interpreter sees the command "print" and takes
   whatever is between the quotation marks and prints it to
   the screen. Variables can be printed inside of quotation
   marks along with nearly any standard character. The
   exception to these are " ' $ @, #, and \. Each of these
   have their own special uses in Perl and must be escaped
   by the use of a backslash (\) in front of them for them
   to be printed to the screen or used in a variable. The
   semicolon at the end tells the system that it is the end
   of any information and/or commands being presented on
   that current line. All command lines must end in a
   semicolon.
5| The exit(0); command tells the script to end. It is more
   useful in the middle of a script where you need it to
   stop immediately.

On the explanation for line 3, I discusses 5 characters
which have their own special uses and purposes in Perl.
Below are descriptions of what each does and is used
for/in:

   " and ' - A double and single quote are both used to
             contain information within a string or to
             contain information which will be printed to a
             user's screen. Any information not enclosed
             within a double or single quote will be
             interpreted as a command, and more often than
             not errors within your script will occur.
   #       - # is used to comment out information. Anything
             on a line AFTER a # will not be interpreted by
             Perl. This comes in handy when you want to
             leave notes about your program within it to
             tell others what you are doing in this
             section. Also, it is helpful for debugging and
             error testing so that you only have to let the
             interpreter deal with where you are having
             problems.
   $       - The Dollar sign is used in Perl to represent
             any single-line variable. Variables may be
             declared at any time and may be written over
             with new information at any time as well.
             Variables will be discussed more later on.
   @       - @ is used to represent an array of
             information, or is also known as a
             multiple-line variable. This is commonly used
             when gathering information stored within a
             file. Arrays will be discussed more later on.
   \       - In order to have a backslash appear in what
             you are printing, you must escape the
             escaper, or type in \\.

Those are a few things to look out for, and can be a real
pain to find if you forget to escape them (place a
backslash, \, before them).


Next, let's take a low-level look at variables. Variables
are strings which contain information which can be used
repeatedly. To add information to a variable, you, on a new
line, enter a dollar sign followed by the name of your
variable. What you have just typed is how you will access
what you are about to store in your variable. To store
information with in the variable, after you've typed in
your dollar sign and name, place an equal sign followed by
a double quote. After this first double quote, enter any
information you wish to store in your variable (Remember to
escape " ' # $ and @) and follow it with another double
quote immediately followed by a semicolon.

Lets do a small exercise with this. Open your text editor
and create a new file. You are going to write a script
which will create a variable named $variable which will
contain the string "This is a Variable!" Once you have done
this, tell the script to print the contents of $variable to
the screen. The answer to this is show below, but it is in
your best interest to attempt to code it yourself.
Remember! You can print variables within the quotations of
the print statement. Once you have coded it, save it as
variable.cgi and run it from your MS-Dos prompt.


1| #!/usr/bin/perl
2| 
3| $variable="This is a Variable!";
4| 
5| print "$variable";
6|
7| exit(0);

The following is what you should see on your MS-Dos prompt:

C:\David\My Tutorials\perl1.0>perl variable.cgi
This is a Variable!
C:\David\My Tutorials\perl1.0>

1| This is the path to the server's perl interpreter.
3| This is where you declare your variable $variable and
   tell the system to make it equal "This is a Variable!"
   Notice the semicolon at the end of the line after the 
   double quote. If it is before the double quote, the
   system will think it is a part of the string.
5| The variable $variable is printed to the screen. Again,
   notice that you can include variables within quotes.
7| The script is ended.

Feel free to mess around with use of declaring variables
and printing them. Try to create two variables and have the
system print both of them. Also attempt mixing printing
variables along with regular text.


Next, I'd like to discuss syntax and manipulation of
variables. This will be a hefty section, so make sure you
understand everything prior to continuing!


Variables can be manipulated in many different ways. For
instance, you can replace a common sequence with something
else, you can split them at a common sequence (which is
helpful for FlatFile Databases), add things to the end
(and start) of them, find their length, and if the
variables contain numbers you can change them to the
closest integers, add, subtract, multiply and divide them,
and even more. This is one of the good parts: data
manipulation, namely (right now) that of variables. Lets
take a look at the first of things I mentioned, replacing
a common sequence with something else.

Lets say that you have a list of one-word items separated
by spaces. Now because it is just a run-on of words with no
real breaks, it is difficult to read. You want to replace
these spaces with a comma followed by a space. This is a
fairly common problem, but the question is: how do you
replace " " with ", "? You would use the following command:

$variable=~ s/S/R/g;

Where "S" is what you are searching for, and "R" is what
you are going to replace it with. For the problem presented
in the paragraph above, lets say that your list of words
was called $list. To solve your problem you would enter the
following:

$list=~ s/ /, /g;

This is called a search and replace string. It does exactly
what I explained: searches the variable for your criteria,
which is what is between the first and second slashes, and
if it finds any it replaces it with what is specified
between the second and third slashes. If it doesn't find
anything that matches your search, then the variable
remains unchanged.

Next, lets return you to your days of Grammar School and
ask the question, what's 2+2? In perl, it's as simple as
what I just said, with the addition of a few sets of
parenthesis. If you wanted to add two and two, you'd setup
something like this:

$answer=(2)+(2);

$answer would now equal 4. If you wanted to do
multiplication, division, or subtraction it would work in
much the same way. NOTE: Order of operations DO apply, so
if you wanted to add 2 and 5 THEN multiply them by three,
your code would look like this:

$answer=((2)+(5))*(3);

$answer in this case would equal 21. If you wrote it just
as (2)+(5)*(3), you would get 2+15 which would be 17.

But wait, what happens if you were to divide 3 by 2 and got
1.5, but you wanted to only take integers and drop the
decimal off of a number? There is a command for this as
well. The int command does that: it rounds a number up to
it's nearest whole retaliative. So 1.5 would be 2, 7.324
would be 8, and -4.3 would be -4. The syntax for this is
shown below:

$answer=int $answer;

OR

$variable=int $answer;

Notice that you don't have to make the variable name the
same as the variable you are taking the integer of.

Another useful option built into perl is the length
function, which counts how many characters long a variable,
or even regular text, is. The syntax for this is:

$length=length ($variable);

Where $length will be the number of characters contained in
the variable $variable.

Before I continue, I'd like to show you how to make a new
line in information being presented. This is especially
helpful for organizing code for web programming so that the
source is actually readable. To do this, you add the
linefeed character to the end of a variable or print
statement, which is \n. Every time the system sees a \n,
everything past that point is on a new line. If you put
\n\n into your code, you would have your information, a
blank line, then another line with your next set of text.

With this, it's time for another project. Open up your text
editor and write a script that will do the following:
- Take 15 and add the total of (4)*(17) to it.
- Take that number and divide it by it's length.
- Take this new number and replace every 4 with a 6.
- Take this last number and take it's integer.
- Also, print out the result after every step on a new
  line.
- Close the file.

Save this file as string.cgi and run it in your MS-Dos
window. The following should be the result:


C:\David\My Tutorials\perl1.0>perl string.cgi
83
41.5
61.5
61
C:\David\My Tutorials\perl1.0>


The code I used to get this result is shown below:


1 | #!/usr/bin/perl
2 |
3 | $number=(15)+((4)*(17));
4 | print "$number\n";
5 |
6 | $number1=($number)/(length ($number));
7 | print "$number1\n";
8 |
9 | $number1=~ s/4/6/g;
10| print "$number1\n";
11|
12| $number2=int $number1;
13| print "$number2";
14| 
15| exit(0);


1 | Path to Perl.
3 | Do the initial math for 14+(4*17).
4 | Print result to screen followed by a new line.
6 | Do next set of math. Notice how you can include the
    length function within a set of commands. The same
    works for the int command.
7 | Print result to screen followed by a new line.
9 | Replace every 4 with a 6.
10| Print result to screen followed by a new line.
12| Take the integer of the number.
13| Print the result out. (No new line as it is the end of
    the script)
15| End script.


Next up: Files. Writing to them and reading from them.
To do this, you use the open command. There are a few
different ways you can open a file, each with their own
purposes. They are listed below along with their own
syntax:

open([OPENINGNAME], "[LOCATION]");   - This syntax is to
                                       just open a file for
                                       reading.
open([OPENINGNAME], ">[LOCATION]");  - This syntax erases
                                       the contents of the
                                       file and begins
                                       writing at the
                                       beginning.
open([OPENINGNAME], ">>[LOCATION]"); - This syntax begins
                                       writing at the very
                                       end of the file.

Where [OPENINGNAME] is the name to which you assign this
particular file procedure (This can be basically anything
and comes in handy the most when you have multiple files
open to be written to at once. I typically just use FILE
for it's value) and [LOCATION] is the location of the file
on the server. For [LOCATION], I prefer to give it a
variable name incase it is needed again further down.
These all look quite similar, but do extremely different
things. Lets go through each one and display working
examples of each.

To open a file in the same directory as your script that is
named myfile.txt. We want the contents of this file to be
placed in an array name @contents. The first two parts (of
four) would be this:

$fileopen="myfile.txt";
open(FILE, "$fileopen");

Next, you need to assign the contents of your file to an
array. Remember, an array begins with an @ and contains
more than one line of information. The syntax of this is
shown below as step 3 in open the file for reading.

@contents=<FILE>;

The name between the pointed brackets is the same as
whatever [OPENINGNAME] is. Finally, since you are finished
reading from the file, you need to close it.

close FILE;

Again, where FILE is should be the same as [OPENINGNAME].
The complete set of code to accomplish this is:

$fileopen="myfile.txt";
open(FILE, "$fileopen");
@contents=<FILE>;
close FILE;

To print the ENTIRE contents of a file to the screen, you
would print the array, @ and all. Example:

print "@contents";

Now lets say you want to write to a file the contents of
the variable $myvariable. For this, you'd place a closing
pointed bracket before the [OPENINGNAME], as shown in the
second syntax for opening files. Assuming that you wanted
to write to myfile.txt again, your code for this task would
be:

$fileopen="myfile.txt";
open(FILE, ">$fileopen");
print FILE "$myvariable";
close FILE;

If you want to write to the end of a file, it is exactly
the same as writing over a file from the beginning, only
there are two closing pointed brackets instead of one. The
syntax is shown below:

$fileopen="myfile.txt";
open(FILE, ">>$fileopen");
print FILE "$myvariable";
close FILE;

We know how to read and write from a file now, so lets see
if we can't get a little something to work, ok? Open your
text editor and follow these steps to create and write to
a file, read from it, write to the end of it, then read it
again:
- Create a variable containing this list, separated by a
  comma and a space (, ) containing the following items:
  Dog, Cat, Horse, Man.
- Create a file called testfile.txt in the same directory
  as your script and write the variable you just created in
  it with a linefeed at the end.
- Open the file back up and read from it this time. Print
  the information to the screen.
- Take your variable and replace each comma and a space
  (, ) with a linefeed.
- Open your file again and print your variable to the end
  of it.
- Open your file and print the contents of it to the screen
  once again.
- Close the file.

Don't forget to run it in your MS-Dos window!


1 | #!/usr/bin/perl
2 | 
3 | $variable="Dog, Cat, Horse, Man";
4 | 
5 | $printfile="testfile.txt";
6 | open(FILE, ">$printfile");
7 | print FILE "$variable";
8 | close FILE;
9 | 
10| open(FILE, "$printfile");
11| @contents=<FILE>;
12| close FILE;
13| 
14| print "@contents";
15| 
16| $variable=~ s/, /\n/g;
17| 
18| open(FILE, ">>$printfile");
19| print FILE "$variable";
20| close FILE;
21| 
22| open(FILE, "$printfile");
23| @newcontents=<FILE>;
24| close FILE;
25| 
26| print "@newcontents";
27| 
28| exit(0);


The output should look something like this:


C:\David\My Tutorials\perl1.0>perl write.cgi
Dog, Cat, Horse, Man
Dog, Cat, Horse, Man
 Dog
 Cat
 Horse
 Man
C:\David\My Tutorials\perl1.0>


Lets look at the code line by line.

1 | Perl interpreter.
3 | Declaring variable that will contain our list.
5 | Naming the variable that we will use to open our file
    every time.
6 | We open the file to write at the beginning, erasing
    whatever contents were previously within it.
7 | Writing the contents of the variable $variable to the
    file.
8 | Closing the file.
10| Opening the file again, this time to read from it.
11| Assigning the information within the file to an array.
12| Closing the file.
14| Printing the contents of the array @contents, which
    contains information from testfile.txt.
16| Search and replace string to change every comma and
    space (, ) to a linefeed.
18| Opening the file again, this time to write new
    information to the end of it.
19| Writing new information to the end of the file.
20| Closing the file.
22| Opening the file again, this time to read from it.
23| Assigning the information within the file to an array.
24| Closing the file.
26| Printing the new array, @newcontents, to the screen,
    which contains everything that was just in testfile.txt
    plus what we added to the end of it.
28| Ending Script.


Ok, now we have arrays and we know they are multi-line
strings. How do we access the information from just one
line of an array? That is simple, the syntax is as follows:
$ARRAYNAME[LINE], where ARRAYNAME is the name of the array
(minus the @) and LINE is the line number for which the
information is on. NOTE: 0 is considered the first line of
an array! Do not forget this as it is very crucial! If you
had an array named @myarray and wanted to get information
from the 3rd line, the variable would be $myarray[2].
These variables can be treated in the exact same way as any
other variable.

Arrays are used for many different things. Lets say you had
a file and you wanted to do the exact same thing to each
line in the file. You would make an array by loading the
file, and then would use the foreach command. Here is an
example with the file we just created in the previous
section:


1| $printfile="testfile.txt";
2| open(FILE, "$printfile");
3| @contents=<FILE>;
4| close FILE;
5| 
6| foreach $line (@contents) {
7| 	print "$line";
8| 	}


That function would print each line of the file to the
screen. Simple enough, right? Lets take a look at lines
6-8 though, because they are quite new.

6| This is the foreach command. $line is what the line will
   be called between { and }. The array you are taking each
   line of goes between parenthesis directly after the
   variable name, in this case $line. Everything after { is
   within this function.
7| The line is printed.
8| This is the end of the foreach statement and is
   designated by a }. Everything after } is not inside of
   this statement. NOTE: The last value of the variable
   designated for the string, in this case $line, will
   still keep its value after the foreach statement has
   ended.


Another command that is commonly used is for. The for
command runs through doing the same thing repeatedly until
the argument is no longer true. If you wanted to do the
same thing 10 times in a row, the syntax for such a command
would be:


1| for ($i = 1; $i < 10; $i++) {
2|	 [COMMANDS]
3|	 }


In the above code, two new concepts are introduced: the for
command in action as well as "++" in line 3. Lets look at
this line by line:

1| We're stating that the variable $i is equal to 1. Notice
   how when you are setting variables equal to numbers that
   you do not need quotations. The for command only sets
   the variable $i value to 1 at the very beginning. It
   then takes the value of $i and determines whether it is
   less than 10 (You could use greater than (>), is not
   (!= OR ne), or is equal to (== OR eq) in this position
   as well. If the value is true (1 < 10), then we approach
   the next section. Any variable with a ++ at the end of
   it means auto-increment, or add 1 to it. So after this
   point, $i is equal to 2. The { denoted the start of the
   commands within this command.
2| Where [COMMANDS] is, you can place any set of syntax or
   commands that you would like to occur.
3| The } denotes the end of the command. It then loops back
   to the beginning again (line 1) and runs through $i < 10
   again. If still true, the process is repeated. If false,
   the script continues on at the line after the }.

For loops are handy for things like records, where you only
want to save say the past 25 entries. For that, line 1
would remain the same except $i < 10 would become $i < 25.


The one-time version of a for loop is the if command. This
command consists of a possible of 3 parts, where the first
must be used no matter what. They are:

1) if    - This is used as a true/false statement, just
           like simple questions and yes or no answers: if
           (this) is the same as (that) then you need to do
           (these things). An example is below.

1| $variable="Hi";
2|
3| if ($variable eq "Hi") {
4| 	print "$variable";
5| 	}

           This asks the system a question, does the value
           of $variable equal "Hi" (Line 1)? If it does,
           begin the commands (the }), then print the value
           of "$variable" (Line 2). After this is done,
           finish this thought (the }). Other things you
           can use in the place of eq are shown below with
           what they do:
           
           eq - If part-A IS equal to part-B, then do what
                is between { and }.
           == - Same as eq.
           ne - If part-A IS NOT equal to part-B, then do
                what is between { and }.
           != - Same as ne.
           <  - If part-A has a LESSER value than part-B,
                then do what is between { and } (Numbers
                only).
           =< - If part-A has the SAME or LESSER value than
                part-B, then do what is between { and }
                (Numbers only).
           >  - If part-A has a GREATER value than part-B,
                then do what is between { and } (Numbers
                only).
           => - If part-A has the SAME or GREATER value
                than part-B, then do what is between { and
                } (Numbers only).
           
           Lets say you have a number of different
           specifications which must be met in order for
           the commands within an if statement to be run
           though, you would write all of them on the same
           line, but they would be separated with &&, which
           basically tells the system AND. An example is
           shown below:

1| $variable="Hi";
2| $newvar="10";
3|
4| if ($variable eq "Hi" && $newvar > 0) {
5| 	print "$variable";
6| 	}

	   In lines 1 and 2 variables are being declared.
	   In line 4, it is asking the system two questions
	   at once: is the value of $variable "Hi" and is
	   $newvar greater than 0? If it is, then it will
	   do the actions specified between { and }.
	
	   At the other end of this though is the dilemma
	   of what if I have many different specifications,
	   but only one needs to be met to invoke the
	   procedures enclosed within the if statement?
	   Rather than writing an if statement to
	   accommodate each of these separate
	   specifications, they would be in the same line
	   as the first statement, but this time would be
	   separated by ||, which tells the system OR. An
	   example is shown below:
	
1| $variable="Hi";
2| $newvar="20";
3|
4| if ($variable eq "Hello" || $newvar < 21) {
5| 	print "$variable";
6| 	}

	   In lines 1 and 2 we are, again, declaring
	   variables. In line 4, the system is being asked
	   if the value of $variable is "Hello", which it
	   is not, or if the value of $newvar is less than
	   21, which it is. If one or more of these
	   statements are true, then to run the commands
	   between { and }.

2) else  - After the completion of an entire if statement
           (from lines 4-6 above), you have the option to
           ask another question. The else command tells the
           system that if the specifications within if are
           not met, then to do what is between { and }
           after else. Here is an example:

1| $variable="Hi";
2|
3| if ($variable eq "Hello") {
4| 	print "$variable";
5| 	}
6| else {
7| 	print "Goodbye";
8|	}

	   In line 1 you declared your variable. In line 3
	   you asked the question does $variable have the
	   value of "Hello". If it does, you run though
	   lines 4 and 5 (then jump to line 9). If it does
	   not, you move to the end of the statement and
	   encounter else. Else asks the question were the
	   specifications presented within the if statement
	   met? If them were not, then do this set of
	   commands instead, which are lines 7 and 8. The
	   else statement can only be used once, must be
	   after an if or an elsif statement, and as the
	   very last option in an if statement. (So one
	   order could be if, elsif, elsif, else. After
	   else that set of "questions" would be finished.)
	   
3) elsif - This is used directly after the if statement or
           after another elsif statement. It asks the
           question if the specifications in the prior if
           and/or elsif statements have not been met, try
           this set of specifications. If the result is
           true, then do this. An example is shown below.

1| $variable="Hi";
2| $newvar="Goodbye";
3|
4| if ($variable eq "Hello") {
5| 	print "$variable";
6| 	}
7| elsif ($newvar eq "Goodbye") {
8| 	print "$newvar";
9| 	}

	   In lines 1 and 2 variables are declared. In
	   lines 4-6, the initial question is asked and, if
	   the result is true, what is between { and } is
	   printed. In lines 7-9, if the answer to the
	   initial question is false (which it is in this
	   case), as second question is asked. If the
	   result of this question is true, then whatever
	   is between this next set of { and } is printed.
	   In elsif statements, just like in if statements,
	   you can have multiple questions separated by ||
	   and &&.
	   
	   After line 9, you could either stop asking
	   questions (as we did), ask another elsif
	   question, or place an else statement to wrap
	   things up. An example of this is shown below:

1 | $variable="Hi";
2 | $newvar="Goodbye";
3 |
4 | if ($variable eq "Hello") {
5 | 	print "$variable";
6 | 	}
7 | elsif ($newvar eq "" || $variable eq "") {
8 | 	print "Blank";
9 | 	}
10| else {
11|	print "Last resort.";
12|	}

	   "Last resort" would be printed to the screen
	   because none of the criteria between lines 4
	   and 9 matched.

It's project time once more. Now that you know a few more
commands in Perl, actually a lot more commands, lets see
if we can't get some use out of them. Follow these steps
and run your script in the MS-Dos window:
- Create a new script in your text editor.
- Open the file "testfile.txt" that we created in an
  earlier project.
- Use a foreach loop to print each line to the screen
  along with which line number it is on (this will be a bit
  on the tricky side and will require some thought.)
- Take the 3rd line of testfile.txt and ask the question
  "Does this variable equal Dog?".
- If it does, have the system print the sentence "Dog is
  equal to Dog."
- If it does not, ask the question "Does the 2nd line equal
  Dog or Human?".
- If this is true, have the system print the word "Yes".
- If it does not, then have the system print "No matches".
- End the script.
- Add a linefeed after EACH printing (including the final).


The result should appear similar to the following:

C:\David\My Tutorials\perl1.0>perl statements.cgi
1 Dog, Cat, Horse, Man

2 Dog

3 Cat

4 Horse

5 Man
No matches

C:\David\My Tutorials\perl1.0>

Notice that there is a blank line after "No matches" but
there is not one after "5 Man". This is because when we
created the original file, testfile.txt, we did not create
an additional line at the end of it. The source code that
I used to produce this is shown below:

1 | #!/usr/bin/perl
2 | 
3 | $myfile="testfile.txt";
4 | open(FILE, "$myfile");
5 | @lines=<FILE>;
6 | close FILE;
7 | 
8 | $i=0;
9 | 
10| foreach $line (@lines) {
11| 	$i++;	
12| 	
13| 	print "$i $line\n";
14| 	}
15| 	
16| if ($lines[2] eq "Dog") {
17| 	print "Dog is equal to Dog.\n";
18| 	}
19| elsif ($lines[1] eq "Dog" || $lines[1] eq "Human") {
20| 	print "Yes\n";
21| 	}
22| else {
23| 	print "No matches\n";
24| 	}
25| 
26| exit(0);

1     | Perl interpreter
3-6   | Opening file and assigning array.
8     | Clearing any data that MIGHT be within $i (a good
        habit to get in).
10-14 | Take each line of testfile.txt and print it. On
        line 11 we auto increment the value of $i and then
        print it before we print each line of testfile.txt.
16-18 | We ask the question "Is the 3rd line of
        testfile.txt 'Dog'? If so, tell us." And if not,
        we move on.
19-21 | We ask the question "Since the 3rd line of
        testfile.txt is not 'Dog, is the 2nd line of
        testfile.txt 'Dog' or 'Human'? Is so, tell us." And
        if not, we move on.
22-24 | If the prior are not true, then we print the
        information "No matches".


Those are all of the conditional statements you'll likely
need to use while programming in Perl. Earlier in this
tutorial I mentioned splitting a string apart by a common
pattern. When you do this, you create an array. The syntax
for such as operation is shown below:

@[ARRAYNAME]=split /[PATTERN]/, "[VARIABLE]";

What this does is it takes a string, [VARIABLE], and cuts
it up into pieces whenever the system sees [PATTERN] and
then places the result into an array, @[ARRAYNAME]. Notice
the comma after the second slash! This is very important
because it tells the system to move onto the next step of
the command.

There are a few different ways to plot out patterns. If you
want to split a variable up into individual characters,
then [PATTERN] would be nonexistent and your syntax would
be like this:

@[ARRAYNAME]=split //, "[VARIABLE]";

If you want to split a variable by non alpha-numeric, it is
a good idea to escape those characters just to be on the
safe side. Perl does wacky things when it splits variables
and adding in extra escape characters doesn't hurts or
hinders your code in this case. Lets have a little example.
We're going to take the variable $myvar and split it up
every time the system sees the word "but". The results will
then be added to the array @result:

@result=split /but/, "$myvar";

The split command gets even more useful if you know how
many different values you want. Lets say you have
information in $list about 4 people and the people are
always in the exact same order, which you know. These 4
people are John, Mark, Julie and Dan, in that same order.
Rather than split that list up and end up with a 4-line
long array, you can make a new variable for each person to
pull their own information out of this list. The syntax for
John, Mark, Julie and Dan if each person's information was
separated by a comma and a space would be:

($John,$Mark,$Julie,$Dan)=split /\, /, "$list", 4;

This will take the string $list and split it exactly 4
times where it finds ", " and will assign the information
up to the first occurrence of ", " to the variable $John,
everything between the first and second occurrence of ", "
to $Mark, everything between the second and third to $Julie
and everything after the third to $Dan. If the system only
finds say, one occurrence of ", ", then $John and $Mark
would remain the same, but $Julie and $Dan would both be
empty. NOTE: If you are assigning information to
independent variables and not to an array, you MUST have a
comma after the closing quote that holds the variable you
are splitting followed by the number of variables you will
make. Also please make sure that the number of different
variables you create ($John,$Mark,$Julie,$Dan) are the same
as the number specified at the end of the command.


Before I move onto how to do web programming with forms and
such, there are two more commands which I would like to
discuss. Those being require and die.

The command require is used for running other scripts or
Perl Modules from your current script. Creating modules
allows many scripts to use the same code without having to
add it to each script. This cuts down on the amount of time
your script is being run on the server by cutting out
unneeded code for being interpreted. The syntax for require
is shown below:

require ("[PATHTOSCRIPT]");

Where [PATHTOSCRIPT] is just that, the path to the script.
If I wanted to call the Perl Module time.pm to get the
server's time and date, and it was located in the
subdirectory /modules/, the code would look like this:

require ("/modules/time.pm");

The other command I want to discuss is the die command.
Just like the exit(0); command, it ends the script, only
with die you can explain why. Here is an example where I
use die along with require:

require ("/modules/time.pm") or die "Can not find module
time.pm";

The system tries first to locate the module, but if it can
not it tells the script to stop right where it is. The
reason is given between directory after 'or die' and is
contained within quotes.


Now we are going to begin wrapping this tutorial up, and
that is with the use of Perl Scripts on the web. First off,
for a perl script to run and function on a web server it's
permissions (CHMOD) must be set to 755 so that it may be
read from by everyone. 755 is the most common, but many
servers prefer 775 or 777. You'll need to check with your
server operation to determine what this is as well as the
path to the Perl interpreter (#!/usr/bin/perl).

Next, in order for any of the HTML you will be printing to
the user's screen to be seen, you must specify what kind of
information is being presented. For web pages, you will
need to have this appear before you attempt to print
anything to the user's screen (if you do not, you will
receive a 500 Internal Server Error):

print "Content-type: text/html\n\n";

That tells the server that you are printing text-HTML.
Other types are images, such as GIFs or JPEGs for counters
using SSI.

When a user fills out a form, the information within each
of the form objects is sent to your script in a raw,
unformatted form. This can be quite annoying, so many
people have written subroutines to format all of the
incoming information. Rather than explain how to do this
yourself, I'll show you what I use and how to get the
information from it.

Below is the subroutine get_form_data. This takes all of
the information that a user manually fills out and selects
and formats it so it is more-usable and readable than
before:

sub get_form_data {
	$list="";
	$buffer = "";
	read(STDIN, $buffer, $ENV{'CONTENT_LENGTH'});
	@pairs=split(/&/,$buffer);
	foreach $pair (@pairs) {
		@a = split(/=/,$pair);
		$name=$a[0];
		$value=$a[1];
		$value =~ s/%([a-fA-F0-9][a-fA-F0-9])/pack("C", hex($1))/eg;
		$value =~ s/~!/ ~!/g;
		$value =~ s/\+/ /g;
		$value =~ s/\r//g;
		$valuu=$value;
		$valuu =~ s/\n/\<BR\>/g;
		$datcopy="$datcopy\n$valuu";
		push (@data,$name);
		push (@data, $value);
		}
	%formdata=@data;
	%formdata;
	}

Place this at the end of your scripts after exit(0); which
use forms on a web page. At the top of your screen after
the first line, the path to the Perl Interpreter, place
this to activate the subroutine:

%formdata=&get_form_data;

From that point on, any and all information that was
submitted from your form will be accessible by the variable
$formdata{'[FIELDNAME]'} where [FIELDNAME] is the name of
the form object. Example: if we have a text field on our
form named userage and we wanted to get the information
that was entered into that field, our variable would be
$formdata{'userage'}.

The other subroutine that is used is get_query_data. This
takes any information that is in the URL to the script
(such as myscript.cgi?name=David&age=16) and sorts and
formats it so that it is readable in much the same way
get_form_data is. The subroutine for this is shown below:

sub get_query_data {
	my(%querydata);
	if ($ENV{QUERY_STRING} =~ /=/) {
	    my(@pairs) = split(/[&;]/,$ENV{QUERY_STRING});
	    my($param,$value,@data);
	    my($list) = '';
	    foreach (@pairs) {
		($param,$value) = split('=',$_,2);
		$param =~ s/%([a-fA-F0-9][a-fA-F0-9])/pack("C", hex($1))/eg;
		$value =~ s/%([a-fA-F0-9][a-fA-F0-9])/pack("C", hex($1))/eg;
		if ($param eq 'filename') {
			$list = "$list$value\t";
			}
		push (@data,$param);
		push (@data,$value);
		}
	%querydata=@data;
	if ($list ne '') { $querydata{'filename'} = $list; }
		}
	%querydata;
	}

Place this at the end of your scripts either before or
after get_form_data (if you use that) and after exit(0);
on the forms which use a direct URL or a method of GET
instead of POST. To activate this subroutine, place this at
the top of your script after the interpreter line:

%querydata=&get_query_data;

Getting information out of this is almost exactly the same
as it is for get_form_data. Instead of
$formdata{'[FIELDNAME]'} it is $querydata{'[FIELDNAME]'}.
So if you want to get the information inside of the field
name, you would use $querydata{'name'}.

Using those subroutines makes life much easier for your and
takes a lot of the pain and stresses of formatting the
results of a submitted form away.

As we near the end of this tutorial, I'd like to give a few
words of advice out about programming web scripts:

- When coding the HTML parts of your script, code them as
  you would if you were making a regular web page. By this
  I mean format them so that it is readable, and remember
  to use line breaks! If you do not, all of the information
  being presented might look alight in your browser, but
  when someone attempts to look at your source code it will
  be a nightmare of run-on HTML.
- Code HTML by the book. Do this so that all browsers can
  use your script and get at the information which they
  have come and used it for. Remember to use <HTML>,
  <head>, and <body> as well as their closing tags! Sloppy
  HTML is never a good thing and just because you have a
  Perl Script generating it on the fly every time is not an
  excuse to let it look that way!
- Modulate your scripts and commonly used parts. If you
  have an if statement with an else or a couple of elsif
  statements after it where each contain vast amounts of
  code, you might want to consider making the commands
  inside of each { and } into a module so that the
  interpreter doesn't have to run though too many extra
  lines of code that it doesn't need! I have had terrible
  experience with this happening and eating up a server's
  CPU and, eventually, crashing it. YOU WANT TO AVOID THIS
  IF AT ALL POSSIBLE!
- Finally, remember to escape the special characters ($, #,
  @, ", ', and \) we discussed at the beginning. Forgetting
  to do so, as well as not having your MS-Dos debugger or
  an on-site debugger working, will cause you to eat up a
  lot of time that could be spent coding, but instead spent
  looking for the one contraction in which you didn't
  escape the single quote. :)

This concludes the very first tutorial I have ever written
for any programming language or program. Feedback about it
is VERY appreciated. My contact information is at the top
of this document. :) Have fun with your web programming,
and the best of luck!