GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  STRUCT::DUMB (3)

.ds Aq ’

NAME

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

CONTENTS

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 "Point3ds height is %d\n", $point3d->z;





 struct Point3D => [qw( x y z )], predicate => "is_Point3D";

 my $point3d = Point3D( 1, 2, 3 );

 printf "This is a Point3D\n" if is_Point3D( $point3d );





 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. Accessor-mutators will croak 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 CODE reference by passing argument values directly to the accessor.)



 $ 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

 $ perl -E use Struct::Dumb; struct Point => [qw( x y )]; Point(1,2)->x(3)
 main::Point->x invoked with arguments at -e line 1.



Objects in this class are (currently) backed by an ARRAY 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 ARRAY will throw an exception.

    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



   struct $name => [ @fieldnames ],
      named_constructor => (1|0),
      predicate         => "is_$name";



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.
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.

    readonly_struct



   readonly_struct $name => [ @fieldnames ],
      ...



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.

NOTES

    Allowing ARRAY dereference

The way that forbidding access to instances as if they were ARRAY references is currently implemented uses an internal method on the generated structure class called _forbid_arrayification. If special circumstances require that this exception mechanism be bypassed, the method can be overloaded with an empty sub {} body, allowing the struct instances in that class to be accessed like normal ARRAY references. For good practice this should be limited by a local override.

For example, Devel::Cycle needs to access the instances as plain ARRAY references so it can walk the data structure looking for reference cycles.



 use Devel::Cycle;

 {
    no warnings redefine;
    local *Point::_forbid_arrayification = sub {};

    memory_cycle_ok( $point );
 }



TODO

o Consider adding an coerce_hash option, giving name of another function to convert structs to key/value pairs, or a HASH ref.

AUTHOR

Paul Evans <leonerd@leonerd.org.uk>
Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 STRUCT::DUMB (3) 2016-04-03

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.