DEV Community: Volker Kroll

Date handling modularized

Volker Kroll — Fri, 28 May 2021 14:34:08 +0000

Thanks to mentioning my first post on the perl weekly newsletter a lot people read the first part of this serie of articles. (Don't know yet, how many parts it will be.) So I decided to write a follow-up.

What can you expect:

Moving functions to modules
testing functions automatically
change a module to a class
inherit the class from a base class

To summarize where we left our little skript in part one:

use strict;

use Getopt::Long;
use DateTime;
use DateTime::Duration;

my $date;   ## the starting date argument
my $dt;     ## DateTime Object of starting date


GetOptions(
        "date=s"         => \$date,
        );

$dt = get_dt($date);
my $today = DateTime->today();



if(!$dt) {
    print "submitted value $date is no date\n";
}
if(is_last_week($dt)) {
    print "submitted date was in the last week\n";
}

sub is_last_week {
    my $dt = shift;
    return unless ref $dt eq "DateTime";
    return if($dt > $today) ;

    my $dur = DateTime::Duration->new(days => 7);
    $today->subtract_duration($dur);
    return 1 if $today < $dt;
}


sub get_dt {
    my $date = shift;

    my($y, $m, $d) = $date =~ /^(\d\d\d\d)-(\d\d)-(\d\d)$/;
    my $dt;
    eval {
        $dt = DateTime->new(year => $y, month => $m, day => $d);
    }; 
    if ($@) {
        print STDERR "Error while generating DateTime: $@\n";
        return 0;
    }
    else {
        return $dt;
    }
}

The script checks a parameter -d if it is a valid date and that the date is in the last week.

Calling the script without a paremeter end with a not so nice error:

perl skript.pl
Error while generating DateTime: Validation failed for type named DayOfMonth declared in package DateTime::Types (/home/kroll/.plenv/versions/5.32.1/lib/perl5/site_perl/5.32.1/x86_64-linux/DateTime/Types.pm) at line 29 in sub named (eval) with value undef

Trace begun at Specio::Exception->new line 57
Specio::Exception::throw('Specio::Exception', 'message', 'Validation failed for type named DayOfMonth declared in package DateTime::Types (/home/kroll/.plenv/versions/5.32.1/lib/perl5/site_perl/5.32.1/x86_64-linux/DateTime/Types.pm) at line 29 in sub named (eval) with value undef', 'type', 'Specio::Constraint::Simple=HASH(0x55a2fa53c0a8)', 'value', undef) called at (eval 201) line 91
DateTime::_check_new_params('year', undef, 'month', undef, 'day', undef) called at /home/kroll/.plenv/versions/5.32.1/lib/perl5/site_perl/5.32.1/x86_64-linux/DateTime.pm line 176
DateTime::new('DateTime', 'year', undef, 'month', undef, 'day', undef) called at skript.pl line 45
eval {...} at skript.pl line 44
main::get_dt(undef) called at skript.pl line 15

submitted value is no date

We will write this on our to-do-list for later.

But for today we want to put the date handling out of the script in a module, so that the script later can do the heavy lifting but the date handling can be reused in other scripts.

Generating a new and empty module

For the perl people it is quite obvious, you generate a directory lib and put the module in and do the normal perl boilerplate:

package Date;

use strict;

use DateTime;
use DateTime::Duration;


1;

And as the test-driven guy I am usually, I added my first test too. In t/date.t you will find:

use Test::More;

use_ok("Date");

done_testing();

And of course this will result green:

$ prove -lv
t/date.t ..
ok 1 - use Date;
1..1
ok

So we can commit it:

Author: Volker Kroll
Date: Thu May 6 11:59:53 2021 +0200

new Module Date

Date is empty

t/date.t has a test, that it loads correctly

Move the get_dt in Date.pm

Not much to do then get the code from the script and paste it in our module. But because I prefer modules to be a little more object-oriented I also added a constructor in the - little weird old oo-perl style.

sub new {
    my $class = shift;
    my $datestring = shift|| undef;
    if ($datestring) {
        bless get_dt($datestring), $class;
    }
}

And a little more testing of course:

use_ok("Date");

my $d = Date::get_dt('2020-01-02');
isa_ok($d, DateTime);
my $date = Date->new('2020-01-02');
isa_ok($date, "Date");

Resulting in:

$ prove -lv
t/date.t ..
ok 1 - use Date;
ok 2 - An object of class 'DateTime' isa 'DateTime'
ok 3 - An object of class 'Date' isa 'Date'
1..3
ok

Enough code to commit it:

Author: Volker Kroll kroll@strato.de
Date: Thu May 6 12:11:15 2021 +0200

get_dt now in Date

get_dt is called like in skript.pl Date::get_dt(yyyy-mm-dd)

additionally you can do a Date->new(yyyy-mm-dd) returned is an object of class Date (that is a DateTime)

Why not make Date a child of DateTime?

While working on my module I thought it might be a good idea to inherit from DateTime so that if I do a Date->new(...) I get a DateTime object back. But, that did not work immediatly, because I need to add a lot of code of DateTime then for follow that constructor. (And to be honest, I forgot how to only add a little in my constructor and letting the "real constructor" do the heavy lifting of DateTime, so I decided for this project to rename my constructor to create (that's easy in perl, where you can name your constructor like you want to).

package Date;

use strict;

use base qw(DateTime);
use DateTime;
use DateTime::Duration;


sub create {
    my $class = shift;
    my $datestring = shift|| undef;
    if ($datestring) {
        return bless get_dt($datestring), $class;
    }
}

Also I wanted my function is_last_week in the module too, we had it before in our little script. For making the tests more easy, I added the possibility to "cheat with today" as A. mentioned. When I add a parameter today in the call it uses that not the "real today":

sub is_last_week {
    my $dt = shift;
    return unless ref $dt;
    my $today = shift ||  DateTime->today();
    return if($dt > $today) ;

    my $dur = DateTime::Duration->new(days => 7);
    $dt->add_duration($dur);
    return 1 if $today < $dt;
    return 0;
}

Now I was able to add some more testing:

use Test::More;
use Data::Dumper;
use DateTime;

use_ok("Date");
test_new();
test_is_last_week();
done_testing();

sub test_new {
    my $d = Date::get_dt('2020-01-02');
    isa_ok($d, DateTime);
    my $date = Date->create('2020-01-02');
    isa_ok($date, Date);
    isa_ok($date, DateTime);
}

sub test_is_last_week {
    my $date = Date->create('2020-01-02');
    my $today = DateTime->new(year => 2020, month => 01, day => 05);
    can_ok($date, "is_last_week");
    isa_ok($date, "Date");
    isa_ok($today, "DateTime");
    is($date->is_last_week($today), 1, "2020-01-02 was in the week before 2020-01-05 ");
    is($date->is_last_week(), 0, "2020-01-02 was not last week from today ");

}

Again resulting in the expected output:

$ prove -lv
t/date.t ..
ok 1 - use Date;
ok 2 - An object of class 'DateTime' isa 'DateTime'
ok 3 - An object of class 'Date' isa 'Date'
ok 4 - An object of class 'Date' isa 'DateTime'
ok 5 - Date->can('is_last_week')
ok 6 - An object of class 'Date' isa 'Date'
ok 7 - An object of class 'DateTime' isa 'DateTime'
ok 8 - 2020-01-02 was in the week before 2020-01-05
ok 9 - 2020-01-02 was not last week from today
1..9
ok

The next step is of course -- as usual -- the commit

Author: Volker Kroll
Date: Fri May 7 11:38:11 2021 +0200

added Tests for date was in last week

changed new to create to not interfere with DateTime new

add function for is_last_week

for testing purposes it is possible to call is_last_week with a given "today" so tests don't become red

Just a few more tests

sub test_is_last_week {
    my $date = Date->create('2020-01-02');
    my $today = DateTime->new(year => 2020, month => 01, day => 05);
    can_ok($date, "is_last_week");
    isa_ok($date, "Date");
    isa_ok($today, "DateTime");
    is($date->is_last_week($today), 1, "2020-01-02 was in the week before 2020-01-05 ");
    is($date->is_last_week(), 0, "2020-01-02 was not last week from today ");
    is($date->is_last_week(), 0, "2020-01-02 was not last week from today ");

}

Now the whole module is tested enough to use it.

t/date.t ..
ok 1 - use Date;
ok 2 - An object of class 'DateTime' isa 'DateTime'
ok 3 - An object of class 'Date' isa 'Date'
ok 4 - An object of class 'Date' isa 'DateTime'
ok 5 - Date->can('is_last_week')
ok 6 - An object of class 'Date' isa 'Date'
ok 7 - An object of class 'DateTime' isa 'DateTime'
ok 8 - 2020-01-02 was in the week before 2020-01-05
ok 9 - 2020-01-02 was not last week from today
ok 10 - 2020-01-02 was not last week from today
1..10
ok

Only a final commit

Author: Volker Kroll
Date: Fri May 7 14:21:09 2021 +0200

some more testing in date.t

Conclusion

Only a few changes changed a lot. Now we are able to easily test the functions we developed. Additionally we can later reuse our (now DateTime) object. But the biggest benefit for the following work is to remove the date handling from the script that will have other work to do. So we separeted the different parts which make them more easy to modify and use.

What will be the next logical step? That is depended of the requirements and the users of the software. But I would probably fix the "bad error message" when called without a parameter. Usually I call the help function (that still needs to be written), when a mandatory parameter is missing. But that will be done in a third part -- maybe -- stay tuned.

Developing a script in small steps

Volker Kroll — Mon, 17 May 2021 17:51:25 +0000

It all started with a git commit I found:

commit 340d908fe537d3163e220c84945bbfc5b49fe8dc
Author: A.
Date: Wed Apr 14 17:28:50 2021 +0200
Deleted redundant INFO messages. Replaced date strings with dt->ymd() calls. Replaced some if nots with unless. Simplified sub _unpack. Set timezone in DateTime objects. Results are returned as tail calls now. Maybe more minor changes.

A. is a fresh developer in my department and as many future devs she did not learn so far - neither in university nor in books - how to organize her work. How to avoid commits ending with Maybe more minor changes. Honestly I know a lot senior devs who still use a version control system like any other backup. So what I wanted to show her, was:

How to organize my programming in small steps
How slowly developing
How to make errors without desaster
How to use your version control
How to write a helpful commit-message
How will I later find something I did

So I started a programming-session on my own, and gave her later the repository and we discussed each step. (Honestly: She found immediately an error in my code, that I did not left there intentionally).

The development was in perl, but I hope other devs find the steps valueable too, so I write it down here. (My first longer article in english)

Step one: all started with a README

- Script with parameters
    -d Date
        -> has to be in the past
        -> must be no older then 7 days

Of course that was the first commit:

commit
Author: Volker Kroll
Date: Wed May 5 16:49:17 2021 +0200

README

we will have the requirements here

Now the fun started, the initial script

use strict;

use Getopt::Long;

my $date ; ## the startingdate

GetOptions(
        "date=s"         => \$date,
        );

print "submitted Date is: $date\n";

The perl people know, that script does not much more then storing a submitted string as parameter --date or -d in the scalar variable $date.
And of course it uses strict as every good perl script does.

I committed this change:

Author: Volker Kroll
Date: Wed May 5 16:52:01 2021 +0200

initial

Parameter d for the date

TODO:

Validation

As promised a validation

## starts as before
sub is_date {
    my $date = shift;

    return 1 if $date =~ /^\d\d\d\d-\d\d-\d\d$/;
    return 0;

}
if(is_date($date)) {
    print "submitted Date is: $date\n";
}
else {
    print "submitted value $date is no date\n";
}

I checked if the submitted date matches the regex ^\d\d\d\d-\d\d-\d\d$ - you are aware, that we perl-devs solve our problems with regexes right?

But enough for the next commit

Author: Volker Kroll
Date: Wed May 5 16:54:49 2021 +0200

first check for date

date is valid if regex \d\d\d\d-\d\d-\d\d is valid

TODO:

better check

exclude non valid month and day

More checks

As announced the next step was to better check for the validity of the date - and stay tuned these steps will be changed later.

sub is_date {
    my $date = shift;

    my $days = ["", 31, 29, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];

    my($y, $m, $d) = $date =~ /^(\d\d\d\d)-(\d\d)-(\d\d)$/;
    if ($m > 0 && $m < 13) {
        print "$m has max $days->[$m] days\n";
        return 1 if $d <= $days->[$m];
    }

    return 0;

}

And the next commit even though theses checks are far from perfect

Author: Volker Kroll
Date: Wed May 5 17:00:23 2021 +0200

more checking of date via regex

added length per month value

check if day is possible in the month

TODO:

that is a bad choice for february

Let's correct the february

As we saw, my checks did not really work in february - only in leap-years, so I had to handle that with a check wether it is a leap year or not.

sub is_date {
    my $date = shift;

    my $days = ["", 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];

    my($y, $m, $d) = $date =~ /^(\d\d\d\d)-(\d\d)-(\d\d)$/;
    if (is_leap_year($y)) {
        $days->[2] = 29;
    }

    if ($m > 0 && $m < 13) {
        print "$m has max $days->[$m] days\n";
        return 1 if $d <= $days->[$m];
    }
    return 0;
}

sub is_leap_year {
    my $y = shift;

    if ($y % 4 == 0) {
        return 1 if $y % 400 == 0;
        return 0 if $y % 100 == 0;
        return 1;
    }
}

Now february is handled correctly in every year. So, up the next commit

Author: Volker Kroll
Date: Wed May 5 17:07:06 2021 +0200

check works even for february

new function is_leap_year TODO

Refactoring - Removing of all own written calendar functions

Refactoring - Use of Date Modules

I had to remove my not so elegant and error-prone date-functions. To get you back on track, here is the whole script after removing that and adding a suitable date module

use strict;

use Getopt::Long;
use DateTime;

my $date ; ## the startingdate

GetOptions(
        "date=s"         => \$date,
        );

sub is_date {
    my $date = shift;

    my $days = ["", 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];

    my($y, $m, $d) = $date =~ /^(\d\d\d\d)-(\d\d)-(\d\d)$/;
    my $dt;
    eval {
        $dt = DateTime->new(year => $y, month => $m, day => $d);
    }; 
    if ($@) {
        print STDERR "Error while generating DateTime: $@\n";
        return 0;
    }
    else {
        return $dt;
    }
}


if(is_date($date)) {
    print "submitted Date is: $date\n";
}
else {
    print "submitted value $date is no date\n";
}

I am using now DateTime for every date operation. If no DateTime object can be created we assume, that the submitted value is not correct and return 0, else we return a DateTime Object.

Author: Volker Kroll
Date: Wed May 5 17:24:41 2021 +0200

removed own calendar functions and added DateTime

validation via Exception of DateTime->new()

TODO:

Refactoring: rename function is_date (returns a dt if true)

Maybe you saw, that I forgot to remove the arry with the days per month... I saw it now, while I write this article

Clean it up 1/2

use strict;

use Getopt::Long;
use DateTime;

my $date;   ## the starting date argument
my $dt;     ## DateTime Object of starting date


GetOptions(
        "date=s"         => \$date,
        );

sub get_dt {
    my $date = shift;

    my $days = ["", 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];

    my($y, $m, $d) = $date =~ /^(\d\d\d\d)-(\d\d)-(\d\d)$/;
    my $dt;
    eval {
        $dt = DateTime->new(year => $y, month => $m, day => $d);
    }; 
    if ($@) {
        print STDERR "Error while generating DateTime: $@\n";
        return 0;
    }
    else {
        return $dt;
    }
}

$dt = get_dt($date);

if($dt) {
    print "submitted Date is: $date\n";
}
else {
    print "submitted value $date is no date\n";
}

Everything I did is mentioned in the commit-message (and there is still that array of days...

Author: Volker Kroll
Date: Wed May 5 17:28:04 2021 +0200

moved function is_date to get_dt

check is now if return of get_dt is a true value a DateTime Object is a true value 0 is not => so the check still works => so we have already a working DateTime Object to work with later

Clean it up 2/2

Now I moved around the code a bit to make it more readable

use strict;

use Getopt::Long;
use DateTime;

my $date;   ## the starting date argument
my $dt;     ## DateTime Object of starting date


GetOptions(
        "date=s"         => \$date,
        );

$dt = get_dt($date);

if($dt) {
    print "submitted Date is: $date\n";
}
else {
    print "submitted value $date is no date\n";
}

The sub get_dt remained the same (and there is still that array)

Author: Volker Kroll
Date: Wed May 5 17:31:00 2021 +0200

moved main code up in the file

Now for more functionality

As we remember the day has to be in the past. So we need to check that. DateTime Objects can easily be compared and DateTime has a function called today(). So my first step was:

$dt = get_dt($date);
my $today = DateTime->today();



if(!$dt) {
    print "submitted value $date is no date\n";
}
if($dt < $today) {
    print "submitted date is in the past\n";
}

That was easy and it worked out of the box.

Author: Volker Kroll
Date: Wed May 5 17:33:56 2021 +0200

check if submitted date is in the past

added new DateTime Object $today

compare $today and DateTime Object of submitted date

TODO

next check: not older then 7 days (see README)

But first let's remove this array....

I think you know how a not existing line looks nevertheless that was worth a commit

Author: Volker Kroll
Date: Wed May 5 17:37:45 2021 +0200

removed old arrayref for days in the month

Check if it was in the last week

In our requirements was that the date has to be in the last seven days. (Whatever that means in detail)

Time for another Date Module DateTime::Duration to calculate that difference.

if(is_last_week($dt)) {
    print "submitted date was in the last week\n";
}

sub is_last_week {
    my $dt = shift;
    return unless ref $dt eq "DateTime";

    my $dur = DateTime::Duration->new(days => 7);
    $dt->add_duration($dur);
    return 1 if $today < $dt;
}

I think that code is easily to understand even for not perl-devs. I add 7 days to the submitted date and compare it with today. (Here is the error that my colleague found immediatly - but more about the bug later).

Author: Volker Kroll
Date: Wed May 5 17:45:57 2021 +0200

check for is_last_week

added DateTime::Duration

checked if submitted date was in the last 7 days

TODO:

Refactoring: Add the check for in the past in is_last_week

Cleanup

As mentioned in the TODO we removed the "is in the past" check from the main and added it to the is_last_week

sub is_last_week {
    my $dt = shift;
    return unless ref $dt eq "DateTime";
    return if($dt > $today) ;

    my $dur = DateTime::Duration->new(days => 7);
    $dt->add_duration($dur);
    return 1 if $today < $dt;
}

Normally all this would end with the this commit:

Author: Volker Kroll kroll@strato.de
Date: Wed May 5 17:48:31 2021 +0200

is_last_week now a valid check for date concerning to specification

The bug

As I wrote before, my colleague spotted a bug in my code. I got this question via chat:

A: The line $dt->add_duration($dur); made me wonder. Is the dt object not changed then? Is this call by value or call by reference?

And she was right. So the next commit was from her, modifying my code and correcting it.

diff --git a/skript.pl b/skript.pl
index 2f5594b..426c4af 100644
--- a/skript.pl
+++ b/skript.pl
@@ -30,7 +30,8 @@ sub is_last_week {
     return if($dt > $today) ;

     my $dur = DateTime::Duration->new(days => 7);
-    $dt->add_duration($dur);
+    #$dt->add_duration($dur);
+    $today->subtract_duration($dur);
     return 1 if $today < $dt;
 }

She changed the direction of the math and modified the no longer used $today

Author: A.
Date: Fri May 7 12:38:15 2021 +0200

is_last_week subtracts from today instead of adding to dt.

Now the script was correct concerning the requirements.

Conclusions

Of course this is a little bit artificial - and most devs will need to confess that they usually commit much bigger chunks of code. Nevertheless, I think it is valuable to develop in these small chunks.

Next steps were making it a bit more modular and added automated tests for further development. But for today this shall be enough.