/ 
WWW-Velib-0.05
River stage zero No dependents
/ WWW::Velib

NAME

WWW::Velib - Download account information from the Velib website

VERSION

This document describes version 0.05 of WWW::Velib, released 2007-11-13.

SYNOPSIS

use WWW::Velib;

my $v = WWW::Velib->new(login => '0000123456', password => '1234');
$v->get_month;
for my $trip ($v->trips) {
  print $trip->date, ' from ', $trip->from,
      ' to ', $trip->to, "\n";
}

DESCRIPTION

Documentation en français ci-dessous.

WWW::Velib connects to the Velib web site with your credentials and extracts the information concerning your account. The available information includes the date your subscription expires, how many trips made this month, their details, and more.

Detailed information regarding the trips you have made using the Velib system are only available for the current month or three weeks, whichever is longer. Beyond this time frame, this information is no longer available on the web site. WWW::Velib allows you to download and store this information locally. From this you can process the information to discover which station you use the most, your average trip duration, on which days you made the most trips and so on.

Please note: try to avoid connecting to the site too often. The information is reasonably static: once a day should be quite sufficient.

METHODS

new

Creates a new WWW::Velib object. The main issue to resolve is how you wish to initialise the object with your credentials. The following named parameters are recognised:

login
pin

The standard approach is to pass two named parameters, login and pin. (password is recognised as an alias for pin).

my $v = WWW::Velib->new(login => '0000123456', pin => '1234');

Note that both logins (account numbers) and PINs are both numeric. If either start with 0, Perl will consider that the numbers are to be interpreted in octal. It is therefore safer to quote them as strings.

If you are lazy, you may dispense with the named parameters, and simply pass in two parameters, both of which must be all-digits, one being 10 digits long, the other being 4 digits long.

my $v = WWW::Velib->new( '0001234567', '9876' );
defer

In normal use, as soon as a WWW::Velib object is instantiated, it will immediately connect to the Velib website. This may be prevented by using defer

my $v = WWW::Velib->new(login => '123', pin => '456', defer => 1);

In this case, the myaccount method may be used to initiate the download at the appropriate time. TODO: Ugly: this will be changed in a future release.

cache_dir

If you want to save the downloaded HTML pages to a local directory, the cache_dir parameter may be used to specifiy the name of the directory.

my $v = WWW::Velib->new(
  login     => '0000123456',
  pin       => '1234',
  cache_dir => '/home/user/moi/velib',
);

The main account page will be stored as myaccount.yyyymmdd-hhmmss and the monthly details page will be stored as month.yyyymmdd-hhmmss.

myaccount

Accepts a filename containing the contents of the authenticated account page.

get_month

Retrieves the details of the trips made during the current month.

balance

Returns the current balance of your account (in Euros). If you have taken a bike for more than half an hour, this amount will be negative. In that case, you will not be able to take another one until you have brought the balance up to at least zero. If you have credited your account with a few euros to make allowances for the occasional long ride, the balance will be positive.

end_date

Returns the date your Velib subscription expires.

remain

Returns the number of days left until the end of the Velib subscription.

in_use

Returns a true value if the Velib' system considers that you have taken out a bike and not returned it. This could be costly...

conso_month

Returns the month (en français) of the account information (current month if used online, otherwise the month appearing in the stored file given to myaccount.

conso_year

Returns the year of the account information.

conso_trips

Returns the number of trips (journeys) made this month.

conso_time

Returns the total amount of time (in minutes) taken this month.

conso_bal

Returns the cost of the bicycle trips made this month. If all trips have taken less than 30 minutes, it will be zero. See also balance).

trips

Returns an array containing the details of all the trip made in the current month. Each element of the array is a WWW::Velib::Trip object: consult that page for information on how to process them. The array is ordered by date, from oldest to newest.

next_trip

Acts as an iterator over the list of trips. Returns the first and subsequent trips on each call. Returns undef after the last trip has been returned.

while (my $trip = $v->next_trip) {
    print $trip->date, ' from ', $trip->from, ' to ', $trip->to, $/;
}
reset_trip

Resets the trip iterator. The next call to next_trip will return the first trip.

DOCUMENTATION EN FRANÇAIS

WWW::Velib établit une connexion au site Web de Velib avec vos indentifiants et extrait l'information au sujet de votre compte. L'information disponible inclut la date de la fin de votre abonnement, combien de trajets vous avez fait ce mois-ci, ainsi que leurs détails.

L'information détaillée concernant les trajets que vous avez effectué avec Velib ne sont disponibles que pour le mois courant ou les trois dernières semaines. Passé ce délai, ces informations ne sont plus disponible sur le site Web.

WWW::Velib vous permet de télécharger et stocker cette information en local. Vous pouvez alors analyser l'information recueillie pour découvrir quelles stations vous employez le plus souvent, la durée moyenne des trajets, quel jour vous avez fait le plus de voyages et ainsi de suite.

TODO: étoffer la doc (y a-t-il des volontaires ?)

NOTES

This is beta code! The API is subject to change: the ugly defer hack must die, and there should be a way to loop through several months of downloaded files.

ACKNOWLEDGEMENTS

Thanks to Max "Corion" Maischein for the wonderful WWW::Mechanize::Shell module that made the heavy lifting a snap to write.

SEE ALSO

AUTHOR

David Landgren, copyright (C) 2007. All rights reserved.

http://www.landgren.net/perl/

If you (find a) use this module, I'd love to hear about it. If you want to be informed of updates, send me a note. You know my first name, you know my domain. Can you figure out my e-mail address?

LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

1 POD Error

The following errors were encountered while parsing the POD:

Around line 349:

Non-ASCII character seen before =encoding in 'français'. Assuming CP1252