From 20cb3157e1e325068ba449c2f454829e2c0979cc Mon Sep 17 00:00:00 2001 From: Ethan Kletschke Date: Wed, 28 Oct 2026 05:37:31 +0200 Subject: [PATCH 01/10] fix: Add optional comma to `count_logs_by_type` regex --- src/lib/Utils/TextFiles/LogFileParsing.pm | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/lib/Utils/TextFiles/LogFileParsing.pm b/src/lib/Utils/TextFiles/LogFileParsing.pm index 99878c7..837b66c 100644 --- a/src/lib/Utils/TextFiles/LogFileParsing.pm +++ b/src/lib/Utils/TextFiles/LogFileParsing.pm @@ -31,8 +31,8 @@ sub count_logs_by_type { # Remove the newline character from the end of $line chomp($line); - # If the start of the line doesn't match the regex (see module manual) - unless ($line =~ /^\[?([a-zA-Z]+)\]?/) { + # If the start of the line doesn't match the regex (see module POD) + unless ($line =~ /^\[?([a-z]+)\]?:?/i) { # Abort the program (temporary code) die "No matching log line"; } From d8945be173346a1c6734f0323ff4e4ad6d9eb9a0 Mon Sep 17 00:00:00 2001 From: Ethan Kletschke Date: Wed, 28 Oct 2026 05:42:34 +0200 Subject: [PATCH 02/10] docs(src): Add description to `LogFileParsing` module --- src/lib/Utils/TextFiles/LogFileParsing.pm | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/lib/Utils/TextFiles/LogFileParsing.pm b/src/lib/Utils/TextFiles/LogFileParsing.pm index 837b66c..90989b2 100644 --- a/src/lib/Utils/TextFiles/LogFileParsing.pm +++ b/src/lib/Utils/TextFiles/LogFileParsing.pm @@ -99,8 +99,8 @@ C - A file parsing module for log files. =head1 DESCRIPTION -=for comment -DO THIS LATER +The C module provides utility functions for parsing, handling, +and using log files. =head1 METHODS From 8ef3b22c1d33b38f9081f005bcbc0dc5e651639b Mon Sep 17 00:00:00 2001 From: Ethan Kletschke Date: Wed, 28 Oct 2026 05:51:08 +0200 Subject: [PATCH 03/10] docs(src): Add POD documentation for `count_logs_by_type()` --- src/lib/Utils/TextFiles/LogFileParsing.pm | 56 ++++++++++++++++++++++- 1 file changed, 54 insertions(+), 2 deletions(-) diff --git a/src/lib/Utils/TextFiles/LogFileParsing.pm b/src/lib/Utils/TextFiles/LogFileParsing.pm index 90989b2..ecbd5ef 100644 --- a/src/lib/Utils/TextFiles/LogFileParsing.pm +++ b/src/lib/Utils/TextFiles/LogFileParsing.pm @@ -104,8 +104,60 @@ and using log files. =head1 METHODS -=for comment -Document methods later +=head2 count_logs_by_type() + +Counts the number of logs of a certain type in a +provided log file. + +Each line is tested against the RegEx C, which +allows for the following log types as line prefixes: + +=over 4 + +=item * C<[LOG]> + +=item * C + +=item * C<[LOG]:> + +=item * C<[log]> + +=back + +=head3 PARAMETERS + +=over 4 + +=item C<$log_type> + +The type of log to count. + +=item C<$filename> + +The relative path to the log file, including the file extension. + +=back + +=head3 ERROR HANDLING + +If the file specified with C<$filename> doesn't exist, the method +currently calls C with a stack trace. This behaviour is subject +to change. + +=head3 LIMITATIONS + +The log type passed to the function has to include only the text +of the log type. For example, if the file includes +C<[ERR]>, the input must be passed without the square +brackets, i.e., C. + +=head3 EXAMPLE USAGE + + use Utils::TextFiles::LogFileParsing qw( + count_logs_by_type + ); + + print count_logs_by_type("ERR", "dev.log"), "\n"; =head1 AUTHOR From 26d3aacc051dbf8af3eeaa9f45930ce026744355 Mon Sep 17 00:00:00 2001 From: Ethan Kletschke Date: Wed, 28 Oct 2026 06:00:21 +0200 Subject: [PATCH 04/10] docs(src): Start POD for `filter_logs` and add another module test --- src/lib/Utils/TextFiles/LogFileParsing.pm | 19 ++++++++++++++++++- src/t/TextFiles.t | 6 ++++++ 2 files changed, 24 insertions(+), 1 deletion(-) diff --git a/src/lib/Utils/TextFiles/LogFileParsing.pm b/src/lib/Utils/TextFiles/LogFileParsing.pm index ecbd5ef..3df405d 100644 --- a/src/lib/Utils/TextFiles/LogFileParsing.pm +++ b/src/lib/Utils/TextFiles/LogFileParsing.pm @@ -104,7 +104,7 @@ and using log files. =head1 METHODS -=head2 count_logs_by_type() +=head2 count_logs_by_type Counts the number of logs of a certain type in a provided log file. @@ -159,6 +159,23 @@ brackets, i.e., C. print count_logs_by_type("ERR", "dev.log"), "\n"; +=head2 filter_logs + +Filters a log file by a specific log type. + +Each log line is tested against the RegEx C, + + +=head3 PARAMETERS + +Test + +=head3 LIMITATIONS + +Unlike with L, you can pass C<[ERR]> for the log type, +and it will work the same as passing C. This is due to the use of +L. + =head1 AUTHOR Ethan Kletschke diff --git a/src/t/TextFiles.t b/src/t/TextFiles.t index bcb19e8..a463da7 100644 --- a/src/t/TextFiles.t +++ b/src/t/TextFiles.t @@ -143,6 +143,12 @@ subtest "LogFileParsing" => sub { "Filters 2 Error logs" ); + is( + scalar filter_logs('[ERR]', 'testing.tmp'), + 2, + "Filters 2 Error logs including square brackets in the log type argument's value" + ); + unlink("testing.tmp"); }; }; From 677c62a0d7888cdfdba8a5c9d5955a2235b90225 Mon Sep 17 00:00:00 2001 From: Ethan Kletschke Date: Wed, 28 Oct 2026 07:15:00 +0200 Subject: [PATCH 05/10] refactor: Remove extra line in POD --- src/lib/Utils/TextFiles/LogFileParsing.pm | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/lib/Utils/TextFiles/LogFileParsing.pm b/src/lib/Utils/TextFiles/LogFileParsing.pm index 3df405d..eb5549c 100644 --- a/src/lib/Utils/TextFiles/LogFileParsing.pm +++ b/src/lib/Utils/TextFiles/LogFileParsing.pm @@ -163,8 +163,7 @@ brackets, i.e., C. Filters a log file by a specific log type. -Each log line is tested against the RegEx C, - +Each log line is tested against the RegEx C. =head3 PARAMETERS From 2d61497a5468b62b9f06d85b04bcedefa6964fb3 Mon Sep 17 00:00:00 2001 From: Ethan Kletschke Date: Wed, 28 Oct 2026 07:44:21 +0200 Subject: [PATCH 06/10] docs(src): Add `RETURN VALUE` heading to `count_logs_by_type` POD docs --- src/lib/Utils/TextFiles/LogFileParsing.pm | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/src/lib/Utils/TextFiles/LogFileParsing.pm b/src/lib/Utils/TextFiles/LogFileParsing.pm index eb5549c..b5bad71 100644 --- a/src/lib/Utils/TextFiles/LogFileParsing.pm +++ b/src/lib/Utils/TextFiles/LogFileParsing.pm @@ -138,6 +138,11 @@ The relative path to the log file, including the file extension. =back +=head3 RETURN VALUE + +Returns an integer, i.e., the number of lines for the provided log type, or +C<0> if the log type was not found in the log file. + =head3 ERROR HANDLING If the file specified with C<$filename> doesn't exist, the method From 629a93269eace5abfde3c884c88772c0122de749 Mon Sep 17 00:00:00 2001 From: Ethan Kletschke Date: Wed, 28 Oct 2026 07:50:28 +0200 Subject: [PATCH 07/10] docs(src): Finish POD for `LogFileParsing.pm` --- src/lib/Utils/TextFiles/LogFileParsing.pm | 37 ++++++++++++++++++++--- 1 file changed, 33 insertions(+), 4 deletions(-) diff --git a/src/lib/Utils/TextFiles/LogFileParsing.pm b/src/lib/Utils/TextFiles/LogFileParsing.pm index b5bad71..f3742f4 100644 --- a/src/lib/Utils/TextFiles/LogFileParsing.pm +++ b/src/lib/Utils/TextFiles/LogFileParsing.pm @@ -145,8 +145,8 @@ C<0> if the log type was not found in the log file. =head3 ERROR HANDLING -If the file specified with C<$filename> doesn't exist, the method -currently calls C with a stack trace. This behaviour is subject +If the file specified with C<$filename> doesn't open or close correctly, +the method currently calls C with a stack trace. This behaviour is subject to change. =head3 LIMITATIONS @@ -168,11 +168,32 @@ brackets, i.e., C. Filters a log file by a specific log type. -Each log line is tested against the RegEx C. +Each log line is tested against the RegEx C, +and only the lines that match will be returned in an array. =head3 PARAMETERS -Test +=over 4 + +=item C<$log_type> + +The type of log to C in the log file. + +=item C<$filename> + +The log file to C. + +=back + +=head3 RETURN VALUE + +Returns an array of the matched lines from C<$filename>. + +=head3 ERROR HANDLING + +If the file specified with C<$filename> doesn't open or close correctly, +the method currently calls C with a stack trace. This behaviour is subject +to change. =head3 LIMITATIONS @@ -180,6 +201,14 @@ Unlike with L, you can pass C<[ERR]> for the log type, and it will work the same as passing C. This is due to the use of L. +=head3 EXAMPLE USAGE + + use Utils::TextFiles::LogFileParsing qw( + filter_logs + ); + + print filter_logs('ERR', 'dev.log'), "\n"; + =head1 AUTHOR Ethan Kletschke From c96ab1047e635319b7f84d2d52ef1734e69d7400 Mon Sep 17 00:00:00 2001 From: Ethan Kletschke Date: Wed, 28 Oct 2026 11:20:49 +0200 Subject: [PATCH 08/10] tests: Rephrase `filter_logs()` test title --- src/t/TextFiles.t | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/t/TextFiles.t b/src/t/TextFiles.t index a463da7..5335012 100644 --- a/src/t/TextFiles.t +++ b/src/t/TextFiles.t @@ -146,7 +146,7 @@ subtest "LogFileParsing" => sub { is( scalar filter_logs('[ERR]', 'testing.tmp'), 2, - "Filters 2 Error logs including square brackets in the log type argument's value" + "Filters 2 Error logs with square brackets in the supplied log type" ); unlink("testing.tmp"); From 072ff88dada5743e18ff2b5e47afc9dc5f765d8b Mon Sep 17 00:00:00 2001 From: Ethan Kletschke Date: Wed, 28 Oct 2026 11:32:23 +0200 Subject: [PATCH 09/10] tests: Test that `linecount` returns 0 for an empty file --- src/t/TextFiles.t | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/src/t/TextFiles.t b/src/t/TextFiles.t index 5335012..a310d99 100644 --- a/src/t/TextFiles.t +++ b/src/t/TextFiles.t @@ -28,6 +28,10 @@ subtest "LineCounter" => sub { ; close $fh; + # Write an empty test file + open $fh, '>', "empty.txt" or die "Could not create empty.txt: $!\n"; + close $fh; + # Test that the linecount subroutine correctly returns a count of 4 is( linecount("LineCounter.tmp"), @@ -48,6 +52,13 @@ subtest "LineCounter" => sub { 0, "Doesn't return 0 for an existing file" ); + + # Test that the linecount returns 0 for an empty file + is( + linecount("empty.txt"), + 0, + "Returns 0 for an empty, existing file" + ); }; subtest "non_empty_linecount()" => sub { @@ -81,6 +92,7 @@ subtest "LineCounter" => sub { # Delete the testing file unlink "LineCounter.tmp"; + unlink "empty.txt"; }; }; From 4af65f97c0928964592e0dac168f499eb195fd8c Mon Sep 17 00:00:00 2001 From: Ethan Kletschke Date: Wed, 28 Oct 2026 11:36:02 +0200 Subject: [PATCH 10/10] docs(src): Add POD for `LineCounter.pm` --- src/lib/Utils/TextFiles/LineCounter.pm | 87 ++++++++++++++++++++++++++ 1 file changed, 87 insertions(+) diff --git a/src/lib/Utils/TextFiles/LineCounter.pm b/src/lib/Utils/TextFiles/LineCounter.pm index 0720ee6..7e1474f 100644 --- a/src/lib/Utils/TextFiles/LineCounter.pm +++ b/src/lib/Utils/TextFiles/LineCounter.pm @@ -77,3 +77,90 @@ sub non_empty_linecount { } 1; + +__END__ + +=pod + +=head1 NAME + +C - A file parsing module for counting lines in files. + +=head1 SYNOPSIS + + use Utils::TextFiles::LineCounter qw(non_empty_linecount); + + print non_empty_linecount('dev.log'), "\n"; + +=head1 DESCRIPTION + +The C module provides utility functions for counting lines in files. + +=head1 METHODS + +=head2 linecount + +Counts the number of lines in a text file. Also counts blank lines. + +=head3 PARAMETERS + +=over 4 + +=item C<$filename> + +The name of the file whose lines to count. + +=back + +=head3 RETURN VALUE + +Returns an integer representing the line count for that file, or +C<0> if the file doesn't exist. + +=head3 ERROR HANDLING + +If the file specified by C<$filename> cannot be opened or closed correctly, +the function calls C. This behaviour is subject to change. + +=head3 EXAMPLE USAGE + + use Utils::TextFiles::LineCounter qw(linecount); + + print linecount('dev.log'), "\n"; + +=head2 non_empty_linecount + +Performs the same line-counting as L, but +doesn't count empty lines. + +=head3 PARAMETERS + +=over 4 + +=item C<$filename> + +The name of the file whose lines are to be counted. + +=back + +=head3 RETURN VALUE + +Returns an integer representing the count of non-empty lines for +C<$filename>. + +=head3 ERROR HANDLING + +If the file specified by C<$filename> cannot be opened or closed correctly, +the function calls C. This behaviour is subject to change. + +=head3 EXAMPLE USAGE + + use Utils::TextFiles::LineCounter qw(non_empty_linecount); + + print non_empty_linecount('dev.log'), "\n"; + +=head1 AUTHOR + +Ethan Kletschke + +=cut