NAME

AmberDB::String - String manipulation, HTML conversion, content detection, and sanitization utility

SYNOPSIS

# 1. Direct usage via AmberDB instance ($adb inherits AmberDB::String):
my $short   = $adb->sub_str($long_text, 50);
my $clean   = $adb->trim_space($raw_text, 1); # flatten newlines
my $html    = $adb->text2html($plain_text);
my $text    = $adb->html2text($html_content);
my $type    = $adb->what_isthis($input_str);  # "email", "phone", "tcno", etc.

# 2. Standalone usage:
use AmberDB::String;
my $str_util = AmberDB::String->new();
my $short    = $str_util->sub_str($long_text, 50);

DESCRIPTION

AmberDB::String provides utility methods for string truncation with word boundary preservation, HTML tag stripping, HTML/entity escaping, bidirectional plain-text/HTML conversion, content type classification (e.g. email, phone, TC identity number, barcodes), and code generation.

Inheritance Note: AmberDB inherits from AmberDB::String (which in turn inherits from AmberDB::Locale). All methods documented below can be invoked directly on any $adb instance (e.g. $adb->sub_str(...)), as well as on standalone AmberDB::String objects.

METHODS

sub_str($string, $length)

Truncates $string to $length characters without breaking words in the middle, appending " ..." to indicate truncation.

my $preview = $adb->sub_str("High performance database engine for Perl", 25);
# => "High performance ..."

short_title($title, [$limit])

Generates an ASCII-clean, sanitized short title suitable for single-line headers or compact UI labels (default limit: 32 chars, minimum: 6 chars). Removes HTML tags and special punctuation before truncating at word boundaries.

my $title = $adb->short_title("Özel Kampanya & İndirimli Ürünler Listesi", 24);
# => "Ozel Kampanya ..."

truncate_text($text, $length)

Strips HTML tags, collapses whitespace via trim_space, and truncates text to $length characters (minimum length: 8 chars), ending cleanly with " ..." at the last complete word boundary.

my $summary = $adb->truncate_text("<p>Detaylı <b>açıklama</b> metni burada yer alır.</p>", 20);
# => "Detayli aciklama ..."

trim_space($string, [$flatten])

Cleans redundant whitespace characters from $string.

• Standard Mode ($flatten = 0 or omitted): Strips leading/trailing spaces and normalizes multiple horizontal spaces, tabs, and newlines while preserving multiline structure.

• Flatten Mode ($flatten = 1): Collapses all whitespace, carriage returns, newlines, and tabs into a single flat space, tightening spaces around commas and semicolons. Ideal for single-line database field storage.

my $flat = $adb->trim_space("  Line 1 \n\n   Line 2  ;  Value  ", 1);
# => "Line 1 Line 2;Value"

remove_tags($data)

Removes HTML tags from $data while converting paragraph (<p>), division (<div>), and line break (<br>) tags into clean newline characters (\n).

my $plain = $adb->remove_tags("<p>Hello<br/>World</p>");
# => "Hello\nWorld"

text2html($text)

Converts plain text into structured HTML. Escapes unsafe characters (&, <, >) for XSS protection, converts double newlines into <p>...</p> paragraphs, and converts single newlines into <br> tags. If input already contains HTML block tags, it is returned intact.

my $html = $adb->text2html("First paragraph.\n\nSecond line 1\nSecond line 2");
# => "<p>First paragraph.</p>\n<p>Second line 1<br>\nSecond line 2</p>"

html2text($html)

Converts HTML formatted content back into plain text. Strips <script> and <style> blocks completely, converts headers and block tags to appropriate line breaks, formats list items with bullet points (- ), decodes common HTML entities, and collapses excessive blank lines.

my $text = $adb->html2text("<h2>Başlık</h2><p>Paragraf 1</p><ul><li>Madde 1</li><li>Madde 2</li></ul>");
# => "Başlık\n\nParagraf 1\n\n- Madde 1\n- Madde 2"

html_ascode($string) / code_ashtml($string)

Encodes sensitive characters (&, ", $, <, >, @) into numeric HTML entities (e.g. &, <, >) to prevent template interpolation or HTML execution while displaying raw source code.

my $safe_code = $adb->html_ascode('my $val = $obj->get("key");');
# => 'my $val = $obj->get("key");'

what_isthis($string)

Inspects $string and automatically determines its logical data type according to pattern rules:

• 'email' — Valid email address pattern.

• 'gsm' — Mobile phone numbers (e.g. +905xxxxxxxxx, 05xxxxxxxxx).

• 'phone' — Landline phone numbers.

• 'tcno' — 11-digit Turkish Republic Citizen ID.

• 'barcode' — 13-digit EAN/UPC barcode numbers (starting with 8 or 9).

• 'number' — Pure positive integer numbers.

• 'domain' — Web domain name pattern (e.g. example.com).

• 'ascii' — Alphanumeric ASCII string without spaces.

• 'letter' — Pure alphabetical letters (locale-aware).

• 'space' — Whitespace-only string.

• 'none' — Undefined or empty string.

• 'other' — Miscellaneous text containing symbols/punctuation.

my $type = $adb->what_isthis("user@example.com"); # "email"
my $type = $adb->what_isthis("05321234567");      # "gsm"
my $type = $adb->what_isthis("12345678901");      # "tcno"

str_code($name)

Generates an 8-character, uppercase, space-padded ASCII code from the first word of $name. Useful for generating short deterministic identifier keys.

my $code = $adb->str_code("Elektronik Ürünler");
# => "ELEKTRON"

AUTHOR

Maruf Cetin <marufcetin@gmail.com>

LICENSE AND COPYRIGHT

Copyright (C) 2017-2026 Maruf Cetin.

This library is free software; you can redistribute it and/or modify it under the terms of the Artistic License 2.0.

cpanm AmberDB

perl -MCPAN -e shell
install AmberDB