                     =====================================
                       Package "Date::Pcalc" Version 1.2
                     =====================================

                  Copyright (c) 1999-2001 J. David Eisenberg,
                                 based on work
                   Copyright (c) 1993-2001 by Steffen Beyer.
                             All rights reserved.


Example applications:
---------------------

You will find some example applications in Perl
in the "examples" subdirectory of this distribution:

                        examples/age_in_days_eu.pl
                        examples/age_in_days_us.pl
                        examples/cal.pl
                        examples/nth_weekday.pl


age_in_days_eu.pl, age_in_days_us.pl:
-------------------------------------

"age_in_days_eu.pl" and "age_in_days_us.pl" are a demonstration of the
multi-language capabilities of this package, as well as of its scanning
capabilities for dates.

First build and install this package (for instructions, see the file
"INSTALL.txt" in this distribution), then change directory to the
"examples" subdirectory, and finally start these two demo programs
with
                        > perl age_in_days_eu.pl
and
                        > perl age_in_days_us.pl
respectively.

They first ask you to choose a language; any uniquely identifying
abbreviation for one of the six languages initially provided by this
package (English, French, German, Spanish, Portuguese, Dutch) will
suffice, like "en" for "English", "es" for "Español" (Spanish),
"f" for "Français" (French), and so on.

These applications then ask you to enter the date of your birthday.

The two applications only differ in the expected format for dates:
In "age_in_days_eu.pl", the order day-month-year is assumed, whereas
"age_in_days_us.pl" assumes the order month-day-year.

For the month you can (at your option) either enter the corresponding
number, or any uniquely identifying abbreviation of the month's name
(or the name of the month in full length) IN THE CHOSEN LANGUAGE.

Moreover, virtually any format for dates is supported:

Examples include "03/01/64", "3.1.1964", "January 3rd, 1964", "030164",
and so on.

Experiment!

After confirming your entry, the program will print out your age in days.

If the system call "time()" (and hence, "localtime()") is not available
on your system, the program will also ask you to enter today's date.

Otherwise the program will automatically use the system-supplied current
date.

cal.pl:
------

This little program is a substitute for the UNIX "cal" command.

In contrast to the UNIX "cal" command, however, this program allows you
to choose a language which will be used for generating the calendar for
the chosen month and year.

(Also in contrast to the UNIX "cal" command, this program will NOT
generate a tiled overview of ALL the months for a given year, however.)

Moreover, you can (at your option) either enter the number of the desired
language, or any uniquely identifying abbreviation of its name (or the name
in full length).

For the month you can also (at your option) either enter the corresponding
number, or any uniquely identifying abbreviation of the month's name (or
the name of the month in full length) *IN THE CHOSEN LANGUAGE*.

For UNIX, make sure that the first line of the file gives the
proper location of perl and that the permissions are set correctly.
Now start the program with the command "./cal.pl"

For MSDOS/Windows, make sure that the extension .pl is associated
with Perl.

(Note that this program is not confined to Win32 systems, it also compiles
and runs perfectly well on pure MS-DOS or other Windows systems!)

The first parameter is the month, the second is the year,
and the third is the desired language (currently 1..6 or "English",
"Français", "Deutsch", "Español", "Português" and "Nederlands"),
the second the month and the third the year. The third parameter
is optional; if not given, the language will be the module's
default language (given in the variable $pcalc_Language).

Example:
                        > cal.pl apr 1998 en

This will print:

                            April 1998
                    Mon Tue Wed Thu Fri Sat Sun
                              1   2   3   4   5
                      6   7   8   9  10  11  12
                     13  14  15  16  17  18  19
                     20  21  22  23  24  25  26
                     27  28  29  30

If you start the "cal.pl" program without parameters, it will
print a usage and exit.

Experiment!

If you like this program, you might want to copy it to some directory in
your search path, like "/usr/local/bin" (UNIX) or "C:\DOS" (MSDOS/Windows).

If you are running this program on a PC (e.g. MS-DOS, Windows DOS box,
GNU/Linux or FreeBSD console), you might want to pipe its output through
the "iso2pc" filter from the "tools" subdirectory (see the file "TOOLS.txt"
of the original Date::Calc distribution for instructions on how to compile
and install this filter), in order to convert the special international
characters from the ISO-Latin-1 character set (used throughout this package)
to one of the (two) character sets commonly used on PC's, as follows:

                    > cal.pl Mar 1998 Portug | iso2pc [-dos]

(for older versions of MS-DOS and the PC-UNIX console) or

                    > cal.pl Mar 1998 Portug | iso2pc -win

(for newer versions of MS-DOS and the Win32 DOS box).

** NOTE ** In the original Date::Calc module, "cal"is a C
program.  I have changed it to perl, and have also changed the
order of the parameters so that it will work in a manner similar
to the UNIX "cal" command, in that you can give it simply a
month and year and will get a reasonable result.

nth_weekday.pl:
---------------

This program is a demonstration of the function "Nth_Weekday_of_Month_Year()"
and the scanning capabilities of this package (in particular the day of week
and month, in this case).

It calculates the date of the "n"th occurrence of the given day of week
in the chosen month and year -- such as, for example, the 3rd Thursday
of a given month and year.

First build and install this package (for instructions, see the file
"INSTALL.txt" in this distribution), then change directory to the
"examples" subdirectory, and finally start this program with the
following command (example):

            > perl nth_weekday.pl 3rd Thursday April 1998

This will print:

        The 3rd Thursday in April 1998 is Thursday, April 16th 1998.

If you start this program without parameters, it will print a usage
and exit.

Note that you can enter the factor ("3rd" in the above example) either
using plain numeric digits ("1", "2", "3", "4" and "5"), or in the usual
abbreviated (English) form as "1st", "2nd", "3rd", "4th" and "5th".

You can also enter the day of week either numerically ("1" through "7"),
or as any uniquely identifying abbreviation of the name of the desired
day of week (or its name in full length) in English.

For the month you can similarly either enter the corresponding number
("1" through "12"), or any uniquely identifying abbreviation of the
month's name (or the name of the month in full length) in English.

Experiment!


