A Stock Portfolio Manager
Let's look at an example program that illustrates just how much time you can save using Perl modules that are already written. The example application is a stock portfolio manager. It maintains any number of portfolios, each of which can contain any number of securities. The portfolio manager downloads the latest share prices for all the stocks in your portfolio from Yahoo! Finance every time you view a portfolio.
First, the program creates a list of portfolios. From that page, you can add a new portfolio or view or delete an existing portfolio. When you view a portfolio, the latest prices for those stocks will be displayed. You can also delete stocks from the portfolio, or add new stocks to the portfolio from that page as well.
One thing this program demonstrates is how you can save yourself a lot of pain and suffering by using modules to take care of a lot of the grunt work in your script. In this example, the CGI modules LWP::Simple and XML::Simple were used. Both were introduced in earlier lessons. I use the LWP module to download stock prices from the Yahoo! Finance Web site. The CGI module takes care of everyday stuff such as processing query parameters on HTTP requests. All the persistent data is stored in an XML file, which is accessed using the XML::Simple module.
The Data File
Let's look at how the data is stored from request to request. Bear in mind that this data file is generated by the XML::Simple module from the data structure used in the program. I actually start out by writing the XML file, use the XML::Simple to read it in, and then write it back out every time the script runs to be sure to catch any changes that were made. Listing 21.1 contains a data listing.
Listing 21.1. The Data for the Stock Portfolio Program
When XML::Simple reads this file, it turns it into a structure of nested hashes (using references). One of the challenges when reading the program is figuring out how the data in this file maps to the data structure used throughout.
How the Program Works
Let's look at how this program is structured. The first thing to point out is that this program actually responds to many different kinds of requests. It is used to view a list of portfolios, view individual portfolios, and handle the addition and removal of both portfolios and stocks. The program expects a parameter named c (for command), which will indicate what sort of action should be taken. If the c parameter is not supplied, the program assumes that you want a list of portfolios.
Depending on the command sent to the program, other parameters might also be expected. The two optional parameters are the name of the portfolio and the ticker symbol of the stock. For example, if the command is del and the p parameter (for portfolio) is foo, the program knows you want to delete the portfolio named foo.
The core of the program is an if construct that checks which command was issued, and performs the tasks associated with that command. For example, if the command is add_stock, the program performs some basic error checking, calls the add_stock subroutine, and then displays the updated portfolio and the add stock form (using the view_portfolio and display_add_stock_form subroutines).
The commands that the program supports are
del_stock— Deletes the specified stock from the specified portfolio.
add_stock— Adds the stock with the ticker specified to the current portfolio.
Before the conditional statement that drives the program, some modules were imported, some variables were initialized, and the parts of the page were printed out that are consistent regardless of which command was used. The footer of the page was printed out following the conditional statement.
Setting Up
Before I get into the meat of the program, some things have to be set up. This means importing the CGI, CGI::Carp (for better error reporting), XML::Simple, and LWP::Simple modules. Then, some global variables for this package that will be used throughout the script are set up. For example, the URLs for downloading stock information from Yahoo! Finance are hard coded, so that if those URLs change, they can be updated at the top of my program.
Also $command is initialized so that if the user fails to supply a command, list is used as the default. Probably the biggest job here, though, is reading in my data file. Amazingly, that part seems simple:
my $portfolios = XMLin("./portfolio.xml", forcearray => 1);
This code reads in a file called portfolio.xml, parses the XML data, and produces a reference to a data structure, which is assigned to a variable called $portfolios. An argument is passed to the XMLin() subroutine, forcearray, which basically tells it to treat all data as though it were in an array instead of handling lists of one item differently. This eliminates problems when a portfolio contains only one stock.
Displaying a List of Portfolios with list_portfolios()
Most of the list_portfolios() subroutine is concerned with printing out HTML, but there's some stuff that's worth inspecting here. For one thing, it introduces the data structure in the XML file. On the first line of the subroutine, a reference to the value in the top-level anonymous hash is created in my datastructure with the key portfolio, using this statement:
my $hashref = $portfolios->{portfolio} ;
The reference that's returned is to a hash containing all the portfolios in my file. On line 87, the keys in that anonymous hash are looped over, like this:
foreach my $port (keys %$hashref)
A list of the portfolios is printed out, along with links to view and delete them.
Displaying the Contents of a Single Portfolio Using view_portfolio()
This subroutine is a bit more complex. First, I read the argument passed to the subroutine and assign it to $port. Then, I create a reference to the hash containing the stocks in the named portfolio, like this:
my $hashref = $portfolios->{portfolio} ->{$port} ->{stock} ;
This reference points to a hash that contains hashes for each stock in the portfolio. The hashes are keyed on the stock's ticker symbol. Each of the stocks are then looped over using a foreach loop (just like the previous subroutine):
foreach my $stock_ticker (keys %$hashref)
In the body of the loop, the first thing to do is create a reference to the stock currently being processed, like this:
my $stock = $hashref->{$stock_ticker} ;
Then, some variables are set up that will be used to display this stock, print out the name of the company, and a delete link. Then, the get_current_price() subroutine is called to fetch the current price of the stock from Yahoo! Finance. I'll discuss that subroutine in a bit. After the price is fetched, a couple of temporary variables are set up so that the data can be used to update the record (which I do immediately after):
$stock->{lastprice} = $current_price;
$stock->{lastfetch} = time;
These two lines update the data structure so that the current price and time will be written to the data file as the previous price and time. At this point, all that's left is to print out the rest of the information about the stock.
Deleting Stocks and Portfolios Using delete_stock() and delete_portfolio()
When a user clicks on a delete link, the appropriate subroutine is called depending on whether they want to delete a stock or a portfolio. The statement used to delete a portfolio is
delete $portfolios->{portfolio} ->{$portfolio_name} ;
And here's the statement that deletes a stock:
delete $portfolios->{portfolio} ->{$portfolio_name} ->{stock} ->{$ticker} ;
As you can see, these statements simply delete values from hashes in the large data structure. When the data is saved, the changes will automatically be applied to the XML data file.
Adding a Portfolio Using add_portfolio()
Adding a portfolio is simple, you just test to make sure that the portfolio name entered doesn't already exist, and add a new empty hash to the data structure, like this:
$portfolios->{portfolio} ->{$portfolio_name} = {} ;
That's all there is to it. The user can populate the new portfolio. They just have to view it and start adding stocks to it.
Adding a Stock Using add_stock()
Okay, here's where the real action is. This subroutine demonstrates how error handling is dealt with, how to access the data structure, and it pulls information down from the Web. I'll go ahead and list the source code for this subroutine so that it can be examined closely:
1: sub add_stock
2: {
3: my $portfolio = shift(@_);
4: my $ticker = shift(@_);
5: my $stock_name = "";
6: my $stock_price = 0;
7:
8: if (exists $portfolios->{portfolio} ->{$portfolio} ->{stock} ->{$ticker} )
9: {
10: $errors .= "<li>That stock is already in the portfolio.</li>
";
11: return;
12: }
13:
14: my $url = $stock_info_url . "$ticker";
15: my $content = get($url);
16:
17: if (!$content)
18: {
19: $errors .= "<li>Couldn't retrieve stock information.</li>
";
20: return;
21: }
22:
23: if ($content =~ /No such ticker symbol/i)
24: {
25: $errors .= "<li>Invalid ticker symbol.</li>
";
26: return;
27: }
28:
29: if ($content =~ /<td colspan=7><font(.+?)><b>(.+?)s+</b>/i)
30: {
31: $stock_name = $2;
32: }
33:
34: if ($content =~ /Last Trade<br>(.+?)<b>([d.]+)</b>/i)
35: {
36: $stock_price = $2;
37: }
38:
39: my $hashref = $portfolios->{portfolio} ->{$portfolio} ->{stock} ;
40:
41: $hashref->{$ticker} = { lastfetch => time, lastprice => $stock_price,
42: company => $stock_name } ;
43: }
First, on lines 3 through 6, set up some variables. The first two variables take their values from the arguments passed to the subroutine, and the next two are set to default values. I'll get the real values from Yahoo! Finance, assume everything goes as planned.
Next, check to ensure that the stock the user is trying to add isn't already in the portfolio. If it is, add an error message, $errors, and return. Next, append the stock ticker to the URL for retrieving information about the stock. Then, use the get subroutine (which is part of LWP::Simple) to request the page associated with that URL. If the page was requested successfully, the HTML code that makes up the page is assigned to $content. Just in case it isn't, a test is done to see whether $content evaluates as true, and if it doesn't, raise an error and return.
If it isn't empty, look for a particular string named No such ticker symbol. This text only appears on the page if the ticker symbol is invalid. If it's there, they've requested a stock using a ticker symbol that doesn't exist, so raise an error and return.
Now we're ready to start grabbing data using regular expressions. First, grab the stock name, and then the current price. By carefully examining the source code of the page, I wrote the regular expressions used to extract this information (and nothing extraneous) from the page. The catch here is that if Yahoo! changes the appearance of this page, there's a pretty good chance that these regular expressions will stop matching what they're supposed to, and therefore, you'll have to update your script. When you extract information from Web pages like this, that's just something you have to contend with. One bit of advice is that you should use as small an expression as possible, which makes it less likely that someone will come along and break your script.
After these two bits of data have been extracted from the page, access the data structure to insert a new anonymous hash into the portfolio. When the data is written to disk, this new stock will be included.
Getting the Current Stock Price Using get_current_price()
I explained add_stock() in detail, therefore, I don't have to go into that much detail for this subroutine because it's sort of like add_stock(), except simpler. Like the previous subroutine, take the ticker symbol as an argument, append it to the URL where stock quotes are found, and then fetch the page containing the pertinent information. If, for some reason, the page isn't found, I raise an error and return from the subroutine.
What we then have is a large regular expression that extracts the current stock price from the HTML that was returned. This is a different regular expression than was used before. The same one could have been used, but because this is an example program, I wanted to use multiple pages and expressions. After the price has been extracted, it's returned.
Writing the Data Using write_data()
One of the last things the program does before exiting is write its data to disk. Transforming the data in $portfolios to XML is easy with XML::Simple, just use the following subroutine call:
my $xml = XMLout($portfolios);
After the XML is stored in the variable $xml, open a filehandle and write the data out to disk.
The Source Code
Listing 21.2 contains the source code for the portfolio.cgi program.
/td><td[^>]*><font[^>]*>(.+?)</font></td><td[^>]*><font[^>]*><b>([d.]+?)</b></font><