File Coverage

lib/Object/Meta.pm

Criterion	Covered	Total	%
statement	48	52	92.3
branch	13	20	65.0
condition	3	12	25.0
subroutine	12	13	92.3
pod	10	10	100.0
total	86	107	80.3

#
# @author Bodo (Hugo) Barwich
# @version 2026-01-29
# @package Object::Meta
# @subpackage lib/Object/Meta.pm

# This Module defines Classes to manage Data in an indexed List
#
#---------------------------------
# Requirements:
#
#---------------------------------
# Features:
#

#==============================================================================
# The Object::Meta Package

=head1 NAME

Object::Meta - Library to manage raw data and meta data as one object but keeping it separate

=cut

package Object::Meta;

our $VERSION = '1.2.0';

#----------------------------------------------------------------------------
#Dependencies

use constant LIST_DATA      => 0;
use constant LIST_META_DATA => 1;

=head1 DESCRIPTION

C implements a class to manage raw data and additional meta data as an object

Of special importance is the B which is use to create an automatical index
in the C.

It does not require lengthly creation of definition modules.

=cut

#----------------------------------------------------------------------------
#Constructors

=head1 METHODS

=head2 Constructor

=head3 new ( [ DATA ] )

This is the constructor for a new C object.

B

=over 4

=item C

The B which is passed in a hash like fashion,
using key and value pairs.

=back

=cut

sub new {
    my $class = ref( $_[0] ) || $_[0];

    #Set the Default Attributes and assign the initial Values
    my $self = [ {}, {} ];

    #Bestow Objecthood
    bless $self, $class;

    if ( scalar(@_) > 1 ) {

        #Parameters are a Key / Value List
        Object::Meta::set( $self, @_[ 1 .. $#_ ] );
    }

    return $self;
}

sub DESTROY {
    my $self = $_[0];

    #Free the Lists
    $self->[LIST_DATA]      = ();
    $self->[LIST_META_DATA] = ();
}

#----------------------------------------------------------------------------
#Administration Methods

=head2 Administration Methods

=head3 set ( DATA )

This method will populate the B with values.

B

=over 4

=item C

A list which is passed in a hash like fashion, using key and value pairs.

=back

=cut

sub set {
    my ( $self, %hshprms ) = @_;

    foreach ( keys %hshprms ) {

        #The Field Name must not be empty
        if ( $_ ne '' ) {
            $self->[LIST_DATA]{$_} = $hshprms{$_};
        }
    }
}

=head3 setMeta ( DATA )

This method will assign values to B.

B

=over 4

=item C

A list which is passed in a hash like fashion, using key and value pairs.

=back

=cut

sub setMeta {
    my ( $self, %hshprms ) = @_;

    foreach ( keys %hshprms ) {

        #The Field Name must not be empty
        if ( $_ ne '' ) {
            $self->[LIST_META_DATA]{$_} = $hshprms{$_};
        }
    }
}

=head3 setIndexField ( INDEX_FIELD )

This method configure the B for this object.

B

=over 4

=item C

The name of the Field which contains the Value by which the object
will be indexed.

=back

=cut

sub setIndexField {
    my ( $self, $sindexfield ) = @_;

    if ( defined $sindexfield ) {
        Object::Meta::setMeta( $self, 'indexfield', $sindexfield );
    }

}

=head3 setIndexValue ( INDEX_VALUE )

This Method assigns the value for the B for this object.

B

=over 4

=item C

The scalar value of the Field by which the object will be indexed.

=back

=cut

sub setIndexValue {
    my ( $self, $sindexvalue ) = @_;
    my $sindexfield = Object::Meta::getIndexField $self;

    if ( defined $sindexvalue
        && $sindexfield ne '' )
    {
        Object::Meta::set( $self, $sindexfield, $sindexvalue );
    }
}

=head3 Clear ()

This method removes all raw data and meta data.

Only the index field configuration is still kept.

See L|/"setIndexField ( INDEX_FIELD )">

=cut

sub Clear {
    my $self = $_[0];

    #Preserve Index Configuration
    my $sindexfield = Object::Meta::getIndexField $self;

    $self->[LIST_DATA]      = ();
    $self->[LIST_META_DATA] = ();

    #Restore Index Configuration
    Object::Meta::setIndexField $self, $sindexfield;
}

#----------------------------------------------------------------------------
#Consultation Methods

=head2 Consultation Methods

=head3 get ( FIELD_NAME [, DEFAULT_VALUE [. IS_META ] ] )

This Method retrieves the value of the field with name C for this object.
It can be a B or a B.

B

=over 4

=item C

The name of the Field which value it must return.

=item C

The default value to return if the Field does not exist.
  (Otherwise it would return C)

=item C

whether the C is a B.

=back

=cut

sub get {
    my ( $self, $sfieldname, $sdefault, $imta ) = @_;
    my $srs = $sdefault;

    unless ($imta) {
        if ( defined $sfieldname
            && $sfieldname ne '' )
        {
            if ( exists $self->[LIST_DATA]{$sfieldname} ) {
                $srs = $self->[LIST_DATA]{$sfieldname};
            }
            else {
                #Check as Meta Field
                $srs = Object::Meta::getMeta( $self, $sfieldname, $sdefault );
            }
        }
    }
    else    #A Meta Field is requested
    {
        #Check a Meta Field
        $srs = Object::Meta::getMeta( $self, $sfieldname, $sdefault );
    }

    return $srs;
}

=head3 getMeta ( FIELD_NAME [, DEFAULT_VALUE ] )

This Method retrieves the value of the B with name C for this object.

B

=over 4

=item C

The name of the Field which value it must return.

=item C

The default value to return if the Field does not exist.
  (Otherwise it would return C)

=back

=cut

sub getMeta {
    my ( $self, $sfieldname, $sdefault ) = @_;
    my $srs = $sdefault;

    if ( defined $sfieldname
        && $sfieldname ne '' )
    {
        $srs = $self->[LIST_META_DATA]{$sfieldname}
          if ( exists $self->[LIST_META_DATA]{$sfieldname} );

    }

    return $srs;
}

=head3 getIndexField ()

This method retrieves the Name of the B with the object will be indexed.

The name of the B is a B which is stored separately.

B The Name of the B or an empty String if the Field is not set.

=cut

sub getIndexField {
    return Object::Meta::getMeta( $_[0], 'indexfield', '' );
}

=head3 getIndexValue ()

This method retrieves the Value of the B by which the object will be indexed.

=cut

sub getIndexValue {
    my $sindexfield = Object::Meta::getIndexField $_[0];

    #print "idx fld: '$sindexfield'; idx vl: '" . $_[0]->get($sindexfield) . "'\n";

    return Object::Meta::get( $_[0], $sindexfield );
}

return 1;