NAME

AmberDB::Base - Core serialization, schema resolution, binary packing, file locking, and low-level I/O base class

SYNOPSIS

# Methods are inherited and invoked directly via AmberDB instance ($adb):

# 1. Serialization of flat or nested data
my $raw_line = $adb->db_encode("Title", [ "tag1", "tag2" ], { key => "val" });
my @fields   = $adb->db_decode($raw_line);

# 2. Schema and Path Resolution
my $schema     = $adb->table_info("catalog_product");
my $table_path = $adb->table_path("catalog_product");

# 3. Compact 8-Byte Binary Index Packing
my $binary_blob = $adb->bin_encode([ 101, 102, 103 ], "num");
my ($total_cnt, @ids) = $adb->bin_decode($binary_blob, 0, 20, "asc", "num");

# 4. Table & Record File Locking
$adb->flock_open("orders_cart", "write", $record_id);
# ... critical section ...
$adb->flock_close("orders_cart", $record_id);

DESCRIPTION

AmberDB::Base serves as the foundational layer of AmberDB. It implements flat-file record serialization with nested data support, deterministic schema loading, path mapping based on storage partitions (dbase, year, section, language), compact 8-byte fixed-width binary packing, file locking, and low-level DB_File access.

Inheritance Note: AmberDB inherits directly from AmberDB::Base via use parent. All methods documented below can be invoked on any $adb instance.

TABLE NAMING CONVENTIONS

AmberDB enforces a strict, deterministic table naming convention:

• Format: All table identifiers must be lowercase alphanumeric characters using snake_case, formatted as <database>_<table_name> (e.g. catalog_product, member_address, orders_item).

• Database Prefix: The prefix prior to the first underscore (_) represents the logical database/group schema name (mapped to <database>.dbase).

• Schema Mapping: A table named catalog_product maps to schema file catalog_product.table and database group configuration catalog.dbase.

• Constraint: Uppercase characters or mixed-case identifiers (such as Catalog_Product) are not supported and will fail database group extraction.

METHODS

db_encode(@fields)

Serializes a list of Perl values (scalars, array references, or hash references) into a tab-delimited flat-file line. Nested structures are encoded using internal prefixes (ARRAY:, HASH:) and escaped safely.

my $encoded = $adb->db_encode("101", "Product Name", [ "red", "blue" ], { stock => 5 });

db_decode($record)

Deserializes a tab-delimited flat-file line back into its native Perl data types. In list context, returns a list of fields; in scalar context, returns an array reference (or single field if only one column exists).

my @fields = $adb->db_decode($encoded);

char_escape($str) / char_unescape($str)

Escapes and unescapes structural control characters (tabs, newlines, pipes, equals signs, ampersands, record separators) into safe entity representations.

uri_encode($str) / uri_decode($str)

Percent-encodes and decodes strings for safe inclusion in URLs or HTTP query strings.

my $encoded_url = $adb->uri_encode("search query & params");

key_encode($key)

Transliterates non-alphanumeric characters into clean ASCII characters, stripping illegal symbols to produce safe disk filenames and index keys.

set_charset($from_encoding, $to_encoding, $data)

Transcodes text data between character encodings (e.g. 'iso-8859-9' to 'utf8').

get_words($string, [$action], [$table])

Tokenizes $string into search index keywords, stripping punctuation, applying language-specific stopwords, and normalizing casing.

my %words = $adb->get_words("Kablosuz Kulaklık & Aksesuarlar");

bin_encode(\@record_ids)

Packs a list of record IDs into a compact 8-byte 64-bit unsigned Big-Endian integer binary buffer (Q>).

my $packed_buffer = $adb->bin_encode([ 1, 2, 3 ]);

bin_decode($binary_buffer, [$start], [$limit], [$direction])

Decodes an 8-byte binary buffer (64-bit uint) using O(1) substr byte-offset slicing without unpacking the entire buffer into memory. Returns ($total_count, @slice_ids).

my ($total, @page_ids) = $adb->bin_decode($packed_buffer, 0, 20, 'desc');

table_info($table_id)

Loads and returns the metadata schema hash for the specified table (e.g. catalog_product). Automatically caches loaded schemas in memory.

my $schema = $adb->table_info("catalog_product");

dbase_info($dbase_name)

Loads and returns configuration settings for a logical database group (e.g. catalog).

my $db_cfg = $adb->dbase_info("catalog");

table_path($table_id)

Resolves and returns the full absolute file system path (without file extension) for the target table based on its schema partition rules (dbase, year, section, language).

my $path_prefix = $adb->table_path("catalog_product");

flock_open($table_id, [$mode], [$record_id])

Acquires a file lock on a table or individual record. $mode can be 'write' (exclusive LOCK_EX, default) or 'read' (shared LOCK_SH). Non-blocking; retries with exponential backoff.

$adb->flock_open("catalog_product", "write", 101);

flock_close($table_id, [$record_id])

Releases a table-level or record-level lock previously acquired by flock_open().

$adb->flock_close("catalog_product", 101);

Low-Level Database Accessors

• recs_get($file_path, @keys) — Fetches raw serialized values for given keys from an open DB_File handle.

• recs_put($file_path, @records) — Bulk writes [ $key, $val ] pairs into an open DB_File handle.

• recs_del($file_path, @keys) — Deletes keys from an open DB_File handle.

• recs_keys($file_path) — Retrieves all keys sequentially from an open DB_File handle using C-level cursor iterations.

• recs_scan($file_path, $mode_or_callback) — Scans all entries in sequential order.

• recs_exist($file_path, @keys) — Fast existence check directly on the underlying database file.

AUTHOR

Maruf Cetin <marufcetin@gmail.com>

LICENSE AND COPYRIGHT

Copyright (C) 2014-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