view release on metacpan or  search on metacpan

lib/object.pm  view on Meta::CPAN

    static SV* coerce_trim(pTHX_ SV *val) {
        STRLEN len;
        const char *pv = SvPV(val, len);
        const char *start = pv;
        const char *end = pv + len;
        while (start < end && isSPACE(*start)) start++;
        while (end > start && isSPACE(*(end-1))) end--;
        return sv_2mortal(newSVpvn(start, end - start));
    }
    
    MODULE = MyTypes  PACKAGE = MyTypes
    
    BOOT:
        object_register_type_xs(aTHX_ "PositiveInt", check_positive_int, NULL);
        object_register_type_xs(aTHX_ "Email", check_email, NULL);
        object_register_type_xs(aTHX_ "TrimmedStr", NULL, coerce_trim);

Usage in Perl:

    use MyTypes;  # Registers types in BOOT
    use object;
    
    object::define('User',
        'id:PositiveInt:required',
        'email:Email',
        'bio:TrimmedStr',
    );
    
    my $user = new User id => 42, email => 'user@example.com';

=head3 Performance Tiers

    Type Source               Check Cost    Total Overhead
    --------------------------------------------------------
    Built-in (Str, Int)       ~0 cycles     inline switch
    Registered C function     ~5 cycles     function pointer
    Perl callback             ~100 cycles   call_sv overhead

=head3 Linking

Your XS module needs to link against the object module. The functions
are exported with C<PERL_CALLCONV> visibility.

=head2 new $class @args

Create a new object. Supports positional or named arguments.

    my $cat = new Cat 'Whiskers', 3;           # positional
    my $cat = new Cat name => 'Whiskers';      # named

=head2 $obj->prototype

Get the prototype object (or undef if none).

=head2 $obj->set_prototype($proto)

Set the prototype object. Fails if object is frozen.

=head2 $obj->lock

Prevent adding new properties. Can be unlocked.

=head2 $obj->unlock

Allow adding new properties again. Fails if frozen.

=head2 $obj->freeze

Permanently prevent modifications. Cannot be undone.

=head2 $obj->is_frozen

Returns true if object is frozen.

=head2 $obj->is_locked

Returns true if object is locked (but may not be frozen).

=head2 object::clone($obj)

Create a shallow copy of an object. All property values are copied, but
references share the same underlying referent. The clone is a fresh object
that is NOT frozen or locked, even if the original was.

    my $original = new Cat name => 'Whiskers', age => 3;
    object::freeze($original);

    my $clone = object::clone($original);
    $clone->age(4);  # works - clone is not frozen
    print $clone->name;  # "Whiskers"

Shallow copy means array/hash reference properties will share data:

    $original->tags(['fluffy']);
    my $clone = $original->clone;
    push @{$clone->tags}, 'playful';
    # $original->tags is now ['fluffy', 'playful']

=head2 object::properties($class)

Return the property names for a class. In list context, returns the property
names. In scalar context, returns the count.

    my @props = object::properties('Cat');   # ('name', 'age')
    my $count = object::properties('Cat');   # 2

    # Check if property exists
    if (grep { $_ eq 'color' } object::properties('Cat')) {
        ...
    }

Returns an empty list (or 0 in scalar context) for non-existent classes.

=head2 object::slot_info($class, $property)

Return detailed metadata about a property slot. Returns a hashref with
information about the slot, or C<undef> if the class or property doesn't
exist.

    my $info = object::slot_info('Person', 'name');
    # Returns:
    # {
    #     name         => 'name',
    #     index        => 1,
    #     type         => 'Str',
    #     is_required  => 1,
    #     is_readonly  => 0,
    #     is_lazy      => 0,
    #     has_default  => 0,
    #     has_trigger  => 0,
    #     has_coerce   => 0,
    #     has_builder  => 0,
    #     has_clearer  => 0,
    #     has_predicate => 0,
    #     has_type     => 1,
    # }

The returned hash always contains these boolean flags:

=over 4

=item * B<is_required> - Property must be provided in new()