AmberDB

 view release on metacpan or  search on metacpan

lib/AmberDB/Base/Schema.pm  view on Meta::CPAN

package AmberDB::Base::Schema;

use 5.016;
use warnings;
use Carp qw(croak cluck);
use File::Spec;
use parent 'AmberDB::Base';

our $VERSION = '5.26.6';
my $CREATED  = '2026-09-06';

# Whitelist of inheritable group-level configuration keys from .dbase to member tables
our %INHERITABLE_DBASE_KEYS = map { $_ => 1 } qw(
    use_ramdisk   ramdisk_ttl   use_cache   cache_ttl
    keep_deleted  log_owner     use_counter
    use_section   section       use_year    year
    use_language  lang
    no_transact   no_backup     table_dir   use_junk
    use_simple
);

# =====================================================================
# SCHEMA FIELD NORMALIZATION, VALIDATION & TYPE CONVERSION
# =====================================================================

# Normalizes and validates a single field value according to schema block definition.
# Usage:
#   my $clean_val = $adb->enc_field($blk_def, $val);
# ------------------------------------------------
sub enc_field {
    my ( $self, $blk, $val ) = @_;

    if ( $blk && ref($blk) eq 'HASH' ) {
        my $type  = lc( $blk->{type}  // 'text' );
        my $valid = lc( $blk->{valid} // '' );

        # 1. Type: number / num (integer, float, negative support)
        if ( $type eq 'num' || $type eq 'number' || $type eq 'numeric' || $type eq 'int' || $type eq 'float' || $type eq 'decimal' ) {
            if ( defined $val && length("$val") ) {
                ( my $trimmed = "$val" ) =~ s/^\s+|\s+$//g;
                if ( $trimmed =~ /^[+-]?[0-9]+(?:\.[0-9]+)?$/ ) {
                    $val = 0 + $trimmed;
                }
                else {
                    $val = 0;
                }
            }
            else {
                $val = 0;
            }
        }
        # 2. Type: ascii
        elsif ( $type eq 'ascii' ) {
            if ( defined $val && length("$val") ) {
                $val = $self->to_ascii("$val");
            }
            else {
                $val = '';
            }
        }
        # 3. Type: date
        elsif ( $type eq 'date' || $type eq 'datetime' || $type eq 'date_short' || $type eq 'date_long' ) {
            if ( ( !defined $val || $val eq '' ) && $valid =~ /auto_date/ ) {
                my $y = $self->year;
                my $m = $self->month;
                my $d = $self->day;
                $val = "$y-$m-$d";
            }
            else {
                $val //= '';
            }
        }
        # 4. Type: array / repeat / loop
        elsif ( $type eq 'array' || $type eq 'list' || $type eq 'repeat' || $type eq 'repeats' || $type eq 'loop' ) {
            if ( defined $val ) {
                if ( ref($val) eq 'ARRAY' ) {
                    # ok
                }

lib/AmberDB/Base/Schema.pm  view on Meta::CPAN

    if ( defined $table && length $table ) {
        $schema->{table} = $table unless defined $schema->{table} && length $schema->{table};
        my ($dbase) = ( $table =~ /^([a-z0-9]+)_/i );
        $dbase //= "";
        $schema->{dbase} = $dbase unless defined $schema->{dbase} && length $schema->{dbase};
    }

    # Normalize UTF-8 characters on schema identity and block definitions
    $schema->{name} = $self->utf_decode( $schema->{name} ) if defined $schema->{name};
    if ( ref( $schema->{blocks} ) eq 'ARRAY' ) {
        for my $b ( @{ $schema->{blocks} } ) {
            next unless ref($b) eq 'HASH';
            for my $k (qw(name option valid)) {
                $b->{$k} = $self->utf_decode( $b->{$k} ) if defined $b->{$k};
            }
        }
    }
    if ( ref( $schema->{facet_block} ) eq 'ARRAY' ) {
        for my $fb ( @{ $schema->{facet_block} } ) {
            next unless ref($fb) eq 'HASH';
            for my $k (qw(label name title)) {
                $fb->{$k} = $self->utf_decode( $fb->{$k} ) if defined $fb->{$k};
            }
        }
    }

    # ------------------------------------------------------------------------
    # Pipeline Step 0b: Dbase Schema Group Inheritance
    # Inherit whitelisted operational flags from .dbase if not overridden.
    # ------------------------------------------------------------------------
    $self->_apply_dbase_inheritance( $table, $schema );

    # ------------------------------------------------------------------------
    # Pipeline Step 1: Global Configuration Inheritance
    # ------------------------------------------------------------------------
    if ( defined $schema->{use_ramdisk} ) {
        $schema->{use_ramdisk} = $self->_normalize_ramdisk_tier( $schema->{use_ramdisk} );
    }
    elsif ( !defined $schema->{use_cache} ) {
        my $global_ram = $self->config('use_ramdisk');
        $global_ram = $self->_normalize_ramdisk_tier($global_ram);
        $global_ram = 0 if $global_ram == 3;
        $schema->{use_ramdisk} = $global_ram;
    }

    # ------------------------------------------------------------------------
    # Pipeline Step 1b: Volatile RAM-Disk Tier 3 Stripping
    # If use_ramdisk == 3, table is pure volatile key-value store on RAM-disk.
    # Strip all indexing, columnar, facet, and relational definitions.
    # ------------------------------------------------------------------------
    if ( ( $schema->{use_ramdisk} // 0 ) == 3 ) {
        delete @{$schema}{
            qw(
              blocks match_block search_block view_block facet_block filter_block
              suggest_block suggest_join
              slug_block sort_block sort_fields use_facet facet_rules use_junk junk_rules
              record_index repeat_start repeat_ids field_rules keep_deleted
            )
        };
        $schema->{use_simple}  = 1;
        $schema->{no_backup}   = 1;
        $schema->{no_transact} = 1;
        $schema->{ramdisk_ttl} = 300 unless defined $schema->{ramdisk_ttl};
    }

    # ------------------------------------------------------------------------
    # Pipeline Step 2: Simple Mode Stripping
    # In simple key-value mode, selectively strip columnar, indexing, relational,
    # and caching definitions to enforce lightweight operation.
    # ------------------------------------------------------------------------
    if ( $schema->{use_simple} && ( $schema->{use_ramdisk} // 0 ) != 3 ) {
        delete @{$schema}{
            qw(
              blocks match_block search_block view_block facet_block filter_block
              suggest_block suggest_join
              slug_block sort_block sort_fields use_facet facet_rules use_junk junk_rules
              record_index repeat_start repeat_ids field_rules
              use_ramdisk ramdisk_ttl use_cache cache_ttl
            )
        };
        return $schema;
    }

    # ------------------------------------------------------------------------
    # Pipeline Step 3: RAM-Disk Environment & Mount Verification
    # If RAM-disk is not physically mounted or ready, strip use_ramdisk.
    # The existence of $schema->{use_ramdisk} is a guaranteed contract of readiness.
    # ------------------------------------------------------------------------
    unless ( $self->ramdisk_is_mounted() ) {
        delete $schema->{use_ramdisk};
        delete $schema->{use_cache};
    }

    # ------------------------------------------------------------------------
    # Pipeline Step 4: Blocks & Relational Foreign Keys (RDBM) Normalization
    # Converts string RDBM definitions like:
    # "catalog_category,2", "catalog_category;2", "catalog_category|2", "catalog_category:2"
    # into canonical hashref: { table => "catalog_category", display => 2 }
    # ------------------------------------------------------------------------
    if ( exists $schema->{blocks} ) {
        if ( ref( $schema->{blocks} ) eq 'ARRAY' ) {
            foreach my $block ( @{ $schema->{blocks} } ) {
                $self->normalize_rdbm($block) if ref($block) eq 'HASH';
            }
        }
        elsif ( ref( $schema->{blocks} ) eq 'HASH' ) {
            foreach my $key ( keys %{ $schema->{blocks} } ) {
                my $block = $schema->{blocks}->{$key};
                $self->normalize_rdbm($block) if ref($block) eq 'HASH';
            }
        }
    }

    # ------------------------------------------------------------------------
    # Pipeline Step 4b: Precompute _has_schema and _block_keys for high-performance lookup
    # ------------------------------------------------------------------------
    if ( exists $schema->{blocks} && ref( $schema->{blocks} ) eq 'ARRAY' && @{ $schema->{blocks} } ) {
        $schema->{_has_schema} = 1;
        my %b_keys;
        for my $idx ( 0 .. $#{ $schema->{blocks} } ) {
            my $b = $schema->{blocks}->[$idx];

lib/AmberDB/Base/Schema.pm  view on Meta::CPAN

            delete $self->{_table}->{$table}->{use_cache};
            return undef;
        }
        return $self->{_table}->{$table}->{ $args[0] };
    }

    # 3. Setter: key-value list or hashref
    my %attrs = ( @args == 1 && ref( $args[0] ) eq "HASH" ) ? %{ $args[0] } : @args;
    my $needs_path_refresh = 0;

    foreach my $key ( keys %attrs ) {
        my $val = $attrs{$key};
        if ( $key eq 'use_ramdisk' ) {
            $val = $self->_normalize_ramdisk_tier($val);
        }
        $self->{_table}->{$table}->{$key} = $val;
        $needs_path_refresh = 1 if $key =~ /^(year|section|lang|table_dir|use_ramdisk)$/;
    }

    $self->normalize_blocks( $table, $self->{_table}->{$table} );

    my $use_ram = $self->{_table}->{$table}->{use_ramdisk} // 0;
    if ($use_ram) {
        $self->{_table}->{$table}->{_ramdisk_ensured} = 1;
        $self->ramdisk_ensure($table);
    }

    if ($needs_path_refresh) {
        delete $self->{_table}->{$table}->{_path};
        $self->table_path($table);
    }

    return $self;
}

# my $table_path = $adb->table_infset($table);
# ------------------------------------------------
sub table_infset {
    my ( $self, $table, $schema_data ) = @_;

    $self->config('use_simple') and return 1;
    if ( ref($schema_data) eq 'HASH' ) {
        $self->normalize_blocks( $table, $schema_data );
        $self->{_table}->{$table} = $schema_data;
    }
    my $tbl = $self->{_table}->{$table};
    ref($tbl) eq 'HASH' or return;

    my $table_path = "$table";
    $table_path =~ s/\\/\//g;
    $table_path =~ s/\//-/g;

    my $table_str = "";

    # Scalar keys
    my @scalar_keys = qw(
      name record_index keep_deleted log_owner parent_table
      use_menu use_simple force use_ramdisk ramdisk_ttl use_cache use_alias
      use_counter use_facet stop_word min_char
      use_junk cache_ttl repeat_ids repeat_start
      no_transact no_backup table_dir
    );
    foreach my $key (@scalar_keys) {
        next unless exists $tbl->{$key};
        next unless defined $tbl->{$key} && $tbl->{$key} ne "";
        ( my $val = $tbl->{$key} ) =~ s/"/\\"/g;
        $table_str .= "\t$key => \"$val\",\n";
    }

    # Array keys
    my @array_keys = qw(
      search_block match_block view_block facet_block
      filter_block slug_block reverse suggest_block
    );
    foreach my $key (@array_keys) {
        next unless ref( $tbl->{$key} ) eq "ARRAY";
        my $array = join ", ", @{ $tbl->{$key} };
        next unless $array;
        $table_str .= "\t$key => [ $array ],\n";
    }

    # Serialize sort_block
    if ( ref( $tbl->{sort_block} ) eq 'ARRAY' && @{ $tbl->{sort_block} } ) {
        $table_str .= "\tsort_block => [\n";
        foreach my $sb ( @{ $tbl->{sort_block} } ) {
            if ( ref($sb) eq 'HASH' ) {
                $table_str .= "\t\t{ blk => $sb->{blk}, type => \"$sb->{type}\"" . ( $sb->{len} ? ", len => $sb->{len}" : "" ) . " },\n";
            }
            else {
                $table_str .= "\t\t$sb,\n";
            }
        }
        $table_str .= "\t],\n";
    }

    # Serialize facet_rules
    if ( ref( $tbl->{facet_rules} ) eq 'ARRAY' && @{ $tbl->{facet_rules} } ) {
        my $fa = $tbl->{facet_rules};
        my $fa_val;
        if ( ref( $fa->[0] ) eq 'ARRAY' ) {
            my @rules_str = map {
                "[" . join( ", ", map { $_ =~ /^\d+$/ ? $_ : "\"$_\"" } @$_ ) . "]"
            } @$fa;
            $fa_val = "[ " . join( ", ", @rules_str ) . " ]";
        }
        else {
            $fa_val = "[ " . join( ", ", map { $_ =~ /^\d+$/ ? $_ : "\"$_\"" } @$fa ) . " ]";
        }
        $table_str .= "\tfacet_rules => $fa_val,\n";
    }

    # Serialize junk_rules
    if ( ref( $tbl->{junk_rules} ) eq 'ARRAY' && @{ $tbl->{junk_rules} } ) {
        my $jr = $tbl->{junk_rules};
        my $jr_val;
        if ( ref( $jr->[0] ) eq 'ARRAY' ) {
            my @rules_str = map {
                "[" . join( ", ", map { $_ =~ /^\d+$/ ? $_ : "\"$_\"" } @$_ ) . "]"
            } @$jr;
            $jr_val = "[ " . join( ", ", @rules_str ) . " ]";
        }



( run in 2.099 seconds using v1.01-cache-2.11-cpan-99fa8243a42 )