VERSION
version 0.002
NAME
WWW::IRail::API - A wrapper for the iRail.be API
SYNOPSIS
use WWW::IRail::API;
use Data::Dumper;
## OO interface ############################################################################
my $irail = new WWW::IRail::API( dataType => 'YAML' );
my $trains_bxl_ost = $irail->lookup_connections(from => 'brussel noord', to => 'oostende');
print Dumper($trains_bxl_ost);
## functional interface ####################################################################
# YAML liveboard with trains departing from *Brussel Noord*
print irail from => 'brussel noord'
# YAML connections of trains between *Brussel Noord* and *Oostende* for tomorrow at 14:00
print irail from => 'brussel noord', to => 'oostende', date => 'tomorrow afternoon'
# JSON station lookup of all stations matching qr/oost/
print irail station => qr/oost/, dataType => 'json'
# XML vehicle lookup
print irail vehicle => 'BE.NMBS.CR2089', dataType => 'XML'
# perl liveboard lookup
my $board = irail from => 'brussel noord', dataType => 'perl';DESCRIPTION
WWW::IRail::API is a set of modules which allow you to query the http://dev.irail.be API for Stations, Connections, Liveboard and Vehicle data.
METHODS
new(key = 'value'> | {key = 'value'}>)
Constructor. Should normally be used without arguments, but if required you could override some internals.
my $irail = new WWW::IRail::API( _client => 'LWP', dataType => 'JSON' );lookup_stations(key = 'value'> | {key = 'value'}>)
Method which takes a string or a hash(ref) and returns a list of stations in the set dataType.
my @list = $irail->lookup_stations(filter => "brussel");
my @list = $irail->lookup_stations(filter => qr/brussel/i);
my @list = $irail->lookup_stations(filter => sub { /brussel/i } );
my $json_string = $irail->lookup_stations(filter => qr/./, dataType => 'JSON');FEATURES
Multiple output formats
The returned results can be in either XML, JSON or YAML format. You can even select between two flavours XML (xml, XML) to suit your taste. Ofcourse, if you stay in perl, you can access the return object directly.
Isolated parsers based on HTTP::[qw/Request Response/]
The internal parsers consist of simply two subs. make_request() which takes in arbitrary query parameters and returns a HTTP::Request object. And parse_response() which takes a HTTP::Response and builds an object which it then returns in the desired output format.
This makes them isolated pieces of code and ideal for testing or plugging into other HTTP aware systems. You can thus safely use WWW::IRail::API::Connection in your code without ever using or loading any other of our modules.
Support for sync or async pluggable clients
Clients take HTTP::Request objects and process() them by a request over the wire. They then simply return the HTTP::Response or they will call a callback with the response as a first parameter.
If you are going to write your own client, you only need to implement a process sub which will be called with ($http_request, $callback) parameters giving you the option to either return from your process call and ignore the callback or call the callback and go async from there.
Natural data parsing
If date matches /\w/ it will hand over parsing to DateTime::Format::Natural. for example: date => 'friday at 6pm';
METHODS
LIMITATIONS
fetching the station list is an all or nothing operation, this should be cached
natural date parsing is in english only. It can also not parse 'friday afternoon' (yet)
TODO
implement caching
implement AE/Coro LWP client (in another module)
EXAMPLES
Example you can run from the commandline to get you started quickly
# install App::cpanminus the easy way
% curl -L http://cpanmin.us | sudo perl - --self-upgrade
# install the WWW::IRail::API modules
% cpanm -S WWW::IRail::API
# run a onliner from the commandline interface
% perl -MWWW::IRail::API -e 'print irail from => "brussel noord", to => "oostende", date => "next friday"SEE ALSO
INSTALLATION
See perlmodinstall for information and options on installing Perl modules.
BUGS AND LIMITATIONS
No bugs have been reported.
Please report any bugs or feature requests through the web interface at http://rt.cpan.org.
AUTHOR
Tim Esselens <tim.esselens@gmail.com>
COPYRIGHT AND LICENSE
This software is copyright (c) 2010 by Tim Esselens.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.