File Coverage

blib/lib/Data/FR/Town.pm

Criterion	Covered	Total	%
statement	51	55	92.7
branch	10	10	100.0
condition			n/a
subroutine	11	13	84.6
pod	9	9	100.0
total	81	87	93.1

package Data::FR::Town;

use 5.006;
use strict;
use warnings;
use Carp;

=head1 NAME

Data::FR::Town - Provides data about french town (INSEE code, ZIP/postal code, name...)

=head1 VERSION

Version 0.01

=cut

our $VERSION = '0.02';

our %TOWNS;

=head1 SYNOPSIS

This module provides basic data about french towns.

    use Data::FR::Town;

    # Multiple ways to get the same town
    my $town1 = Data::FR::Town->new( {insee => "01001"});
    my $town2 = Data::FR::Town->new( {zip => "01400"});
    my $town3 = Data::FR::Town->find( {insee => "01001"});
    my $town3 = Data::FR::Town->find( {zip => "01400"});

    Now you can get data about the selected town, using the getters :

    my $zip = $town1->zip();
    my $name = $town1->name();
    my $cname = $town1->cname();
    ...

=head1 SUBROUTINES/METHODS

=head2 new ( \%params )

Return a town object selected through the specified parameters.

%params accept two valid keys : 'insee' and 'zip' to specfy the town.

=cut

sub new {
    my $class  = shift;
    my $params = shift;

    my $self = bless {}, $class;

    for my $line () {
        chomp $line;

        my ( $insee, $article, $name, $cname, $zip, $dep, $depname, $origin ) = split ';', $line;

        $class::TOWNS{insee}{$insee}{article} = $article;
        $class::TOWNS{insee}{$insee}{name}    = $name;
        $class::TOWNS{insee}{$insee}{cname}   = $cname;
        $class::TOWNS{insee}{$insee}{zip}     = $zip;
        $class::TOWNS{insee}{$insee}{dep}     = $dep;
        $class::TOWNS{insee}{$insee}{depname} = $depname;
        $class::TOWNS{insee}{$insee}{origin}  = $origin;
        $class::TOWNS{zip}{$zip}              = $class::TOWNS->{insee}{$insee};

    }

    for my $param ( keys %{$params} ) {
        if ( $param =~ /insee/ ) {
            return $class->find( { insee => $params->{$param} } );
        } elsif ( $param =~ /zip/ ) {
            return $class->find( { zip => $params->{$param} } );

        } else {
            croak "Unknown parameter : $param";
        }
    }

    return bless $self, $class;
}

=head2 find ( \%params )

Return a town object selected through the specified parameters.

%params accept two valid keys : 'insee' and 'zip' to specfy the town.

=cut

sub find {
    my $class  = shift;
    my $params = shift;

    $class = ref $class if ref $class;

    for my $param ( keys %$params ) {
        if ( $class::TOWNS{$param}{ $params->{$param} } ) {
            return bless $class::TOWNS{$param}{ $params->{$param} }, $class;
        } else {
            croak "Unknown parameter : $param" unless $param =~ /(zip|insee)/;
            return undef;
        }
    }
}

=head2 insee ()

Return the INSEE code associated to this town

=cut

sub insee {
    my $self = shift;

    return $self->{insee};
}

=head2 zip ()

Return the zip/postal code associated to this town

=cut

sub zip {
    my $self = shift;

    return $self->{zip};
}

=head2 article ()

Return the article associated to this town, as some french town may have one.
(La Courneuve)

=cut

sub article {
    my $self = shift;

    return $self->{article};
}

=head2 name ()

Return the name of the town
The first letter is uppercased the other ones are lowercase

=cut

sub name {
    my $self = shift;

    return $self->{name};
}

=head2 cname ()

Return the capitalized name of the town
All letters are (non accentuated) uppercase.

=cut

sub cname {
    my $self = shift;

    return $self->{cname};
}

=head2 dep ()

Return the department's number

=cut

sub dep {
    my $self = shift;

    return $self->{dep};
}

=head2 depname ()

Return the department's name

=cut

sub depname {
    my $self = shift;

    return $self->{depname};
}

=head1 DISCLAIMER

This version is based on the data from the INSEE site :
http://www.insee.fr/fr/methodes/nomenclatures/cog/telechargement/2012/txt/comsimp2012.zip

As this data is free and quite stable, the information about the INSEE
code, name are quite accurate.

The information about the postal/zip code is however much more difficult to
get AND subject to change.

I'll try to keep the postal/zip codes up to date, but anyone knowing a way to get
automatically these data could greatly contribute by telling it (or providing the data)

Don't hesitate to contact me on this subject.


Arnaud (Arhuman) ASSAD, C<<  >>

=head1 AUTHOR

Arnaud (Arhuman) ASSAD, C<<  >>

=head1 BUGS

Please report any bugs or feature requests to C, or through
the web interface at L.  I will be notified, and then you'll

=head1 SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Data::FR::Town


You can also look for information at:

=over 4

=item * RT: CPAN's request tracker (report bugs here)

L

=item * AnnoCPAN: Annotated CPAN documentation

L

=item * CPAN Ratings

L

=item * Search CPAN

L

=back


=head1 ACKNOWLEDGEMENTS


=head1 LICENSE AND COPYRIGHT

Copyright 2012 Arnaud (Arhuman) ASSAD.

This program is free software; you can redistribute it and/or modify it
under the terms of either: the GNU General Public License as published
by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.


=cut

1;    # End of Data::FR::Town

__DATA__