File Coverage

blib/lib/WWW/IRail/API/Liveboard.pm

Criterion	Covered	Total	%
statement	15	17	88.2
branch			n/a
condition			n/a
subroutine	7	7	100.0
pod			n/a
total	22	24	91.6

package WWW::IRail::API::Liveboard;
BEGIN {
  $WWW::IRail::API::Liveboard::AUTHORITY = 'cpan:ESSELENS';
}
BEGIN {
  $WWW::IRail::API::Liveboard::VERSION = '0.003';
}
use strict;
use Carp qw/croak/;
use HTTP::Request::Common;
use JSON::XS;
use XML::Simple;
use YAML qw/freeze/;

sub make_request {
    my %attr = ref $_[0] eq 'HASH' ? %{$_[0]} : @_;

    $attr{station} ||= $attr{from} || $attr{to};
    $attr{direction} ||= $attr{dir} || $attr{from} ? 'DEP' : $attr{to} ? 'ARR' : 'DEP';
    $attr{direction} =~ s/^(arr|dep).*/\U$1/i;

    croak 'too few arguments' unless $attr{station};

    my %urimap = ( direction => 'arrdep' );

    my $url = 'http://dev.api.irail.be/liveboard/?'.
                join '&', map { ($urimap{$_} || $_) .'='.$attr{$_} }
                qw/station direction/;

    my $req = new HTTP::Request(GET => $url);

    return $req;
}

sub parse_response {
    my ($http_response, $dataType) = @_;

    my $obj = XMLin($http_response->content,
        NoAttr => $dataType eq 'XML' ? 0 : 1,
        SuppressEmpty => 1,
        NormaliseSpace => 2,
        ForceArray => [ 'departure', 'arrival' ],
        KeyAttr => [],
        GroupTags => { departures => 'departure', arrivals => 'arrival' },
    );

    ($obj->{timestamp}) = ($http_response->content =~ m/timestamp="(\d+)"/);

    for ($dataType) {
        /xml/i and return XMLout $obj, RootName => 'liveboard', GroupTags => { departures => 'departure', arrivals => 'arrival' };
        /json/i and return JSON::XS->new->ascii->pretty->allow_nonref->encode($obj);
        /yaml/i and return freeze $obj;
        /perl/i and return $obj;
    }

    return $obj; # default to perl

}

42;



=pod

=head1 VERSION

version 0.003

=head1 NAME

WWW::IRail::API::Liveboard - HTTP::Request builder and HTTP::Response parser for the IRail API Liveboard data

=head1 SYNOPSIS

    make_request ( station => 'oostende' );     # departures by default

    make_request ( to => 'oostende' );          # arrivals coming into oostende

=head1 DESCRIPTION

This module builds a L and has a parser for the
L. It's up to you to transmit it over the wire. If don't want
to do that yourself, don't use this module directly and use L
instead.

=head1 METHODS

=head2 make_request( I 'val'> | I<{ key => 'val' }> )

Only the C argument is required, but if you either use C or C it will be seen as
the station name with the direction set accordingly. Memento: trains leaving B => 'oostende' and
trains arriving inB => 'oostende'. If the direction could not be deduced it defaults to C<'departures'>

    make_request ( from => 'oostende' );

    make_request ( station => 'oostende', direction => 'departures' );

    make_request ( { station => 'oostende', dir => 'arr' } );

the API direction parameter is extracted from your input using C
so you can choose between less typing or better readability.

=head2 parse_response( I<$http_response>, I )

rses the HTTP::Response you got back from the server, which if all went well contains XML.
That XML is then transformed into other data formats

=over 4

=item *

xml

=item *

XML

=item *

YAML

=item *

JSON

=item *

perl (default)

=back

=head3 example of output when dataType = 'xml'










=head3 example of output when dataType = 'XML'




          1
          DENDERMONDE
          1291043100


          1
          DENDERMONDE
          1291044480


          2
          GERAARDSBERGEN
          1291046100


          1
          DENDERMONDE
          1291046700


      MOLLEM


=head3 example of output when dataType = 'YAML'

    ---
    departures:
      - platform: 1
        station: DENDERMONDE
        time: 1291043100
        vehicle: BE.NMBS.CR1564
      - platform: 1
        station: DENDERMONDE
        time: 1291044480
        vehicle: BE.NMBS.CR5316
      - platform: 2
        station: GERAARDSBERGEN
        time: 1291046100
        vehicle: BE.NMBS.CR1588
      - platform: 1
        station: DENDERMONDE
        time: 1291046700
        vehicle: BE.NMBS.CR1565
    station: MOLLEM
    timestamp: 1291044267

=head3 example of output when dataType = 'JSON'

    {
       "departures" : [
          {
             "station" : "DENDERMONDE",
             "time" : "1291043100",
             "vehicle" : "BE.NMBS.CR1564",
             "platform" : "1"
          },
          {
             "station" : "DENDERMONDE",
             "time" : "1291044480",
             "vehicle" : "BE.NMBS.CR5316",
             "platform" : "1"
          },
          {
             "station" : "GERAARDSBERGEN",
             "time" : "1291046100",
             "vehicle" : "BE.NMBS.CR1588",
             "platform" : "2"
          },
          {
             "station" : "DENDERMONDE",
             "time" : "1291046700",
             "vehicle" : "BE.NMBS.CR1565",
             "platform" : "1"
          }
       ],
       "station" : "MOLLEM",
       "timestamp" : "1291044295"
    }

=head3 example of output when dataType = 'perl'

    {
          'departures' => [
                          {
                            'station' => 'DENDERMONDE',
                            'time' => '1291043100',
                            'vehicle' => 'BE.NMBS.CR1564',
                            'platform' => '1'
                          },
                          {
                            'station' => 'DENDERMONDE',
                            'time' => '1291044480',
                            'vehicle' => 'BE.NMBS.CR5316',
                            'platform' => '1'
                          },
                          {
                            'station' => 'GERAARDSBERGEN',
                            'time' => '1291046100',
                            'vehicle' => 'BE.NMBS.CR1588',
                            'platform' => '2'
                          },
                          {
                            'station' => 'DENDERMONDE',
                            'time' => '1291046700',
                            'vehicle' => 'BE.NMBS.CR1565',
                            'platform' => '1'
                          }
                        ],
          'station' => 'MOLLEM',
          'timestamp' => '1291044344'
   };

=head1 METHODS

=head1 INSTALLATION

See perlmodinstall for information and options on installing Perl modules.

=head1 BUGS AND LIMITATIONS

No bugs have been reported.

Please report any bugs or feature requests through the web interface at
L.

=head1 AUTHOR

Tim Esselens

=head1 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.

=cut


__END__