Just to clarify, this is not a rare mistake. As we are always in a rush to release the new version of our module/application whatever we always make such mistakes. Even if not specifically with "age".

The origin

So we have this code in the Person.pm file:

package Person;
use Moo;

has age => (is => 'rw');
has name => (is => 'rw');

1;

and we have the following code using it:

use strict;
use warnings;
use 5.010;

use Person;

my $teacher = Person->new(name => 'Foo');
$teacher->age(20);
say $teacher->name;
say $teacher->age;

my $student = Person->new(age => 18, name => 'Bar');
say $student->age;
say $student->name;

Nothing special here.

Replace the attribute by a method

The age attribute was exposed to the outside world (people using the class) in two places. One of them was the constructor where we could pass a value to the age attribute, and the other one was the ->age accessor.

In the first attempt we will make sure the accessor still works.

We will introduce a new attribute called birthdate which will be just a timestamp returned by the time() function of perl, and we will remove the age attribute. We also add a new method called age that will have two ways of operation.

If called with a number as the age of the person in years, the value will be converted to the internal representation (which is the current time less the year in seconds) and stored it in the birthdate attribute.

If called without a parameter, then it will calculate the current age (in whole numbers) as the difference between the current time and the birthdate.

Here is the new version of Person.pm:

package Person;
use Moo;

has birthdate => (is => 'rw');
has name => (is => 'rw');

my $YEAR = 60*60*24*365;

sub age {
    my ($self, $age) = @_;

    if ($age) {
        $self->birthdate( time - $age * $YEAR );
    }

    return int( (time - $self->birthdate) / $YEAR );
}

1;

In order to simplify the example I used the variable $YEAR that holds an approximate number of seconds in a year. This is good enough for our current example, though in a real application we would probably use a DateTime object there.

Let's see how well this works:

use strict;
use warnings;
use 5.010;

use Person;

my $teacher = Person->new(name => 'Foo');
$teacher->age(20);
say $teacher->name;
say $teacher->age;

prints

Foo
20

which is what we expected.

We can even extend our code with a little experiment:

my $teacher2 = Person->new(name => 'FooBar');
$teacher2->age(19.99999999);
say $teacher2->name;
say $teacher2->age;
sleep 5;
say $teacher2->age;

We set the age to be just before the age of 20, we wait and see how the returned age (that we wanted to be a whole number) changes from 19 to 20:

FooBar
19
20

Last, but not least, we try to pass age in the constructor:

my $student = Person->new(age => 18, name => 'Bar');
say $student->name;
say $student->age;

The output shows that the age attribute was swallowed by Moo and thus we get a warning:

Bar
Use of uninitialized value in subtraction (-) at Person.pm line 16.

Fixing the constructor

In order to fix the constructor we are going to use the BUILDARGS method of Moo.

If you implement this method in your class, Moo will call it before calling the constructor. It will get all the parameters the constructor gets (the name of the class and all the arguments you passed to the ->new call), and the method should return a reference to a hash holding the (probably updated) parameters of the constructor.

When we call Person->new(name => 'Bar', age => 18), perl would call the new method with the following arguments: 'Person', name => 'Bar', age => 18, which is just the same a 'Person', 'name', 'Bar', 'age', 18. (If in doubt, see the explanation about the fat-arrow.)

Moo already provides the new constructor, hence we don't have to call it. Moo also check is we have implemented a method called BUILDARGS. If we have such function in our module, then, before calling the new method, Moo will call this method. So in our case $class will be 'Person' and %args will contain two key-value pairs:

   'name' => 'Bar',
   'age' => 18

We remove the age and replace it with a birthdate key and with the appropriate value. Then we return the reference to this hash.

Moo will grab that hash-reference and call new passing the name of the class ('Person') and the new set of arguments that can be found in this hash reference.

Thus we could replace the 'age' argument passed in by the user, by the 'birthdate' argument.

sub BUILDARGS {
    my ($class, %args) = @_;

    my $age = delete $args{age};
    if ($age) {
        $args{birthdate} = time - $age * $YEAR;
    }
    return \%args;
}

If you want to see it for yourself, add the following code to the Person.pm file:

sub BUILDARGS {
    my ($class, %args) = @_;

    use Data::Dumper;
    print "Class: $class\n";
    warn Dumper \%args;

    my $age = delete $args{age};
    if ($age) {
        $args{birthdate} = time - $age * $YEAR;
    }
    return \%args;
}

and run the following script:

use strict;
use warnings;
use 5.010;

use Person;

my $teacher = Person->new(name => 'Foo');
my $student = Person->new(age => 18, name => 'Bar');

The output will look like this:

Class: Person
$VAR1 = {
          'name' => 'Foo'
        };
Class: Person
$VAR1 = {
          'name' => 'Bar',
          'age' => 18
        };

You can see the name of the class was 'Person' in both cases and the data received in %args matches what we passed to the new call.

Put it together and test it

The whole Person.pm file:

package Person;
use Moo;

has birthdate => (is => 'rw');
has name => (is => 'rw');

my $YEAR = 60*60*24*365;

sub BUILDARGS {
    my ($class, %args) = @_;
    my $age = delete $args{age};
    if ($age) {
        $args{birthdate} = time - $age * $YEAR;
    }
    return \%args;
}

sub age {
    my ($self, $age) = @_;

    if ($age) {
        $self->birthdate( time - $age * $YEAR );
    }

    return int( (time - $self->birthdate) / $YEAR );
}

1;

The script:

use strict;
use warnings;
use 5.010;

use Person;

my $teacher = Person->new(name => 'Foo');
$teacher->age(20);
say $teacher->name;
say $teacher->age;

my $student = Person->new(age => 18, name => 'Bar');
say $student->name;
say $student->age;

The output:

Foo
20
Bar
18

Conclusion

So we changed the internal representation of age replacing the age attribute by a birthdate attribute. The users of our class don't need to change anything as the retained the old API.

We could now decide to deprecate the old API but keep it around for a while to let our users adjust their code, or we can decide to keep it around forever.