/ 
Finance-StockAccount-0.01
River stage zero No dependents
/ Finance::StockAccount::Set

NAME

Finance::StockAccount::Set - a one-stock building block used by Finance::StockAccount

VERSION

Version 0.01

SYNOPSIS

Finance::StockAccount::Set objects are the building blocks of a Finance::StockAccount object. Each Set is the complete record of transactions and accounting for a particular stock. Sets are also collections of Realizations. See perldoc Finance::StockAccount for context.

Typical usage of sets involves adding Finance::StockAccount::Transaction objects to them, analyzing them with the accountSales method, and then retriving stats from them:

my $at = Finance::StockAccount::AccountTransaction->new($init);
my $set = Finance::StockAccount::Set->new([$at]);
$set->accountSales();
my $profit = $set->profit();

METHODS

realizations

my $realizations = $set->realizations();

Returns a reference to an array of all realizations in the set. Like the other methods concerning realizations below, this is only meaningful after $set->accountSales() has been run.

realizationCount

my $realizationCount = $set->realizationCount();

Answers the question: how many realizations are in the set?

transactionCount

my $transactionCount = $set->transactionCount();

How many realized transactions are in the set?

unrealizedTransactionCount

my $unrealizedTransactionCount = $set->unrealizedTransactionCount();

How many unrealized transactions are in the set?

realizedTransactions

my $realizedTransactions = $set->realizedTransactions();

Returns a reference to the array of all realized transactions in the set.

unrealizedTransactions

my $unrealizedTransactions = $set->unrealizedTransactions();

Returns a reference to the array of all unrealized transactions in the set.

availableAcquisitions

my $aa = $set->availableAcquisitions();

Returns a reference to the array of AccountTransaction objects in the set for which $at->available() and ($at->buy() or $at->short()) is true. Meaning they are acquisitions available for potential match with divestments. This is particularly useful to the user/trader when she wants to see what purchases (or shorts) are available for sale (or cover) at the current price, and judge what profit might be made from divestment and what quantity to divest.

availableAcquisitionsString

print $set->availableAcquisitionsString();

Returns a formatted string of the above information. Note that in version 0.01 of this module, the only column adjusted from the Transaction object to the AccountTransaction object for this printing is the "Quantity" column, which shows the number of shares available. This was a bit of a shortcut, and I might come back and fix it later, as an acquisition that has been partially matched with a divestment already would show the commission and most importantly the cash effect of the entire transaction, not just the available shares, which can be misleading.

stale

$set->stale() and $set->accountSales();

Returns true if the Set object has changed in a significant way since the last accountSales() call, false otherwise. If called with a parameter, can also be used to set the staleness status of the set.

Typical ways a Set will change that affect staleness include the addition of new stock transactions and the setting or removal of a date range limit.

symbol

my $symbol = $set->symbol();

Get the set stock symbol.

startDate

$set->startDate($tm); # $tm is a Time::Moment object

Set a start date for a date range limit. If no argument is passed, retrieves the start date:

my $tm = $set->startDate();

endDate

Same as startDate, but gets/sets the end of the period.

setDateLimit

$set->setDateLimit($tm1, $tm2);

Same as:

$set->startDate($tm1);
$set->endDate($tm2);

clearDateLimit

$set->clearDateLimit();

Remove date range restrictions -- established by startDate, endDate, or setDateLimit methods -- from the set.

transactionDates

my $transactionDates = $set->transactionDates();

Returns a reference on a array of the Time::Moment objects for every transaction in the set.

printTransactionDates

$set->printTransactionDates();

Actually prints to STDOUT the dates returned by the transactionDates method.

accountSales

$set->stale() and $set->accountSales();

Calling account sales triggers the primary work of the Set module: it matches up each divestment with a prior acquisition, and then uses that matching to populate all the statistics properties of the object, and it sets the stale property to false. This is why most methods that return statistics will call accountSales if stats are stale.

checkStats

$set->checkStats();

Runs accountSales if the stats data is stale, i.e., if the object has changed in a significant way since it last ran.

profit

my $profit = $set->profit();

Runs checkStats and then returns the profit for the set.

commissions

Runs checkStats and then returns the total commissions.

totalOutlays

Runs checkStats and then returns the outlays, what was spent on acquisitions including overhead (commissions and fees).

totalRevenues

Runs checkSTats and then returns the revenues, less overhead.

profitOverOutlays

Runs checkStats and then returns the profit divided by the outlays.

regulatoryFees

Runs checkStats and then returns the regulatory fees.

otherFees

Runs checkStats and then returns the total other fees paid.

success

Runs checkStats and then returns a boolean value for whether any acquisitions were successfully paired with a divesment. Can be used to determine whether there are any meaningful relationship upon which stats can be based.

realizations

Runs checkStats and then returns a reference to the list of Realization objects created.

realizationsString

Loops through the list returned by $set->realizations() and returns a string that can be printed to view it.

AUTHOR

John Everett Refior, <jrefior at gmail.com>

BUGS

Please report any bugs or feature requests to bug-finance-stockaccount at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Finance-StockAccount. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Finance::StockAccount::Set

You can also look for information at:

ACKNOWLEDGEMENTS

I would like to thank the Perl Monks for contributing their wisdom when I posted questions about how to handle date/time and whether there was already a module capable of doing what I planned.

LICENSE AND COPYRIGHT

Copyright 2014 John Everett Refior.

This program is free software; you can redistribute it and/or modify it under the terms of the the Artistic License (2.0). You may obtain a copy of the full license at:

http://www.perlfoundation.org/artistic_license_2_0

Any use, modification, and distribution of the Standard or Modified Versions is governed by this Artistic License. By using, modifying or distributing the Package, you accept this license. Do not use, modify, or distribute the Package, if you do not accept this license.

If your Modified Version has been derived from a Modified Version made by someone other than you, you are nevertheless required to ensure that your Modified Version complies with the requirements of this license.

This license does not grant you the right to use any trademark, service mark, tradename, or logo of the Copyright Holder.

This license includes the non-exclusive, worldwide, free-of-charge patent license to make, have made, use, offer to sell, sell, import and otherwise transfer the Package with respect to any patent claims licensable by the Copyright Holder that are necessarily infringed by the Package. If you institute patent litigation (including a cross-claim or counterclaim) against any party alleging that the Package constitutes direct or contributory patent infringement, then this Artistic License to you shall terminate on the date that such litigation is filed.

Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS IS' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES. THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY YOUR LOCAL LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.