view release on metacpan or  search on metacpan

lib/Data/Mirror.pm  view on Meta::CPAN

a copy of the remote resource if needed, and then parse it. If a program uses
data sources of many different types (say JSON, XML and CSV) then it often does
the same thing over and over again, just using different modules for parsing.

C<Data::Mirror> does all that for you, so you can focus on using the data.

=head1 USAGE

The general form of this module's API is:

    $value = Data::Mirror::mirror_TYPE($url);

where C<TYPE> corresponds to the expected data type of the resource at C<$url>
(which can be a string or a L<URI>).

The return value will be C<undef> if there's an error. The module will C<carp()>
so you can catch any errors.

I<Note: it's possible that the remote resource will actually be someting that
evaluates to C<undef> (for example, a JSON document that is exactly C<"null">,
or a YAML document that is exactly C<"~">), or if there is an error parsing the
resource once retrieved. Consider wrapping the method call in C<eval> if you
need to distinguish between these scenarios.>

By default, if the locally cached version of the resource is younger than
C<$Data::Mirror::TTL_SECONDS> old, C<Data::Mirror> will just use it and won't
try to refresh it, but you can override that per-request by passing the C<$ttl>
argument:

    $value = Data::Mirror::mirror_TYPE($url, $ttl);

=head1 EXPORTS

To import all the functions listed below, include C<:all> in the tags imported
by C<use>:

    use Data::Mirror qw(:all);

You can also import specific functions separately:

    use Data::Mirror qw(mirror_json mirror_csv);

=head1 PACKAGE VARIABLES

=head2 $TTL_SECONDS

This is the global "time to live" of local copies of files, which is used if
the C<$ttl> argument is not passed to a mirror function. By default it's 300
seconds.

If C<Data::Mirror> receives a 304 response from the server, then it will
update the mtime of the local file so that another refresh will not occur
until a further C<$TTL_SECONDS> seconds has elapsed. The mtime will either be
the current timestamp, or the value of the C<Expires> header, whichever is
later.

=head2 $UA

This is an L<LWP::UserAgent> object used to retrieve remote resources. You
may wish to use this variable to configure various aspects of its behaviour,
such as credentials, user agent string, TLS options, etc.

=head2 $JSON

This is a L<JSON::XS> object used for JSON decoding. You may wish to use this
variable to change how it processes JSON data.

=head2 $CSV

This is a L<Text::CSV_XS> object used for CSV parsing. You may wish to use this
variable to change how it processes CSV data.

=head2 $XDG

This is a L<File::XDG> object used to obtain the user's cache directory.

=head1 FUNCTIONS

=head2 mirror_file()

This method returns a string containg a name of a local file containing the
resource. All the other functions listed in this section use C<mirror_file()>
under the hood.

C<Data::Mirror> will write local copies of files to the appropriate temporary
directory, determined using the C<$XDG-E<gt>cache_home()> (prior to v0.08, the
value of C<File::Spec-E<gt>tmpdir()> was used). This means that different
programs, run by the same user, that use L<Data::Mirror> to retrieve the same
URL, will effectively share a cache for that URL, but other users on the system
will not.

=head2 mirror_str($url)

This method returns a UTF-8 encoded string containing the resource. If it's
possible that the resource might be large enough to use up a lot of memory,
consider using C<mirror_file()> or C<mirror_fh()> instead.

=head2 mirror_fh()

This method returns an L<IO::File> handle containing the resource.

=head2 mirror_xml()

This method returns an L<XML::LibXML::Document> handle containing the resource.

=head2 mirror_json()

This method returns a JSON data structure containing the resource. This could be
C<undef>, a simple string, or an arrayref or hashref.

=head2 mirror_yaml()

This method returns a YAML data structure containing the resource. This could be
C<undef>, a simple string, or an arrayref or hashref.

=head2 mirror_csv()

This method returns a reference to an array of arrayrefs containing the CSV rows
in the resource.

=head1 OTHER FUNCTIONS