Ubuntu Manpage: Finance::QuoteHist::Generic - Base class for retrieving historical stock quotes.

Provided by: libfinance-quotehist-perl_1.32-1_all

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 additional 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-2021 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.