Mail/Make/Headers/Subject.pm

filter: Statementstmt 94.3% 101 / 107 Branchbran 73.3% 22 / 30 Conditioncond 37.5% 3 / 8 MC/DCmcdc 20.0% 1 / 5 Subroutinesub 92.0% 23 / 25 Podpod 75.0% 6 / 8 totaltotal 85.2% 156 / 183 CC 19 SCAR 12.8
CC
19
Cov
87%
_encode_subject
10.1
as_string
3.1
value
3.0
CRAP 3.6
« Mail/Make/Headers/ContentTransferEncoding.pm ↑ Summary Mail/Make/Body/InCore.pm »
1 ##----------------------------------------------------------------------------
2 ## MIME Email Builder - ~/lib/Mail/Make/Headers/Subject.pm
3 ## Version v0.1.1
4 ## Copyright(c) 2026 DEGUEST Pte. Ltd.
5 ## Author: Jacques Deguest <jack@deguest.jp>
6 ## Created 2026/03/03
7 ## Modified 2026/03/05
8 ## All rights reserved
9 ##
10 ## This program is free software; you can redistribute it and/or modify it
11 ## under the same terms as Perl itself.
12 ##----------------------------------------------------------------------------
13 package Mail::Make::Headers::Subject;
14 BEGIN
15 9 ▶{
Subroutine BEGIN: called CC=1 SCAR=0.0
16 9 ▶ use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
17 9 ▶ use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
18 9 warnings::register_categories( 'Mail::Make' );
19 9 ▶ use parent qw( Module::Generic );
Subroutine BEGIN: called CC=1 SCAR=0.0
20 9 ▶ use vars qw( $VERSION $EXCEPTION_CLASS );
Subroutine BEGIN: called CC=1 SCAR=0.0
21 9 ▶ use utf8;
Subroutine BEGIN: called CC=1 SCAR=0.0
22 9 ▶ use Encode ();
Subroutine BEGIN: called CC=1 SCAR=0.0
23 9 ▶ use Mail::Make::Exception;
Subroutine BEGIN: called CC=1 SCAR=0.0
24 9 ▶ use MIME::Base64 ();
Subroutine BEGIN: called CC=1 SCAR=0.0
25 9 ▶ use overload(
Subroutine BEGIN: called CC=1 SCAR=0.0
26 '""' => 'as_string',
27 82 ▶ 'bool' => sub { 1 },
Subroutine __ANON__: called CC=1 SCAR=0.0
28 9 );
29 9 our $EXCEPTION_CLASS = 'Mail::Make::Exception';
30 9 our $VERSION = 'v0.1.1';
31 # RFC 2047 §2: an encoded-word must not exceed 75 characters total.
32 # =?UTF-8?B? ... ?= - the wrapper is 12 chars, leaving 63 for base64 text.
33 # 63 base64 chars encode floor(63 * 3/4) = 47 raw bytes.
34 # We use 45 bytes per chunk (multiple of 3) to keep base64 clean.
35 use constant
36 9 ▶ {
Subroutine BEGIN: called CC=1 SCAR=0.0
37 9 CHARSET => 'UTF-8',
38 EW_MAX_BYTES => 45,
39 FOLD_SEP => "\015\012 ",
40 9 };
41 };
42  
43 9 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
44 9 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
45  
46 sub init
47 82 ▶{
Subroutine init: called CC=2 SCAR=7.0
Pod documented
48 82 my $self = shift( @_ );
49 82 $self->{_raw} = undef; # original Perl string, not yet encoded
50 82 $self->{_encoded} = undef; # RFC 2047 form, cached after first encode
51 82 $self->{_exception_class} = $EXCEPTION_CLASS;
52 82 ▶ $self->SUPER::init( @_ ) || return( $self->pass_error );
Branch: 1 branch
BranchTrueFalseTotal
$self->SUPER::init(@_) or return $self->pass_error 82 0 82
53 82 return( $self );
54 }
55  
56 # as_string() returns the RFC 2047 encoded form suitable for the wire.
57 # Pure ASCII values are returned unchanged.
58 sub as_string
59 78 ▶{
Subroutine as_string: called CC=3 SCAR=11.3
Pod documented
60 78 my $self = shift( @_ );
61 78 ▶ return( '' ) if( !defined( $self->{_raw} ) );
Branch: 1 branch
BranchTrueFalseTotal
unless defined $self->{"_raw"} 0 78 78
62 78 ▶ return( $self->{_encoded} ) if( defined( $self->{_encoded} ) );
Branch: 1 branch
BranchTrueFalseTotal
if defined $self->{"_encoded"} 0 78 78
63 78 $self->{_encoded} = _encode_subject( $self->{_raw} );
64 78 return( $self->{_encoded} );
65 }
66  
67 # decode( $encoded_string ) is a class or instance method.
68 # Decodes an RFC 2047 encoded Subject value back to a Perl string.
69 sub decode
70 9 ▶{
Subroutine decode: called CC=2 SCAR=7.1
Pod documented
71 9 my $self = shift( @_ );
72 9 ▶ my $str = shift( @_ ) // return( $self->error( "No value to decode." ) );
Condition50%1/2
shift @_ // (return $self->error("No value to decode."))
l!l
90
MC/DC0%0/1
shift @_ // (return $self->error("No value to decode."))
shift @_
Truth table50%1/2
A
A= shift @_
Aresult
11
00
73 9 return( _decode_subject( $str ) );
74 }
75  
76 # field_name() always returns 'Subject'
77 1 ▶sub field_name { return( 'Subject' ); }
Subroutine field_name: called CC=1 SCAR=0.0
Pod documented
78  
79 # raw() returns the decoded Perl string (the original value before encoding)
80 1 ▶sub raw { return( shift->{_raw} ); }
Subroutine raw: called CC=1 SCAR=0.0
Pod documented
81  
82 # value( [$text] ) sets or gets the subject text.
83 # On assignment: stores the raw Perl string; clears the encoded cache.
84 # On retrieval: returns the decoded Perl string (i.e. human-readable).
85 sub value
86 79 ▶{
Subroutine value: called CC=3 SCAR=11.1
Pod documented
87 79 my $self = shift( @_ );
88 79 ▶ if( @_ )
Branch: 1 branch
BranchTrueFalseTotal
if (@_) 78 1 79
89 {
90 78 my $text = shift( @_ );
91 78 ▶ unless( defined( $text ) )
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $text) 0 78 78
92 {
93 0 return( $self->error( "Subject value must be a defined scalar." ) );
94 }
95 78 $self->{_raw} = $text;
96 78 $self->{_encoded} = undef; # invalidate cache
97 78 return( $self );
98 }
99 1 return( $self->{_raw} );
100 }
101  
102 # _decode_ew( $charset, $encoding, $text ) → decoded Perl string fragment
103 sub _decode_ew
104 16 ▶{
Subroutine _decode_ew: called CC=3 SCAR=11.0
105 16 my( $charset, $enc, $text ) = @_;
106 16 my $bytes;
107 16 ▶ if( uc( $enc ) eq 'B' )
Branch: 1 branch
BranchTrueFalseTotal
if (uc $enc eq 'B') { } 15 1 16
108 {
109 15 $bytes = MIME::Base64::decode_base64( $text );
110 }
111 else
112 {
113 # Q encoding: _ → space, =XX → byte
114 1 $text =~ s/_/ /g;
115 1 $text =~ s/=([0-9A-Fa-f]{2})/chr( hex( $1 ) )/ge;
116 1 $bytes = $text;
117 }
118 16 local $@;
119 16 my $decoded = eval{ Encode::decode( $charset, $bytes ) };
120 16 ▶ return( $@ ? $bytes : $decoded );
Branch: 1 branch
BranchTrueFalseTotal
$@ ? : 0 16 16
121 }
122  
123 # _decode_subject( $wire_string ) → $perl_string
124 # Decodes all RFC 2047 encoded-words in $wire_string.
125 # Handles both ?B? (Base64) and ?Q? (Quoted-Printable) forms.
126 sub _decode_subject
127 9 ▶{
Subroutine _decode_subject: called CC=3 SCAR=11.0
128 9 my $str = shift( @_ );
129 9 ▶ return( $str ) unless( defined( $str ) && $str =~ /=\?/ );
Branch: 1 branch
BranchTrueFalseTotal
unless defined $str and $str =~ /=\?/ 1 8 9
Condition66%2/3
defined $str and $str =~ /=\?/
!ll&&!rl&&r
018
MC/DC50%1/2
defined $str and $str =~ /=\?/
defined $str $str =~ /=\?/
Truth table66%2/3
A and B
A= defined $strB= $str =~ /=\?/
ABresult
0X0
100
111
130  
131 # Collapse folding whitespace between consecutive encoded-words:
132 # RFC 2047 §6.2: whitespace between two encoded-words is ignored.
133 8 $str =~ s/\?=[ \t]*(?:\015\012)?[ \t]*=\?/?==?/g;
134  
135 8 $str =~ s/=\?([A-Za-z0-9_-]+)\?([BbQq])\?([^?]*)\?=/_decode_ew( $1, $2, $3 )/ge;
136 8 return( $str );
137 }
138  
139 # _encode_subject( $perl_string ) → $wire_string
140 # Returns the string as-is if it is pure printable ASCII (RFC 2822 §2.2).
141 # Otherwise encodes the UTF-8 bytes in one or more RFC 2047 Base64
142 # encoded-words, folded with CRLF SP between them.
143 sub _encode_subject
144 78 ▶{
Subroutine _encode_subject: called CC=9 SCAR=23.1
145 78 my $text = shift( @_ );
146  
147 # Pure printable ASCII + tab/space: no encoding needed.
148 # We also reject bare CRs and LFs here; they are illegal in a header.
149 78 ▶ return( $text ) unless( $text =~ /[^\x09\x20-\x7E]/ );
Branch: 1 branch
BranchTrueFalseTotal
unless $text =~ /[^\x09\x20-\x7E]/ 61 17 78
150  
151 # Ensure the string carries Perl's UTF-8 flag before encoding to bytes.
152 # If the flag is off (raw octets from a context without Encode::decode),
153 # Encode::encode treats each octet as Latin-1, producing double-encoding:
154 # e.g. U+2014 (E2 80 94) becomes C3 A2 C2 80 C2 94 instead of E2 80 94.
155 17 ▶ utf8::decode( $text ) unless( utf8::is_utf8( $text ) );
Branch: 1 branch
BranchTrueFalseTotal
unless utf8::is_utf8($text) 2 15 17
156  
157 # Encode the entire string to UTF-8 bytes, then split into safe chunks.
158 # Crucially: we split on byte boundaries that do NOT break a multi-byte UTF-8 sequence.
159 # Because we encode the whole string first we work purely in bytes and the split is
160 # safe.
161 17 my $bytes = Encode::encode( CHARSET, $text );
162  
163 17 my @words;
164 17 my $offset = 0;
165 17 my $total = length( $bytes );
166 17 ▶ while( $offset < $total )
Branch: 1 branch
BranchTrueFalseTotal
if ($offset < $total) 31 17 48
167 {
168 # Grab up to EW_MAX_BYTES bytes, but do not cut inside a multi-byte sequence.
169 # UTF-8 continuation bytes are 0x80..0xBF; a leading byte of a multi-byte sequence
170 # is 0xC0..0xFF. We back up until we sit at a leading byte boundary (or the very end).
171 31 my $len = EW_MAX_BYTES;
172 31 ▶ $len = $total - $offset if( $offset + $len > $total );
Branch: 1 branch
BranchTrueFalseTotal
if $offset + $len > $total 15 16 31
173 31 my $chunk = substr( $bytes, $offset, $len );
174  
175 # If the byte immediately after our chunk is a UTF-8 continuation byte (0x80–0xBF),
176 # the last character of our chunk is split.c
177 # Walk backwards to a safe cut point.
178 31 ▶ if( $offset + $len < $total )
Branch: 1 branch
BranchTrueFalseTotal
if ($offset + $len < $total) 14 17 31
179 {
180 14 my $next = ord( substr( $bytes, $offset + $len, 1 ) );
181 14 ▶ if( ( $next & 0xC0 ) == 0x80 )
Branch: 1 branch
BranchTrueFalseTotal
if (($next & 192) == 128) 0 14 14
182 {
183 # Find last leading byte in chunk
184 0 ▶ while( $len > 0 && ( ord( substr( $chunk, $len - 1, 1 ) ) & 0xC0 ) == 0x80 )
Branch: 1 branch
BranchTrueFalseTotal
if ($len > 0 and (ord substr($chunk, $len - 1, 1) & 192) == 128) 0 0 0
Condition0%0/3
$len > 0 and (ord substr($chunk, $len - 1, 1) & 192) == 128
!ll&&!rl&&r
000
MC/DC0%0/2
$len > 0 and (ord substr($chunk, $len - 1, 1) & 192) == 128
$len > 0 (ord substr($chunk, $len - 1, 1) & 192) == 128
Truth table0%0/3
A and B
A= $len > 0B= (ord substr($chunk, $len - 1, 1) & 192) == 128
ABresult
0X0
100
111
185 {
186 0 $len--;
187 }
188 0 $chunk = substr( $bytes, $offset, $len );
189 }
190 }
191  
192 31 my $b64 = MIME::Base64::encode_base64( $chunk, '' );
193 31 push( @words, '=?' . CHARSET . '?B?' . $b64 . '?=' );
194 31 $offset += $len;
195 }
196  
197 17 return( join( FOLD_SEP, @words ) );
198 }
199  
200 # NOTE: STORABLE support
201 0 ▶sub STORABLE_freeze { CORE::return( CORE::shift->FREEZE( @_ ) ); }
Subroutine STORABLE_freeze: not called CC=1 SCAR=6.9
Pod undocumented
202  
203 0 ▶sub STORABLE_thaw { CORE::return( CORE::shift->THAW( @_ ) ); }
Subroutine STORABLE_thaw: not called CC=1 SCAR=6.9
Pod undocumented
204  
205 9 1;
206 # NOTE: POD
207 __END__
« Mail/Make/Headers/ContentTransferEncoding.pm ↑ Summary Mail/Make/Body/InCore.pm »