/ 
Finance-Shares-1.00
/ Finance::Shares::test

NAME

Finance::Shares::test - user programmable control

SYNOPSIS

Three examples of how to specify a test, one showing the minimum required and the other illustrating all the possible fields.

    use Finance::Shares::Model;

    my @spec = (
	...
	tests => [
	    basic => qq( # perl code here ),
	    
	    iterative => {
		before => qq( # perl code here ),
		during => qq( # perl code here ),
		after  => qq( # perl code here ),
	    },
	    
	    code => sub { print "hello world\n" },
	],

	samples => [
	    ...
	    one => {
		tests => ['basic', 'iterative'],
		# NOT 'code' !
		...
	    }
	],
    );

    my $fsm = new Finance::Shares::Model( @spec );
    $fsm->build();

DESCRIPTION

This module allows model test code to write points or lines on the graphs.

The code must be declared within a tests block in a Finance::Shares::Model specification. Each test is a segment of plain text containing perl code. This is compiled by the model engine and run as required.

Test Types

As shown by the SYNOPSIS examples, there are three types of test.

Simple text

The simplest and most common form, this perl fragment is run on every data point in the sample where it is applied. It can be used to produce conditional signal marks on the charts, noting dates and prices for potential stock positions either as printed output or by invoking a callback function.

Hash ref

This may have three keys, before, during and after. Each is a perl fragment in text form. before is run once, before the sample is considered. during is run for every point in the sample and is identical to "Simple text". after is run once after during has finished.

This form allows one-off invocation of callbacks, or an open-print-close sequence for writing signals to file.

Raw code

These are the callbacks invoked by the previous types of perl fragment. The parameters are those used to call the code. See "call" below.

Variables

In addition to perl variables declared with my or our, undeclared scalar variables are used to refer to the values of other lines on the chart.

Before the code is compiled a search is made for everything that looks like a scalar variable i.e. matches qr/\$(\w+)/. This will be replaced with a value if it is a tag from either names, lines or a fully qualified line name (see "Fully Qualified Line Names" in Finance::Shares::Model). Otherwise it is assumed to be a valid perl scalar and is left alone.

If it does refer to a line, the value becomes the value for the line at that date. Clearly this only makes sense while the test is iterating through the data in the during phase.

NOTE: Avoid all variable names that are used by Model. These include $open, $high, $low, $close and $volume - aliases for the Finance::Shares::data lines.

Each test also has a special variable $self available. This is a hash ref holding persistent values (similar to an object ref, but not blessed). These values are predefined.

$self->{date}

Only useful in the during phase, this is set to the current date.

$self->{stock}

This is the stock code, as given to the model's sample entry for this page.

$self->{first}

The first date which has data available. The during phase starts with this.

$self->{last}

The last date which has data available. The during phase ends with this.

$self->{start}

The first date normally displayed on the chart.

$self->{end}

The last date normally displayed on the chart.

$self->{by}

How the time periods are counted. Will be one of quotes, weekdays, days, weeks, months.

$self->{quotes}

This is the Finance::Shares::data object used to store the dates, price and volume data for the page. See "Page Names" in Finance::Shares::Model.

It should not normally be needed, but it provides a door into the engine for those who need to access it.

Marking the Chart

A special function is provided which will add a point to a chart line. It is called as

mark( tag, value )
tag

This must refer to lines block entry which has mark as the function field.

value

Can be a number or undefined, but is often a psuedo-scalar variable refering to a line. See "Variables" above.

Example

    lines => [
	circle => {
	    function => 'mark',
	},
	average => {
	    function => 'moving_average',
	},
    ],

    tests => [
	show => q(
	    mark('circle', $average);
	),
    ],

    sample => {
	test => 'show',
    },

In this example the moving average line is marked twice. As well as the normal line, the show test is invoked and a circle (the default mark) is placed at every position where average is defined.

Notice that the engine invokes the moving average function for you as it is referred to in the test. There is no need to list it explicitly as a line.

Calling Foreign Code

Model test entries may be code refs as well as text. The code is then called using a special function.

call( tag, arguments )
tag

This must be a tag in a tests block identifying a code ref.

arguments

This list of arguments (or none) is passed to the subroutine identified by tag.

Example

    tests => [
	tcode => {
	    my $v = shift;
	    print "$v->{stock} quotes from $v->{first}\n";
	},
	doit => {
	    before => q(
		call('tcode', $self);
	    ),
	},
    ],

    sample => {
	test => 'doit',
    },

Remember that $self has a number of predefined fields, {stock} and {first} among them. The before code is only invoked at the start of the test. It calls the subroutine which prints a message.

This might seem an involved way to go about it, but it is extremely powerful. The subroutine call is made within code which has all the model values (as well as the complete power of perl) available. It may be passed whatever values you choose.

Example

This is a slightly more useful example. It assumes that the MyPortfolio module has exported subroutines defined for simulating buying/selling shares and keeping track of positions you hold in the market. A 'buy' call is made when the stock price seems to rise.

    # declare function modules used
    use Finance::Shares::moving_average;
    
    # import callback from another module
    use MyPortFolio 'enter_long_position';

    # Model specification begins
    ...
    
    lines => [
	fast => {
	    function => 'moving_average',
	    period   => 5,
	},
	slow => {
	    function => 'moving_average',
	    period   => 20,
	},
    ],

    tests => [
	buy  => &enter_long_position,
	code => q(
	    call('buy', 'pf1', $self->{date}, $low, $high)
		    if $fast >= $slow;
	);
    ],

    sample => {
	test => 'code',
    },

When the 5 day moving average crosses above the 20 day one, the callback is invoked. It will be passed a portfolio ID, the date, lowest and highest proces for the day.

<realism> A buy signal would need to be invoked on the basis if at least yesterday's data as todays is usually not yet known! This might be done by using a $self->{buy} flag and having after => 1 set in the appropriate dates entry. </realism>

BUGS

Please let me know when you suspect something isn't right. A short script working from a CSV file demonstrating the problem would be very helpful.

AUTHOR

Chris Willmot, chris@willmot.org.uk

LICENCE

Copyright (c) 2002-2003 Christopher P Willmot

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. A copy can be found at http://www.gnu.org/copyleft/gpl.html

SEE ALSO

Finance::Shares::Overview provides an introduction to the suite, and fsmodel is the principal script.

Modules involved in processing the model include Finance::Shares::Model, Finance::Shares::MySQL, Finance::Shares::Chart. Chart and file details may be found in PostScript::File, PostScript::Graph::Paper, PostScript::Graph::Key, PostScript::Graph::Style.

All functions are invoked from their own modules, all with lower-case names such as Finance::Shares::moving_average. The nitty-gritty on how to write each line specification are found there.

The quote data is stored in a Finance::Shares::data object. For information on writing additional line functions see Finance::Share::Function and Finance::Share::Line. Also, Finance::Share::test covers writing your own tests.