# perldoc > Class::Struct

---
type: CommandReference
command: Class::Struct
mode: perldoc
section: 3pm
source: perldoc
---

## Quick Reference

- `use Class::Struct;` — load the module
- `struct( CLASS_NAME => [ ELEMENT_LIST ] );` — create array-based struct class
- `struct( CLASS_NAME => { ELEMENT_LIST } );` — create hash-based struct class
- `struct( ELEMENT_LIST );` — create struct class in current package
- `$obj = new Myobj;` — construct a struct object
- `$obj->element;` — fetch element value
- `$obj->element('value');` — assign to element
- `$obj = Myobj->new( name => 'value', ... );` — initialize during construction

## Name

Class::Struct - declare struct-like datatypes as Perl classes

## Synopsis

perl
use Class::Struct;

# Array-based struct (explicit class name)
struct( CLASS_NAME => [ ELEMENT_NAME => ELEMENT_TYPE, ... ] );

# Hash-based struct
struct( CLASS_NAME => { ELEMENT_NAME => ELEMENT_TYPE, ... } );

# Implicit class name (current package)
package CLASS_NAME;
use Class::Struct;
struct( ELEMENT_NAME => ELEMENT_TYPE, ... );

# Compile-time creation
use Class::Struct CLASS_NAME => [ELEMENT_NAME => ELEMENT_TYPE, ...];
use Class::Struct CLASS_NAME => {ELEMENT_NAME => ELEMENT_TYPE, ...};

# Example with multiple types
package Myobj;
use Class::Struct;
struct( s => '$', a => '@', h => '%', c => 'My_Other_Class' );
## Options (Element Types and Accessor Methods)

Each element in the struct is declared with a name and a type. The type string determines the accessor behavior:

- `'$'` — scalar element. Accessor returns the value; assignment with argument. Default undef.
- `'*$'` — scalar element. Accessor returns a reference to the element.
- `'@'` — array element. With no argument, returns reference to the whole array. With one argument (index), returns array element value. With two arguments (index, value), assigns to array element. Default `()`.
- `'*@'` — array element. Same as `'@'` but returns a reference to the array element rather than the value.
- `'%'` — hash element. With no argument, returns reference to the whole hash. With one argument (key), returns hash element value. With two arguments (key, value), assigns to hash element. Default `()`.
- `'*%'` — hash element. Same as `'%'` but returns a reference to the hash element.
- `'Class_Name'` — class element. Accessor takes an object of the named class (or subclass) and returns it. Default uninitialized.
- `'*Class_Name'` — class element. Accessor returns a reference to the element itself.

Accessor methods can be overridden by defining a subroutine of the same name in the package.

### Initializing with `new`

The constructor `new` can take a list of `element_name => value` pairs. The value for a scalar is a scalar; for an array, an array reference; for a hash, a hash reference; for a class element, an object or a hash reference of initializers for the nested struct's constructor.

### Class Creation at Compile Time

Using `use Class::Struct CLASS_NAME => ...` creates the class at compile time, making the order of events consistent with other Perl modules.

## Examples

### Example 1: Nested structs

perl
use Class::Struct;

struct( Rusage => {
    ru_utime => 'Timeval',
    ru_stime => 'Timeval',
});

struct( Timeval => [
    tv_secs  => '$',
    tv_usecs => '$',
]);

my $t = Rusage->new(
    ru_utime => Timeval->new(),
    ru_stime => Timeval->new()
);

$t->ru_utime->tv_secs(100);
$t->ru_utime->tv_usecs(0);
$t->ru_stime->tv_secs(5);
$t->ru_stime->tv_usecs(0);
### Example 2: Overriding accessor

perl
package MyObj;
use Class::Struct;
struct( 'MyObj', { count => '$', stuff => '%' } );

sub count {
    my $self = shift;
    if (@_) {
        die 'count must be nonnegative' if $_[0] < 0;
        $self->{'MyObj::count'} = shift;
        warn "Too many args to count" if @_;
    }
    return $self->{'MyObj::count'};
}

package main;
$x = new MyObj;
print "\$x->count(5) = ", $x->count(5), "\n";   # prints 5
print "\$x->count = ", $x->count, "\n";         # prints 5
print "\$x->count(-5) = ", $x->count(-5), "\n"; # dies
### Example 3: Initialization with nested class

perl
use Class::Struct;

struct Breed => {
    name  => '$',
    cross => '$',
};

struct Cat => [
    name     => '$',
    kittens  => '@',
    markings => '%',
    breed    => 'Breed',
];

my $cat = Cat->new(
    name     => 'Socks',
    kittens  => ['Monica', 'Kenneth'],
    markings => { socks => 1, blaze => "white" },
    breed    => Breed->new(name => 'short-hair', cross => 1),
    # or: breed => {name => 'short-hair', cross => 1},
);

print "Once a cat called ", $cat->name, "\n";
print "(which was a ", $cat->breed->name, ")\n";
print "had 2 kittens: ", join(' and ', @{$cat->kittens}), "\n";
## See Also

- [Class::Struct on perldoc.perl.org](https://perldoc.perl.org/Class::Struct)