blib/lib/AmberDB/Base/Schema.pm untested

filter: Statementstmt 0.0% 0 / 622 Branchbran 0.0% 0 / 454 Conditioncond 0.0% 0 / 529 MC/DCmcdc 0.0% 0 / 301 Subroutinesub 0.0% 0 / 27 Podpod 0.0% 0 / 19 totaltotal 0.0% 0 / 1952 CC 228 SCAR 60.8
CC
228
Cov
0%
normalize_blocks
1190.0
table_infset
756.0
table_path
650.0
CRAP 436.6
1 package AmberDB::Base::Schema;
2  
3 use 5.016;
4 use warnings;
5 use Carp qw(croak cluck);
6 use File::Spec;
7 use parent 'AmberDB::Base';
8  
9 our $VERSION = '5.26.6';
10 my $CREATED = '2026-09-06';
11  
12 # Whitelist of inheritable group-level configuration keys from .dbase to member tables
13 our %INHERITABLE_DBASE_KEYS = map { $_ => 1 } qw(
14 use_ramdisk ramdisk_ttl use_cache cache_ttl
15 keep_deleted log_owner use_counter
16 use_section section use_year year
17 use_language lang
18 no_transact no_backup table_dir use_junk
19 use_simple
20 );
21  
22 # =====================================================================
23 # SCHEMA FIELD NORMALIZATION, VALIDATION & TYPE CONVERSION
24 # =====================================================================
25  
26 # Normalizes and validates a single field value according to schema block definition.
27 # Usage:
28 # my $clean_val = $adb->enc_field($blk_def, $val);
29 # ------------------------------------------------
30 sub enc_field {
31 my ( $self, $blk, $val ) = @_;
32  
33 if ( $blk && ref($blk) eq 'HASH' ) {
34 my $type = lc( $blk->{type} // 'text' );
35 my $valid = lc( $blk->{valid} // '' );
36  
37 # 1. Type: number / num (integer, float, negative support)
38 if ( $type eq 'num' || $type eq 'number' || $type eq 'numeric' || $type eq 'int' || $type eq 'float' || $type eq 'decimal' ) {
39 if ( defined $val && length("$val") ) {
40 ( my $trimmed = "$val" ) =~ s/^\s+|\s+$//g;
41 if ( $trimmed =~ /^[+-]?[0-9]+(?:\.[0-9]+)?$/ ) {
42 $val = 0 + $trimmed;
43 }
44 else {
45 $val = 0;
46 }
47 }
48 else {
49 $val = 0;
50 }
51 }
52 # 2. Type: ascii
53 elsif ( $type eq 'ascii' ) {
54 if ( defined $val && length("$val") ) {
55 $val = $self->to_ascii("$val");
56 }
57 else {
58 $val = '';
59 }
60 }
61 # 3. Type: date
62 elsif ( $type eq 'date' || $type eq 'datetime' || $type eq 'date_short' || $type eq 'date_long' ) {
63 if ( ( !defined $val || $val eq '' ) && $valid =~ /auto_date/ ) {
64 my $y = $self->year;
65 my $m = $self->month;
66 my $d = $self->day;
67 $val = "$y-$m-$d";
68 }
69 else {
70 $val //= '';
71 }
72 }
73 # 4. Type: array / repeat / loop
74 elsif ( $type eq 'array' || $type eq 'list' || $type eq 'repeat' || $type eq 'repeats' || $type eq 'loop' ) {
75 if ( defined $val ) {
76 if ( ref($val) eq 'ARRAY' ) {
77 # ok
78 }
79 elsif ( ref($val) ) {
80 $val = [$val];
81 }
82 elsif ( length("$val") ) {
83 $val = [ split /[,|]/, "$val" ];
84 }
85 else {
86 $val = [];
87 }
88 }
89 else {
90 $val = [];
91 }
92 }
93 # 5. Type: hash
94 elsif ( $type eq 'hash' || $type eq 'dict' || $type eq 'json' ) {
95 if ( defined $val && ref($val) eq 'HASH' ) {
96 # ok
97 }
98 else {
99 $val = {};
100 }
101 }
102 # 6. Type: text / string
103 elsif ( $type eq 'text' || $type eq 'string' || $type eq 'tinytext' || $type eq 'html' ) {
104 $val //= '';
105 }
106 # 7. Type: binary / base64
107 elsif ( $type eq 'binary' || $type eq 'base64' ) {
108 $val //= '';
109 }
110 # 8. Type: auto_id
111 elsif ( $type eq 'auto_id' || $type eq 'autoid' ) {
112 # auto_id is handled by table_autoid
113 }
114 }
115  
116 return $val;
117 }
118  
119 # Normalizes and validates field values according to schema block definitions prior to encoding/writing.
120 # Usage:
121 # my @clean_fields = $adb->enc_validate($tableid, \@fields, $has_id);
122 # ------------------------------------------------
123 sub enc_validate {
124 my ( $self, $tableid, $fields_ref, $has_id ) = @_;
125  
126 return wantarray ? () : [] unless defined $fields_ref;
127 my @fields = ( ref($fields_ref) eq 'ARRAY' ) ? @$fields_ref : ($fields_ref);
128 return wantarray ? @fields : \@fields unless @fields;
129  
130 # Bypass in simple mode or when no tableid is given
131 return wantarray ? @fields : \@fields
132 if $self->config('use_simple') || !defined $tableid || $tableid eq '';
133  
134 my $table_info = $self->table_info($tableid);
135 return wantarray ? @fields : \@fields
136 unless $table_info && ref( $table_info->{blocks} ) eq 'ARRAY' && @{ $table_info->{blocks} };
137  
138 my $blocks = $table_info->{blocks};
139 my @cleaned;
140  
141 for ( my $i = 0 ; $i < @fields ; $i++ ) {
142 my $blk_idx = $has_id ? $i : ( $i + 1 );
143 my $blk = $blocks->[$blk_idx];
144 if ( !$blk && $table_info->{repeat_start} && $blk_idx >= $table_info->{repeat_start} ) {
145 $blk = $blocks->[ $table_info->{repeat_start} ] // $blocks->[-1];
146 }
147 push @cleaned, $self->enc_field( $blk, $fields[$i] );
148 }
149  
150 return wantarray ? @cleaned : \@cleaned;
151 }
152  
153 # Normalizes and casts a single field value according to schema block definition upon decoding/reading.
154 # Usage:
155 # my $decoded_val = $adb->dec_field($blk_def, $val);
156 # ------------------------------------------------
157 sub dec_field {
158 my ( $self, $blk, $val ) = @_;
159  
160 if ( $blk && ref($blk) eq 'HASH' ) {
161 my $type = lc( $blk->{type} // 'text' );
162  
163 # 1. Type: number / num -> Ensure numeric scalar (0 + $val)
164 if ( $type eq 'num' || $type eq 'number' || $type eq 'numeric' || $type eq 'int' || $type eq 'float' || $type eq 'decimal' ) {
165 if ( defined $val && length("$val") ) {
166 ( my $trimmed = "$val" ) =~ s/^\s+|\s+$//g;
167 if ( $trimmed =~ /^[+-]?[0-9]+(?:\.[0-9]+)?$/ ) {
168 $val = 0 + $trimmed;
169 }
170 else {
171 $val = 0;
172 }
173 }
174 else {
175 $val = 0;
176 }
177 }
178 # 2. Type: array / repeat / loop -> Ensure ARRAY ref
179 elsif ( $type eq 'array' || $type eq 'list' || $type eq 'repeat' || $type eq 'repeats' || $type eq 'loop' ) {
180 if ( !defined $val ) {
181 $val = [];
182 }
183 elsif ( ref($val) ne 'ARRAY' ) {
184 $val = length("$val") ? [ split /[,|]/, "$val" ] : [];
185 }
186 }
187 # 3. Type: hash -> Ensure HASH ref
188 elsif ( $type eq 'hash' || $type eq 'dict' || $type eq 'json' ) {
189 if ( !defined $val || ref($val) ne 'HASH' ) {
190 $val = {};
191 }
192 }
193 # 4. Text / ASCII / Date / Binary
194 else {
195 $val //= '';
196 }
197 }
198  
199 return $val;
200 }
201  
202 # Normalizes and casts field values according to schema block definitions upon decoding/reading.
203 # Usage:
204 # my @decoded_fields = $adb->dec_validate($tableid, \@fields, $has_id);
205 # ------------------------------------------------
206 sub dec_validate {
207 my ( $self, $tableid, $fields_ref, $has_id ) = @_;
208  
209 return wantarray ? () : [] unless defined $fields_ref;
210 my @fields = ( ref($fields_ref) eq 'ARRAY' ) ? @$fields_ref : ($fields_ref);
211 return wantarray ? @fields : \@fields unless @fields;
212  
213 # Bypass in simple mode or when no tableid is given
214 return wantarray ? @fields : \@fields
215 if $self->config('use_simple') || !defined $tableid || $tableid eq '';
216  
217 my $table_info = $self->table_info($tableid);
218 return wantarray ? @fields : \@fields
219 unless $table_info && ref( $table_info->{blocks} ) eq 'ARRAY' && @{ $table_info->{blocks} };
220  
221 my $blocks = $table_info->{blocks};
222 my @cleaned;
223  
224 for ( my $i = 0 ; $i < @fields ; $i++ ) {
225 my $blk_idx = $has_id ? $i : ( $i + 1 );
226 my $blk = $blocks->[$blk_idx];
227 if ( !$blk && $table_info->{repeat_start} && $blk_idx >= $table_info->{repeat_start} ) {
228 $blk = $blocks->[ $table_info->{repeat_start} ] // $blocks->[-1];
229 }
230 push @cleaned, $self->dec_field( $blk, $fields[$i] );
231 }
232  
233 return wantarray ? @cleaned : \@cleaned;
234 }
235  
236 # =====================================================================
237 # TABLE SANITIZATION & SCHEMA ARGUMENTS
238 # =====================================================================
239  
240 # Sanitizes table/file identifier.
241 # Allows subdirectories and dots (e.g. 'uyeler/bekleyen.uyeler', '/.dosya')
242 # Strictly strips path traversal segments ('..', '.', './', '.\', '../', '..\')
243 # ------------------------------------------------
244 sub sanitize_table {
245 my ( $self, $table ) = @_;
246 return "" unless defined $table && length $table;
247  
248 # 1. Normalize backslashes to forward slashes
249 $table =~ s/\\/\//g;
250  
251 # 2. Strip database extension if present at end
252 my $ext = $self->{db_ext} // "db";
253 $table =~ s/\.\Q$ext\E$//;
254  
255 # 3. Filter allowed characters: alphanumeric, underscore, dot, hyphen, slash
256 $table =~ s/[^\w\.\-\/]+//g;
257  
258 # 4. Collapse multiple consecutive slashes
259 $table =~ s{/+}{/}g;
260  
261 # 5. Remove path traversal components: split into segments and filter out '.' and '..'
262 my @clean_segments;
263 foreach my $seg ( split m{/}, $table ) {
264 next if $seg eq '' || $seg eq '.' || $seg eq '..';
265 push @clean_segments, $seg;
266 }
267  
268 return join( '/', @clean_segments );
269 }
270  
271 # ($id, $path) = $self->schema_arg($arg, "table"|"dbase")
272 # ------------------------------------------------
273 sub schema_arg {
274 my ( $self, $arg, $ext ) = @_;
275 return ( "", "" ) unless defined $arg && length $arg;
276  
277 if ( $arg =~ m{[\\/]|\.${ext}$} ) {
278 ( my $id = $arg ) =~ s{.+[\\/]([^\\/]+?)(?:\.${ext})?$}{$1};
279 $id = $self->sanitize_table($id);
280 return ( $id, $arg );
281 }
282 my $clean = $self->sanitize_table($arg);
283 my $schema_dir = $self->path('schema_dir')
284 || ( $self->path('dbase_dir') ? $self->path('dbase_dir') . "/schema" : "schema" );
285 return ( $clean, "$schema_dir/$clean.$ext" );
286 }
287  
288 # =====================================================================
289 # SCHEMA LOADERS, ATTRIBUTES & WRITERS
290 # =====================================================================
291  
292 # Safely evaluates a Perl schema definition file via `do`.
293 # Normalizes paths, catches syntax errors and verifies hash structure.
294 # ---------------------------------------------------------------------------
295 sub do_schema {
296 my ( $self, $path ) = @_;
297 return unless defined $path && length $path && -f $path;
298  
299 $path =~ s{\\}{/}g;
300 $path = "./$path" unless $path =~ m{^(?:\./|/|[a-zA-Z]:)};
301  
302 my $data = eval { do $path };
303 if ($@) {
304 cluck "[AMBERDB_SCHEMA] Syntax error in schema file '$path': $@\n";
305 return undef;
306 }
307  
308 return ( ref($data) eq 'HASH' ) ? $data : undef;
309 }
310  
311 # Retrieves database group schema definition.
312 # my $dbase_info = $adb->dbase_info($dbase);
313 # ------------------------------------------------
314 sub dbase_info {
315 my ( $self, $arg ) = @_;
316  
317 return unless $arg;
318 my ( $dbase, $dbase_path ) = $self->schema_arg( $arg, "dbase" );
319  
320 return $self->{_dbase}->{$dbase}
321 if $self->{_dbase}->{$dbase} && %{ $self->{_dbase}->{$dbase} };
322  
323 my $ramdisk_schema = $self->{_path}->{schema_rdir} || $self->path('schema_rdir');
324 my $target_path = $dbase_path;
325 if ( $ramdisk_schema && -e "$ramdisk_schema/$dbase.dbase" ) {
326 $target_path = "$ramdisk_schema/$dbase.dbase";
327 }
328  
329 if ( my $do_data = $self->do_schema($target_path) ) {
330 $do_data->{name} = $self->utf_decode( $do_data->{name} ) if defined $do_data->{name};
331 $self->{_dbase}->{$dbase} = $do_data;
332 if ( $ramdisk_schema && !-e "$ramdisk_schema/$dbase.dbase" && $self->dir_exist($ramdisk_schema) ) {
333 require File::Copy;
334 eval { File::Copy::copy( $dbase_path, "$ramdisk_schema/$dbase.dbase" ) };
335 }
336 }
337  
338 return $self->{_dbase}->{$dbase};
339 }
340  
341 # Applies inherited configuration from the database group (.dbase) to a table schema.
342 # Only copies whitelisted keys (%INHERITABLE_DBASE_KEYS) that are not already defined
343 # on the table schema (preserving table-level overrides).
344 sub _apply_dbase_inheritance {
345 my ( $self, $table, $schema ) = @_;
346  
347 return unless ref($schema) eq 'HASH';
348  
349 my $dbase = $schema->{dbase};
350 if ( !defined $dbase || !length $dbase ) {
351 my $t = defined $table ? $table : ( $schema->{table} // '' );
352 ($dbase) = ( $t =~ /^([a-z0-9]+)_/i );
353 $dbase //= "";
354 }
355 return unless length $dbase;
356  
357 my $dbase_info = $self->dbase_info($dbase);
358 return unless $dbase_info && ref($dbase_info) eq 'HASH';
359  
360 for my $key ( keys %INHERITABLE_DBASE_KEYS ) {
361 if ( exists $dbase_info->{$key} && !exists $schema->{$key} ) {
362 $schema->{$key} = $dbase_info->{$key};
363 }
364 }
365 }
366  
367 # ============================================================================
368 # TABLE SCHEMA NORMALIZATION & VALIDATION PIPELINE
369 # Normalizes, converts, and validates table schema definitions through an ordered
370 # rule pipeline. Ensures consistent in-memory structures across disk loading,
371 # table_attr, and table_infset.
372 # Usage:
373 # $adb->normalize_blocks($table, $schema_hashref);
374 # ============================================================================
375 sub normalize_blocks {
376 my ( $self, $table, $schema ) = @_;
377  
378 return {} unless ref($schema) eq 'HASH';
379  
380 # ------------------------------------------------------------------------
381 # Pipeline Step 0: Table Identity & Metadata
382 # Ensure table name and database group are present in schema.
383 # ------------------------------------------------------------------------
384 if ( defined $table && length $table ) {
385 $schema->{table} = $table unless defined $schema->{table} && length $schema->{table};
386 my ($dbase) = ( $table =~ /^([a-z0-9]+)_/i );
387 $dbase //= "";
388 $schema->{dbase} = $dbase unless defined $schema->{dbase} && length $schema->{dbase};
389 }
390  
391 # Normalize UTF-8 characters on schema identity and block definitions
392 $schema->{name} = $self->utf_decode( $schema->{name} ) if defined $schema->{name};
393 if ( ref( $schema->{blocks} ) eq 'ARRAY' ) {
394 for my $b ( @{ $schema->{blocks} } ) {
395 next unless ref($b) eq 'HASH';
396 for my $k (qw(name option valid)) {
397 $b->{$k} = $self->utf_decode( $b->{$k} ) if defined $b->{$k};
398 }
399 }
400 }
401 if ( ref( $schema->{facet_block} ) eq 'ARRAY' ) {
402 for my $fb ( @{ $schema->{facet_block} } ) {
403 next unless ref($fb) eq 'HASH';
404 for my $k (qw(label name title)) {
405 $fb->{$k} = $self->utf_decode( $fb->{$k} ) if defined $fb->{$k};
406 }
407 }
408 }
409  
410 # ------------------------------------------------------------------------
411 # Pipeline Step 0b: Dbase Schema Group Inheritance
412 # Inherit whitelisted operational flags from .dbase if not overridden.
413 # ------------------------------------------------------------------------
414 $self->_apply_dbase_inheritance( $table, $schema );
415  
416 # ------------------------------------------------------------------------
417 # Pipeline Step 1: Global Configuration Inheritance
418 # ------------------------------------------------------------------------
419 if ( defined $schema->{use_ramdisk} ) {
420 $schema->{use_ramdisk} = $self->_normalize_ramdisk_tier( $schema->{use_ramdisk} );
421 }
422 elsif ( !defined $schema->{use_cache} ) {
423 my $global_ram = $self->config('use_ramdisk');
424 $global_ram = $self->_normalize_ramdisk_tier($global_ram);
425 $global_ram = 0 if $global_ram == 3;
426 $schema->{use_ramdisk} = $global_ram;
427 }
428  
429 # ------------------------------------------------------------------------
430 # Pipeline Step 1b: Volatile RAM-Disk Tier 3 Stripping
431 # If use_ramdisk == 3, table is pure volatile key-value store on RAM-disk.
432 # Strip all indexing, columnar, facet, and relational definitions.
433 # ------------------------------------------------------------------------
434 if ( ( $schema->{use_ramdisk} // 0 ) == 3 ) {
435 delete @{$schema}{
436 qw(
437 blocks match_block search_block view_block facet_block filter_block
438 suggest_block suggest_join
439 slug_block sort_block sort_fields use_facet facet_rules use_junk junk_rules
440 record_index repeat_start repeat_ids field_rules keep_deleted
441 )
442 };
443 $schema->{use_simple} = 1;
444 $schema->{no_backup} = 1;
445 $schema->{no_transact} = 1;
446 $schema->{ramdisk_ttl} = 300 unless defined $schema->{ramdisk_ttl};
447 }
448  
449 # ------------------------------------------------------------------------
450 # Pipeline Step 2: Simple Mode Stripping
451 # In simple key-value mode, selectively strip columnar, indexing, relational,
452 # and caching definitions to enforce lightweight operation.
453 # ------------------------------------------------------------------------
454 if ( $schema->{use_simple} && ( $schema->{use_ramdisk} // 0 ) != 3 ) {
455 delete @{$schema}{
456 qw(
457 blocks match_block search_block view_block facet_block filter_block
458 suggest_block suggest_join
459 slug_block sort_block sort_fields use_facet facet_rules use_junk junk_rules
460 record_index repeat_start repeat_ids field_rules
461 use_ramdisk ramdisk_ttl use_cache cache_ttl
462 )
463 };
464 return $schema;
465 }
466  
467 # ------------------------------------------------------------------------
468 # Pipeline Step 3: RAM-Disk Environment & Mount Verification
469 # If RAM-disk is not physically mounted or ready, strip use_ramdisk.
470 # The existence of $schema->{use_ramdisk} is a guaranteed contract of readiness.
471 # ------------------------------------------------------------------------
472 unless ( $self->ramdisk_is_mounted() ) {
473 delete $schema->{use_ramdisk};
474 delete $schema->{use_cache};
475 }
476  
477 # ------------------------------------------------------------------------
478 # Pipeline Step 4: Blocks & Relational Foreign Keys (RDBM) Normalization
479 # Converts string RDBM definitions like:
480 # "catalog_category,2", "catalog_category;2", "catalog_category|2", "catalog_category:2"
481 # into canonical hashref: { table => "catalog_category", display => 2 }
482 # ------------------------------------------------------------------------
483 if ( exists $schema->{blocks} ) {
484 if ( ref( $schema->{blocks} ) eq 'ARRAY' ) {
485 foreach my $block ( @{ $schema->{blocks} } ) {
486 $self->normalize_rdbm($block) if ref($block) eq 'HASH';
487 }
488 }
489 elsif ( ref( $schema->{blocks} ) eq 'HASH' ) {
490 foreach my $key ( keys %{ $schema->{blocks} } ) {
491 my $block = $schema->{blocks}->{$key};
492 $self->normalize_rdbm($block) if ref($block) eq 'HASH';
493 }
494 }
495 }
496  
497 # ------------------------------------------------------------------------
498 # Pipeline Step 4b: Precompute _has_schema and _block_keys for high-performance lookup
499 # ------------------------------------------------------------------------
500 if ( exists $schema->{blocks} && ref( $schema->{blocks} ) eq 'ARRAY' && @{ $schema->{blocks} } ) {
501 $schema->{_has_schema} = 1;
502 my %b_keys;
503 for my $idx ( 0 .. $#{ $schema->{blocks} } ) {
504 my $b = $schema->{blocks}->[$idx];
505 $b_keys{$idx} = 1;
506 if ( ref($b) eq 'HASH' ) {
507 my $name = $b->{name};
508 my $id = $b->{id};
509 $b_keys{ lc($name) } = 1 if defined $name;
510 $b_keys{ lc($id) } = 1 if defined $id;
511  
512 # Plural and singular aliases for repeating blocks
513 if ( defined $name ) {
514 $b_keys{ lc("${name}s") } = 1;
515 $b_keys{ lc($1) } = 1 if $name =~ /^(.+)s$/i;
516 }
517 if ( defined $id && ( !defined $name || $id ne $name ) ) {
518 $b_keys{ lc("${id}s") } = 1;
519 $b_keys{ lc($1) } = 1 if $id =~ /^(.+)s$/i;
520 }
521 }
522 }
523 $b_keys{repeat} = 1 if $schema->{repeat_start};
524 $b_keys{repeats} = 1 if $schema->{repeat_start};
525 $schema->{_block_keys} = \%b_keys;
526 }
527 else {
528 $schema->{_has_schema} = 0;
529 $schema->{_block_keys} = {};
530 }
531  
532 # ------------------------------------------------------------------------
533 # Pipeline Step 5: (Future Schema Rules / Extensions)
534 # Alanları ve sınırları belirlenmiş yeni şema kuralları buraya eklenebilir.
535 # ------------------------------------------------------------------------
536  
537 return $schema;
538 }
539  
540 # Normalizes rdbm definition within a block into canonical { table => $t, display => $d }
541 sub normalize_rdbm {
542 my ( $self, $block ) = @_;
543 return unless ref($block) eq 'HASH';
544  
545 return unless defined $block->{rdbm} && $block->{rdbm} ne '';
546  
547 # Case A: Already a hashref { table => '...', display => ... }
548 if ( ref( $block->{rdbm} ) eq 'HASH' ) {
549 my $t = $block->{rdbm}->{table};
550 my $d = $block->{rdbm}->{display};
551 $t = defined $t ? "$t" : "";
552 $t =~ s/^\s+|\s+$//g;
553 $d = ( defined $d && $d =~ /^\d+$/ ) ? int($d) : ( defined $block->{display} && $block->{display} =~ /^\d+$/ ? int($block->{display}) : 1 );
554 $block->{rdbm} = {
555 table => $t,
556 display => $d,
557 };
558 return;
559 }
560  
561 # Case B: String format like "catalog_category,2", "catalog_category;2", "catalog_category|2", "catalog_category:2"
562 if ( !ref( $block->{rdbm} ) ) {
563 my $raw = "$block->{rdbm}";
564 $raw =~ s/^\s+|\s+$//g;
565 if ( !length $raw ) {
566 delete $block->{rdbm};
567 return;
568 }
569  
570 # Split on comma, semicolon, pipe, or colon (, ; | :)
571 my ( $t, $d ) = split( /[,;:|]/, $raw, 2 );
572 $t =~ s/^\s+|\s+$//g if defined $t;
573 $d =~ s/^\s+|\s+$//g if defined $d;
574  
575 if ( defined $t && length $t ) {
576 my $disp = ( defined $d && $d =~ /^\d+$/ )
577 ? int($d)
578 : ( defined $block->{display} && $block->{display} =~ /^\d+$/
579 ? int( $block->{display} )
580 : 1 );
581 $block->{rdbm} = {
582 table => $t,
583 display => $disp,
584 };
585 }
586 else {
587 delete $block->{rdbm};
588 }
589 }
590 }
591  
592 # my $table_info = $adb->table_info($table_id);
593 # ------------------------------------------------
594 sub table_info {
595 my ( $self, $arg ) = @_;
596  
597 return {} unless $arg;
598 return {} if $self->config('use_simple');
599  
600 my ( $table, $table_path ) = $self->schema_arg( $arg, "table" );
601 $table && $table_path or return {};
602  
603 if ( $self->{_table}->{$table} && %{ $self->{_table}->{$table} } ) {
604 return { %{ $self->{_table}->{$table} } };
605 }
606  
607 my ($dbase) = ( $table =~ /^([a-z0-9]+)_/i );
608 $dbase //= "";
609  
610 my $ramdisk_schema = $self->path('schema_rdir');
611 my $target_path = $table_path;
612 if ( $ramdisk_schema && -e "$ramdisk_schema/$table.table" ) {
613 if ( -e $table_path && ( ( stat($table_path) )[9] > ( stat("$ramdisk_schema/$table.table") )[9] ) ) {
614 require File::Copy;
615 eval { File::Copy::copy( $table_path, "$ramdisk_schema/$table.table" ) };
616 }
617 $target_path = "$ramdisk_schema/$table.table";
618 }
619  
620 if ( my $do_data = $self->do_schema($target_path) ) {
621 $self->normalize_blocks( $table, $do_data );
622 $self->{_table}->{$table} = $do_data;
623  
624 if ( $ramdisk_schema && !-e "$ramdisk_schema/$table.table" && $self->dir_exist($ramdisk_schema) ) {
625 require File::Copy;
626 eval { File::Copy::copy( $table_path, "$ramdisk_schema/$table.table" ) };
627 }
628 if ( $do_data->{use_ramdisk} ) {
629 $do_data->{_ramdisk_ensured} = 1;
630 $self->ramdisk_ensure($table);
631 }
632 }
633 else {
634 my $schema = $self->{_table}->{$table} ||= {};
635 $self->normalize_blocks( $table, $schema );
636 $self->{_table}->{$table} = $schema;
637 if ( $schema->{use_ramdisk} && !$schema->{_ramdisk_ensured} ) {
638 $schema->{_ramdisk_ensured} = 1;
639 $self->ramdisk_ensure($table);
640 }
641 }
642  
643 if ( $self->{_table}->{$table} && %{ $self->{_table}->{$table} } ) {
644 $self->{_table}->{$table}->{table} //= $table;
645 $self->{_table}->{$table}->{dbase} //= $dbase if $dbase;
646  
647 $self->dbase_info($dbase) if $dbase;
648  
649 return { %{ $self->{_table}->{$table} } };
650 }
651  
652 return {};
653 }
654  
655 # Checks if a table has defined schema blocks (.table file with blocks).
656 # Pure O(1) in-memory cache lookup.
657 # ------------------------------------------------
658 sub has_schema {
659 my ( $self, $tableid ) = @_;
660 return 0 unless defined $tableid && length $tableid;
661  
662 $self->table_info($tableid);
663 my $tbl_cache = $self->{_table}->{$tableid};
664  
665 return ( $tbl_cache && $tbl_cache->{_has_schema} ) ? 1 : 0;
666 }
667  
668 # Checks if a given hash structure matches the schema defined in table_info.
669 # Returns 1 if table has a schema AND hash contains valid schema block keys.
670 # Returns 0 immediately if table has no schema OR if ANY key does not belong to schema.
671 # Short-circuits on the very first unmatched key with zero allocation.
672 # ------------------------------------------------
673 sub schema_matches_hash {
674 my ( $self, $tableid, $hash ) = @_;
675  
676 return 0 unless defined $tableid && length $tableid;
677 return 0 unless ref($hash) eq 'HASH' && %$hash;
678  
679 my $tbl_cache = $self->{_table}->{$tableid};
680 if ( !$tbl_cache || !exists $tbl_cache->{_has_schema} ) {
681 $self->table_info($tableid);
682 $tbl_cache = $self->{_table}->{$tableid};
683 }
684  
685 # Fast short-circuit: table without schema cannot match
686 return 0 unless $tbl_cache && $tbl_cache->{_has_schema};
687  
688 my $known_keys = $tbl_cache->{_block_keys};
689 return 0 unless $known_keys && %$known_keys;
690  
691 # Immediate rejection loop: If ANY key does NOT belong to the schema, exit immediately!
692 my $has_field = 0;
693 for my $k ( keys %$hash ) {
694 my $lc_k = lc($k);
695 next if $lc_k eq 'id' || $lc_k eq '0';
696 return 0 unless $known_keys->{$lc_k};
697 $has_field = 1;
698 }
699  
700 return $has_field || exists $hash->{id} || exists $hash->{ID} || exists $hash->{0} ? 1 : 0;
701 }
702  
703 # my $table_path = $adb->table_path($table);
704 # ------------------------------------------------
705 sub table_path {
706 my ( $self, $table, $with_ext ) = @_;
707  
708 $table = $self->sanitize_table($table);
709 return "" unless defined $table && length $table;
710  
711 # return if processed earlier and still exists on disk
712 if ( $self->{_table}->{$table}->{_path} ) {
713 my $ext = $self->{db_ext} || "db";
714 if ( -e ( $self->{_table}->{$table}->{_path} . ".$ext" ) ) {
715 return $self->{_table}->{$table}->{_path} . ($with_ext ? ".$ext" : "");
716 }
717 delete $self->{_table}->{$table}->{_path};
718 }
719  
720 # load table info first
721 my $table_info = $self->table_info($table);
722  
723 # Volatile RAM-Disk Tier 3: table lives strictly on RAM-disk
724 if ( $table_info && ( $table_info->{use_ramdisk} // 0 ) == 3 && $self->ramdisk_is_mounted() ) {
725 my $target = $self->ramdisk_path($table);
726 $self->{_table}->{$table}->{_path} = $target;
727 return $target . ( $with_ext ? ".$self->{db_ext}" : "" );
728 }
729  
730 # set simple mode if DATADIR directory does not exist
731 if ( !$self->dir_exist( $self->path('dbase_dir') ) ) {
732 $self->config( use_simple => 1 );
733 }
734  
735 # return table path if simple mode
736 if ( $self->config('use_simple') ) {
737 my $target = ( $self->path('dbase_dir') || "." ) . "/$table";
738 my ($parent_dir) = $target =~ m{^(.+)[/\\][^/\\]+$};
739 if ( $parent_dir && !$self->dir_exist($parent_dir) ) {
740 croak "[AMBERDB_FATAL] Database directory '$parent_dir' does not exist for table '$table'";
741 }
742 $self->{_table}->{$table}->{_path} = $target;
743 return $target . ($with_ext ? ".$self->{db_ext}" : "");
744 }
745  
746 # set path value
747 my $dbase_dir = $self->path('dbase_dir') || ".";
748  
749 my ($dbase) = ( $table =~ /^([a-z0-9]+)_/i );
750 $dbase //= "";
751  
752 # if root dbase
753 if ( $self->{_dbase}->{$dbase}->{root} ) {
754 my $target = ( $self->path('dbase_dir') || "." ) . "/$table";
755 my ($parent_dir) = $target =~ m{^(.+)[/\\][^/\\]+$};
756 if ( $parent_dir && !$self->dir_exist($parent_dir) ) {
757 croak "[AMBERDB_FATAL] Database directory '$parent_dir' does not exist for table '$table'";
758 }
759 $self->{_table}->{$table}->{_path} = $target;
760 return $self->{_table}->{$table}->{_path} . ($with_ext ? ".$self->{db_ext}" : "");
761 }
762  
763 if ( $table_info && exists $table_info->{table_dir} ) {
764 my $tdir = $table_info->{table_dir} // '';
765 if ( $tdir ) {
766 $tdir =~ s{^[\\/]+|[\\/]+$}{}g;
767 $dbase_dir .= "/$tdir";
768 }
769 # if length $tdir == 0 (table_dir => ''), overwrite default: keep $dbase_dir directly
770 }
771 else {
772 # if using year
773 my $yeardir;
774 if (
775 $self->config('use_year')
776 and ( $self->{_dbase}->{$dbase}->{year}
777 or $self->{_table}->{$table}->{year} )
778 )
779 {
780 $yeardir = $self->path('year_dir') || $self->year;
781 }
782 else {
783 delete( $self->{_dbase}->{$dbase}->{year} )
784 if ( $self->{_dbase}->{$dbase}->{year} );
785  
786 delete( $self->{_table}->{$table}->{year} )
787 if ( $self->{_table}->{$table}->{year} );
788 $yeardir = "table";
789 }
790 $dbase_dir .= "/$yeardir" if $yeardir;
791  
792 # if using section
793 if (
794 $self->config('use_section')
795 and ( $self->{_dbase}->{$dbase}->{section}
796 or $self->{_table}->{$table}->{section} )
797 ) {
798 my $section = $self->{_table}->{$table}->{section} || $self->config('section') || "center";
799 $dbase_dir .= "_$section";
800 }
801  
802 # if using language
803 if (
804 $self->config('use_language') and
805 ( $self->{_dbase}->{$dbase}->{lang} ||
806 $self->{_table}->{$table}->{lang} )
807 ) {
808 my $lang = $self->{_dbase}->{$dbase}->{lang} ||
809 $self->{_table}->{$table}->{lang} // "";
810  
811 $dbase_dir .= "_$lang";
812 }
813 }
814  
815 unless ( $self->dir_exist($dbase_dir) ) {
816 if ( $table_info && exists $table_info->{table_dir} ) {
817 $self->make_path($dbase_dir);
818 }
819 else {
820 croak "[AMBERDB_FATAL] Database directory '$dbase_dir' does not exist for table '$table'";
821 }
822 }
823  
824 my $target = "$dbase_dir/$table";
825 $self->{_table}->{$table}->{_path} = $target;
826  
827 return $self->{_table}->{$table}->{_path} . ($with_ext ? ".$self->{db_ext}" : "");
828 }
829  
830 # my $attrs = $adb->table_attr($table);
831 # ------------------------------------------------
832 sub table_attr {
833 my ( $self, $table, @args ) = @_;
834  
835 $table = $self->sanitize_table($table);
836 return unless defined $table && length $table;
837  
838 # Ensure full table schema is loaded before querying or modifying attributes
839 unless ( $self->{_table}->{$table} && $self->{_table}->{$table}->{_has_schema} ) {
840 $self->table_info($table);
841 }
842  
843 # 1. No extra arguments: return shallow copy of table attributes
844 if ( !@args ) {
845 unless ( $self->ramdisk_is_mounted() ) {
846 delete $self->{_table}->{$table}->{use_ramdisk};
847 delete $self->{_table}->{$table}->{use_cache};
848 }
849 return { %{ $self->{_table}->{$table} || {} } };
850 }
851  
852 # 2. Single scalar argument: getter -> $adb->table_attr($table, 'use_simple')
853 if ( @args == 1 && !ref( $args[0] ) ) {
854 if ( ( $args[0] eq 'use_ramdisk' || $args[0] eq 'use_cache' ) && !$self->ramdisk_is_mounted() ) {
855 delete $self->{_table}->{$table}->{use_ramdisk};
856 delete $self->{_table}->{$table}->{use_cache};
857 return undef;
858 }
859 return $self->{_table}->{$table}->{ $args[0] };
860 }
861  
862 # 3. Setter: key-value list or hashref
863 my %attrs = ( @args == 1 && ref( $args[0] ) eq "HASH" ) ? %{ $args[0] } : @args;
864 my $needs_path_refresh = 0;
865  
866 foreach my $key ( keys %attrs ) {
867 my $val = $attrs{$key};
868 if ( $key eq 'use_ramdisk' ) {
869 $val = $self->_normalize_ramdisk_tier($val);
870 }
871 $self->{_table}->{$table}->{$key} = $val;
872 $needs_path_refresh = 1 if $key =~ /^(year|section|lang|table_dir|use_ramdisk)$/;
873 }
874  
875 $self->normalize_blocks( $table, $self->{_table}->{$table} );
876  
877 my $use_ram = $self->{_table}->{$table}->{use_ramdisk} // 0;
878 if ($use_ram) {
879 $self->{_table}->{$table}->{_ramdisk_ensured} = 1;
880 $self->ramdisk_ensure($table);
881 }
882  
883 if ($needs_path_refresh) {
884 delete $self->{_table}->{$table}->{_path};
885 $self->table_path($table);
886 }
887  
888 return $self;
889 }
890  
891 # my $table_path = $adb->table_infset($table);
892 # ------------------------------------------------
893 sub table_infset {
894 my ( $self, $table, $schema_data ) = @_;
895  
896 $self->config('use_simple') and return 1;
897 if ( ref($schema_data) eq 'HASH' ) {
898 $self->normalize_blocks( $table, $schema_data );
899 $self->{_table}->{$table} = $schema_data;
900 }
901 my $tbl = $self->{_table}->{$table};
902 ref($tbl) eq 'HASH' or return;
903  
904 my $table_path = "$table";
905 $table_path =~ s/\\/\//g;
906 $table_path =~ s/\//-/g;
907  
908 my $table_str = "";
909  
910 # Scalar keys
911 my @scalar_keys = qw(
912 name record_index keep_deleted log_owner parent_table
913 use_menu use_simple force use_ramdisk ramdisk_ttl use_cache use_alias
914 use_counter use_facet stop_word min_char
915 use_junk cache_ttl repeat_ids repeat_start
916 no_transact no_backup table_dir
917 );
918 foreach my $key (@scalar_keys) {
919 next unless exists $tbl->{$key};
920 next unless defined $tbl->{$key} && $tbl->{$key} ne "";
921 ( my $val = $tbl->{$key} ) =~ s/"/\\"/g;
922 $table_str .= "\t$key => \"$val\",\n";
923 }
924  
925 # Array keys
926 my @array_keys = qw(
927 search_block match_block view_block facet_block
928 filter_block slug_block reverse suggest_block
929 );
930 foreach my $key (@array_keys) {
931 next unless ref( $tbl->{$key} ) eq "ARRAY";
932 my $array = join ", ", @{ $tbl->{$key} };
933 next unless $array;
934 $table_str .= "\t$key => [ $array ],\n";
935 }
936  
937 # Serialize sort_block
938 if ( ref( $tbl->{sort_block} ) eq 'ARRAY' && @{ $tbl->{sort_block} } ) {
939 $table_str .= "\tsort_block => [\n";
940 foreach my $sb ( @{ $tbl->{sort_block} } ) {
941 if ( ref($sb) eq 'HASH' ) {
942 $table_str .= "\t\t{ blk => $sb->{blk}, type => \"$sb->{type}\"" . ( $sb->{len} ? ", len => $sb->{len}" : "" ) . " },\n";
943 }
944 else {
945 $table_str .= "\t\t$sb,\n";
946 }
947 }
948 $table_str .= "\t],\n";
949 }
950  
951 # Serialize facet_rules
952 if ( ref( $tbl->{facet_rules} ) eq 'ARRAY' && @{ $tbl->{facet_rules} } ) {
953 my $fa = $tbl->{facet_rules};
954 my $fa_val;
955 if ( ref( $fa->[0] ) eq 'ARRAY' ) {
956 my @rules_str = map {
957 "[" . join( ", ", map { $_ =~ /^\d+$/ ? $_ : "\"$_\"" } @$_ ) . "]"
958 } @$fa;
959 $fa_val = "[ " . join( ", ", @rules_str ) . " ]";
960 }
961 else {
962 $fa_val = "[ " . join( ", ", map { $_ =~ /^\d+$/ ? $_ : "\"$_\"" } @$fa ) . " ]";
963 }
964 $table_str .= "\tfacet_rules => $fa_val,\n";
965 }
966  
967 # Serialize junk_rules
968 if ( ref( $tbl->{junk_rules} ) eq 'ARRAY' && @{ $tbl->{junk_rules} } ) {
969 my $jr = $tbl->{junk_rules};
970 my $jr_val;
971 if ( ref( $jr->[0] ) eq 'ARRAY' ) {
972 my @rules_str = map {
973 "[" . join( ", ", map { $_ =~ /^\d+$/ ? $_ : "\"$_\"" } @$_ ) . "]"
974 } @$jr;
975 $jr_val = "[ " . join( ", ", @rules_str ) . " ]";
976 }
977 else {
978 $jr_val = "[ " . join( ", ", map { $_ =~ /^\d+$/ ? $_ : "\"$_\"" } @$jr ) . " ]";
979 }
980 $table_str .= "\tjunk_rules => $jr_val,\n";
981 }
982  
983 # Serialize suggest_join
984 if ( ref( $tbl->{suggest_join} ) eq 'ARRAY' && @{ $tbl->{suggest_join} } ) {
985 my $sj = $tbl->{suggest_join};
986 my @rules_str = map {
987 ref($_) eq 'ARRAY' ? "[" . join( ", ", @$_ ) . "]" : "[$_]"
988 } @$sj;
989 my $sj_val = "[ " . join( ", ", @rules_str ) . " ]";
990 $table_str .= "\tsuggest_join => $sj_val,\n";
991 }
992  
993 # Serialize blocks in correct format
994 if ( ref( $tbl->{blocks} ) eq "ARRAY" && @{ $tbl->{blocks} } ) {
995 $table_str .= "\tblocks => [\n";
996 my %seen;
997 foreach my $blok ( @{ $tbl->{blocks} } ) {
998 next unless ( defined $blok->{id} && length $blok->{id} ) && ( defined $blok->{name} && length $blok->{name} );
999 next if $seen{ $blok->{id} }++;
1000 $table_str .= "\t\t{ id => \"$blok->{id}\",";
1001 $table_str .= " name => \"$blok->{name}\",";
1002 $blok->{type} and $table_str .= " type => \"$blok->{type}\",";
1003 $blok->{input} and $table_str .= " input => \"$blok->{input}\",";
1004 $blok->{valid} and $table_str .= " valid => \"$blok->{valid}\",";
1005 if ( ref( $blok->{rdbm} ) eq 'HASH' && $blok->{rdbm}{table} ) {
1006 my $disp = $blok->{rdbm}{display} || 0;
1007 $table_str .=
1008 " rdbm => { table => \"$blok->{rdbm}{table}\", display => $disp },";
1009 }
1010 elsif ( defined $blok->{rdbm} && $blok->{rdbm} ne '' && !ref( $blok->{rdbm} ) ) {
1011 $table_str .= " rdbm => \"$blok->{rdbm}\",";
1012 }
1013 if ( ref( $blok->{extend} ) eq 'HASH' && $blok->{extend}{table} ) {
1014 my $join_col = $blok->{extend}{join} || 'id';
1015 $table_str .=
1016 " extend => { table => \"$blok->{extend}{table}\", join => \"$join_col\" },";
1017 }
1018 $blok->{option} and
1019 $table_str .= " option => \"$blok->{option}\",";
1020 $table_str .= " },\n";
1021 }
1022 $table_str .= "\t],\n";
1023 }
1024  
1025 if ($table_str) {
1026 my $schema_dir = $self->path('schema_dir') || ( $self->path('dbase_dir') ? $self->path('dbase_dir') . "/schema" : "schema" );
1027 open my $YZ, ">:encoding(UTF-8)", "$schema_dir/$table_path.table"
1028 or do {
1029 cluck "[DB_SCHEMA] Could not write schema $schema_dir/$table_path.table: $!\n";
1030 return;
1031 };
1032 print $YZ "{\n";
1033 print $YZ $table_str;
1034 print $YZ "}\n";
1035 close $YZ;
1036 }
1037  
1038 return 1;
1039 }
1040  
1041 # my $norm_info = $adb->norm_info($table_id);
1042 # ------------------------------------------------
1043 sub norm_info {
1044 my ( $self, $arg ) = @_;
1045  
1046 return {} unless $arg;
1047 return {} if $self->config('use_simple');
1048  
1049 my ( $table, $norm_path ) = $self->schema_arg( $arg, "norm" );
1050 $table && $norm_path or return {};
1051  
1052 $self->{_norm} ||= {};
1053 if ( $self->{_norm}->{$table} && %{ $self->{_norm}->{$table} } ) {
1054 return { %{ $self->{_norm}->{$table} } };
1055 }
1056  
1057 if ( my $do_data = $self->do_schema($norm_path) ) {
1058 $self->{_norm}->{$table} = $do_data;
1059 return $do_data;
1060 }
1061 return {};
1062 }
1063  
1064 # my $norm_hash = $adb->field_normalize($table_id, $raw_string, [$opts]);
1065 # ------------------------------------------------
1066 sub field_normalize {
1067 my ( $self, $table_id, $raw, $opts ) = @_;
1068 return {} unless defined $raw && $raw ne '';
1069  
1070 my $norm_info = $self->norm_info($table_id);
1071 return { raw_features => $raw } unless $norm_info && %$norm_info;
1072  
1073 my $str = "$raw";
1074 $str =~ s/<br\s*\/?>/ /gi;
1075 $str =~ s/\\n/ /g;
1076 $str =~ s/\\r/ /g;
1077 $str =~ s/\\t/ /g;
1078  
1079 # Preprocess
1080 if ( $norm_info->{preprocess} ) {
1081 for my $p ( @{ $norm_info->{preprocess} } ) {
1082 my ( $pat, $repl ) = @$p;
1083 if ( $repl eq q{$1 $2} ) {
1084 $str =~ s/$pat/$1 $2/g;
1085 }
1086 elsif ( $repl eq q{. $1} ) {
1087 $str =~ s/$pat/. $1/g;
1088 }
1089 elsif ( $repl eq q{$1 $2 Sayfa} ) {
1090 $str =~ s/$pat/$1 $2 Sayfa/gi;
1091 }
1092 else {
1093 $str =~ s/$pat/$repl/g;
1094 }
1095 }
1096 }
1097  
1098 my %res;
1099 if ( $norm_info->{rules} ) {
1100 for my $r ( @{ $norm_info->{rules} } ) {
1101 my $field = $r->{field};
1102  
1103 if ( $r->{map} ) {
1104 for my $m ( @{ $r->{map} } ) {
1105 my ( $pat, $target ) = @$m;
1106 if ( $str =~ $pat ) {
1107 $res{$field} = $target;
1108 last;
1109 }
1110 }
1111 }
1112 elsif ( $r->{match_all} ) {
1113 my @matches = ( $str =~ /$r->{match_all}/g );
1114 if (@matches) {
1115 if ( ( $r->{select} // 'max' ) eq 'max' ) {
1116 my ($m) = sort { $b <=> $a } @matches;
1117 $res{$field} = $m + 0;
1118 }
1119 elsif ( $r->{select} eq 'min' ) {
1120 my ($m) = sort { $a <=> $b } @matches;
1121 $res{$field} = $m + 0;
1122 }
1123 }
1124 }
1125 elsif ( $r->{match} ) {
1126 if ( $str =~ $r->{match} ) {
1127 if ( $r->{format} && ref( $r->{format} ) eq 'CODE' ) {
1128 $res{$field} = $r->{format}->( $1, $2, $3 );
1129 }
1130 elsif ( ( $r->{type} // '' ) eq 'integer' ) {
1131 $res{$field} = $1 + 0;
1132 }
1133 elsif ( ( $r->{type} // '' ) eq 'titlecase' ) {
1134 $res{$field} = ucfirst( lc($1) );
1135 }
1136 elsif ( ( $r->{type} // '' ) eq 'trim' ) {
1137 my $val = $1;
1138 $val =~ s/^\s+|\s+$//g;
1139 $res{$field} = $val;
1140 }
1141 else {
1142 $res{$field} = $1;
1143 }
1144 }
1145 }
1146 }
1147 }
1148  
1149 $res{raw_features} = $raw;
1150  
1151 # If source_block or target table schema mapping is requested
1152 if ( $opts && $opts->{as_array} ) {
1153 my $table_info = $self->table_info($table_id);
1154 if ( $table_info && $table_info->{blocks} ) {
1155 my @rec;
1156 my $blocks = $table_info->{blocks};
1157 for my $b (@$blocks) {
1158 my $fid = $b->{id};
1159 push @rec, ( $res{$fid} // '' );
1160 }
1161 return \@rec;
1162 }
1163 }
1164  
1165 return \%res;
1166 }
1167  
1168 1;