| 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
| |||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||
| 62 | 78 | ▶ | return( $self->{_encoded} ) if( defined( $self->{_encoded} ) ); | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 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."))
MC/DC0%0/1
shift @_ // (return $self->error("No value to decode."))
shift @_
Truth table50%1/2
A
A= shift @_
| |||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||
| 89 | { | ||||||||||||||||||||||||||||
| 90 | 78 | my $text = shift( @_ ); | |||||||||||||||||||||||||||
| 91 | 78 | ▶ | unless( defined( $text ) ) | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||
| 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
Condition66%2/3
defined $str and $str =~ /=\?/
MC/DC50%1/2
defined $str and $str =~ /=\?/
defined $str
$str =~ /=\?/
Truth table66%2/3
A and B
A= defined $strB= $str =~ /=\?/
| |||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||
| 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
| |||||||||||||||||||||||||||||
| 179 | { | ||||||||||||||||||||||||||||
| 180 | 14 | my $next = ord( substr( $bytes, $offset + $len, 1 ) ); | |||||||||||||||||||||||||||
| 181 | 14 | ▶ | if( ( $next & 0xC0 ) == 0x80 ) | ||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||
| 182 | { | ||||||||||||||||||||||||||||
| 183 | # Find last leading byte in chunk | ||||||||||||||||||||||||||||
| 184 | 0 | ▶ | while( $len > 0 && ( ord( substr( $chunk, $len - 1, 1 ) ) & 0xC0 ) == 0x80 ) | ||||||||||||||||||||||||||
|
Branch: 1 branch
Condition0%0/3
$len > 0 and (ord substr($chunk, $len - 1, 1) & 192) == 128
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
| |||||||||||||||||||||||||||||
| 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__ | ||||||||||||||||||||||||||||