-----------------------
Exercise #4 for DAT2330 due April 16
-----------------------
-Ian! D. Allen - idallen@idallen.ca

Global weight: 4% of your total mark this term
Due date: 14h30 (2:30pm) Friday, April 16, 2004.

The deliverables for this exercise are to be submitted online on the
Course Linux Server using the "datsubmit" method described in the exercise
description, below.  No paper; no email; no FTP.

Late-submission date:  I will accept without penalty exercises that are
submitted late but before 09h00 (9am) on Monday, April 19.  After that
late-submission date, the exercise is worth zero marks; but, it must still
be completed and submitted successfully to earn credit in the course.

Exercises submitted by the *due date* will be marked online and your
marks will be sent to you by email after the late-submission date.
A sample answer will be posted online after the late-submission date.
This exercise is due on or before 14h30 (2:30pm) Friday, April 16, 2004.

-----------------
Exercise Synopsis
-----------------

    You will write a shell script to implement a date reminder service.

    When the script is executed, it will look in a reminder file and
    print lines matching the date.  The date defaults to today; but,
    other user-supplied dates can be given on the command line:

       $ ./exercise04.sh
       2004 Mar 30 Dentist appointment.

       $ ./exercise04.sh "April 2"
       2004 Apr 2 DAT2330 midterm test.

       $ ./exercise04.sh tomorrow
       2004 Mar 31 Dentist appointment.

    You could put this script in your .bash_profile and have it remind
    you of important dates, birthdays, tests, etc.
    
--------------
Specifications
--------------

Write an executable shell script on the Course Linux Server named
exercise04.sh that will implement the following specifications.

The script will be divided into two sections:

 I.  Handle command line input, user input, and input validation.

 II. Loop reading lines (from the date reminder file) and print the
     reminders that match the user-supplied date.

The two sections are described in detail below.

Follow the 9-part script format described in Notes file: script_style.txt

Build exercise04.sh ONE STATEMENT AT A TIME and test it after each line.
You will not be able to make it work if you write a dozen lines and
then try to debug it.  You will find the "-v" and "-x" options to bash
helpful to debug your script:  $ bash -u -v ./my.sh

Syntax description:
-------------------

 a) The first argument to this script is an optional date string.
    (If only one argument is present, assume it is the date string.)

    The user can set the date string to be any STRING accepted by the
    "--date=STRING" option to the GNU/Linux "date" command, including
    strings such as "yesterday", "tomorrow", "next week", "last month",
    etc.  See Appendix "A" to this exercise, below, for details.

 b) The second argument is an optional reminder file name.  The syntax
    of lines in the reminder file is given in Appendix "B" to this
    exercise, below.  (To supply the reminder file name as a second
    argument, you must also supply a date string as the first argument.)

I - Input and Validation:
-------------------------

 1. Print a good error message and exit the script if there are too
    many arguments.  [4 lines]

 2. The first optional argument to this script is a date string:

    If the first argument is present on the command line, use the first
    argument as the date string value.  If first argument is missing,
    the date string value should be set to the string "today".  [5 lines]

 3. Print a good error message and exit the script if the date string
    is empty (null string - no characters).  (Note: This is not a file
    or a file name.  The date string argument is a string of characters.)
    [4 lines]

 4. The second optional argument to this script is a reminder file name:

    Here is the pseudocode for this step [14 lines]:

    If the second argument is present on the command line
       Use the second argument as the reminder file name.
    Otherwise:
       Set the reminder file name to be the default name "reminders.txt".
       If that reminder file name isn't the name of an existing plain file
	   Display a warning message that the file isn't found
	   If standard input is a terminal
	      Get a new reminder file name from the user.
	      (... but quick-exit the script if given EOF by the user.)
	   Otherwise:
	      Set the reminder file name to be empty
	   Endif
       Endif
    Endif

    You can test whether or not standard input is coming from a terminal
    (from your keyboard) using the return status of the "tty" command.
    Suppress or throw away the standard output of the tty command;
    check only the return status of the command.

    Note that the reminder file name may end up being empty (the null
    string).  That's okay.  If the file name is empty, the script will
    read date reminder lines from standard input instead of from the file.

 5. If the file name entered by the user is *not* an empty string, do
    the actions in this step [16 lines]:
 
    Validate the file: make sure it is a non-empty, readable, plain file.
    Exit with a good error message if any of these tests fail.

    Open the file as standard input to the script using this new shell
    input redirection syntax:

       exec < XXXX || exit 1

    where XXXX is replaced in your script by the user-entered file name.

    After executing the above "exec" line, the rest of the script will
    behave as if you had typed "<XXXX" after the script on the command
    line.  In particular, input statements issued by the rest of the
    script will read lines from this file, not from the user's keyboard.

    Note that if the file name entered by the user is a null string, then
    no file will be opened in this step and no "exec" redirection line
    will be done and standard input to the script will not be changed.

 6. Pass the date string (from the start of the script) to the GNU/Linux
    date command using the appropriate --date=STRING option and save the
    date command output in a variable.  (See Appendix "A", below, to see
    examples of how the GNU/Linux date command works.)  If there is no
    output (a bad --date=STRING format string will mean no output and an
    empty variable), print a good error message about the unrecognized
    date format and exit the script.  [5 lines]

 7. Extract the month, the day, and the year from the saved date output
    variable in the previous step into three separate shell variables.
    Each of these three data items is a separate field, e.g. the month
    is the second field in the output of date.  To extract each field,
    you can send the date output variable into a pipe using the "echo"
    command, and repeat that for each of three extractions.  [3 lines]

    Each of the three variables will contain only the one extracted field:
    the day, the month, or the year.

    Note that the date string argument to the script is not used directly
    by the script.  The date string argument (e.g. "today") is first
    passed to the --date option of the "date" command, and the output
    of that is captured and split into day, month, and year fields.

At this point in the script, we have processed all the comand line
arguments (0, 1, or 2 of them) and made sure that the user's date and
file name are correct.

If there was a date reminder file name, we have opened that file onto
standard input of the script so that any subsequent input done by
the script will read reminder file lines from that date reminder file
(instead of reading the lines from the user's keyboard).

We have three shell variables containing the user-supplied month, day,
and year.  We will use these three variables to match dates read from
the date reminder file.

II - Read the date reminder file
--------------------------------

 8. If standard input is still a terminal (meaning that the user entered
    no reminder file name above and we are about to read his/her
    keyboard), warn the user with a prompt that date reminder lines will
    be coming from standard input (the user's keyboard).  [3 lines]

    You can test whether or not standard input is a terminal using the
    return status of the "tty" command (suppress the output of tty).

    Note that you only need to issue the prompt here in this step;
    the actual reading of input will come in the loop in the next step.
    Only print the prompt reminder if standard input is a terminal.

 9. Loop reading reminder file lines from standard input until EOF.

    Each reminder file line read should be split on blanks into five
    separate variables containing these five parts of the input line:

    EXAMPLE LINE:  18 Mar 2004 PRINT Dentist appt. downtown

      1) variable 1 <- the day of the reminder (e.g. 18)
      2) variable 2 <- the month of the reminder (e.g. Mar)
      3) variable 3 <- the year of the reminder (e.g. 2004)
      4) variable 4 <- the command word (e.g. PRINT)
      5) variable 5 <- the rest of the line (e.g. Dentist appt. downtown)
 
    Note that if there is an existing date reminder file, standard input
    will have been redirected to come from this open file, thanks to
    the use of the "exec < XXXX" statement done in an earlier step.
    You only need to loop reading lines from standard input in this step.

    Count each line from the input as it is read in the loop.  Error
    messages should refer to this line number (the line number of the
    line containing the error).

    Select the line for printing if the day field, month field, and year
    field in the line match the contents of the day variable, month
    variable, and year variable set previously from the user-supplied
    date string.  (Select the line if the day, month, and year of the
    user's date match the day, month, and year on the input line.)

    A wildcard asterisk "*" used in any field in the line matches any
    corresponding value in the user-supplied date, i.e. if the input
    line has a day wildcard:

        * Mar 2004 PRINT Dentist appt. downtown

    the "*" will match any user-supplied day.  (The above reminder
    will be selected for printing if the month and year match.)

    In other words, the user-supplied day variable matches the day in
    the input line if either the day in the input line is the same day as
    the user-supplied day or if the day in the input line is the wildcard
    "*" character.  The same logic applies for the month and year.

    If a line is selected for printing (the date matches), it must also
    have the word "PRINT" in the fourth field on the line; otherwise,
    generate an error and do not print the line.  In other words, if
    the first three fields on the line match the user-supplied date,
    the fourth field must be the command word "PRINT".

    If the line is selected for printing, print the fifth field on the
    line (the entire rest of the line), preceded by the user-specified
    year, month, and day.  Here is a sample reminder file line and
    the resulting output line from your script if the line is selected
    for printing:

    Reminder file:  18 Mar 2004 PRINT This prints on 18 March 2004.
    Your output:    2004 Mar 18 This prints on 18 March 2004.

    Reminder file:  * Mar 2004 PRINT This prints on 18 March 2004.
    Your output:    2004 Mar 18 This prints on 18 March 2004.

    See Appendix "C" for more examples of this output format.

    Count the number of lines actually printed.

    Keep looping, reading and possibly printing reminder lines, until
    EOF is read.    [approximately 17 lines]

10. Exit the script with a bad status if no lines were printed;
    otherwise, exit with a good status (indicating at least one line
    was matched and printed).  [4 lines]

Bonus marks - see Appendix "D".

Documentation
-------------

    Add comments and blank lines before each group of commands in the
    script, explaining *why* you are doing these things in the script.
    (What is the purpose of the group of commands?  Why is it there?)

    Scripts without comments are unsatisfactory; they are worth zero
    marks.  You must submit comments with your scripts.

    One comment may serve to explain several Unix commands; you do not
    need a comment in front of every single command line in the script.
    See the comment style described in Notes file "script_style.txt".

==========
Submission
==========

Submit the finished exercise04.sh file file for marking as Exercise 04
on the Course Linux Server, using the following datsubmit command line:

       $ datsubmit 04 exercise04.sh

This "datsubmit" program will copy the selected file to me for marking.
Do not delete your copiy; keep it.  Verify that you submitted your file,
using this command line:

       $ datsubmit 04 -list

Note that the digit "1" and the letter "l" (lower-case "L") are different.
Do not confuse the two.

You may redo this exercise and re-submit your results as many times as
you like.

The "-delete" option of datsubmit will delete the most recent submission
you have made.  I will mark only the most recent submission that is
submitted before the final hand-in cutoff date.

For Exercise 04, always use "04" as the first argument to "datsubmit".

-----------------------------------------
Appendix "A" - the GNU/Linux date command
-----------------------------------------

The GNU/Linux date command has some flexible options to change what
date it prints, using the --date=STRING option.  To see how the STRING
argument works you may wish to experiment with some test options to the
date command.  Try these:

   $ date
   $ date --date=today
   $ date --date=tomorrow
   $ date --date=yesterday
   $ date --date="last week"
   $ date --date="next month"
   $ date --date="December 25"
   $ date --date="January 35 2004"

Note that, no matter what valid STRING you specify, the date command
always outputs the same 28 character date format.  Note also that a
STRING value of "January 35" doesn't produce an error; it produces an
output date of February 4!

Running "date" with no arguments is the same as saying --date=today.

An invalid date STRING argument produces an error message and empty
standard output:

    $ x=$( date --date=XXXXXXXXXXXXX )
    date: invalid date `XXXXXXXXXXXXX'
    $ echo $x

    $

See the manual page for all the details.

The first (optional) argument to your script is a date string that will be
passed as the STRING argument to the --date option of the "date" command.
The output will be saved in a variable, and then the day, month, and
year will be extracted and used.

---------------------------------------------
Appendix "B" - the basic Reminder File Format
---------------------------------------------

The basic reminder file has five fields per line, separated by blanks, e.g.:

    18 Mar 2004 PRINT This prints on 18 March 2004.

The first three fields on each line give the date on which this reminder
should be selected for printing.  The fourth field is the command word
"PRINT".  The fifth field is everything else on the line (including
blanks) - this is the reminder text that is to be printed if the date
on this line matches the date supplied by the user of the script.

The five fields in each line are defined to be:

 1. The numeric day of the month, e.g. 1, 2, ..., 31
 2. The 3-letter name of the month, e.g. Jan, Feb, Mar, ..., Dec
 3. The 4-digit year, e.g. 1954, 1999, 2004, 2066, etc.
 4. An upper-case command word: PRINT
 5. All the rest of the characters on the line (including spaces).

All fields are case-sensitive - "print" does not match "PRINT" and "mon"
does not match "Mon".  You must have the correct capitalization.

Any of the first three fields on a line (day, month, or year) may be
given as an asterisk "*", which is used as a wildcard match to indicate
that this field matches any day, or any month, or any year (see below
for examples).  A line containing three wildcards matches every day in
every month in every year - it is always selected.

Lines in which the first three fields do not match the user-specified
date are simply ignored by the script; there is no error-checking for
mis-spelled days, months, or years.  Only exact date matches (with
wildcards) work.

Here is a sample reminder file:

----------- cut here ---------------------------------------------------
Lines like this that don't match any date are just ignored.

18  Mar 2004 PRINT This prints on 18 March 2004.
18  Mar *    PRINT This prints on 18 March of every year.
18  *   2004 PRINT This prints on the 18th of every month in 2004.
18  *   *    PRINT This prints on the 18th of every month.

*   Mar 2004 PRINT This prints on every day in March 2004.
*   Mar *    PRINT This prints on every day in March of every year.
*   *   2004 PRINT This prints on every day of every month in 2004.
*   *   *    PRINT This prints every day.
----------- cut here ---------------------------------------------------

The following bad format line should generate an "unknown line type" message:

   * * * xxx This line must generate an error message (missing command PRINT)

Error messages must contain the input line number of the error.

----------------------------------------
Appendix "C" - sample inputs and outputs
----------------------------------------

Given the reminder file example in Appendix "B", copied to the current
directory under the name "reminders.txt", here is the expected output
for various command line date string arguments:

    $ date
    Thu Mar 18 00:16:55 EST 2004

    $ date --date=today
    Thu Mar 18 00:16:57 EST 2004

    $ wc reminders.txt
     11     107     532 reminders.txt

    $ ./exercise04.sh
    2004 Mar 18 This prints on 18 March 2004.
    2004 Mar 18 This prints on 18 March of every year.
    2004 Mar 18 This prints on the 18th of every month in 2004.
    2004 Mar 18 This prints on the 18th of every month.
    2004 Mar 18 This prints on every day in March 2004.
    2004 Mar 18 This prints on every day in March of every year.
    2004 Mar 18 This prints on every day of every month in 2004.
    2004 Mar 18 This prints every day.

    $ ./exercise04.sh "today"
    2004 Mar 18 This prints on 18 March 2004.
    2004 Mar 18 This prints on 18 March of every year.
    2004 Mar 18 This prints on the 18th of every month in 2004.
    2004 Mar 18 This prints on the 18th of every month.
    2004 Mar 18 This prints on every day in March 2004.
    2004 Mar 18 This prints on every day in March of every year.
    2004 Mar 18 This prints on every day of every month in 2004.
    2004 Mar 18 This prints every day.

    $ ./exercise04.sh "yesterday"
    2004 Mar 17 This prints on every day in March 2004.
    2004 Mar 17 This prints on every day in March of every year.
    2004 Mar 17 This prints on every day of every month in 2004.
    2004 Mar 17 This prints every day.

    $ ./exercise04.sh "tomorrow"
    2004 Mar 19 This prints on every day in March 2004.
    2004 Mar 19 This prints on every day in March of every year.
    2004 Mar 19 This prints on every day of every month in 2004.
    2004 Mar 19 This prints every day.

    $ ./exercise04.sh "April 18 2004"
    2004 Apr 18 This prints on the 18th of every month in 2004.
    2004 Apr 18 This prints on the 18th of every month.
    2004 Apr 18 This prints on every day of every month in 2004.
    2004 Apr 18 This prints every day.

    $ ./exercise04.sh "May 30 2004"
    2004 May 30 This prints on every day of every month in 2004.
    2004 May 30 This prints every day.

    $ ./exercise04.sh "Dec 31 2005"
    2005 Dec 31 This prints every day.

If "reminders.txt" is not found, the script must prompt:

    $ mv reminders.txt foo.txt
    $ ./exercise04.sh "Dec 31 2005"
    SOME GOOD MESSAGE HERE ABOUT CANT FIND REMINDERS.TXT
    SOME KIND OF INPUT PROMPT:
    foo.txt        <=== THIS LINE IS TYPED BY THE USER
    2005 Dec 31 This prints every day.

Write your own error message and prompt; don't use the above junk.

If you redirect input, no prompting for an input file is done:

    $ ./exercise04.sh "Dec 31 2005" <foo.txt
    2005 Dec 31 This prints every day.

Note that the date printed in front of the reminder is the year,
month, and day derived from the user's date input string argument.
It is not the date from the file, since the date in the file may
contain one or more wildcard characters.

Make sure your script has the correct exit status.

---------------------------------------------
Appendix "D" - the Bonus Reminder File Format
---------------------------------------------

For the Bonus script, the Reminder File is enhanced with the following
two additional capabilities:

 A) +5%: The first field on a line (the day) may also be the 3-letter
    day of the week:  Mon, Tue, Wed, Thu, Fri, Sat, Sun   Example:

       Thu Mar 2004 PRINT This prints on every Thursday in March of 2004.

    Now, the first field in the input line matches if it matches the
    current month day (e.g. 18) *or* it matches the current weekday
    (e.g. Thu), *or* it is the wildcard character "*". The logic for
    matching the month and year is unchanged.

 B) +5%: The fourth field may be the upper-case command word "EXECUTE",
    indicating that the remainder of the line (the fifth field) should be
    sent to the Unix shell for execution instead of being printed.
 
       Thu Mar 2004 EXECUTE hostname ; who | grep $USER

    For the bonus, the fourth field may now be either "PRINT" or "EXECUTE".

    Count the number of lines actually printed or executed.  At the
    end of the script (after the reminder file is finished), exit the
    script with a bad status if no lines were printed or executed.

    To implement EXECUTE lines, echo the fifth field in the line (which
    contains the entire rest of the line that you have put into a shell
    variable) into a pipe to the standard input of a shell.  The shell
    will read the line from standard input and execute it.

The Bonus Reminder File format handles all the formats of the basic
Reminder File.  The new bonus formats only *add* capabilities; they
don't alter the basic behaviour.  Your old reminder files will still work.

Here is a sample Bonus Reminder File showing only the two new additional
bonus formats:

----------- cut here ---------------------------------------------------
This bonus file also handles weekdays in the first field (+5%):

Thu Mar 2004 PRINT This prints on every Thursday in March of 2004.
Thu Mar *    PRINT This prints on every Thursday in March of every year.
Thu *   2004 PRINT This prints on every Thursday in every month in 2004.
Thu *   *    PRINT This prints on every Thursday.
*   *   *    PRINT This still prints on every day.

The following are examples of the bonus "EXECUTE" type of lines that
are not printed but are sent to the Unix shell for execution (+5%):

*   *   *    EXECUTE date
18  Mar *    EXECUTE date | wc
*   Mar 2004 EXECUTE sort /etc/passwd | head -3
Thu *   *    EXECUTE who | grep idallen
*   *   *    EXECUTE echo "This could be any Unix shell input line."

----------- cut here ---------------------------------------------------

The following bad format line should generate an "unknown line type" message:

   * * * xxx This must generate an error message (not PRINT or EXECUTE)

Error messages must contain the input line number of the error.