Summary

Detailed Description

• For this assignment you have to write a calendar system.
• The calendar system is to keep track of upcoming events. It should allow the addition of new events, the purging of past events, and the displaying of upcoming events.
• You may implement this assignment in any language you like that is available on the undergrad computers. Using C++ or shell would probably give you the most benefit, since they will be tested in the exam...

• The specification is as follows:
  • Your program must be called calendar.
  • It has three modes of operation: add, show and purge.
  • The add mode is as follows:
    • The program will be executed as: calendar add <date>
    • <date> can have the following forms:
      • dd/mm/yyyy : for example 15/01/2002 or 13/2/2002
      • dd/mm/yy : for example 15/01/02 or 13/2/02 (the century is assummed to be 20)
      • dd/mm : for example 15/01 or 13/2 (the year is assummed to be the current year)
    • The event message should be read from standard input
  • The show mode is as follows:
    • The program will be executed as: calendar [date]
    • The date is specified with the same formats as the add mode
    • All the events that occur between today and the specified date should be output (if the date is in the past an error message should be displayed)
    • The events do not have to be output in chronological order
    • If no date is specified then events that occur today and tomorrow should be output (If today is a Friday, then all events from today until the next Monday should be output)
    • If the word all is given for the date then all the entries past, present and future should be output
  • The purge mode is as follows:
    • The program will be executed as: calendar purge
    • All previous events should be removed (everything which has a date before today)
  • Your program should store the events in a file named in the environment variable $CALENDAR
  • You can store the events in the $CALENDAR file using any format you like, with the restriction that it must be text
  • Event descriptions will only be one line long - you should ignore any other input in the add mode
  • When outputting events in the show mode they should be output as follows:
    • day_of_week day month year : descriptions
    • for example: Mon 14 Jan 2002 : Assignment 1 due
  • For testing and marking purposes your program should read today's date from the environment variable $CALENDAR_DATE, which will be stored in the format output by the date command, for example Mon Jan 14 12:47:19 EST 2002.

• Here is an example of how the program should behave (bold text is typed by the user)

  bash$ export CALENDAR=calendar.file
  bash$ export CALENDAR_DATE="Thu Jan 24 12:47:19 EST 2002"
  bash$ calendar add 14/1
  Assignment 1 (String Class) due for COMP2004
  bash$ calendar add 11/2/02
  Assignment 3 (Paging Simulation) due for COMP2004
  bash$ calendar add 25/1/2002
  Assignment 2 (Calendar System) due for COMP2004
  bash$ calendar
  Fri 25 Jan 2002 : Assignment 2 (Calendar System) due for COMP2004
  bash$ calendar 31/12
  Fri 25 Jan 2002 : Assignment 2 (Calendar System) due for COMP2004
  Mon 11 Feb 2002 : Assignment 3 (Paging Simulation) due for COMP2004
  bash$ calendar all
  Mon 14 Jan 2002 : Assignment 1 (String Class) due for COMP2004
  Fri 25 Jan 2002 : Assignment 2 (Calendar System) due for COMP2004
  Mon 11 Feb 2002 : Assignment 3 (Paging Simulation) due for COMP2004
  bash$ calendar purge
  bash$ calendar all
  Fri 25 Jan 2002 : Assignment 2 (Calendar System) due for COMP2004
  Mon 11 Feb 2002 : Assignment 3 (Paging Simulation) due for COMP2004
  bash$ exit
  

• Design is important in this assignment. If you approach the problem properly the solution will be quite simple. I strongly suggest you think about how you can break the program into pieces before you start writing code.
• You are allowed to use multiple languages, you could write a small program in C++ which is called by a shell script for example. You are allowed to have multiple executables which are called by your calendar program, just make sure you put them in the tar file (and that make will compile them if they are C++ code).
• You can also get the helper Date class: Date.cc, Date.h. If you are using shell you will probably still want to use the Date class to write helper programs like: day_name.cc and add_days_to_date.cc.

• Your submission must consist of any files required for your calendar system to run.
• The program will be compiled with the command

  make

  so you should make sure that if you have any C++, you have a corresponding Makefile to compile it. If you did not use any C++ and thus do not need make (eg, you have a shell script called calendar which is already set to be executable) then just ignore make - it will just run and do nothing. After make has been run (whether it does anything or not), your calendar program must be able to be run.

• Your submission must be placed in a tar file. In order to do this, refer to the submission instructions page.
• Once you have created the tar file you need to submit it, which is also described on the submission instructions page.

Common Questions

1. When I run my program it does nothing...
   There is a unix command called calendar which does something very similar to the assignment, you are probably running it instead, try running your program as ./calendar

2. I'm using C++, how do I access the shell variables CALENDAR and CALENDAR_DATE?
   There is a C library function called getenv that you can call. See the man page (run the command man getenv) for details. Basically you will use getenv("CALENDAR") to get the name of the file to use, and the obvious for the date.

3. I'm using C++, how do I read from and write to a file?
   You use the fstream library which is just like the iostream library. information is available here. They work just like cin and cout so once you see the examples of how to create them it should be easy.

4. I'm using C++, how can I read the rest of a line?
   You can use either of the getline() or get() methods in the istream class. getline() is a pain because it reads into C-style strings of a fixed size (ie. you have to define char s[256];). The easier way is to use get(), which returns a char as an int (ie. you do something like int ch = std::cin.get();). This is so that it can signal end-of-file by returning the 'character' EOF. Thus you can have a while loop which keeps reading a single character and appending it to a C++-style string, until you read a character which is either EOF or '\n'. Reference information on getline() and get().

5. Does my program need to set the environment variables CALENDAR and CALENDAR_DATE?
   No. They will be set by the machine marking before it runs your program. So to test your program, you should set them by hand in an xterm before running your program. You do this using the export command, as shown in the earlier example.

6. What's the point of the CALENDAR environment variable?
   Your calendar program will be run once each time an event is added, some events are shown, or some events are purged. This means that if an event is added, and then a show command is given, your program has been run twice. This means that you can't just store events in memory when you get an add instruction, because if you did, that event would be lost when your program finishes (which is before you get a show instruction). So you need to store events in a file somewhere, so that they can be read back in later. The name of the file into which you should store the events is the value the CALENDAR environment variable.

7. I'm confused. Does the CALENDAR environment variable store a file or what?
   An environment variable simple stores a string. So the CALENDAR environment variable stores a string. It's up to you as a programmer to treat that particular string as the name of a file. The way you would typically do that (in C++) is to pass that string to the constructor of an ofstream object.

8. Does my program need to create the file with filename given by the CALENDAR environment variable?
   If the file with filename given by the CALENDAR environment variable doesn't exist, your program should create the file (since a file must exist before it can have information written into it). Otherwise you should assume that the file contains events which were stored by previous runs of your calendar program. The machine marking will remove all data from the calendar file before running your program, so if the calendar file exists when your program is run for the first time, then the file will be empty (ie. 0 bytes).

9. What's the point of the CALENDAR_DATE environment variable?
   If you were writing a proper calendar program, then your program would need to figure out what day today is. It would do that by asking the computer for the current date and time. However, if you were to write your code in that way it would make machine marking very hard, because I would have to change the date of my computer to test your code with different values of "today". To avoid this problem, your program should figure out what day today is by looking at the value of the CALENDAR_DATE environment variable. This is a string, and so you'll need to figure out a way to convert it into a date of some sort so that you can actually use it.

10. What do I do if I get an invalid date?
    You can assume that every date you'll be given in an add instruction will be a valid date (ie. you won't be asked to add an event for 36/1/2002). However, you may be given a date which is in the wrong format. For example, you might be given a date which looks like "22//2002". In this case, you should ignore the add request, and not add the event description which is specified on stdin. You can assume that the contents of the CALENDAR_DATE environment variable will always be in the same format as shown in the example earlier, which is the format used by the date command. If you do man date to get the manual page for date, it tells you that this format corresponds to using the format string "%a %b %e %T %Z %Y" with the strftime function. If you want, you can do man strftime to get a detailed description of each of the "%" codes used by date.

11. Which days should I show if today is a Saturday or Sunday?
    Well, neither Saturday nor Sunday is Friday, so the normal rule of today and tomorrow applies (ie. for Saturday, show Saturday and Sunday, for Sunday, show Sunday and Monday). Friday is the only day which needs to show more than just today and tomorrow.