MooX::Struct(3pm)

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

NAME

6       MooX::Struct - make simple lightweight record-like structures that make
7       sounds like cows
8

SYNOPSIS

10        use MooX::Struct
11           Point   => [ 'x', 'y' ],
12           Point3D => [ -extends => ['Point'], 'z' ],
13        ;
14
15        my $origin = Point3D->new( x => 0, y => 0, z => 0 );
16
17        # or...
18        my $origin = Point3D[ 0, 0, 0 ];
19

DESCRIPTION

21       MooX::Struct allows you to create cheap struct-like classes for your
22       data using Moo.
23
24       While similar in spirit to MooseX::Struct and Class::Struct,
25       MooX::Struct has a somewhat different usage pattern. Rather than
26       providing you with a "struct" keyword which can be used to define
27       structs, you define all the structs as part of the "use" statement.
28       This means they happen at compile time.
29
30       A struct is just an "anonymous" Moo class. MooX::Struct creates this
31       class for you, and installs a lexical alias for it in your namespace.
32       Thus your module can create a "Point3D" struct, and some other module
33       can too, and they won't interfere with each other. All struct classes
34       inherit from MooX::Struct.
35
36       Arguments for MooX::Struct are key-value pairs, where keys are the
37       struct names, and values are arrayrefs.
38
39        use MooX::Struct
40           Person   => [qw/ name address /],
41           Company  => [qw/ name address registration_number /];
42
43       The elements in the array are the attributes for the struct (which will
44       be created as read-only attributes), however certain array elements are
45       treated specially.
46
47       ·   As per the example in the "SYNOPSIS", "-extends" introduces a list
48           of parent classes for the struct. If not specified, then classes
49           inherit from MooX::Struct itself.
50
51           Structs can inherit from other structs, or from normal classes. If
52           inheriting from another struct, then you must define both in the
53           same "use" statement.  Inheriting from a non-struct class is
54           discouraged.
55
56            # Not like this.
57            use MooX::Struct Point   => [ 'x', 'y' ];
58            use MooX::Struct Point3D => [ -extends => ['Point'], 'z' ];
59
60            # Like this.
61            use MooX::Struct
62               Point   => [ 'x', 'y' ],
63               Point3D => [ -extends => ['Point'], 'z' ],
64            ;
65
66       ·   Similarly "-with" consumes a list of roles.
67
68       ·   If an attribute name is followed by a coderef, this is installed as
69           a method instead.
70
71            use MooX::Struct
72               Person => [
73                  qw( name age sex ),
74                  greet => sub {
75                     my $self = shift;
76                     CORE::say "Hello ", $self->name;
77                  },
78               ];
79
80           But if you're defining methods for your structs, then you've
81           possibly missed the point of them.
82
83       ·   If an attribute name is followed by an arrayref, these are used to
84           set the options for the attribute. For example:
85
86            use MooX::Struct
87               Person  => [ name => [ is => 'ro', required => 1 ] ];
88
89           Using the "init_arg" option would probably break stuff. Don't do
90           that.
91
92       ·   Attribute names may be "decorated" with prefix and postfix
93           "sigils". The prefix sigils of "@" and "%" specify that the
94           attribute isa arrayref or hashref respectively. (Blessed arrayrefs
95           and hashrefs are accepted; as are objects which overload "@{}" and
96           "%{}".) The prefix sigil "$" specifies that the attribute value
97           must not be an unblessed arrayref or hashref.  The prefix sigil "+"
98           indicates the attribute is a number, and provides a default value
99           of 0, unless the attribute is required. The postfix sigil "!"
100           specifies that the attribute is required.
101
102            use MooX::Struct
103               Person  => [qw( $name! @children )];
104
105            Person->new();         # dies, name is required
106            Person->new(           # dies, children should be arrayref
107               name     => 'Bob',
108               children => 2,
109            );
110
111       Prior to the key-value list, some additional flags can be given. These
112       begin with hyphens. The flag "-rw" indicates that attributes should be
113       read-write rather than read-only.
114
115        use MooX::Struct -rw,
116           Person => [
117              qw( name age sex ),
118              greet => sub {
119                 my $self = shift;
120                 CORE::say "Hello ", $self->name;
121              },
122           ];
123
124       The "-retain" flag can be used to indicate that MooX::Struct should not
125       use namespace::clean to enforce lexicalness on your struct class
126       aliases.
127
128       Flags "-trace" and "-deparse" may be of use debugging.
129
130   Instantiating Structs
131       There are two supported methods of instatiating structs. You can use a
132       traditional class-like constructor with named parameters:
133
134        my $point = Point->new( x => 1, y => 2 );
135
136       Or you can use the abbreviated syntax with positional parameters:
137
138        my $point = Point[ 1, 2 ];
139
140       If you know about Moo and peek around in the source code for this
141       module, then I'm sure you can figure out additional ways to instantiate
142       them, but the above are the only supported two.
143
144       When inheritance or roles have been used, it might not always be clear
145       what order the positional parameters come in (though see the
146       documentation for the "FIELDS" below), so the traditional class-like
147       style may be preferred.
148
149   Methods
150       Structs are objects and thus have methods. You can define your own
151       methods as described above. MooX::Struct's built-in methods will always
152       obey the convention of being in ALL CAPS (except in the case of
153       "_data_printer").  By using lower-case letters to name your own
154       methods, you can avoid naming collisions.
155
156       The following methods are currently defined. Additionally all the
157       standard Perl ("isa", "can", etc) and Moo ("new", "does", etc) methods
158       are available.
159
160       "OBJECT_ID"
161           Returns a unique identifier for the object.
162
163           May only be called as an instance method.
164
165       "FIELDS"
166           Returns a list of fields associated with the object. For the
167           "Point3D" struct in the SYNPOSIS, this would be 'x', 'y', 'z'.
168
169           The order the fields are returned in is equal to the order they
170           must be supplied for the positional constructor.
171
172           Attributes inherited from roles, or from non-struct base classes
173           are not included in "FIELDS", and thus cannot be used in the
174           positional constructor.
175
176           May be called as an instance or class method.
177
178       "TYPE"
179           Returns the type name of the struct, e.g. 'Point3D'.
180
181           May be called as an instance or class method.
182
183       "CLASSNAME"
184           Returns the internally used package name for the struct, e.g.
185           'MooX::Struct::__ANON__::0007'. Pretty rare you'd want to see this.
186
187           May be called as an instance or class method.
188
189       "TYPE_TINY"
190           Returns a Type::Tiny type constraint corresponding to the
191           CLASSNAME, suitable for a Moose/Moo "isa".
192
193            package Foo {
194              use Moo;
195              use MooX::Struct Bar => [qw( $name )];
196
197              has left_bar  => (is => 'rw', isa => Bar->TYPE_TINY);
198              has right_bar => (is => 'rw', isa => Bar->TYPE_TINY);
199
200              ...;
201            }
202
203           May be called as an instance or class method.
204
205       "TO_HASH"
206           Returns a reference to an unblessed hash where the object's fields
207           are the keys and the object's values are the hash values.
208
209           May only be called as an instance method.
210
211       "TO_ARRAY"
212           Returns a reference to an unblessed array where the object's values
213           are the array items, in the same order as listed by "FIELDS".
214
215           May only be called as an instance method.
216
217       "TO_STRING"
218           Joins "TO_ARRAY" with whitespace. This is not necessarily a
219           brilliant stringification, but easy enough to overload:
220
221            use MooX::Struct
222               Point => [
223                  qw( x y ),
224                  TO_STRING => sub {
225                     sprintf "(%d, %d)"), $_[0]->x, $_[0]->y;
226                  },
227               ]
228            ;
229
230           May only be called as an instance method.
231
232       "CLONE"
233           Creates a shallow clone of the object.
234
235           May only be called as an instance method.
236
237       "EXTEND"
238           An exverimental feature.
239
240           Extend a class or object with additional attributes, methods, etc.
241           This method takes almost all the same arguments as "use
242           MooX::Struct", albeit with some slight differences.
243
244            use MooX::Struct Point => [qw/ +x +y /];
245            my $point = Point[2, 3];
246            $point->EXTEND(-rw, q/+z/);  # extend an object
247            $point->can('z');   # true
248
249            my $new_class = Point->EXTEND('+z');  # extend a class
250            my $point_3d  = $new_class->new( x => 1, y => 2, z => 3 );
251            $point_3d->TYPE;  # Point !
252
253            my $point_4d = $new_class->EXTEND(\"Point4D", '+t');
254            $point_4d->TYPE;  # Point4D
255
256            my $origin = Point[]->EXTEND(-with => [qw/ Math::Role::Origin /]);
257
258           This feature has been included mostly because it's easy to
259           implement on top of the existing code for processing "use
260           MooX::Struct". Some subsets of this functionality are sane, such as
261           the ability to add traits to an object.  Others (like the ability
262           to add a new uninitialized, read-only attribute to an existing
263           object) are less sensible.
264
265           May be called as an instance or class method.
266
267       "BUILDARGS"
268           Moo internal fu.
269
270       "_data_printer"
271           Automatic pretty printing with Data::Printer.
272
273            use Data::Printer;
274            use MooX::Struct Point => [qw/ +x +y /];
275            my $origin = Point[];
276            p $origin;
277
278           Use Data::Printer 0.36 or above please.
279
280       With the exception of "FIELDS" and "TYPE", any of these can be
281       overridden using the standard way of specifying methods for structs.
282
283   Overloading
284       MooX::Struct overloads stringification and array dereferencing. Objects
285       always evaluate to true in a boolean context. (Even if they stringify
286       to the empty string.)
287

CAVEATS

289       Because you only get an alias for the struct class, you need to be
290       careful with some idioms:
291
292          my $point = Point3D->new(x => 1, y => 2, z => 3);
293          $point->isa("Point3D");   # false!
294          $point->isa( Point3D );   # true
295
296          my %args  = (...);
297          my $class = exists $args{z} ? "Point3D" : "Point";  # wrong!
298          $class->new(%args);
299
300          my $class = exists $args{z} ?  Point3D  :  Point ;  # right
301          $class->new(%args);
302

BUGS

304       Please report any bugs to
305       <http://rt.cpan.org/Dist/Display.html?Queue=MooX-Struct>.
306

AUTHOR

311       Toby Inkster <tobyink@cpan.org>.
312

COPYRIGHT AND LICENCE

314       This software is copyright (c) 2012-2013, 2017-2018 by Toby Inkster.
315
316       This is free software; you can redistribute it and/or modify it under
317       the same terms as the Perl 5 programming language system itself.
318

DISCLAIMER OF WARRANTIES

320       THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
321       WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
322       MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
323
324
325
326perl v5.28.1                      2018-06-09                   MooX::Struct(3)