=head1 NAME

Finance::Shares::Lesson2 - Sampling stock quotes

=head1 DESCRIPTION

The heart of all Finance::Shares processing is the L<Finance::Shares::Sample> module.  This script, called
F<02sample.pl> can be found in the F<tutorial> directory of the Finance::Shares package.

    #!/usr/bin/perl
    use strict;
    use warnings;
    use Getopt::Long;
    use Finance::Shares::Sample;
    use Finance::Shares::Chart;

    my $help;
    my $stock = 'MSFT';
    my $start = '2002-01-01';
    my $end   = '2002-01-31';
    my $usage = <<END;
    Usage:
	$0 --stock=<code> --start=<YYYY-MM-DD> --end=<YYYY-MM-DD>
    END

    GetOptions (
	'help'    => \$help,
	'stock=s' => \$stock,
	'start=s' => \$start,
	'end=s'   => \$end,
    );
    print $usage and exit if $help;

    # Create MySQL object giving access to the data
    my $fss = new Finance::Shares::Sample(
	source => {
	    user     => 'test',
	    password => 'test',
	    database => 'test',
	    debug    => 2,
	},

	symbol      => $stock,
	start_date  => $start,
	end_date    => $end,
	mode	    => 'cache',
    );

    # Create Chart object showing the data
    my $fsc = new Finance::Shares::Chart(
	sample => $fss,
    );

    $fsc->output($stock);
    print "$stock quotes from $start to $end saved as $stock.ps\n";

This script introduces two new objects, a B<Sample> and a B<Chart>.  Run it and it should produce a postscript
file called F<MSFT.ps>.  On a KDE system, this can be viewed using B<KGhostView>; gnome and other X-windows users
would use B<gv> or B<ghostview> (I find the 'antialias' and 'watch file' features of B<gv> ideal).  If anyone would like to suggest how postscript files are viewed on other
systems, I'd be glad to pass them on.  But you should be able to print the chart with

S< >   $ B<lpr MSFT.ps>

Although not covered in this tutorial, it is worth noting that the Sample B<source> option can take an array or
a CSV file name as well as the hash ref used here.  See L<Finance::Shares::Chart> for more details.

=over 4

=item 1.

Like the rest of the Finance::Shares suite, this script has defaults enabling it do something vaguely sensible.
But there are also options available.  Try this:

S< >   $ B<02sample.pl --help>

Run the script again, this time requesting about 3 months of quotes for some company of your own choice.  See
L<http://finance.yahoo.com> for some suitable stock codes.

=item 2.

Three months is more data that can be crammed onto the default page.  Do you notice how the only some of the dates
are shown?  One way to overcome this limitation is to get Sample to summarize the data and display it by weeks or
months instead of days.  Add a B<dates_by> hash key so the Sample constructor now ends:

	symbol     => $stock,
	start_date => $start,
	end_date   => $end,
	
S< >       B<dates_by>   B<=E<gt> 'weeks',>

	mode	   => 'cache',
    );

It should now be possible to show about 10 months of weekly quotes.  The high-low and open-close values are now
values for the week.

=item 3.

Another way of getting a little more space is by turning the page sideways.  Add a B<file> section (3 lines) to
the Chart constructor.

    my $fsc = new Finance::Shares::Chart(
	sample	=> $fss,

        file	=> {
	    landscape => 1,
	},

    );

Run the script again and check that the chart is now printed landscape.  Do you think 52 weeks would fit now?

=item 4.

So what about months?  Surely four years' data can be viewed on one page?  Change B<dates_by> to 'months' and see
what happens.

Bearing in mind that the high-low and open-close readings are now shown for the whole month, why are the volume
totals not shown for comparison, too?

=item 5*.

Under most circumstances it is the end date which is important, and the earlier values are only needed for
building up an historical picture.  

For example, Bollinger bands are lines drawn above and below the prices, giving a buy or sell signal when the
price is outside this band.  However, this function needs 20 previous days' readings before the upper and lower
boundaries can be calculated.

The Sample module provides a few support functions which can help here.  Make these changes to the script:

    ...
    use Getopt::Long;
    
S< >   use Finance::Shares::Sample B<qw(increment_date)>;

    use Finance::Shares::Chart;
    ...
    print $usage and exit if $help;

S< >   B<$start = increment_date($end, -28);>

    # Create MySQL object giving access to the data
    my $fss = new Finance::Shares::Sample(
	...

S< >       dates_by => 'B<days>',

	...
    );

The chart should now show the 20 days up to whatever end date is specified.  It was necessary to give 28 days to
B<increment_date> because it was dealing with real dates having 7 days in a week.  But there are (normally)
5 quotes per week, so 20/5 * 7 = 28.

=item 6*.

Change the script so that the following command will chart the 26 weeks leading up to the 17th June 2002.

    $ 02sample.pl --period=26 --dates=weeks --end='2002-06-17'
    
=back

=cut

