Articles

Although Personal Stock Streamer already has a built-in capital gains report, I took it upon myself to rewrite it in VBScript not only to prove that it can be done, but to extend it and make it easily customizable.

Normally, calculating capital gains for a given ticker would require applying each transaction checking whether it generated a change in position, and whether that position actually generated capital gains.  For example, a simple buy transaction may not generate capital gains, but a sale transaction may generate a gain or a loss if there is an open long position. This type of processing is already done internally within Personal Stock Streamer to calculate gains and losses, and to duplicate this in script would require a lot of work.  Getting this functionality for free is one advantage of having the capital gains report embedded in the main application.

So for this extension I had to cheat a little bit: I modified the script plug-in in Personal Stock Streamer 7.1 to expose the functionality described above, so that it would be trivially simple (and much faster) to rewrite the capital gains report in script.  This also eliminated the need to duplicate the transaction processing logic that is already inside Personal Stock Streamer.  What I did is add an optional argument to the Ticker::ApplyTransactionToCurrentHoldings() and Ticker::ApplyTransactionsToCurrentHoldingsUntil() methods that allows you to pass a reference to a callback object.  This callback object would define a handful of methods that would be called at the appropriate time by the main application, and all the report had to do was gather and summarize the data.  In the case of this report, the callback object is the same object that the report is running in, so I just pass "me" as the argument.

Before I go into describing these callback methods, I should say something about the design of the handler class for this report.  In order to separate out the long-term gains, short-term gains, and other income and expenses, I created three arrays that get populated with summary data by the callback methods I am about to describe.  This neatly separates the processing and output code, which allows easy modification of the formatting code to get any style of report you need.

The report handler defines four callback methods.  The first two, OnCBAddHoldings and OnCBSubtractHoldings, are called by Personal Stock Streamer whenever a transaction affects the current holdings for a ticker.  Because not all transactions that affect holdings are related to the capital gains report, there is a quick check at the beginning of each method to make sure that only certain transactions get saved in the summary arrays.  The second two callback methods, OnCBAddIncome and OnCBSubtractIncome, are called for dividends, income, and expense transactions that do not affect the holdings.  This allows us to put together a nice summary of those transactions as well.  There is absolutely nothing complicated about these callback methods because all they do is store the summary data for later.

After the processing is finished, the output method is called once for each of the three sections of the report, which sorts the array by ticker and generates the HTML output that is displayed in the Reports view.  One possible enhancement that could be made in a future version of this report is to have sub-totals for each ticker to make it easier to see the gains for individual investments.

The full source code for the Capital Gains report is available here.