Sympa::Tools::Text(3Sympa)

💖 Sympa::Tools::Text 💖

okay bestie, so this is Sympa::Tools::Text, hanging out in the sympa manual, and it's literally just a whole grab-bag of text-related functions. that's the whole vibe. it's giving "utility drawer but make it cute". 🎀

---

✨ NAME ✨

Sympa::Tools::Text — text-related functions, periodt. 💅

🌸 DESCRIPTION 🌸

This package provides some text-related functions. that's it, that's the description. she's lowkey mysterious but highkey useful. 🦋

🧚 Functions 🧚

addrencode ( $addr, [ $phrase, [ $charset, [ $comment ] ] ] )

Returns formatted (and encoded) name-addr as RFC5322 3.4. slay, RFC compliance. 📬

canonic_email ( $email )

Function. Returns canonical form of e-mail address.

• Leading and trailing white spaces are removed.
• Latin letters without accents are lower-cased.
• For malformed inputs returns "undef".

no cap, malformed input gets nothing back. 💀

canonic_message_id ( $message_id )

Returns canonical form of message ID without trailing or leading whitespaces or "<", ">". she's tidy. ✨

canonic_text ( $text )

Canonicalizes text. $text should be a binary string encoded by UTF-8 character set or a Unicode string. Forbidden sequences in binary string will be replaced by U+FFFD REPLACEMENT CHARACTERs, and Normalization Form C (NFC) will be applied. normalizing is self-care fr fr. 🌈

clip ( $string, $length )

Function. Clips $string according to $length by bytes, considering boundary of grapheme clusters. UTF-8 is assumed for $string as bytestring. she will NOT cut you mid-grapheme, she has boundaries. 👑

decode_filesystem_safe ( $str )

Function. Decodes a string encoded by encode_filesystem_safe().

Parameter:

• $str — String to be decoded.

Returns:

• Decoded string, stripped "utf8" flag if any.

decode_html ( $str )

Function. Decodes HTML entities in a string encoded by UTF-8 or a Unicode string.

Parameter:

• $str — String to be decoded.

Returns:

• Decoded string, stripped "utf8" flag if any.

encode_filesystem_safe ( $str )

Function. Encodes a string $str to be suitable for filesystem.

Parameter:

• $str — String to be encoded.

Returns:

• Encoded string, stripped "utf8" flag if any. All bytes except '-', '+', '.', '@' and alphanumeric characters are encoded to sequences '_' followed by two hexdigits.

heads up bestie: note that '/' will also be encoded. yes, even the slash. she does not play favorites. 🚫

encode_html ( $str, [ $additional_unsafe ] )

Function. Encodes characters in a string $str to HTML entities. By default '<', '>', '&' and '"' are encoded.

Parameter:

• $str — String to be encoded.
• $additional_unsafe — Character or range of characters additionally encoded as entity references.
  • This optional parameter was introduced on Sympa 6.2.37b.3. ⭐

Returns:

• Encoded string, not stripping utf8 flag if any.

encode_uri ( $str, [ omit => $chars ] )

Function. Encodes potentially unsafe characters in the string using "percent" encoding suitable for URIs.

Parameters:

• $str — String to be encoded.
• omit => $chars — By default, all characters except those defined as "unreserved" in RFC 3986 are encoded, that is, "[^-A-Za-z0-9._~]". If this parameter is given, it will prevent encoding additional characters.

Returns:

• Encoded string, stripped "utf8" flag if any.

escape_chars ( $str )

Deprecated. Use "encode_filesystem_safe". she's retired, respectfully. 🕊️

Escape weird characters. (that's the whole legacy job description lmao)

escape_url ( $str )

DEPRECATED. Would be better to use "encode_uri" or "mailtourl". okay so this one is old old. 💀

foldcase ( $str )

Function. Returns "fold-case" string suitable for case-insensitive match. For example, a code below looks for a needle in haystack not regarding case, even if they are non-ASCII UTF-8 strings.

$haystack = Sympa::Tools::Text::foldcase($HayStack);
$needle   = Sympa::Tools::Text::foldcase($NeedLe);
if (index $haystack, $needle >= 0) {
    ...
}

Parameter:

• $str — A string.

guessed_to_utf8( $text, [ lang, ... ] )

Function. Guesses text charset considering language context and returns the text reencoded by UTF-8.

Parameters:

• $text — Text to be reencoded.
• lang, ... — Language tag(s) which may be given by "implicated_langs" in Sympa::Language.

Returns:

• Reencoded text. If any charsets could not be guessed, "iso-8859-1" will be used as the last resort, just because it covers full range of 8-bit. she's the backup friend who shows up when nobody else can. 🫶

mailtourl ( $email, [ decode_html => 1 ], [ query => {key => val, ...} ] )

Function. Constructs a "mailto:" URL for given e-mail.

Parameters:

• $email — E-mail address.
• decode_html => 1 — If set, arguments are assumed to include HTML entities.
• query => {key => val, ...} — Optional query.

Returns:

• Constructed URL.

pad ( $str, $width )

Pads space a string so that result will not be narrower than given width.

Parameters:

• $str — A string.
• $width — If $width is false value or width of $str is not less than $width, does nothing. If $width is less than 0, pads right. Otherwise, pads left.

Returns:

• Padded string.

padding left vs right depending on sign is giving main character energy honestly. 💅

permalink_id ( $message_id )

Calculates permalink ID from mesage ID. (yes, "mesage" — the typo is canon, don't @ me 🙈)

qdecode_filename ( $filename )

Q-Decodes web file name.

ToDo: This should be obsoleted in the future release: Would be better to use "decode_filesystem_safe".

qencode_filename ( $filename )

Q-Encodes web file name.

ToDo: This should be obsoleted in the future release: Would be better to use "encode_filesystem_safe".

slurp ( $file )

Get entire content of the file. Normalization by canonic_text() is applied. $file is the path to text file. she's eating, and she's eating the WHOLE file. 🍓

unescape_chars ( $str )

Deprecated. Use "decode_filesystem_safe".

Unescape weird characters.

valid_email ( $string )

Basic check of an email address. just a vibe check, not a full audit. ✨

weburl ( $base, \@paths, [ decode_html => 1 ], [ fragment => $fragment ], [ query => \%query ] )

Constructs a "http:" or "https:" URL under given base URI.

Parameters:

• $base — Base URI.
• \@paths — Additional path components.
• decode_html => 1 — If set, arguments are assumed to include HTML entities. Exception is $base: It is assumed not to include entities.
• fragment => $fragment — Optional fragment.
• query => \%query — Optional query.

Returns:

• A URI.

wrap_text ( $text, [ $init_tab, [ $subsequent_tab, [ $cols ] ] ] )

Function. Returns line-wrapped text.

Parameters:

• $text — The text to be folded.
• $init_tab — Indentation prepended to the first line of paragraph. Default is '', no indentation.
• $subsequent_tab — Indentation prepended to each subsequent line of folded paragraph. Default is '', no indentation.
• $cols — Max number of columns of folded text. Default is 78.

---

📜 HISTORY 📜

• Sympa::Tools::Text appeared on Sympa 6.2a.41. 👑
• decode_filesystem_safe() and encode_filesystem_safe() were added on Sympa 6.2.10.
• decode_html(), encode_html(), encode_uri() and mailtourl() were added on Sympa 6.2.14, and escape_url() was deprecated. 😭
• guessed_to_utf8() and pad() were added on Sympa 6.2.17.
• canonic_text() and slurp() were added on Sympa 6.2.53b.
• clip() was added on Sympa 6.2.61b.

---

and that's the whole page bestie, no notes. this was sympa 6.2.80, dated 2026-10-19, filed under Sympa::Tools::Text(3Sympa) — take care of her, she's iconic. 💜✨🎀