1Struct::Dumb(3)       User Contributed Perl Documentation      Struct::Dumb(3)
2
3
4

NAME

6       "Struct::Dumb" - make simple lightweight record-like structures
7

SYNOPSIS

9          use Struct::Dumb;
10
11          struct Point => [qw( x y )];
12
13          my $point = Point(10, 20);
14
15          printf "Point is at (%d, %d)\n", $point->x, $point->y;
16
17          $point->y = 30;
18          printf "Point is now at (%d, %d)\n", $point->x, $point->y;
19
20          struct Point3D => [qw( x y z )], named_constructor => 1;
21
22          my $point3d = Point3D( z => 12, x => 100, y => 50 );
23
24          printf "Point3d's height is %d\n", $point3d->z;
25
26          struct Point3D => [qw( x y z )], predicate => "is_Point3D";
27
28          my $point3d = Point3D( 1, 2, 3 );
29
30          printf "This is a Point3D\n" if is_Point3D( $point3d );
31
32          use Struct::Dumb qw( -named_constructors )
33
34          struct Point3D => [qw( x y z )];
35
36          my $point3d = Point3D( x => 100, z => 12, y => 50 );
37

DESCRIPTION

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
45       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
50       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
61          $ perl -E 'use Struct::Dumb; struct Point => [qw( x y )]; Point(30)'
62          usage: main::Point($x, $y) at -e line 1
63
64          $ 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
67          $ 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
70       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
75       Note: That on development perls that support "use feature 'class'",
76       this is used instead of a blessed ARRAY reference. This implementation
77       choice should be transparent to the end-user, as all the same features
78       are supported.
79
80   CONSTRUCTOR FORMS
81       The "struct" and "readonly_struct" declarations create two different
82       kinds of constructor function, depending on the setting of the
83       "named_constructor" option. When false, the constructor takes
84       positional values in the same order as the fields were declared. When
85       true, the constructor takes a key/value pair list in no particular
86       order, giving the value of each named field.
87
88       This option can be specified to the "struct" and "readonly_struct"
89       functions. It defaults to false, but it can be set on a per-package
90       basis to default true by supplying the "-named_constructors" option on
91       the "use" statement.
92
93       When using named constructors, individual fields may be declared as
94       being optional. By preceeding the field name with a "?" character, the
95       constructor is instructed not to complain if a named parameter is not
96       given for that field; instead it will be set to "undef".
97
98          struct Person => [qw( name age ?address )],
99             named_constructor => 1;
100
101          my $bob = Person( name => "Bob", age => 20 );
102          # This is valid because 'address' is marked as optional
103

FUNCTIONS

105   struct
106          struct $name => [ @fieldnames ],
107             named_constructor => (1|0),
108             predicate         => "is_$name";
109
110       Creates a new structure type. This exports a new function of the type's
111       name into the caller's namespace. Invoking this function returns a new
112       instance of a type that implements those field names, as accessors and
113       mutators for the fields.
114
115       Takes the following options:
116
117       named_constructor => BOOL
118           Determines whether the structure will take positional or named
119           arguments.
120
121       predicate => STR
122           If defined, gives the name of a second function to export to the
123           caller's namespace. This function will be a type test predicate;
124           that is, a function that takes a single argmuent, and returns true
125           if-and-only-if that argument is an instance of this structure type.
126
127   readonly_struct
128          readonly_struct $name => [ @fieldnames ],
129             ...
130
131       Similar to "struct", but instances of this type are immutable once
132       constructed. The field accessor methods will not be marked with the
133       ":lvalue" attribute.
134
135       Takes the same options as "struct".
136

DATA::DUMP FILTER

138       Since version 0.10.
139
140       If Data::Dump is loaded, an extra filter is applied so that struct
141       instances are printed in a format matching that which would construct
142       them.
143
144          struct Colour => [qw( red green blue )];
145
146          use Data::Dump;
147
148          my %hash = ( col => Colour( 0.8, 0.5, 0.2 ) );
149          Data::Dump::dd \%hash;
150
151          # prints {col => main::Colour(0.8, 0.5, 0.2)}
152

NOTES

154   Allowing ARRAY dereference
155       The way that forbidding access to instances as if they were ARRAY
156       references is currently implemented uses an internal method on the
157       generated structure class called "_forbid_arrayification". If special
158       circumstances require that this exception mechanism be bypassed, the
159       method can be overloaded with an empty "sub {}" body, allowing the
160       struct instances in that class to be accessed like normal ARRAY
161       references. For good practice this should be limited by a "local"
162       override.
163
164       For example, Devel::Cycle needs to access the instances as plain ARRAY
165       references so it can walk the data structure looking for reference
166       cycles.
167
168          use Devel::Cycle;
169
170          {
171             no warnings 'redefine';
172             local *Point::_forbid_arrayification = sub {};
173
174             memory_cycle_ok( $point );
175          }
176

TODO

178       •   Consider adding an "coerce_hash" option, giving name of another
179           function to convert structs to key/value pairs, or a HASH ref.
180

AUTHOR

182       Paul Evans <leonerd@leonerd.org.uk>
183
184
185
186perl v5.36.0                      2023-01-20                   Struct::Dumb(3)
Impressum