1Struct::Dumb(3) User Contributed Perl Documentation Struct::Dumb(3)
2
6 "Struct::Dumb" - make simple lightweight record-like structures
7
9 use Struct::Dumb;
10 struct Point => [qw( x y )];
12 my $point = Point(10, 20);
14 printf "Point is at (%d, %d)\n", $point->x, $point->y;
16 $point->y = 30;
18 printf "Point is now at (%d, %d)\n", $point->x, $point->y;
19 struct Point3D => [qw( x y z )], named_constructor => 1;
21 my $point3d = Point3D( z => 12, x => 100, y => 50 );
23 printf "Point3d's height is %d\n", $point3d->z;
25 struct Point3D => [qw( x y z )], predicate => "is_Point3D";
27 my $point3d = Point3D( 1, 2, 3 );
29 printf "This is a Point3D\n" if is_Point3D( $point3d );
31 use Struct::Dumb qw( -named_constructors )
33 struct Point3D => [qw( x y z )];
35 my $point3d = Point3D( x => 100, z => 12, y => 50 );
37
39 "Struct::Dumb" creates record-like structure types, similar to the
40 "struct" keyword in C, C++ or C#, or "Record" in Pascal. An invocation
41 of this module will create a construction function which returns new
42 object references with the given field values. These references all
43 respond to lvalue methods that access or modify the values stored.
44 It's specifically and intentionally not meant to be an object class.
46 You cannot subclass it. You cannot provide additional methods. You
47 cannot apply roles or mixins or metaclasses or traits or antlers or
48 whatever else is in fashion this week.
49 On the other hand, it is tiny, creates cheap lightweight array-backed
51 structures, uses nothing outside of core. It's intended simply to be a
52 slightly nicer way to store data structures, where otherwise you might
53 be tempted to abuse a hash, complete with the risk of typoing key
54 names. The constructor will "croak" if passed the wrong number of
55 arguments, as will attempts to refer to fields that don't exist.
56 Accessor-mutators will "croak" if invoked with arguments. (This helps
57 detect likely bugs such as accidentally passing in the new value as an
58 argument, or attempting to invoke a stored "CODE" reference by passing
59 argument values directly to the accessor.)
60 $ perl -E 'use Struct::Dumb; struct Point => [qw( x y )]; Point(30)'
62 usage: main::Point($x, $y) at -e line 1
63 $ perl -E 'use Struct::Dumb; struct Point => [qw( x y )]; Point(10,20)->z'
65 main::Point does not have a 'z' field at -e line 1
66 $ perl -E 'use Struct::Dumb; struct Point => [qw( x y )]; Point(1,2)->x(3)'
68 main::Point->x invoked with arguments at -e line 1.
69 Objects in this class are (currently) backed by an ARRAY reference
71 store, though this is an internal implementation detail and should not
72 be relied on by using code. Attempting to dereference the object as an
73 ARRAY will throw an exception.
74 CONSTRUCTOR FORMS
76 The "struct" and "readonly_struct" declarations create two different
77 kinds of constructor function, depending on the setting of the
78 "named_constructor" option. When false, the constructor takes
79 positional values in the same order as the fields were declared. When
80 true, the constructor takes a key/value pair list in no particular
81 order, giving the value of each named field.
82 This option can be specified to the "struct" and "readonly_struct"
84 functions. It defaults to false, but it can be set on a per-package
85 basis to default true by supplying the "-named_constructors" option on
86 the "use" statement.
87 When using named constructors, individual fields may be declared as
89 being optional. By preceeding the field name with a "?" character, the
90 constructor is instructed not to complain if a named parameter is not
91 given for that field; instead it will be set to "undef".
92 struct Person => [qw( name age ?address )],
94 named_constructor => 1;
95 my $bob = Person( name => "Bob", age => 20 );
97 # This is valid because 'address' is marked as optional
98
100 struct
101 struct $name => [ @fieldnames ],
102 named_constructor => (1|0),
103 predicate => "is_$name";
104 Creates a new structure type. This exports a new function of the type's
106 name into the caller's namespace. Invoking this function returns a new
107 instance of a type that implements those field names, as accessors and
108 mutators for the fields.
109 Takes the following options:
111 named_constructor => BOOL
113 Determines whether the structure will take positional or named
114 arguments.
115 predicate => STR
117 If defined, gives the name of a second function to export to the
118 caller's namespace. This function will be a type test predicate;
119 that is, a function that takes a single argmuent, and returns true
120 if-and-only-if that argument is an instance of this structure type.
121 readonly_struct
123 readonly_struct $name => [ @fieldnames ],
124 ...
125 Similar to "struct", but instances of this type are immutable once
127 constructed. The field accessor methods will not be marked with the
128 ":lvalue" attribute.
129 Takes the same options as "struct".
131
133 Since version 0.10.
134 If Data::Dump is loaded, an extra filter is applied so that struct
136 instances are printed in a format matching that which would construct
137 them.
138 struct Colour => [qw( red green blue )];
140 use Data::Dump;
142 my %hash = ( col => Colour( 0.8, 0.5, 0.2 ) );
144 Data::Dump::dd \%hash;
145 # prints {col => main::Colour(0.8, 0.5, 0.2)}
147
149 Allowing ARRAY dereference
150 The way that forbidding access to instances as if they were ARRAY
151 references is currently implemented uses an internal method on the
152 generated structure class called "_forbid_arrayification". If special
153 circumstances require that this exception mechanism be bypassed, the
154 method can be overloaded with an empty "sub {}" body, allowing the
155 struct instances in that class to be accessed like normal ARRAY
156 references. For good practice this should be limited by a "local"
157 override.
158 For example, Devel::Cycle needs to access the instances as plain ARRAY
160 references so it can walk the data structure looking for reference
161 cycles.
162 use Devel::Cycle;
164 {
166 no warnings 'redefine';
167 local *Point::_forbid_arrayification = sub {};
168 memory_cycle_ok( $point );
170 }
171
173 • Consider adding an "coerce_hash" option, giving name of another
174 function to convert structs to key/value pairs, or a HASH ref.
175
177 Paul Evans <leonerd@leonerd.org.uk>
178perl v5.36.0 2022-07-22 Struct::Dumb(3)