| 1 | package Net::DNS::Text; | ||||||||||||
| 2 | |||||||||||||
| 3 | 28 | ▶ | use strict; | ||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||
| 4 | 28 | ▶ | use warnings; | ||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||
| 5 | |||||||||||||
| 6 | 28 | our $VERSION = (qw$Id: Text.pm 2043 2026-01-14 13:35:59Z willem $)[2]; | |||||||||||
| 7 | |||||||||||||
| 8 | |||||||||||||
| 9 | =head1 NAME | ||||||||||||
| 10 | |||||||||||||
| 11 | Net::DNS::Text - DNS text representation | ||||||||||||
| 12 | |||||||||||||
| 13 | =head1 SYNOPSIS | ||||||||||||
| 14 | |||||||||||||
| 15 | use Net::DNS::Text; | ||||||||||||
| 16 | |||||||||||||
| 17 | $object = Net::DNS::Text->new('example'); | ||||||||||||
| 18 | $string = $object->string; | ||||||||||||
| 19 | |||||||||||||
| 20 | $object = Net::DNS::Text->decode( \$data, $offset ); | ||||||||||||
| 21 | ( $object, $next ) = Net::DNS::Text->decode( \$data, $offset ); | ||||||||||||
| 22 | |||||||||||||
| 23 | $data = $object->encode; | ||||||||||||
| 24 | $text = $object->value; | ||||||||||||
| 25 | |||||||||||||
| 26 | =head1 DESCRIPTION | ||||||||||||
| 27 | |||||||||||||
| 28 | The C<Net::DNS::Text> module implements a class of text objects | ||||||||||||
| 29 | with associated class and instance methods. | ||||||||||||
| 30 | |||||||||||||
| 31 | Each text object instance has a fixed identity throughout its | ||||||||||||
| 32 | lifetime. | ||||||||||||
| 33 | |||||||||||||
| 34 | =cut | ||||||||||||
| 35 | |||||||||||||
| 36 | |||||||||||||
| 37 | 28 | ▶ | use integer; | ||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||
| 38 | 28 | ▶ | use Carp; | ||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||
| 39 | |||||||||||||
| 40 | |||||||||||||
| 41 | 28 | ▶ | use constant ASCII => ref eval { | ||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||
| 42 | 28 | require Encode; | |||||||||||
| 43 | 28 | Encode::find_encoding('ascii'); | |||||||||||
| 44 | 28 | }; | |||||||||||
| 45 | |||||||||||||
| 46 | 28 | ▶ | use constant UTF8 => scalar eval { ## not UTF-EBCDIC [see Unicode TR#16 3.6] | ||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||
| 47 | 28 | Encode::encode_utf8( chr(182) ) eq pack( 'H*', 'C2B6' ); | |||||||||||
| 48 | 28 | }; | |||||||||||
| 49 | |||||||||||||
| 50 | |||||||||||||
| 51 | =head1 METHODS | ||||||||||||
| 52 | |||||||||||||
| 53 | =head2 new | ||||||||||||
| 54 | |||||||||||||
| 55 | $object = Net::DNS::Text->new('example'); | ||||||||||||
| 56 | |||||||||||||
| 57 | Creates a text object which encapsulates a single character | ||||||||||||
| 58 | string component of a resource record. | ||||||||||||
| 59 | |||||||||||||
| 60 | Arbitrary single-byte characters can be represented by \ followed | ||||||||||||
| 61 | by exactly three decimal digits. Such characters are devoid of | ||||||||||||
| 62 | any special meaning. | ||||||||||||
| 63 | |||||||||||||
| 64 | A character preceded by \ represents itself, without any special | ||||||||||||
| 65 | interpretation. | ||||||||||||
| 66 | |||||||||||||
| 67 | =cut | ||||||||||||
| 68 | |||||||||||||
| 69 | 28 | my ( %escape, %escapeUTF8, %unescape ); ## precalculated escape tables | |||||||||||
| 70 | |||||||||||||
| 71 | 479 | ▶ | sub new { | ||||||||||
|
Subroutine
new: called CC=2 SCAR=6.9
Pod
documented
| |||||||||||||
| 72 | 479 | my $self = bless [], shift; | |||||||||||
| 73 | 479 | local $_ = &_encode_utf8; | |||||||||||
| 74 | |||||||||||||
| 75 | 477 | s/^\042(.*)\042$/$1/s; # strip paired quotes | |||||||||||
| 76 | |||||||||||||
| 77 | 477 | s/\134([\060-\071]{3})/$unescape{$1}/eg; # restore numeric escapes | |||||||||||
| 78 | 477 | s/\134([^\134])/$1/g; # restore character escapes | |||||||||||
| 79 | 477 | s/\134\134/\134/g; # restore escaped escapes | |||||||||||
| 80 | |||||||||||||
| 81 | 477 | ▶ | while ( length $_ > 255 ) { | ||||||||||
|
Branch: 1 branch
| |||||||||||||
| 82 | 2 | my $chunk = substr( $_, 0, 255 ); # carve into chunks | |||||||||||
| 83 | 2 | $chunk =~ s/[\300-\377][\200-\277]*$//; | |||||||||||
| 84 | 2 | push @$self, $chunk; | |||||||||||
| 85 | 2 | substr( $_, 0, length $chunk ) = ''; | |||||||||||
| 86 | } | ||||||||||||
| 87 | 477 | push @$self, $_; | |||||||||||
| 88 | |||||||||||||
| 89 | 477 | return $self; | |||||||||||
| 90 | } | ||||||||||||
| 91 | |||||||||||||
| 92 | |||||||||||||
| 93 | =head2 decode | ||||||||||||
| 94 | |||||||||||||
| 95 | $object = Net::DNS::Text->decode( \$buffer, $offset ); | ||||||||||||
| 96 | |||||||||||||
| 97 | ( $object, $next ) = Net::DNS::Text->decode( \$buffer, $offset ); | ||||||||||||
| 98 | |||||||||||||
| 99 | Creates a text object which represents the decoded data at the | ||||||||||||
| 100 | indicated offset within the data buffer. | ||||||||||||
| 101 | |||||||||||||
| 102 | The argument list consists of a reference to a scalar containing | ||||||||||||
| 103 | the wire-format data and offset of the text data. | ||||||||||||
| 104 | |||||||||||||
| 105 | The returned offset value indicates the start of the next item in | ||||||||||||
| 106 | the data buffer. | ||||||||||||
| 107 | |||||||||||||
| 108 | =cut | ||||||||||||
| 109 | |||||||||||||
| 110 | 16607 | ▶ | sub decode { | ||||||||||
|
Subroutine
decode: called CC=5 SCAR=16.1
Pod
documented
| |||||||||||||
| 111 | 16607 | my $class = shift; | |||||||||||
| 112 | 16607 | my $buffer = shift; # reference to data buffer | |||||||||||
| 113 | 16607 | ▶ | my $offset = shift || 0; # offset within buffer | ||||||||||
|
Condition100%2/2
shift() || 0
MC/DC100%1/1
shift() || 0
shift()
Truth table100%2/2
A
A= shift()
| |||||||||||||
| 114 | 16607 | my $size = shift; # specify size of unbounded text | |||||||||||
| 115 | |||||||||||||
| 116 | 16607 | ▶ | unless ( defined $size ) { | ||||||||||
|
Branch: 1 branch
| |||||||||||||
| 117 | 16599 | $size = unpack "\@$offset C", $$buffer; | |||||||||||
| 118 | 16599 | $offset++; | |||||||||||
| 119 | } | ||||||||||||
| 120 | |||||||||||||
| 121 | 16607 | my $next = $offset + $size; | |||||||||||
| 122 | 16607 | ▶ | croak 'corrupt wire-format data' if $next > length $$buffer; | ||||||||||
|
Branch: 1 branch
| |||||||||||||
| 123 | |||||||||||||
| 124 | 16605 | my $self = bless [unpack( "\@$offset a$size", $$buffer )], $class; | |||||||||||
| 125 | |||||||||||||
| 126 | 16605 | ▶ | return wantarray ? ( $self, $next ) : $self; | ||||||||||
|
Branch: 1 branch
| |||||||||||||
| 127 | } | ||||||||||||
| 128 | |||||||||||||
| 129 | |||||||||||||
| 130 | =head2 encode | ||||||||||||
| 131 | |||||||||||||
| 132 | $data = $object->encode; | ||||||||||||
| 133 | |||||||||||||
| 134 | Returns the wire-format encoded representation of the text object | ||||||||||||
| 135 | suitable for inclusion in a DNS packet buffer. | ||||||||||||
| 136 | |||||||||||||
| 137 | =cut | ||||||||||||
| 138 | |||||||||||||
| 139 | 360 | ▶ | sub encode { | ||||||||||
|
Subroutine
encode: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||
| 140 | 360 | my $self = shift; | |||||||||||
| 141 | 360 | return join '', map { pack( 'C a*', length $_, $_ ) } @$self; | |||||||||||
| 142 | } | ||||||||||||
| 143 | |||||||||||||
| 144 | |||||||||||||
| 145 | =head2 raw | ||||||||||||
| 146 | |||||||||||||
| 147 | $data = $object->raw; | ||||||||||||
| 148 | |||||||||||||
| 149 | Returns the wire-format encoded representation of the text object | ||||||||||||
| 150 | without the explicit length field. | ||||||||||||
| 151 | |||||||||||||
| 152 | =cut | ||||||||||||
| 153 | |||||||||||||
| 154 | 31 | ▶ | sub raw { | ||||||||||
|
Subroutine
raw: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||
| 155 | 31 | my $self = shift; | |||||||||||
| 156 | 31 | return join '', map { pack( 'a*', $_ ) } @$self; | |||||||||||
| 157 | } | ||||||||||||
| 158 | |||||||||||||
| 159 | |||||||||||||
| 160 | =head2 value | ||||||||||||
| 161 | |||||||||||||
| 162 | $value = $text->value; | ||||||||||||
| 163 | |||||||||||||
| 164 | Character string representation of the text object. | ||||||||||||
| 165 | |||||||||||||
| 166 | =cut | ||||||||||||
| 167 | |||||||||||||
| 168 | 58 | ▶ | sub value { | ||||||||||
|
Subroutine
value: called CC=2 SCAR=6.9
Pod
documented
| |||||||||||||
| 169 | 58 | ▶ | return unless defined wantarray; | ||||||||||
|
Branch: 1 branch
| |||||||||||||
| 170 | 32 | my $self = shift; | |||||||||||
| 171 | 32 | return _decode_utf8( join '', @$self ); | |||||||||||
| 172 | } | ||||||||||||
| 173 | |||||||||||||
| 174 | |||||||||||||
| 175 | =head2 string | ||||||||||||
| 176 | |||||||||||||
| 177 | $string = $text->string; | ||||||||||||
| 178 | |||||||||||||
| 179 | Conditionally quoted RFC1035 zone file representation of the text object. | ||||||||||||
| 180 | |||||||||||||
| 181 | =cut | ||||||||||||
| 182 | |||||||||||||
| 183 | 40 | ▶ | sub string { | ||||||||||
|
Subroutine
string: called CC=2 SCAR=6.9
Pod
documented
| |||||||||||||
| 184 | 40 | my $self = shift; | |||||||||||
| 185 | |||||||||||||
| 186 | 40 | my @s = map { split '', $_ } @$self; # escape special and ASCII non-printable | |||||||||||
| 187 | 40 | my $s = _decode_utf8( join '', map { $escape{$_} } @s ); | |||||||||||
| 188 | 40 | ▶ | return $s =~ /[ \t\n\r\f();]|^$/ ? qq("$s") : $s; # quote special characters and empty string | ||||||||||
|
Branch: 1 branch
| |||||||||||||
| 189 | } | ||||||||||||
| 190 | |||||||||||||
| 191 | |||||||||||||
| 192 | =head2 unicode | ||||||||||||
| 193 | |||||||||||||
| 194 | $string = $text->unicode; | ||||||||||||
| 195 | |||||||||||||
| 196 | Conditionally quoted Unicode representation of the text object. | ||||||||||||
| 197 | |||||||||||||
| 198 | =cut | ||||||||||||
| 199 | |||||||||||||
| 200 | 898 | ▶ | sub unicode { | ||||||||||
|
Subroutine
unicode: called CC=2 SCAR=6.9
Pod
documented
| |||||||||||||
| 201 | 898 | my $self = shift; | |||||||||||
| 202 | |||||||||||||
| 203 | 898 | my @s = map { split '', $_ } @$self; # escape special and non-printable | |||||||||||
| 204 | 898 | my $s = _decode_utf8( join '', map { $escapeUTF8{$_} } @s ); | |||||||||||
| 205 | 898 | ▶ | return $s =~ /[ \t\n\r\f();]|^$/ ? qq("$s") : $s; # quote special characters and empty string | ||||||||||
|
Branch: 1 branch
| |||||||||||||
| 206 | } | ||||||||||||
| 207 | |||||||||||||
| 208 | |||||||||||||
| 209 | ######################################## | ||||||||||||
| 210 | |||||||||||||
| 211 | # perlcc: address of encoding objects must be determined at runtime | ||||||||||||
| 212 | 28 | my $ascii = ASCII ? Encode::find_encoding('ascii') : undef; # Osborn's Law: | |||||||||||
| 213 | 28 | my $utf8 = UTF8 ? Encode::find_encoding('utf8') : undef; # Variables won't; constants aren't. | |||||||||||
| 214 | |||||||||||||
| 215 | |||||||||||||
| 216 | 970 | ▶ | sub _decode_utf8 { ## UTF-8 to perl internal encoding | ||||||||||
|
Subroutine
_decode_utf8: called CC=1 SCAR=0.0
| |||||||||||||
| 217 | 970 | local $_ = shift; | |||||||||||
| 218 | |||||||||||||
| 219 | # partial transliteration for non-ASCII character encodings | ||||||||||||
| 220 | tr | ||||||||||||
| 221 | 970 | [\040-\176\000-\377] | |||||||||||
| 222 | [ !"#$%&'()*+,\-./0-9:;<=>?@A-Z\[\\\]^_`a-z{|}~?] unless ASCII; | ||||||||||||
| 223 | |||||||||||||
| 224 | 970 | my $z = length($_) - length($_); # pre-5.18 taint workaround | |||||||||||
| 225 | 970 | return ASCII ? substr( ( UTF8 ? $utf8 : $ascii )->decode($_), $z ) : $_; | |||||||||||
| 226 | } | ||||||||||||
| 227 | |||||||||||||
| 228 | |||||||||||||
| 229 | 479 | ▶ | sub _encode_utf8 { ## perl internal encoding to UTF-8 | ||||||||||
|
Subroutine
_encode_utf8: called CC=2 SCAR=6.9
| |||||||||||||
| 230 | 479 | local $_ = shift; | |||||||||||
| 231 | 479 | ▶ | croak 'argument undefined' unless defined $_; | ||||||||||
|
Branch: 1 branch
| |||||||||||||
| 232 | |||||||||||||
| 233 | # partial transliteration for non-ASCII character encodings | ||||||||||||
| 234 | tr | ||||||||||||
| 235 | 477 | [ !"#$%&'()*+,\-./0-9:;<=>?@A-Z\[\\\]^_`a-z{|}~] | |||||||||||
| 236 | [\040-\176] unless ASCII; | ||||||||||||
| 237 | |||||||||||||
| 238 | 477 | my $z = length($_) - length($_); # pre-5.18 taint workaround | |||||||||||
| 239 | 477 | return ASCII ? substr( ( UTF8 ? $utf8 : $ascii )->encode($_), $z ) : $_; | |||||||||||
| 240 | } | ||||||||||||
| 241 | |||||||||||||
| 242 | |||||||||||||
| 243 | 28 | %escape = eval { ## precalculated ASCII escape table | |||||||||||
| 244 | 28 | my %table = map { ( chr($_) => chr($_) ) } ( 0 .. 127 ); | |||||||||||
| 245 | |||||||||||||
| 246 | 28 | foreach my $n ( 0 .. 31, 34, 92, 127 .. 255 ) { # numerical escape | |||||||||||
| 247 | 4564 | my $codepoint = sprintf( '%03u', $n ); | |||||||||||
| 248 | |||||||||||||
| 249 | # transliteration for non-ASCII character encodings | ||||||||||||
| 250 | 4564 | $codepoint =~ tr [0-9] [\060-\071]; | |||||||||||
| 251 | |||||||||||||
| 252 | 4564 | $table{chr($n)} = pack 'C a3', 92, $codepoint; | |||||||||||
| 253 | } | ||||||||||||
| 254 | |||||||||||||
| 255 | 28 | return %table; | |||||||||||
| 256 | }; | ||||||||||||
| 257 | |||||||||||||
| 258 | 28 | %escapeUTF8 = eval { ## precalculated UTF-8 escape table | |||||||||||
| 259 | 28 | my @octet = UTF8 ? ( 128 .. 191, 194 .. 254 ) : (); | |||||||||||
| 260 | 28 | return ( %escape, map { ( chr($_) => chr($_) ) } @octet ); | |||||||||||
| 261 | }; | ||||||||||||
| 262 | |||||||||||||
| 263 | |||||||||||||
| 264 | 28 | %unescape = eval { ## precalculated numeric escape table | |||||||||||
| 265 | 28 | my %table; | |||||||||||
| 266 | |||||||||||||
| 267 | 28 | foreach my $n ( 0 .. 255 ) { | |||||||||||
| 268 | 7168 | my $key = sprintf( '%03u', $n ); | |||||||||||
| 269 | |||||||||||||
| 270 | # transliteration for non-ASCII character encodings | ||||||||||||
| 271 | 7168 | $key =~ tr [0-9] [\060-\071]; | |||||||||||
| 272 | |||||||||||||
| 273 | 7168 | $table{$key} = pack 'C', $n; | |||||||||||
| 274 | } | ||||||||||||
| 275 | 28 | $table{"\060\071\062"} = pack 'C2', 92, 92; # escaped escape | |||||||||||
| 276 | |||||||||||||
| 277 | 28 | return %table; | |||||||||||
| 278 | }; | ||||||||||||
| 279 | |||||||||||||
| 280 | |||||||||||||
| 281 | 28 | 1; | |||||||||||
| 282 | __END__ | ||||||||||||