Finance::StockAccount::Set - a one-stock building block used by Finance::StockAccount
Version 0.01
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();
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.
my $realizationCount = $set->realizationCount();
Answers the question: how many realizations are in the set?
my $transactionCount = $set->transactionCount();
How many realized transactions are in the set?
my $unrealizedTransactionCount = $set->unrealizedTransactionCount();
How many unrealized transactions are in the set?
my $realizedTransactions = $set->realizedTransactions();
Returns a reference to the array of all realized transactions in the set.
my $unrealizedTransactions = $set->unrealizedTransactions();
Returns a reference to the array of all unrealized transactions in the set.
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.
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.
$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.
my $symbol = $set->symbol();
Get the set stock symbol.
$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();
Same as startDate, but gets/sets the end of the period.
$set->setDateLimit($tm1, $tm2);
Same as:
$set->startDate($tm1); $set->endDate($tm2);
$set->clearDateLimit();
Remove date range restrictions -- established by startDate, endDate, or setDateLimit methods -- from the set.
my $transactionDates = $set->transactionDates();
Returns a reference on a array of the Time::Moment objects for every transaction in the set.
$set->printTransactionDates();
Actually prints to STDOUT the dates returned by the transactionDates method.
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.
$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.
my $profit = $set->profit();
Runs checkStats and then returns the profit for the set.
Runs checkStats and then returns the total commissions.
Runs checkStats and then returns the outlays, what was spent on acquisitions including overhead (commissions and fees).
Runs checkSTats and then returns the revenues, less overhead.
Runs checkStats and then returns the profit divided by the outlays.
Runs checkStats and then returns the regulatory fees.
Runs checkStats and then returns the total other fees paid.
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.
Runs checkStats and then returns a reference to the list of Realization objects created.
Loops through the list returned by $set->realizations() and returns a string that can be printed to view it.
John Everett Refior, <jrefior at gmail.com>
<jrefior at gmail.com>
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.
bug-finance-stockaccount at rt.cpan.org
You can find documentation for this module with the perldoc command.
perldoc Finance::StockAccount::Set
You can also look for information at:
RT: CPAN's request tracker (report bugs here)
http://rt.cpan.org/NoAuth/Bugs.html?Dist=Finance-StockAccount
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/Finance-StockAccount
CPAN Ratings
http://cpanratings.perl.org/d/Finance-StockAccount
Search CPAN
http://search.cpan.org/dist/Finance-StockAccount/
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.
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.
To install Finance::StockAccount, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Finance::StockAccount
CPAN shell
perl -MCPAN -e shell install Finance::StockAccount
For more information on module installation, please visit the detailed CPAN module installation guide.