NAME

Geo::Address::Mail - A Mailing Address on Earth

SYNOPSIS

Geo::Address::Mail provides a generic object representation of a mailing address that may be subclassed to provide more specific typing of attributes. The core class, Geo::Address::Mail provides common, loosely typed attributes and methods.

    use Geo::Address::Mail::US;

    my $add = Geo::Address::Mail::US->new(
        name => 'Cory G Watson',
        street => '123 Main St',
        city => 'Testville',
        postal_code => '12345'
    );

SUBCLASSING

The real reason for Geo::Address::Mail is to provide a common class that can be used to build mailing address objects for other countries.

Subclasses are expected additional type refinement and attributes. For example, Geo::Address::Mail::US uses a more specific type for validation USPS ZIP codes and adds a street2 attribute for an optional additional line of addressing.

SUBCLASS NAMING

Subclasses should be named with Geo::Address::Mail and the two-letter ISO-3166 country codes.

ADDITIONAL USES

Using a common address object enables a family of distributions that provide interesting address functionality such as Geo::Address::Mail::Standardizer.

ATTRIBUTES

city

The city/town/village/municipality in which this address resides.

company

The name of the company that is to receive the mail piece.

country

The country in which this address resides. This is likely not necessary unless the address is in a different country.

name

The name of the person that is to receive the mail piece.

postal_code

The postal code of the address. Called the ZIP code in the US.

street

The number and name of the street that is to receive the mail piece.

  2020 Main St

METHODS

clone(%prams)

Close this Geo::Address::Mail instance, replacing any of the attributes specified in the new instance.

new_for_country ($code, ...)

Attempts to load and instantiate a subclass of Geo::Address::Mail based on the provided two-letter code (upper or lower case). Any remaining arguments are passed to the constructor of the specified class. Note: you will have to have the class for the specified country accessible.

  # Instantiate a US address
  my $usaddr = Geo::Address::Mail->new_for_country('US', { ... });

standardize ($partial_name_of_standardizer_class, ...)

Shortcut to use a Geo::Address::Mail::Standardizer. You can provide either the partial name (the bits after Standardizer, e.g. 'USPS::AMS' for Geo::Address::Mail::Standardizer::USPS::AMS) or a full class name (prefixed with a +, e.g. '+My::Standardizer'). Returns whatever is returned by the standardize method of the requested Standardizer implementation.

Note: Any argument passed after the name of the class will be passed on to the constructer of the loaded standardizer.

AUTHOR

Cory G Watson, <gphat at cpan.org>

ACKNOWLEDGEMENTS

COPYRIGHT & LICENSE

Copyright 2010 Cory G Watson.

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.

cpanm Geo::Address::Mail

perl -MCPAN -e shell
install Geo::Address::Mail