HOWTO Write a Finance::Shares function module
=============================================

Functions are all methods of a Finance::Shares::Sample object but, thanks to
Perl's flexibility, they don't have to be in the same file.  The start of your
module file should look like this:

    package Finance::Shares::MyModule;
    our $VERSION = 0.01;
    use strict;
    use warnings;

    package Finance::Shares::Sample;
    use Finance::Shares::Sample qw(%function);

There will be one method which is the access point for the Finance::Shares
function you are writing.  That code ref must be declared in %function.  There
should be a short and a long name.

    $function{my_calculation} = \&my_calc_function
    $function{calc}           = \&my_calc_function

You are free to use whatever parameters you need, but they should be
in key-value format and be consistent with existing modules if possible.

It is recommended that defaults are set AFTER the parameters are read:
(Remember that '$self' is a Finance::Shares::Sample object.)

    sub my_calc_function {
	my $self = shift;
	my $args = { @_ };
	$args->{period} = 5 unless defined $args->{period};
	$args->{strict} = 1 unless defined $args->{strict};
    }

Although neater, this code will fail.  If the list of parameters is assigned
elsewhere, 'undef' values will not take on the default.  Consider the following.

    sub my_func {
	my $self = shift;
	my $args = {
	    period = 5,
	    strict = 1,
	    shown  = 1,
	    @_,
	};
	...
    }

    my $period = 21;
    my $strict;

    my @input = ( period => $period, strict => $strict );
    $sample->my_func( @input );

'shown' will have the value 1 from the defaults and 'period' will take the 21
passed in.  However, 'strict' will be undef and not 1.  Shame, but there it is.


Your method should call Finance::Shares::Sample's add_line() and return the
identifier(s) you gave it/them.  The data add_line() expects is a hash keyed by
date, with the values (possibly undefined) associated with each.  See value() in
Finance::Shares::Sample for a simple outline.


Your method will be called with code like this:

    use Finance::Shares::Sample qw(call_function %function);

    my $sample    = new Finance::Shares::Sample(...);
    my @args      = ( period => 5, strict => 1 );

    my $id = call_function( \%function, 'my_calculation', $sample, @args );
    my @id = call_function( \%function, 'calc',           $sample, @args );

Note that functions can generate more than one line, and these identifiers can
be obtained by calling in list context.

