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 for an example 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-2013 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).