#!/usr/local/bin/perl

#    This is a simple program with a large number of comments to help you
# understand some basic Perl commands dealing with screen output, keyboard
# input, and file accessing. It asks you for a file name, checks that it
# exists, sorts it in memory by lines in ascending order according to the
# first word, and then creates a new file containing the sorted data.
#
#	       Copyright(C)1999,2001 by Daniel B. Sedory


#    Each extended comment here most often refers to the line(s) of code
# below the comment.
#
#    Unless specified otherwise, a print command sends data to the 
# "Stadard Output" device (usually a display screen).

print "What file do you wish to SORT? ";

# The "Standard Input" device is the keyboard. In this case whatever you
# type in at the keyboard is assigned to the variable $inpfilename when
# the program detects that you have pressed the <ENTER> key -- sending a
# CR (carriage return) and LF (line feed) or "new line" to the program.  

$inpfilename = <STDIN>;

# This next line employs "pattern matching" and "substitution" to remove
# the "new line" character from the end of our input -- which is placed
# there when we press the <ENTER> key.  The =~ symbol is called the
# "pattern binding" operator and it binds the operand on the left side
# (in this case our input line) to the substitution operation on the right
# side.  This is a key operation in Perl programs and you should review as
# many examples as you can find after reading all about pattern matching
# and substitutions.  Essentially this line means: search for the \n ("new
# line" character) in $inpfilename, and replace it with nothing (there is
# nothing between the // at the end of the expression); thus effectively
# removing it from our input.

$inpfilename =~ s/\n//;

#    NOTE: There are always different ways to do the same thing in Perl.
# As a matter of fact, "TIMTOWTDI" (pronounced: Tim-toad-y) or "There is
# more than one way to do it" is a Perl Motto!
#    I wanted you to learn something about "pattern binding" and matching
# in the example above, but the problem of ridding input data of the "new
# line" character is almost always taken care of by using the "chop"
# function like this:
#
# chop($inpfilename);
#
# The "chop" function always removes the last character from the variable.
# (Note that "chop" changes $inpfilename without using an assignment
# operator.)   

#          What Happens if you Enter a Non-existent Filename?
#
# The two || characters stand for a logical OR which is used in kind of a
# tricky way here:  If Perl can open the file you specified, then there's
# no need to evaluate the second half of the line; it's already TRUE.  If
# it can't open the file, then it needs to evaluate the second half of the
# expression which tells Perl to "die" (or halt) after printing the error
# message.  "FILE" is just a label or "handle" used to refer to the input
# input file here, and could be anything else you wish to name it. The <
# symbol next to the filename means we are going to READ from the file
# instead of write to it.

open (FILE, "<$inpfilename") || die("Could not open $inpfilename file");

# Note that Perl often prints its own error messages (especially if you
# are using the Debug parameter!) and entering the name of a non-existent
# file or simply pressing the <ENTER> key will often result in an output
# similar to this:
#
#    Could not open  file at sortdata.pl line 56, <STDIN> chunk 1.

# This next line reads in the whole file, assigning each line of the file
# as an element within the array " @lines ."  The first line of the file
# could now be referenced as @lines[0] and the second line as @lines[1]
# etc., but we won't need to refer to individual lines for this program.

@lines = <FILE>;
close(FILE);

print "SORTED output file will be called sorted.txt\n\n";

# When you open a filename with the symbol > in front of its name, it not
# only means we're going to overwrite everything in that file if it already
# exists, but actually create a new file (named sorted.txt in this case)
# if the file doesn't exist.   If you're working in a directory with very
# important files, you should add some code that checks for the existence
# of a file named 'sorted.txt' and give the user the option of overwriting
# it or exiting the program.

open(PIPS, ">sorted.txt");

# Here is the main function of the program: SORT (an array); saving the
# sorted data in the same array.

@lines = sort (@lines);

# Rather than sending data to the screen, this next print command writes
# the contents of the sorted array @lines to the file sorted.txt, since we
# have referenced it with the same file handle, PIPS, in the open function
# above.

print PIPS (@lines);
close(PIPS);

# The following two lines are just a quick and easy way to keep the program
# from halting, so you can read the screen output (print statements) above
# if you're working in a DOS-Window (which often closes automatically if
# you execute the program - by clicking on it - from the RUN box or a File
# Explorer window; not the case if you open a DOS-Window and use the DOS
# Command prompt instead).

print "Press the <ENTER> key to quit!";
$pause = <STDIN>;

exit;

# In summary, the whole program could be made more useful by removing the
# unecessary print statements and using the chop function to shrink it down
# to just this:
# ----------------------------------------------------------------------
#	#!/usr/local/bin/perl
#
#	print "What file do you wish to SORT? ";
#	$inpfile = <STDIN>;
#	chop($inpfile);
#
#	open (FILE, "<$inpfile") || die("Could not open $inpfile file");
#
#	@lines = <FILE>;
#	close(FILE);
#
#	open(PIPS, ">sorted.txt");
#	@lines = sort (@lines);
#	print PIPS (@lines);
#	close(PIPS);
#
#	exit;
# ----------------------------------------------------------------------


# Copyright(C)1999,2001 by Daniel B. Sedory