NAME¶
Finance::QuoteHist::Generic - Base class for retrieving historical stock quotes.
SYNOPSIS¶
package Finance::QuoteHist::MyFavoriteSite;
use strict;
use vars qw(@ISA);
use Finance::QuoteHist::Generic;
@ISA = qw(Finance::QuoteHist::Generic);
sub url_maker {
# This method returns a code reference for a routine that, upon
# repeated invocation, will provide however many URLs are necessary
# to fully obtain the historical data for a given target mode and
# parsing mode.
}
DESCRIPTION¶
This is the base class for retrieving historical stock quotes. It is built
around LWP::UserAgent. Page results are currently parsed as either CSV or HTML
tables.
In order to actually retrieve historical stock quotes, this class should be
subclassed and tailored to a particular web site. In particular, the
"url_maker()" factory method should be overridden, which provides a
code reference to a routine that provides however many URLs are necessary to
retrieve the data over a list of symbols within the given date range, for a
particular target (quotes, dividends, splits). Different sites have different
formats and different limitations on how many quotes are returned for each
query. See Finance::QuoteHist::Yahoo and Finance::QuoteHist::QuoteMedia for
some examples of how to do this.
For more complicated sites, such as Yahoo, overriding additonal methods might be
necessary for dealing with things such as splits and dividends.
METHODS¶
- new()
- Returns a new Finance::QuoteHist::Generic object. Valid
attributes are:
- start_date
- end_date
- Specify the date range from which you would like historical
quotes. These dates get parsed by the "ParseDate()" method in
Date::Manip, so see Date::Manip(3) for more information on valid
date strings. They are quite flexible, and include such strings as '1 year
ago'. Date boundaries can also be dynamically set with methods of the same
name. The absence of a start date means go to the beginning of the
history. The absence of an end date means go up to the most recent
historical date. The absence of both means grab everything.
- symbols
- Indicates which ticker symbols to include in the search for
historical quotes. Passed either as a string (for single ticker) or an
array ref for multiple tickers.
- granularity
- Returns rows at 'daily', 'weekly', or 'monthly' levels of
granularity. Defaults to 'daily'.
- attempts
- Sets how persistently the module tries to retrieve the
quotes. There are two places this will manifest. First, if there are what
appear to be network errors, this many network connections are attempted
for that URL. Secondly, for quotes only, if pages were successfully
retrieved, but they contained no quotes, this number of attempts are made
to retrieve a document with data. Sometimes sites will report a temporary
internal error via HTML, and if it is truly transitory this will usually
get around it. The default is 3.
- lineup
- Passed as an array reference (or scalar for single class),
this list indicates which Finance::QuoteHist::Generic sub classes should
be invoked in the event this class fails in its attempt to retrieve
historical quotes. In the event of failure, the first class in this list
is invoked with the same parameters as the original class, and the
remaining classes are passed as the lineup to the new class. This sets up
a daisy chain of redundancy in the event a particular site is hosed. See
Finance::QuoteHist(3) to see an example of how this is done in a
top level invocation of these modules. This list is empty by default.
- quote_precision
- Sets the number of decimal places to which quote values are
rounded. This might be of particular significance if there is
auto-adjustment taking place (which is only under particular circumstances
currently...see Finance::QuoteHist::Yahoo). Setting this to 0 will disable
the rounding behavior, returning the quote values as they appear on the
sites (assuming no auto-adjustment has taken place). The default is
4.
- row_filter
- When provided a subroutine reference, the routine is
invoked with an array reference for each raw row retrieved from the quote
source. This allows user-defined filtering or formatting for the items of
each row. This routine is invoked before any built-in routines are called
on the row. The array must be modified directly rather than returned as a
value. Use sparingly since the built-in filtering and normalizing routines
do expect each row to more or less look like historical stock data.
Rearranging the order of the columns in each row is contraindicated.
- env_proxy
- When set, instructs the underlying LWP::UserAgent to load
proxy configuration information from environment variables. See the
"ua()" method and LWP::UserAgent for more information.
- auto_proxy
- Same as env_proxy, but tests first to see if
$ENV{http_proxy} is present.
- verbose
- When set, many status messages are printed to STDERR
indicating progression through URLs and lineup invocations.
- quiet
- When set, certain failure messages are suppressed from
appearing on STDERR. These messages would normally appear regardless the
setting of the "verbose" flag.
The following methods are the primary user interface methods; methods of
interest to developers wishing to make their own site-specific instance of
this module will find information on overriding methods further below.
- quotes()
- Retrieves historical quotes for all provided symbols over
the specified date range. Depending on context, returns either a list of
rows or an array reference to the same list of rows.
- dividends()
- splits()
- If available, retrieves dividend or split information for
all provided symbols over the specified date range. If there are no
site-specific subclassed modules in the lineup capable of getting
dividends or splits, the user will be notified on STDERR unless the
quiet flag was requested during object creation.
- start_date(date_string)
- end_date(date_string)
- Set the date boundaries of all queries. The
date_string is interpreted by the Date::Manip module. The absence
of a start date means retrieve back to the beginning of that ticker's
history. The absence of an end date means retrieve up to the latest date
in the history.
- clear_cache()
- When results are gathered for a particular date range,
whether they be via direct query or incidental extraction, they are
cached. This cache is cleared by invoking this method directly, by
resetting the boundary dates of the query, or by changing the
"adjusted()" setting.
- quote_source(ticker_symbol)
- dividend_source(ticker_symbol)
- split_source(ticker_symbol)
- After query, these methods can be used to find out which
particular subclass in the lineup fulfilled the corresponding
request for a particular ticker symbol.
The following methods are the primary methods of interest for developers wishing
to make a site-specific subclass. The
url_maker() factory is typically
all that is necessary.
- url_maker()
- Returns a subroutine reference that serves as an iterrator
for producing URLs based on target and parse mode. Repeated calls to this
routine produce subsequent URLs in the sequence.
- extractors()
- For a particular target mode and parse mode, returns a hash
containing code references to extraction routines for the remaining
targets. For example, for target 'quote' in parse mode 'html' there might
be extractor routines for both 'dividend' and 'split'.
- ua()
- Accessor method for the LWP::UserAgent object used to
process HTTP::Request for individual URLs. This can be handy for such
things as configuring proxy access for the underlying user agent. Example:
# Manual configuration
$qh1->ua->proxy(['http'], 'http://proxy.sn.no:8001/');
# Load from environment variables
$qh2->ua->env_proxy();
See LWP::UserAgent for more information on the capabilities of that
module.
The following are potentially useful for calling within methods overridden
above:
- parse_mode($parse_mode)
- Set the current parsing mode. Currently parsers are
available for html and csv.
- target_mode($target_mode)
- Return the current target mode.
- dates($start_date, $end_date)
- Returns a list of business days between and including the
provided boundary dates. If no arguments are provided, start_date
and end_date default to the currently specified date range.
- labels(%parms)
- Used to override the default labels for a given target mode
and parse mode. Takes the following named parameters:
- target_mode
- Can currently be 'quote', 'dividend', or 'split'. Default
is 'quote'.
- parse mode
- Can currently be 'csv' or 'html'. The default is typically
'csv' but might vary depending on the quote source.
- labels
- The following are the default labels. Text entries convert
to case- insensitive regular expressions):
target_mode
-------------------------------------------------------
quote => ['date','open','high','low','close',qr(vol|shares)i]
dividend => ['date','div']
split => ['date','post','pre']
DISCLAIMER¶
The data returned from these modules is in no way guaranteed, nor are the
developers responsible in any way for how this data (or lack thereof) is used.
The interface is based on URLs and page layouts that might change at any time.
Even though these modules are designed to be adaptive under these
circumstances, they will at some point probably be unable to retrieve data
unless fixed or provided with new parameters. Furthermore, the data from these
web sites is usually not even guaranteed by the web sites themselves, and
oftentimes is acquired elsewhere. See the documentation for each site-specific
module for more information regarding the disclaimer for that site.
Above all, play nice.
AUTHOR¶
Matthew P. Sisk, <
sisk@mojotoad.com>
COPYRIGHT¶
Copyright (c) 2000-2011 Matthew P. Sisk. All rights reserved. All wrongs
revenged. This program is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.
SEE ALSO¶
Finance::QuoteHist(3),
HTML::TableExtract(3),
Date::Manip(3),
perlmodlib(1),
perl(1).