Common.pm

filter: Statementstmt 44.9% 67 / 149 Branchbran 0.0% 0 / 34 Conditioncond 0.0% 0 / 17 MC/DCmcdc 0.0% 0 / 10 Subroutinesub 45.1% 14 / 31 Podpod 0.0% 0 / 17 totaltotal 31.4% 81 / 258 CC 27 SCAR 27.1
CC
27
Cov
34%
dmsg
56.0
fatal
42.0
writeh
20.0
CRAP 15.0
↑ Summary Common/Handle.pm »
1 1 ▶use Object::Pad ':experimental(:all)';
Subroutine BEGIN: called CC=1 SCAR=0.0
2  
3 package IO::Handle::Common;
4  
5 1 ▶class IO::Handle::Common : does(IO::Handle::Common::Base);
Subroutine BEGIN: called CC=1 SCAR=0.0
6 1 our $VERSION = '0.01.1';
7  
8 1 ▶use utf8;
Subroutine BEGIN: called CC=1 SCAR=0.0
9 1 ▶use v5.40;
Subroutine BEGIN: called CC=1 SCAR=0.0
10  
11 1 ▶use Carp qw'croak';
Subroutine BEGIN: called CC=1 SCAR=0.0
12 1 ▶use Const::Fast;
Subroutine BEGIN: called CC=1 SCAR=0.0
13 1 ▶use Data::Dumper::Names;
Subroutine BEGIN: called CC=1 SCAR=0.0
14 1 ▶use Devel::StackTrace::WithLexicals;
Subroutine BEGIN: called CC=1 SCAR=0.0
15 1 ▶use PadWalker;
Subroutine BEGIN: called CC=1 SCAR=0.0
16 1 ▶use IO::Handle::Common::Handle;
Subroutine BEGIN: called CC=1 SCAR=0.0
17 1 ▶use Time::Piece;
Subroutine BEGIN: called CC=1 SCAR=0.0
18 1 ▶use Const::Fast;
Subroutine BEGIN: called CC=1 SCAR=0.0
19  
20 1 ▶use parent 'Class::Exporter';
Subroutine BEGIN: called CC=1 SCAR=0.0
21 1 ▶use vars qw'@EXPORT @EXPORT_OK';
Subroutine BEGIN: called CC=1 SCAR=0.0
22  
23 1 @EXPORT = qw(dmsg info success error fatal msg);
24 1 @EXPORT_OK = ( @EXPORT, qw'$io' );
25  
26 field $debug : param = $ENV{DEBUG} // 0;
27  
28 0 field $ddn_uplvl : param : accessor = 3;
29 0 ▶field $trace_indent : param : accessor = $ENV{DEBUG_INDENT} // 1;
Subroutine ddn_uplvl: not called CC=2 SCAR=14.0
Pod undocumented
Branch: 1 branch
BranchTrueFalseTotal
@_ and $ddn_uplvl = shift() 0 0 0
30 0 ▶field $skip_frames : param : accessor = $ENV{DEBUG_SKIPFRAMES} // 1;
Subroutine trace_indent: not called CC=2 SCAR=14.0
Pod undocumented
Branch: 1 branch
BranchTrueFalseTotal
@_ and $trace_indent = shift() 0 0 0
31  
32 0 ▶field $info_head : param : accessor = [qw'▶ ▷'];
Subroutine skip_frames: not called CC=2 SCAR=14.0
Pod undocumented
Branch: 1 branch
BranchTrueFalseTotal
@_ and $skip_frames = shift() 0 0 0
33 0 ▶field $err_head : param : accessor = ['❌️'];
Subroutine info_head: not called CC=2 SCAR=14.0
Pod undocumented
Branch: 1 branch
BranchTrueFalseTotal
@_ and $info_head = shift() 0 0 0
34 0 ▶field $field_head : param : accessor = [@$err_head];
Subroutine err_head: not called CC=2 SCAR=14.0
Pod undocumented
Branch: 1 branch
BranchTrueFalseTotal
@_ and $err_head = shift() 0 0 0
35 0 ▶field $success_head : param : accessor = ['⭕️'];
Subroutine field_head: not called CC=2 SCAR=14.0
Pod undocumented
Branch: 1 branch
BranchTrueFalseTotal
@_ and $field_head = shift() 0 0 0
36 0 ▶field $msg_head : param : accessor = [undef];
Subroutine success_head: not called CC=2 SCAR=14.0
Pod undocumented
Branch: 1 branch
BranchTrueFalseTotal
@_ and $success_head = shift() 0 0 0
37  
38 # field $dmsg_head : accessor;
39  
40 # ADJUST : params (:$dmsg_head = undef) {
41 # $dmsg_head //= [
42 # sub {
43 # $self->headfmt(
44 # Time::Piece->now->to_string('%Y-%m-%d %H:%M:%S%f') );
45 # }
46 # ]
47 # };
48  
49 0 ▶field $head = {
Subroutine msg_head: not called CC=2 SCAR=13.0
Pod undocumented
Branch: 1 branch
BranchTrueFalseTotal
@_ and $msg_head = shift() 0 0 0
50 info => undef,
51 err => undef,
52 success => undef,
53 fatal => undef,
54 msg => undef,
55 dmsg => undef
56 };
57  
58 1 ADJUST : params (:$prepend_head //= undef) {
59  
60 # my $headfield_ptn = join "|", @$prepend_head;
61 # const my $headfield_re => qr/($headfield_ptn)+/i;
62 if ($prepend_head) {
63 if ( $prepend_head == 1 ) {
64 @$head = ( 1 x scalar @$head - 1 );
65 }
66 elsif ( refstr($prepend_head) eq 'ARRAY' ) {
67 const my $headfield_re => eval "qr/(" . join "|",
68 @$prepend_head . ")+/i";
69 $$head{$_} = 1 for grep { $_ =~ $headfield_re } @$prepend_head;
70 }
71 elsif ( refstr($prepend_head) eq 'HASH' ) {
72 foreach my ( $k, $v ) (%$prepend_head) {
73 $$head{$k} = 1;
74 eval "\$${k}_head = [\$v]";
75 }
76 }
77 }
78  
79 # elsif ( !reftype($prepend_head) && $prepend_head =~ $headfield_re ) {
80 # $self->adjust( $prepend_head, 1 );
81 # }
82 };
83  
84 method $io {
85 $self;
86 1 }
87  
88 0 ▶method writeh( $line, $handle, %opt ) {
Subroutine writeh: not called CC=4 SCAR=30.0
Pod undocumented
89  
90 0 ▶ if ( $line isa 'ARRAY' ) {
Branch: 2 branches
BranchTrueFalseTotal
if ($line isa 'ARRAY') { } 0 0 0
elsif (not ref $line) { } 0 0 0
91 0 $handle->say($_) for $line->@*;
92 }
93 elsif ( !ref $line ) {
94 0 $handle->say($line);
95 }
96 1 }
97  
98 0 ▶method outh ($line) {
Subroutine outh: not called CC=1 SCAR=6.9
Pod undocumented
99 0 state $h = IO::Handle::Common::Handle->new( fd => *STDOUT, mode => '>' );
100 0 $self->writeh( $line, $h );
101 1 }
102  
103 0 ▶method errh ($line) {
Subroutine errh: not called CC=1 SCAR=6.9
Pod undocumented
104 0 state $h = IO::Handle::Common::Handle->new( fd => *STDERR, mode => '>' );
105 0 $self->writeh( $line, $h );
106 1 }
107  
108 1 const our $ltrimtab_re => qr/^\t/;
109 1 const our $lb_re => qr/\R/;
110  
111 0 ▶method dmsg {
Subroutine dmsg: not called CC=7 SCAR=40.3
Pod undocumented
112 0 ▶ return unless $debug // $ENV{DEBUG};
Branch: 1 branch
BranchTrueFalseTotal
unless $debug // $ENV{"DEBUG"} 0 0 0
Condition0%0/3
$debug // $ENV{"DEBUG"}
l!l&&r!l&&!r
000
MC/DC0%0/2
$debug // $ENV{"DEBUG"}
$debug $ENV{"DEBUG"}
Truth table0%0/3
A // B
A= $debugB= $ENV{"DEBUG"}
ABresult
1X1
011
000
113 0 my @caller = caller 1;
114  
115 0 local $Data::Dumper::Names::UpLevel = $ddn_uplvl;
116 0 local $Data::Dumper::Pad = " ";
117 0 local $Data::Dumper::Indent = 1;
118  
119 0 my $out;
120 0 $out .= Dumper(@_);
121 $out .=
122 $debug && $debug == 2
123 ? join "\n",
124 0 ▶ map { ( my $line = $_ ) =~ s/$ltrimtab_re/ /; " $line" } split /$lb_re/,
Branch: 1 branch
BranchTrueFalseTotal
$debug && $debug == 2 ? : 0 0 0
Condition0%0/7
$debug and $debug == 2
!ll&&!rl&&r
000
$trace_indent // 1
l!l
00
$skip_frames // 1
l!l
00
MC/DC0%0/2
$debug and $debug == 2
$debug $debug == 2
MC/DC0%0/1
$trace_indent // 1
$trace_indent
MC/DC0%0/1
$skip_frames // 1
$skip_frames
Truth table0%0/3
A and B
A= $debugB= $debug == 2
ABresult
0X0
100
111
Truth table0%0/2
A
A= $trace_indent
Aresult
11
00
Truth table0%0/2
A
A= $skip_frames
Aresult
11
00
125 Devel::StackTrace::WithLexicals->new(
126 indent => $trace_indent // 1,
127 skip_frames => $skip_frames // 1
128 )->as_string
129 : "at $caller[1]:$caller[2]\n";
130  
131 0 $self->errh($out);
132 0 $out;
133 1 }
134  
135 0 ▶method info ($line) {
Subroutine info: not called CC=2 SCAR=17.9
Pod undocumented
136 0 ▶ $line = "$info_head $line" if $$head{info};
Branch: 1 branch
BranchTrueFalseTotal
if $head->{"info"} 0 0 0
137 0 $self->errh($line);
138 1 }
139  
140 0 ▶method error ($line) {
Subroutine error: not called CC=2 SCAR=17.9
Pod undocumented
141 0 ▶ $line = "$err_head $line" if $$head{error};
Branch: 1 branch
BranchTrueFalseTotal
if $head->{"error"} 0 0 0
142 0 $self->errh($line);
143 1 }
144  
145 0 ▶method fatal ( $line, $status = ( $? || 255 ), %opt ) {
Subroutine fatal: not called CC=6 SCAR=37.4
Pod undocumented
Condition0%0/2
$? || 255
l!l
00
MC/DC0%0/1
$? || 255
$?
Truth table0%0/2
A
A= $?
Aresult
11
00
146 0 ▶ $status = $status >> 8 if ( $status > 255 );
Branch: 1 branch
BranchTrueFalseTotal
if $status > 255 0 0 0
147  
148 0 ▶ error "Status ($status) must be between 0 and 255"
Branch: 1 branch
BranchTrueFalseTotal
unless $status >= 0 or $status <= 255 0 0 0
Condition0%0/3
$status >= 0 or $status <= 255
l!l&&r!l&&!r
000
MC/DC0%0/2
$status >= 0 or $status <= 255
$status >= 0 $status <= 255
Truth table0%0/3
A or B
A= $status >= 0B= $status <= 255
ABresult
1X1
011
000
149 unless $status >= 0 || $status <= 255;
150  
151 0 $self->error( $line, %opt );
152 0 croak $status;
153 1 }
154  
155 0 ▶method success ($line) {
Subroutine success: not called CC=2 SCAR=17.9
Pod undocumented
156 0 ▶ $line = "$success_head $line" if $$head{success};
Branch: 1 branch
BranchTrueFalseTotal
if $head->{"success"} 0 0 0
157 0 $self->outh($line);
158 1 }
159  
160 0 ▶method msg ($line) {
Subroutine msg: not called CC=2 SCAR=17.9
Pod undocumented
161 0 ▶ $self->outh( ( $$head{msg} // '' ) . $line );
Condition0%0/2
$head->{"msg"} // ""
l!l
00
MC/DC0%0/1
$head->{"msg"} // ""
$head->{"msg"}
Truth table0%0/2
A
A= $head->{"msg"}
Aresult
11
00
162 }
163  
164 # method headfmt( $instr, %opt ) {
165 # $instr;
166 # }
167  
168 # method prompt { ... }
169 # method getc { ... }
170 # method getline { ... }
171  
172 =encoding utf-8
173  
174 =head1 NAME
175  
176 IO::Handle::Common - Nearly ubiquitous methods for script and file IO
177  
178 =head1 SYNOPSIS
179  
180 use IO::Handle::Common; # Exports info, error, fatal, success, msg, dmsg and path by default
181  
182 # Pretty-print @args only if $debug || $ENV{DEBUG} is set to something truth-y
183 dmsg ...; #
184  
185 fatal "$?..." if $?; # die without line numbers or other non-enduser information
186  
187 success "..." # ...
188  
189 =head1 DESCRIPTION
190  
191 IO::Handle::Common is a collection of methods useful for script output, both
192 debug and user-facing, and file-based IO wrapped loosely around IO::Handle and
193 Path::Tiny.
194  
195 =head1 AUTHOR
196  
197 Ian P Bradley E<lt>ian@pennyfoss.orgE<gt>
198  
199 =head1 COPYRIGHT
200  
201 Copyright 2026- Ian P Bradley
202  
203 =head1 LICENSE
204  
205 This library is free software; you can redistribute it and/or modify
206 it under the same terms as Perl itself.
207  
208 =head1 SEE ALSO
209  
210 =cut
↑ Summary Common/Handle.pm »