NAME

String::CodiceFiscale - convert personal data into italian Codice Fiscale

SYNOPSIS

 use String::CodiceFiscale;
  
 $obj = String::CodiceFiscale->new(
     sn      =>  'Wall',         # surname
     fn      =>  'Larry',        # first name
     date    =>  '1987-12-18',   # Perl's birthday
     sex     =>  'M',            # M or F
     bp      =>  'Z404',         # birthplace, Codice Catastale code
 );
 
 print $obj->cf, "\n";           # prints Codice Fiscale
 
 # and the other way around
 
 $obj = String::CodiceFiscale->parse('WLLLRY87T18Z404B');
 
 unless ($obj) {                 # check for errors
    print "We have an error: " . String::CodiceFiscale->error;
 }
 
 print "This person identifies as " . 
    ($obj->sex eq 'M' ? 'male' : 'female') . 
    " and was born on " . $obj->date . " (unless he's more than 100)\n"; 

 for (qw(Wallace Wall Weeler Awalala)) {
     print "$_\t could be his surname\n" if $obj->sn_match($_);
 }

 for (qw(Ilary Elryk Larry Kilroy Leroy)) {
     print "$_\t could be his first name\n" if $obj->fn_match($_);
 }
 

DESCRIPTION

String::CodiceFiscale might help you in the tricky task of verifying and/or producing a Codice Fiscale. It also gives you some utilities to "reverse engineer" a given Codice Fiscale and find out what personal data could have produce it.

For more info about the Codice Fiscale format see the Appendix. Please note that [] "square brackets" in the following documentation will mark optional parameters and not anonymous array references.

CLASS METHODS

new([%PARAMS])

Creates a new object. It receives parameters in hash fashion and will use every key of the hash as an object method called with the respective value. See below for possible methods.

parse(CF)

Creates a new object from parsing the given STRING as a Codice Fiscale. It won't return a valid object if the given Codice Fiscale won't pass some validation checks. Please note that this method will try to handle gently and accept Codice Fiscale which contain special characters in the normally numeric fields (birth year and day, last three digits of the codice catastale code) while the set methods below will only accept numeric values in the same fields.

validate(CF)

Utility method. It will return a true value if STRING is a valid Codice Fiscale. Unless it will return a false value.

error()

Returns a string containing a descriptive error of what went wrong during the last failed call to a class method.

OBJECT METHODS

All get/set methods give you back the actual value of the attribute. If you provide a STRING they will try to set the attribute after some validation checks. If these checks fail the method will return a false value. Otherwise it will return the value you provided.

GET/SET METHODS

sn([SURNAME])

Get/set method to retrieve or set the surname.

fn([FIRST_NAME])

Get/set method to retrieve or set the first name.

date([YYYY-MM-DD])

Get/set the date of birth. It can parse only dates provided in the ISO 8601 format (YYYY-MM-DD). The year could have the same problems discussed in the year() method.

year([YEAR])

Get/set method for year. Please note that Codice Fiscale code HAS the Millenium Bug. So if you're asking for a year after parsing a codice fiscale what you will get will be a guess about what the year of birth is: this could be wrong for people older than 100.

month([MONTH])

Get/set method to retrieve or set the month.

day([DAY_OF_MONTH])

Get/set method to retrieve or set the day of month.

sex([SEX])

Get/set method for sex. Accept "M" for male and "F" for female.

bp([BIRTH_PLACE])

Get/set method for birthplace. The birthplace must be already encoded in the codice catastale form and match /^[A-Z]\d\d\d$/ . No lookup of city names is provided yet.

ENCODING METHODS

cf([DUPLICATE_NUMBER])

Try to give you a valid codice fiscale. It will return a false value if some data is missing. Note how the generated codice fiscale has no warranty to be unique. By passing a DUPLICATE_NUMBER as an optional parameter, the library will try to generate a Codice Fiscale using special characters to avoid collisions. "0" will return the default Codice Fiscale. From 1 onward the library will substitute special characters to create unique codes. Please note that while the algorithm to determine the default Codice Fiscale for the first 7 duplicates is easily understood, after the 8th duplicate it's just guesswork on my part.

crc

Gives back just the control character. Return a false value on failure.

REVERSE ENGINEERING METHODS

sn_match(STRING)

Matches if STRING could be the surname that was used to generate the codice fiscale previously acquired through the parse() method. Please beware that there are infinite surnames that could produce the same coding in codice fiscale.

fn_match(STRING)

Matches if STRING could be the first name that was used to generate the codice fiscale previously acquired through the parse() method. See sn_match() for more info.

APPENDIX

Yet to be written. It would likely contain more info and caveats about the codice fiscale algorithm.

TO DO

- Perfect the error handling

- Write more documentation and clear up obscure points

- Create alias for methods whose names are less than obvious

- Italian documentation and italian aliases

AUTHOR

Giulio Motta, <giulienk@cpan.org>

COPYRIGHT AND LICENSE

Copyright 2003-2020 by Giulio Motta

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