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;


       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.

    Note: That on development perls that support use feature 'class', this
    is used instead of a blessed ARRAY reference. This implementation
    choice should be transparent to the end-user, as all the same features
    are supported.

 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.

    When using named constructors, individual fields may be declared as
    being optional. By preceeding the field name with a ? character, the
    constructor is instructed not to complain if a named parameter is not
    given for that field; instead it will be set to undef.

       struct Person => [qw( name age ?address )],
          named_constructor => 1;
    
       my $bob = Person( name => "Bob", age => 20 );
       # This is valid because 'address' is marked as optional

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

DATA::DUMP FILTER

    Since version 0.10.

    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.

       struct Colour => [qw( red green blue )];
    
       use Data::Dump;
    
       my %hash = ( col => Colour( 0.8, 0.5, 0.2 ) );
       Data::Dump::dd \%hash;
    
       # prints {col => main::Colour(0.8, 0.5, 0.2)}

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

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