diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 92 |
1 files changed, 92 insertions, 0 deletions
@@ -0,0 +1,92 @@ +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; + + + + 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. + + $ 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 + + 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. + +FUNCTIONS + struct $name => [ @fieldnames ], %opts + 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. + + readonly_struct $name => [ @fieldnames ], %opts + 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'. + +AUTHOR + Paul Evans <leonerd@leonerd.org.uk> + |