Struct::Dumb(3pm) User Contributed Perl Documentation Struct::Dumb(3pm)
NAME
"Struct::Dumb" - make simple lightweight record-like structures
SYNOPSIS
use Struct::Dumb;
struct Point => [qw( x y )];
my $point = Point(10, 20);
printf "Point is at (%d, %d)\n", $point->x, $point->y;
$point->y = 30;
printf "Point is now at (%d, %d)\n", $point->x, $point->y;
struct Point3D => [qw( x y z )], named_constructor => 1;
my $point3d = Point3D( z => 12, x => 100, y => 50 );
printf "Point3d's height is %d\n", $point3d->z;
struct Point3D => [qw( x y z )], predicate => "is_Point3D";
my $point3d = Point3D( 1, 2, 3 );
printf "This is a Point3D\n" if is_Point3D( $point3d );
use Struct::Dumb qw( -named_constructors )
struct Point3D => [qw( x y z )];
my $point3d = Point3D( x => 100, z => 12, y => 50 );
DESCRIPTION
"Struct::Dumb" creates record-like structure types, similar to the
"struct" keyword in C, C++ or C#, or "Record" in Pascal. An invocation
of this module will create a construction function which returns new
object references with the given field values. These references all
respond to lvalue methods that access or modify the values stored.
It's specifically and intentionally not meant to be an object class.
You cannot subclass it. You cannot provide additional methods. You
cannot apply roles or mixins or metaclasses or traits or antlers or
whatever else is in fashion this week.
On the other hand, it is tiny, creates cheap lightweight array-backed
structures, uses nothing outside of core. It's intended simply to be a
slightly nicer way to store data structures, where otherwise you might
be tempted to abuse a hash, complete with the risk of typoing key
names. The constructor will "croak" if passed the wrong number of
arguments, as will attempts to refer to fields that don't exist.
Accessor-mutators will "croak" if invoked with arguments. (This helps
detect likely bugs such as accidentally passing in the new value as an
argument, or attempting to invoke a stored "CODE" reference by passing
argument values directly to the accessor.)
$ perl -E 'use Struct::Dumb; struct Point => [qw( x y )]; Point(30)'
usage: main::Point($x, $y) at -e line 1
$ perl -E 'use Struct::Dumb; struct Point => [qw( x y )]; Point(10,20)->z'
main::Point does not have a 'z' field at -e line 1
$ perl -E 'use Struct::Dumb; struct Point => [qw( x y )]; Point(1,2)->x(3)'
main::Point->x invoked with arguments at -e line 1.
Objects in this class are (currently) backed by an ARRAY reference
store, though this is an internal implementation detail and should not
be relied on by using code. Attempting to dereference the object as an
ARRAY will throw an exception.
Note: That on development perls that support "use feature 'class'",
this is used instead of a blessed ARRAY reference. This implementation
choice should be transparent to the end-user, as all the same features
are supported.
CONSTRUCTOR FORMS
The "struct" and "readonly_struct" declarations create two different
kinds of constructor function, depending on the setting of the
"named_constructor" option. When false, the constructor takes
positional values in the same order as the fields were declared. When
true, the constructor takes a key/value pair list in no particular
order, giving the value of each named field.
This option can be specified to the "struct" and "readonly_struct"
functions. It defaults to false, but it can be set on a per-package
basis to default true by supplying the "-named_constructors" option on
the "use" statement.
When using named constructors, individual fields may be declared as
being optional. By preceeding the field name with a "?" character, the
constructor is instructed not to complain if a named parameter is not
given for that field; instead it will be set to "undef".
struct Person => [qw( name age ?address )],
named_constructor => 1;
my $bob = Person( name => "Bob", age => 20 );
# This is valid because 'address' is marked as optional
FUNCTIONS
struct
struct $name => [ @fieldnames ],
named_constructor => (1|0),
predicate => "is_$name";
Creates a new structure type. This exports a new function of the type's
name into the caller's namespace. Invoking this function returns a new
instance of a type that implements those field names, as accessors and
mutators for the fields.
Takes the following options:
named_constructor => BOOL
Determines whether the structure will take positional or named
arguments.
predicate => STR
If defined, gives the name of a second function to export to the
caller's namespace. This function will be a type test predicate;
that is, a function that takes a single argmuent, and returns true
if-and-only-if that argument is an instance of this structure type.
readonly_struct
readonly_struct $name => [ @fieldnames ],
...
Similar to "struct", but instances of this type are immutable once
constructed. The field accessor methods will not be marked with the
":lvalue" attribute.
Takes the same options as "struct".
DATA::DUMP FILTER
Since version 0.10.
If Data::Dump is loaded, an extra filter is applied so that struct
instances are printed in a format matching that which would construct
them.
struct Colour => [qw( red green blue )];
use Data::Dump;
my %hash = ( col => Colour( 0.8, 0.5, 0.2 ) );
Data::Dump::dd \%hash;
# prints {col => main::Colour(0.8, 0.5, 0.2)}
NOTES
Allowing ARRAY dereference
The way that forbidding access to instances as if they were ARRAY
references is currently implemented uses an internal method on the
generated structure class called "_forbid_arrayification". If special
circumstances require that this exception mechanism be bypassed, the
method can be overloaded with an empty "sub {}" body, allowing the
struct instances in that class to be accessed like normal ARRAY
references. For good practice this should be limited by a "local"
override.
For example, Devel::Cycle needs to access the instances as plain ARRAY
references so it can walk the data structure looking for reference
cycles.
use Devel::Cycle;
{
no warnings 'redefine';
local *Point::_forbid_arrayification = sub {};
memory_cycle_ok( $point );
}
TODO
• Consider adding an "coerce_hash" option, giving name of another
function to convert structs to key/value pairs, or a HASH ref.
AUTHOR
Paul Evans <leonerd@leonerd.org.uk>
perl v5.36.0 2023-02-14 Struct::Dumb(3pm)
Generated by dwww version 1.15 on Tue Jun 25 13:18:25 CEST 2024.