NAME

Data::Random::Contact - Generate random contact data

VERSION

version 0.05

SYNOPSIS

    use Data::Random::Contact;

    my $randomizer = Data::Random::Contact->new();

    my $person       = $rand->person();
    my $household    = $rand->household();
    my $organization = $rand->organization();

DESCRIPTION

This module is still alpha, and the API may change in future releases.

This module generates random data for contacts. This is useful if you're working an application that manages this sort of data.

It generates three types of contacts, people, households, and organizations.

LICENSING

The data that this module uses comes from several sources. Names are based on data from Fake Name Generator (http://www.fakenamegenerator.com). This data is dual-licensed under GPLv3 or CC BY-SA 3.0 (United Stated). See http://www.fakenamegenerator.com/license.php for licensing details.

The address data is all real addresses from the VegGuide.org website (http://vegguide.org). This data is licensed under the CC BY-NC-SA 3.0 (United Stated) license.

All other data is generated algorithmically.

Whether a license can apply to things like addresses and names is debatable, but I am not a lawyer.

METHODS

This module provides just a few public methods:

Data::Random::Contact->new()

This constructs a new object. It accepts two optional parameters:

• language

  This can either be a language name like "EN" or an instantiated language class, for example Data::Random::Contact::Language::EN.

  The language is used to generate names.

  This defaults to "EN".

  Currently this distribution only ships with one language, English (Data::Random::Contact::Language::EN).

• country

  This can either be a country name like "US" or an instantiated country class, for example Data::Random::Contact::Country::US.

  The country is used to generate phone numbers and addresses.

  This defaults to "EN".

  Currently this distribution only ships with one country, US (Data::Random::Contact::Country::US).

$randomizer->person()

This returns a random set of data for a single person.

See "RETURNED DATA" for details.

$randomizer->household()

This returns a random set of data for a single household.

See "RETURNED DATA" for details.

$randomizer->organization()

This returns a random set of data for a single organization.

See "RETURNED DATA" for details.

RETURNED DATA

Each of the methods that return contact data returns a complicated hashref-based data structure.

Shared Data

Some of the data is shared across all contact types:

All contact types return email, phone, and address data. This data is available under the appropriate key ("email", "phone", or "address") in the top-level data structure.

Under that key the data is further broken down by type, which will be something like "home", "work", "office", etc. Every contact will have all the valid keys set. In other words, a person will always have both a home and work email address.

The email data will always be at one of these domains: pookmail.com, trashymail.com, dodgit.com, mailinator.com, or spambob.com.

The phone number will be a string containing all the phone number data.

Each address is further broken down as a hashref data structure.

See the appropriate language module for details on phone numbers and addresses.

Here's an example of the shared data for a person (using US data):

    {
        address => {
            home => {
                city        => "Reno",
                postal_code => 89503,
                region      => "Nevada",
                region_abbr => "NV",
                street_1    => "501 W. 1st St.",
                street_2    => undef
            },
            work => {
                city        => "Minneapolis",
                postal_code => 55406,
                region      => "Minnesota",
                region_abbr => "MN",
                street_1    => "2823 E. Franklin Avenue",
                street_2    => undef
            }
        },
        email => {
            home => "charlotte.t.dolan\@pookmail.com",
            work => "charlotte0\@dodgit.com"
        },
        phone => {
            home   => "508-383-7535",
            mobile => "775-371-7227",
            work   => "602-995-6077"
        },
    }

Person Data

Since much of this data is language-specific, you should see the appropriate language module for details. Some keys may be undefined, depending on the language.

The data for a person includes:

• given

  The person's given name.

  The set of names used is determined by the language.

• middle

  The person's middle name or initial.

  The set of names used is determined by the language.

• surname

  The person's surname.

  The set of names used is determined by the language.

• gender

  This will be either "male" or "female".

• salutation

  A salutation for the person ("Mr", "Ms", etc.). These salutations are gender-specific.

  The set of salutations used is determined by the language.

• suffix

  An optional suffix like "Jr" or "III".

  The set of salutations used is determined by the language.

• birth_date

  A DateTime object representing the person's birth date. The date will be somewhere between 15 and 100 years in the past.

• email addresses

  The email address types for a person are "home" and "work".

• phone numbers

  The phone number types for a person are "home", "work", and "mobile".

• addresses

  The address types for a person are "home" and "work".

Household Data

The data for a person includes:

• name

  The household name.

  The set of names used is determined by the language.

• email addresses

  The only email address type for a household is "home".

• phone numbers

  The only phone number type for a household is "home".

• addresses

  The only address type for a household is "home".

Organization Data

The data for a person includes:

• name

  The organization name.

  The set of names used is determined by the language.

• email addresses

  The only email address type for an organization is "home".

• phone numbers

  The only phone number type for an organization is "office".

• addresses

  The address types for a organization are "headquarters" and "branch".

Data Dumps

Here are complete data dumps for each contact type:

• Person

      {
          given      => "Gregory",
          middle     => "Antoine",
          surname    => "Jones",
          birth_date => bless( {'...'}, 'DateTime' ),
          salutation => "Mr",
          suffix     => "IV",
          gender     => "male",
          address => {
              home => {
                  city        => "Boulder",
                  postal_code => 80304,
                  region      => "Colorado",
                  region_abbr => "CO",
                  street_1    => "2785 Iris Avenue",
                  street_2    => undef
              },
              work => {
                  city        => "Albuquerque",
                  postal_code => 87106,
                  region      => "New Mexico",
                  region_abbr => "NM",
                  street_1    => "2110 Central Ave SE",
                  street_2    => undef
              }
          },
          email      => {
              home => "gregory.antoine.jones\@trashymail.com",
              work => "gregory0\@pookmail.com"
          },
          phone  => {
              home   => "881-348-3582",
              mobile => "727-862-8526",
              work   => "305-389-4232"
          },
      }

• Household

      {
          name    => "The Briley Household",
          address => {
              home => {
                  city        => "Lombard",
                  postal_code => undef,
                  region      => "Illinois",
                  region_abbr => "IL",
                  street_1    => "2361 Fountain Square Dr.",
                  street_2    => undef
              }
          },
          email => { home => "The.Briley.Household\@mailinator.com" },
          phone => { home => "307-342-9913" }
      }

• Organization

      {
          name    => "pastorate womanish",
          address => {
              branch => {
                  city        => "Northbrook",
                  postal_code => undef,
                  region      => "Illinois",
                  region_abbr => "IL",
                  street_1    => "1819 Lake Cook Rd.",
                  street_2    => undef
              },
              headquarters => {
                  city        => "Springfield",
                  postal_code => undef,
                  region      => "New Jersey",
                  region_abbr => "NJ",
                  street_1    => "518 Millburn Ave",
                  street_2    => undef
              }
          },
          email => { home   => "pastorate.womanish\@mailinator.com" },
          phone => { office => "876-278-8382" }
      }

AUTHOR

Dave Rolsky <autarch@urth.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2011 by Dave Rolsky.

This is free software, licensed under:

  The Artistic License 2.0 (GPL Compatible)

cpanm Data::Random::Contact

perl -MCPAN -e shell
install Data::Random::Contact