.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Struct::Dumb 3pm" .TH Struct::Dumb 3pm "2023-02-14" "perl v5.36.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" "Struct::Dumb" \- make simple lightweight record\-like structures .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Struct::Dumb; \& \& struct Point => [qw( x y )]; \& \& my $point = Point(10, 20); \& \& printf "Point is at (%d, %d)\en", $point\->x, $point\->y; \& \& $point\->y = 30; \& printf "Point is now at (%d, %d)\en", $point\->x, $point\->y; .Ve .PP .PP .Vb 1 \& struct Point3D => [qw( x y z )], named_constructor => 1; \& \& my $point3d = Point3D( z => 12, x => 100, y => 50 ); \& \& printf "Point3d\*(Aqs height is %d\en", $point3d\->z; .Ve .PP .PP .Vb 1 \& struct Point3D => [qw( x y z )], predicate => "is_Point3D"; \& \& my $point3d = Point3D( 1, 2, 3 ); \& \& printf "This is a Point3D\en" if is_Point3D( $point3d ); .Ve .PP .PP .Vb 1 \& use Struct::Dumb qw( \-named_constructors ) \& \& struct Point3D => [qw( x y z )]; \& \& my $point3d = Point3D( x => 100, z => 12, y => 50 ); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\f(CW\*(C`Struct::Dumb\*(C'\fR creates record-like structure types, similar to the \f(CW\*(C`struct\*(C'\fR keyword in C, \*(C+ or C#, or \f(CW\*(C`Record\*(C'\fR 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. .PP 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. .PP 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 \f(CW\*(C`croak\*(C'\fR if passed the wrong number of arguments, as will attempts to refer to fields that don't exist. Accessor-mutators will \f(CW\*(C`croak\*(C'\fR 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 \&\f(CW\*(C`CODE\*(C'\fR reference by passing argument values directly to the accessor.) .PP .Vb 2 \& $ perl \-E \*(Aquse Struct::Dumb; struct Point => [qw( x y )]; Point(30)\*(Aq \& usage: main::Point($x, $y) at \-e line 1 \& \& $ perl \-E \*(Aquse Struct::Dumb; struct Point => [qw( x y )]; Point(10,20)\->z\*(Aq \& main::Point does not have a \*(Aqz\*(Aq field at \-e line 1 \& \& $ perl \-E \*(Aquse Struct::Dumb; struct Point => [qw( x y )]; Point(1,2)\->x(3)\*(Aq \& main::Point\->x invoked with arguments at \-e line 1. .Ve .PP Objects in this class are (currently) backed by an \s-1ARRAY\s0 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 \s-1ARRAY\s0 will throw an exception. .PP \&\fINote\fR: That on development perls that support \f(CW\*(C`use feature \*(Aqclass\*(Aq\*(C'\fR, this is used instead of a blessed \s-1ARRAY\s0 reference. This implementation choice should be transparent to the end-user, as all the same features are supported. .SS "\s-1CONSTRUCTOR FORMS\s0" .IX Subsection "CONSTRUCTOR FORMS" The \f(CW\*(C`struct\*(C'\fR and \f(CW\*(C`readonly_struct\*(C'\fR declarations create two different kinds of constructor function, depending on the setting of the \f(CW\*(C`named_constructor\*(C'\fR 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. .PP This option can be specified to the \f(CW\*(C`struct\*(C'\fR and \f(CW\*(C`readonly_struct\*(C'\fR functions. It defaults to false, but it can be set on a per-package basis to default true by supplying the \f(CW\*(C`\-named_constructors\*(C'\fR option on the \f(CW\*(C`use\*(C'\fR statement. .PP When using named constructors, individual fields may be declared as being optional. By preceeding the field name with a \f(CW\*(C`?\*(C'\fR character, the constructor is instructed not to complain if a named parameter is not given for that field; instead it will be set to \f(CW\*(C`undef\*(C'\fR. .PP .Vb 2 \& struct Person => [qw( name age ?address )], \& named_constructor => 1; \& \& my $bob = Person( name => "Bob", age => 20 ); \& # This is valid because \*(Aqaddress\*(Aq is marked as optional .Ve .SH "FUNCTIONS" .IX Header "FUNCTIONS" .SS "struct" .IX Subsection "struct" .Vb 3 \& struct $name => [ @fieldnames ], \& named_constructor => (1|0), \& predicate => "is_$name"; .Ve .PP 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. .PP Takes the following options: .IP "named_constructor => \s-1BOOL\s0" 4 .IX Item "named_constructor => BOOL" Determines whether the structure will take positional or named arguments. .IP "predicate => \s-1STR\s0" 4 .IX Item "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. .SS "readonly_struct" .IX Subsection "readonly_struct" .Vb 2 \& readonly_struct $name => [ @fieldnames ], \& ... .Ve .PP Similar to \*(L"struct\*(R", but instances of this type are immutable once constructed. The field accessor methods will not be marked with the \&\f(CW\*(C`:lvalue\*(C'\fR attribute. .PP Takes the same options as \*(L"struct\*(R". .SH "DATA::DUMP FILTER" .IX Header "DATA::DUMP FILTER" \&\fISince version 0.10.\fR .PP 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. .PP .Vb 1 \& struct Colour => [qw( red green blue )]; \& \& use Data::Dump; \& \& my %hash = ( col => Colour( 0.8, 0.5, 0.2 ) ); \& Data::Dump::dd \e%hash; \& \& # prints {col => main::Colour(0.8, 0.5, 0.2)} .Ve .SH "NOTES" .IX Header "NOTES" .SS "Allowing \s-1ARRAY\s0 dereference" .IX Subsection "Allowing ARRAY dereference" The way that forbidding access to instances as if they were \s-1ARRAY\s0 references is currently implemented uses an internal method on the generated structure class called \f(CW\*(C`_forbid_arrayification\*(C'\fR. If special circumstances require that this exception mechanism be bypassed, the method can be overloaded with an empty \f(CW\*(C`sub {}\*(C'\fR body, allowing the struct instances in that class to be accessed like normal \s-1ARRAY\s0 references. For good practice this should be limited by a \f(CW\*(C`local\*(C'\fR override. .PP For example, Devel::Cycle needs to access the instances as plain \s-1ARRAY\s0 references so it can walk the data structure looking for reference cycles. .PP .Vb 1 \& use Devel::Cycle; \& \& { \& no warnings \*(Aqredefine\*(Aq; \& local *Point::_forbid_arrayification = sub {}; \& \& memory_cycle_ok( $point ); \& } .Ve .SH "TODO" .IX Header "TODO" .IP "\(bu" 4 Consider adding an \f(CW\*(C`coerce_hash\*(C'\fR option, giving name of another function to convert structs to key/value pairs, or a \s-1HASH\s0 ref. .SH "AUTHOR" .IX Header "AUTHOR" Paul Evans