NAME

VERSION

SYNOPSIS

 use Class::Generate qw(class subclass delete_class);

 # Declare class Class_Name, with the following types of members:
 class
     Class_Name => [
         s => '$',                      # scalar
         a => '@',                      # array
         h => '%',                      # hash
         c => 'Class',                  # Class
         c_a => '@Class',               # array of Class
         c_h => '%Class',               # hash of Class
         '&m' => 'body',                # method
     ];

 # Allocate an instance of class_name, with members initialized to the
 # given values (pass arrays and hashes using references).
 $obj = Class_Name->new ( s => scalar,
                          a => [ values ],
                          h => { key1 => v1, ... },
                          c => Class->new,
                          c_a => [ Class->new, ... ],
                          c_h => [ key1 => Class->new, ... ] );

                # Scalar type accessor:
 $obj->s($value);                       # Assign $value to member s.
 $member_value = $obj->s;               # Access member's value.

                # (Class) Array type accessor:
 $obj->a([value1, value2, ...]);        # Assign whole array to member.
 $obj->a(2, $value);                    # Assign $value to array member 2.
 $obj->add_a($value);                   # Append $value to end of array.
 @a = $obj->a;                          # Access whole array.
 $ary_member_value = $obj->a(2);        # Access array member 2.
 $s = $obj->a_size;                     # Return size of array.
 $value = $obj->last_a;                 # Return last element of array.

                # (Class) Hash type accessor:
 $obj->h({ k_1=>v1, ..., k_n=>v_n })    # Assign whole hash to member.
 $obj->h($key, $value);                 # Assign $value to hash member $key.
 %hash = $obj->h;                       # Access whole hash.
 $hash_member_value = $obj->h($key);    # Access hash member value $key.
 $obj->delete_h($key);                  # Delete slot occupied by $key.
 @keys = $obj->h_keys;                  # Access keys of member h.
 @values = $obj->h_values;              # Access values of member h.

 $another = $obj->copy;                 # Copy an object.
 if ( $obj->equals($another) ) { ... }  # Test equality.

 subclass s  => [ <more members> ], -parent => 'class_name';

DESCRIPTION

CPAN contains similar packages. Why another? Because object-oriented programming, especially in a dynamic language like Perl, is a complicated endeavor. I wanted a package that would work very hard to catch the errors you (well, I anyway) commonly make. I wanted a package that could help me enforce the contract of object-oriented programming. I also wanted it to get out of my way when I asked.

THE CLASS FUNCTION

    class Class_Name => [ specification ];      # Objects are array-based.
    class Class_Name => { specification };      # Objects are hash-based.

The result is a Perl 5 class, in a package "Class_Name". This package must not exist when "class" is invoked.

An array-based object is faster and smaller. A hash-based object is more flexible. Subsequent sections explain where and why flexibility matters.

The specification consists of zero or more name/value pairs. Each pair declares one member of the class, with the given name, and with attributes specified by the given value.

MEMBER TYPES

    class Person => [ name => '$', age => '$' ];

creates a class named "Person" with two scalar members, "name" and "age".

If the type is followed by an identifier, the identifier is assumed to be a class name, and the member is restricted to a blessed reference of the class (or one of its subclasses), an array whose elements are blessed references of the class, or a hash whose keys are strings and whose values are blessed references of the class. For scalars, the "$" may be omitted; i.e., "Class_Name" and $Class_Name are equivalent. The class need not be declared using the "Class::Generate" package.

CREATING INSTANCES

    class Person => [ name => '$', age => '$' ];
    $p = Person->new;                   # Neither name nor age is defined.
    $q = Person->new( name => 'Jim' );  # Only name is defined.
    $r = Person->new( age => 32 );      # Only age is defined.

ACCESSOR METHODS

    $p = Person->new;
    $p->age(32);                # Sets age member to 32.
    print $p->age;              # Prints 32.

    class Person => [
        name => '$',
        spouse => 'Person'      # Works, even though Person
    ];                          # isn't yet defined.
    $p = Person->new(name => 'Simon Bar-Sinister');
    $q = Person->new(name => 'Polly Purebred');
    $r = Person->new(name => 'Underdog');
    $r->spouse($q);                             # Underdog marries Polly.
    print $r->spouse->name;                     # Prints 'Polly Purebred'.
    print "He's married" if defined $p->spouse; # Prints nothing.
    $p->spouse('Natasha Fatale');               # Croaks.

    class Person => [ name => '$', kids => '@Person' ];
    $p = Person->new;
    $p->add_kids(Person->new(name => 'Heckle'),
                 Person->new(name => 'Jeckle'));
    print $p->kids_size;        # Prints 1.
    $p->kids([Person->new(name => 'Bugs Bunny'),
              Person->new(name => 'Daffy Duck')]);
    $p->add_kids(Person->new(name => 'Yosemite Sam'),
                 Person->new(name => 'Porky Pig'));
    print $p->kids_size;        # Prints 3.
    $p->kids(2, Person->new(name => 'Elmer Fudd'));
    print $p->kids(2)->name;    # Prints 'Elmer Fudd'.
    @kids = $p->kids;           # Get all the kids.
    print $p->kids($p->kids_size)->name; # Prints 'Porky Pig'.
    print $p->last_kids->name;     # So does this.

    class Person => [ name => '$', kids => '%Kid_Info' ];
    class Kid_Info => [
        grade  => '$',
        skills => '@'
    ];
    $f = new Person(
        name => 'Fred Flintstone',
        kids => { Pebbles => new Kid_Info(grade => 1,
                                          skills => ['Programs VCR']) }
    );
    print $f->kids('Pebbles')->grade;   # Prints 1.
    $b = new Kid_Info;
    $b->grade('Kindergarten');
    $b->skills(['Knows Perl', 'Phreaks']);
    $f->kids('BamBam', $b);
    print join ', ', $f->kids_keys;     # Prints "Pebbles, BamBam",
                                        # though maybe not in that order.

COMMON METHODS

OBJECT INSTANCE METHODS

    $p = $o->copy;

    if ( $o1->equals($o2) ) { ... }

ADVANCED MEMBER SPECIFICATIONS

type=>string

If you use a hash reference for a member's value, you must use the "type" attribute to specify its type:

    scalar_member => { type => '$' }
    

required=>boolean

If the "required" attribute is true, the member must be passed each time the class' constructor is invoked:

    class Person => [ name => { type => '$', required => 1 } ];
    Person->new ( name => 'Wilma' );    # Valid
    Person->new;                        # Invalid
    

Also, you may not call "undef_name" for the member.

default=>value

The "default" attribute provides a default value for a member if none is passed to the constructor:

    class Person => [ name => '$',
                      job => { type => '$',
                               default => "'Perl programmer'" } ];
    $p = Person->new(name => 'Larry');
    print $p->job;              # Prints 'Perl programmer'.
    $q = Person->new(name => 'Bjourne', job => 'C++ programmer');
    print $q->job;              # Unprintable.
    

The value is treated as a string that is evaluated when the constructor is invoked.

For array members, use a string that looks like a Perl expression that evaluates to an array reference:

    class Person => {
        name => '$',
        lucky_numbers => { type => '@', default => '[42, 17]' }
    };
    class Silly => {
        UIDs => {               # Default value is all UIDs
            type => '@',        # currently in /etc/passwd.
            default => 'do {
                local $/ = undef;
                open PASSWD, "/etc/passwd";
                [ map {(split(/:/))[2]} split /\n/, <PASSWD> ]
            }'
        }
    };
    

Specify hash members analogously.

The value is evaluated each time the constructor is invoked. In "Silly", the default value for "UIDs" can change between invocations. If the default value is a reference rather than a string, it is not re-evaluated. In the following, default values for "e1" and "e2" are based on the members of @default_value each time "Example->new" is invoked, whereas "e3"'s default value is set when the "class" function is invoked to define "Example":

    @default_value = (1, 2, 3);
    $var_name = '@' . __PACKAGE__ . '::default_value';
    class Example => {
        e1 => { type => '@', default => "[$var_name]" },
        e2 => { type => '@', default => \@default_value },
        e3 => { type => '@', default => [ @default_value ] }
    };
    Example->new;       # e1, e2, and e3 are all identical.
    @default_value = (10, 20, 30);
    Example->new;       # Now only e3 is (1, 2, 3).
    

There are two more things to know about default values that are strings. First, if a member is typed, the "class" function evaluates its (string-based) default value to ensure that it is of the correct type for the member. Be aware of this if your default value has side effects (and see "Checking Default Value Types").

Second, the context of the default value is the "new()" method of the package generated to implement your class. That's why "e1" in "Example", above, needs the name of the current package in its default value.

post=>code

The value of this attribute is a string of Perl code. It is executed immediately after the member's value is modified through its accessor. Within "post" code, you can refer to members as if they were Perl identifiers. For instance:

    class Person => [ age => { type => '$',
                               post => '$age *= 2;' } ];
    $p = Person->new(age => 30);
    print $p->age;      # Prints 30.
    $p->age(15);
    print $p->age;      # Prints 30 again.
    

The trailing semicolon used to be required, but everyone forgot it. As of version 1.06 it's optional: '$age*=2' is accepted and equivalent to '$age*=2;' (but see "BUGS").

You reference array and hash members as usual (except for testing for definition; see "BUGS"). You can reference individual elements, or the whole list:

    class Foo => [
        m1 => { type => '@', post => '$m1[$#m1/2] = $m2{xxx};' },
        m2 => { type => '%', post => '@m1 = keys %m2;' }
    ];
    

You can also invoke accessors. Prefix them with a "&":

    class Bar => [
        m1 => { type => '@', post => '&undef_m1;' },
        m2 => { type => '%', post => '@m1 = &m2_keys;' }
    ];
    $o = new Bar;
    $o->m1([1, 2, 3]);          # m1 is still undefined.
    $o->m2({a => 1, b => 2});   # Now m1 is qw(a b).
    

pre=>code

The "pre" key is similar to the "post" key, but it is executed just before an member is changed. It is not executed if the member is only accessed. The "pre" and "post" code have the same scope, which lets you share variables. For instance:

    class Foo => [
        mem => { type => '$', pre => 'my $v = $mem;', post => 'return $v;' }
    ];
    $o = new Foo;
    $p = $o->mem(1);    # Sets $p to undef.
    $q = $o->mem(2);    # Sets $q to 1.
    

is a way to return the previous value of "mem" any time it's modified (but see "NOTES").

assert=>expression

The value of this key should be a Perl expression that evaluates to true or false. Use member names in the expression, as with "post". The expression will be tested any time the member is modified through its accessors. Your code will "croak" if the expression evaluates to false. For instance,

    class Person => [
        name => '$',
        age => { type => '$',
                 assert => '$age =~ /^\d+$/ && $age < 200' } ];
    

ensures the age is reasonable.

The assertion is executed after any "post" code associated with the member.

private=>boolean

If the "private" attribute is true, the member cannot be accessed outside the class; that is, it has no accessor functions that can be called outside the scope of the package defined by "class". A private member can, however, be accessed in "post", "pre", and "assert" code of other members of the class.

protected=>boolean

If the "protected" attribute is true, the member cannot be accessed outside the class or any of its subclasses. A protected member can, however, be accessed in "post", "pre", and "assert" code of other members of the class or its subclasses.

readonly=>boolean

If this attribute is true, then the member cannot be modified through its accessors. Users can set the member only by using the class constructor. The member's accessor that is its name can retrieve but not set the member. The "undef_"name accessor is not defined for the member, nor are other accessors that might modify the member. (Code in "post" can set it, however.)

key=>boolean

If this attribute is true, then the member participates in equality tests. See "Equals".

nocopy=>value

The "nocopy" attribute gives you some per-member control over how the "copy" method. If "nocopy" is false (the default), the original's value is copied as described in "Copy". If "nocopy" is true, the original's value is assigned rather than copied; in other words, the copy and the original will have the same value if the original's value is a reference.

AFFECTING THE CONSTRUCTOR

required=>list of constraints

This is another (and more general) way to require that parameters be passed to the constructor. Its value is a reference to an array of constraints. Each constraint is a string that must be an expression composed of Perl logical operators and member names. For example:

    class Person => {
        name   => '$',
        age    => '$',
        height => '$',
        weight => '$',
        new => { required => ['name', 'height^weight'] }
    };
    

requires member "name", and exactly one of "height" or "weight". Note that the names are not prefixed with "$", "@", or "%".

Specifying a list of constraints as an array reference can be clunky. The "class" function also lets you specify the list as a string, with individual constraints separated by spaces. The following two strings are equivalent to the above "required" attribute:

    'name height^weight'
    'name&(height^weight)'
    

However, 'name & (height ^ weight)' would not work. The "class" function interprets it as a five-member list, four members of which are not valid expressions.

This equivalence between a reference to array of strings and a string of space-separated items is used throughout "Class::Generate". Use whichever form works best for you.

post=>string of code

The "post" key is similar to the "post" key for members. Its value is code that is inserted into the constructor after parameter values have been assigned to members. The "class" function performs variable substitution.

The "pre" key is not recognized in "new".

assert=>expression

The "assert" key's value is inserted just after the "post" key's value (if any). Assertions for members are inserted after the constructor's assertion.

comment=>string

This attribute's value can be any string. If you save the class to a file (see "Saving the Classes"), the string is included as a comment just before the member's methods.

style=>style definition

The "style" attribute controls how parameters are passed to the class' constructor. See "PARAMETER PASSING STYLES".

ADDING METHODS

Add methods using an member of the form "'&name'=>body", where "body" is a string containing valid Perl code. This yields a method "name" with the specified "body". For object methods, the "class" function performs variable substitution as described in "ADVANCED MEMBER SPECIFICATIONS". For example,

    class Person => [ first_name => '$',
                      last_name  => '$',
                      '&name'    => q{return "$first_name $last_name";}
    ];
    $p = Person->new(first_name => 'Barney', last_name => 'Rubble');
    print $p->name;     # Prints "Barney Rubble".

    class Stack => [    # Venerable example.
        top_e    => { type => '$', private => 1, default => -1 },
        elements => { type => '@', private => 1, default => '[]' },
        '&push' => '$elements[++$top_e] = $_[0];',
        '&pop'  => '$top_e--;',
        '&top'  => 'return $elements[$top_e];'
    ];

A method has the following attributes which, like members, are specified as a hash reference:

body=>code

This attribute specifies the method's body. It is required if other attributes are given.

private=>boolean

The method cannot be accessed outside the class.

    class Example => [
        m1 => '$',
        m2 => '$',
        '&public_interface' => q{return &internal_algorithm;},
        '&internal_algorithm' => { private => 1,
                                   body => q{return $m1 + 4*$m2;} }
    ];
    $e = Example->new(m1 => 2, m2 => 4);
    print $e->public_interface;         # Prints 18.
    print $e->internal_algorithm;       # Run-time error.
    

protected=>boolean

If true, the method cannot be accessed outside the class or any of its subclasses.

class_method=>boolean

If true, the method applies to classes rather than objects. Member name substitution is not performed within a class method. You can, however, use accessors, as usual:

    class Foo => [
        m1 => '$', m2 => '@',
        '&to_string' => {
            class_method => 1,
            body => 'my $o = $_[0];
                     return $o->m1 . "[" . join(",", $o->m2) . "]"';
        }
    ];
    $f = Foo->new(m1 => 1, m2 => [2, 3]);
    print Foo->to_string($f);   # Prints "1[2,3]"
    

You can also call class methods from within instance and class methods. Use the "Class->method" syntax.

Currently, a class method may be public or private, but not protected.

objects=>list of object instance expressions

This attribute is only used for class methods. It is needed when the method refers to a private or protected member or method. Its argument is a list, each element of which is a Perl expression that occurs in the body of the class method. The expression must evaluate to an instance of the class. It will be replaced by an appropriate reference to the private member or method. For example:

    class Bar => [
        mem1 => '$',
        mem2 => { type => '@', private => 1 },
        '&meth1' => 'return $mem1 + $#mem2;',
        '&meth2' => { private => 1,
                      body    => 'return eval join "+", @mem2;' },
        '&cm1' => { class_method => 1,
                    objects => '$o',
                    body => 'my $o = Bar->new(m1 => 8);
                             $o->mem2([4, 5, 6]);
                             return $o->meth2;' },
        '&cm2' => { class_method => 1,
                    objects => ['$o', 'Bar->new(m1 => 3)'],
                    body => 'my $o => Bar->new(m1 => 8);
                             $o->mem2(0, Bar->new(m1 => 3)->meth2);
                             return $o;' }
    ];
    

The "objects" attribute for "cm1" tells "class" to treat all occurrences of the string $o as an instance of class "Bar", giving the expression access to private members and methods of "Bar". The string can be an arbitrary expression, as long as it's valid Perl and evaluates to an instance of the class; hence the use of "Bar->new(m1 => 3)" in "cm2". The string must match exactly, so "Bar->new(m1 => 8)" is not replaced.

You can add a method named &equals to provide your own definition of equality. An example:

    $epsilon = 0.1e-20;
    class Imaginary_No => {                     # Treat floating-point
        real => '$',                            # values as equal if their
        imag => '$',                            # difference is less than
        '&equals' => qq|my \$o = \$_[0];        # some epsilon.
                        return abs(\$real - \$o->real) < $epsilon &&
                               abs(\$imag - \$o->imag) < $epsilon;|
    };

If you declare &equals to be private, you create a class whose instances cannot be tested for equality except within the class.

THE SUBCLASS FUNCTION

    subclass S => [ specification ], -parent => P

declares a package "s", and a constructor function "new", just like "class"; but "s->new" yields a blessed reference that inherits from "P". You can use all the attributes discussed above in the specification of a subclass. (Prior to version 1.02 you specified the parent using "parent=>P", but this is deprecated in favor of "-parent=>P".)

As of version 1.05, the "class" function also accepts "-parent". In other words,

    class S => [ specification ], -parent => P
    subclass S => [ specification ], -parent => P

are equivalent.

Class "P" need not have been defined using the "class" or "subclass" function. It must have a constructor named "new", however, or at least be an ancestor of a class that does.

A subclass may be either an array or hash reference. Its parent must be the same type of reference.

You can inherit from multiple classes, providing all are hash-based ("Class::Generate" does not support multiple inheritance for array-based classes). Just list more than one class as the value of "parent":

    subclass S => { specification }, -parent => 'P1 P2 P3';

Elements of the @ISA array for package "S" appear in the order you list them. This guarantee should let you determine the order in which methods are invoked.

The subclass constructor automatically calls its parent constructor. It passes to the parent constructor any parameters that aren't members of the subclass.

Subclass members with the same name as that of their parent override their parent methods.

You can access a (non-private) member or method of a parent within user-defined code in the same way you access members or methods of the class:

    class Person => [
        name => '$',
        age => '$',
        '&report' => q{return "$name is $age years old"}
    ];
    subclass Employee => [
        job_title => '$',
        '&report' => q{return "$name is $age years old and is a $job_title";}
    ], -parent => 'Person';
    subclass Manager => [
        workers => '@Employee',
        '&report' => q{return "$name is $age years old, is a $job_title, " .
                              "and manages " . (&workers_size + 1) . " people";}
    ], -parent => 'Employee';

If a class has multiple parents, and these parents have members whose names conflict, the name used is determined by a depth-first search of the parents.

The previous example shows that a subclass may declare a member or method whose name is already declared in one of its ancestors. The subclass declaration overrides any ancestor declarations: the "report" method behaves differently depending on the class of the instance that invokes it.

Sometimes you override an ancestor's method to add some extra functionality. In that situation, you want the overriding method to invoke the ancestor's method. All user-defined code in "Class::Generate" has access to a variable $self, which is a blessed reference. You therefore can use Perl's "SUPER::" construct to get at ancestor methods:

    class Person => [
        name => '$',
        age => '$',
        '&report' => q{return &name . ": $age years old"}
    ];
    subclass Employee => [
        job_title => '$',
        '&report' => q{return $self->SUPER::report . "; job: $job_title";}
    ], -parent => 'Person';
    subclass Manager => [
        workers => '@Employee',
        '&report' => q{return $self->SUPER::report . "; manages: " .
                              (&workers_size + 1) . " people";}
    ], -parent => 'Employee';

Currently, you cannot access a protected method of an ancestor this way. The following code will generate a run-time error:

    class Foo => [
        '&method' => { protected => 1, body => '...' },
    ];
    subclass Bar => [
        '&method' => { protected => 1, body => '$self->SUPER::method;' }
    ], -parent => 'Foo';

THE DELETE_CLASS FUNCTION

    class Person => [ name => '$' ];
    delete_class 'Person';                       # Nah...
    class Name => [ last => '$', first => '$' ]; # ... let's really encapsulate.
    class Person => [ name = 'Name' ];           # That's better.

FLAGS

-use=>list

Your "pre" or "post" code, or your methods, may want to use functions declared in other packages. List these packages as the value of the "-use" flag. For example, suppose you are creating a class that does date handling, and you want to use functions in the "Time::Local" and "Time::localtime" packages. Write the class as follows:

    class Date_User => [ ... ],
        -use => 'Time::Local Time::localtime';
    

Any code you add to "Date_User" can now access the time functions declared in these two packages.

To import functions, you need to use the array reference form:

    class Foo => [ ... ],
        -use => ["FileHandle 'autoflush'"];
    

Otherwise, the "class" function would assume you want to use two packages, "Filehandle" and 'autoflush'.

-class_vars=>list

A class can have class variables, i.e., variables accessible to all instances of the class as well as to class methods. Specify class variables using the "-class_vars" flag. For example, suppose you want the average age of all Persons:

    $compute_average_age = '$n++; $total += $age; $average = $total/$n;';
    class Person => [
        name => '$',
        age  => { type => '$', required => 1, readonly => 1 },
        new  => { post => $compute_average_age }
    ],
        -class_vars => '$n $total $average';
    $p = Person->new(age => 24);                # Average age is now 24.
    $q = Person->new(age => 30);                # Average age is now 27.
    

You can also provide an initial value for class variables. Specify the value of "-class_vars" as an array reference. If any member of this array is a hash reference, its members are taken to be variable name/initial value pairs. For example:

    class Person => [ name => '$',
                      age => { type => '$', required => 1, readonly => 1 },
                      new => { post => $compute_average_age }
    ],
          -class_vars => [ { '$n' => 0 },
                           { '$total' => 0 },
                           '$average' ];
    

"Class::Generate" evaluates the initial value as part of evaluating your class. This means you must quote any strings:

    class Room => [
    ],
          -class_vars => [ { '$board' => "'white'" } ];
    

-virtual=>boolean

A virtual class is a class that cannot be instantiated, although its descendents can. Virtual classes are useful as modeling aids and debugging tools. Specify them using the "-virtual" flag:

    class Parent =>   [ e => '$' ], -virtual => 1;
    subclass Child => [ d => '$' ], -parent => 'Parent';
    Child->new;         # This is okay.
    Parent->new;        # This croaks.
    

There is no built-in way to specify a virtual method, but the following achieves the desired effect:

    class Foo => [ '&m' => 'die "m is a virtual method";' ];
    

-comment=>string

The string serves as a comment for the class.

-options=>{ options }

This flag lets you specify options that alter the behavior of "Class::Generate". See "OPTIONS".

-exclude=>string

Sometimes it isn't appropriate for a user to be able to copy an object. And sometimes testing the equality of two object instances makes no sense. For these and other situations, you have some control over the automatically generated methods for each class.

You control method generation using the "-exclude" flag. Its value is a string of space-separated regular expressions. A method is included if it does not match any of the regular expressions. For example, a person has a unique social security number, so you might want a class where a person can't be copied:

    class Person => [
        name => '$',
        ssn  => { type => '$', readonly => 1 }
    ], -exclude => '^copy$';
    $o = Person->new name => 'Forrest Gump', ssn => '000-00-0000';
    $p = $o->copy;      # Run-time error.
    

The "-exclude" flag can describe a whole range of esoteric restrictions:

    class More_Examples => [
        mem1 => { type => '$', required => 1 },
        mem2 => { type => '@', required => 1 },
        mem3 => '%',
        new => { post => '%mem3 = map { $_ => $mem1 } @mem2' }
    ], -exclude => 'undef_ mem2_size mem3';
    $o = More_Examples->new mem1 => 1, mem2 => [2, 3, 4];
    @keys = $o->mem3_keys;      # Run-time error.
    $o->undef_mem1;             # Ditto.
    print $o->last_mem2;        # This works as expected.
    print $o->mem2_size;        # But this blows up.
    

In "More_Examples", it isn't possible to undefine a member. The size of "mem2" can't be determined. And "mem3" is effectively private (it can't even be accessed from class methods).

PARAMETER PASSING STYLES

Key/Value

This is the default. Parameters are passed using the "name=>value" form, as shown in previous examples. Specify it as "style=>'key_value'" if you want to be explicit.

Positional

Parameters are passed based on a positional order you specify. For example:

    class Foo => [ e1 => '$', e2 => '@', e3 => '%',
                   new => { style => 'positional e1 e2 e3' } ];
    $obj = Foo->new(1);                 # Sets e1 to 1.
    $obj = Foo->new(1, [2,3]);          # Ditto, and sets e2 to (2,3).
    my %hash = (foo => 'bar');
    $obj = Foo->new(1,                  # Ditto,
                    [2, 3],             # ditto,
                    {%hash});           # and sets e3 to %hash.
    

You must list all non-private members, although you do not have to include all of them in every invocation of "new". Also, if you want to set "e1" and "e3" but not "e2", you can give "undef" as "e2"'s value:

    $obj = Foo->new(1, undef, { e3_value => 'see what I mean?' });
    

Mixed Styles

Parameters are passed mixing the positional and key/value styles. The values following "mix" are the names of the positional parameters, in the order in which they will be passed. This style is useful when certain parameters are "obvious". For example:

    class Person => [
        first_name => { type => '$', required => 1 },
        last_name  => { type => '$', required => 1 },
        favorite_language => '$',
        favorite_os       => '$',
        new => { style => 'mix first_name last_name' }
    ];
    $obj = Person->new('Joe',  'Programmer', favorite_language => 'Perl');
    $obj = Person->new('Sally', 'Codesmith', favorite_os       => 'Linux');
    

The positional parameters need not be required, but they must all be given if you want to set any members passed as key/value parameters.

Your Own Parameter Handling

Finally, sometimes you want a constructor whose parameters aren't the members. Specify such classes using "own". Access the parameters through @_, as usual in Perl:

    class Person => [
        first => { type => '$', private => 1 },
        last  => { type => '$', private => 1 },
        new   => { style => 'own',
                   post => '($first, $last) = split /\s+/, $_[0];' },
        '&name' => q|return $last . ', ' . $first;|
    ];
    $p = Person->new('Fred Flintstone');
    print $p->name;                     # Prints 'Flintstone, Fred'.
    

If "own" is followed by a space, and the class has a parent, everything after the space is treated as a space-separated list of Perl expressions, and these expressions are passed to the superclass constructor. The expressions are passed in the order given. Thus:

    subclass Child => [
        grade => '$',
        new   => { style => 'own $_[0]', post => '$grade = $_[1];' }
    ], -parent => 'Person';
    

Now you can create a "Child" by passing the grade as the second parameter, and the name as the first:

    $c = Child->new('Penny Robinson', 5);
    

The "own" style causes the "type", "required", and "default" member specifications to be ignored.

If you use styles other than "key_value", you must be aware of how a subclass constructor passes parameter to its superclass constructor. "Class::Generate" has some understanding of styles, but not all combinations make sense, and for those that do, you have to follow certain conventions. Here are the rules for a subclass "S" with parent "P":

1.

If "S"'s constructor uses the "key_value" style, "P"'s constructor must use the "key_value" or "own" style. The parameters are treated as a hash; "P"'s constructor receives a hash with all elements indexed by nonprivate members of "S" deleted. "P"'s constructor must not expect the hash elements to be passed in a prespecified order.

2.

If "S"'s constructor uses the "positional" style, "P"'s constructor may use any style. If "S" has "n" nonprivate members, then parameters 0..n-1 are used to assign members of "S". Remaining parameters are passed to "P::new", in the same order they were passed to "S::new".

3.

If "S"'s constructor uses the "mix" style, "P"'s constructor may use any style. If "S" has n nonprivate members, of which p are passed by position, then parameters 0..(p-1)+2*(n-p) are used to assign members of "S". Remaining parameters are passed to "P::new", in the same order they were passed to "S::new".

4.

If "S"'s constructor uses the "own" style, you are responsible for ensuring that it passes parameters to "P"'s constructor in the correct style.

OPTIONS

1.

Via the "-options" flag, the value of which is a hash reference containing the individual options. This affects an individual class.

2.

By setting a variable declared in "Class::Generate". The variable has the same name as the option. This affects all subsequently generated classes except those where the option is explicitly overridden via the "-options" flag. You may export these variables, although they are not exported by default.

The following sections list the options that "class" and "subclass" recognize.

    class Person => [
        name    => '$',
        parents => '@Person',
        new     => { style => 'positional name parents' }
    ];
    $p = Person->new('Will Robinson');
    $p->parents( [ Person->new('John Robinson'),
                   Person->new('Maureen Robinson') ] );

    class Person => [
        name    => '$',
        parents => '@Person',
        new     => { style => 'positional name parents' }
    ],
        -options => { accept_refs => 0 };
    $p = Person->new('Will Robinson');
    $p->add_parents( Person->new('Maureen Robinson'),
                     Person->new('John Robinson') );

    class Foo => {
        array => '@'
    };
    subclass Bar => {
        bar_mem => {
            type => '$',
            pre => 'print "array_size is ", $this->array_size;'
        }
    }, -parent => 'Foo',
       -options => { instance_var => 'this' };

    class C => { ... };
    $o = C->new;        # Always works.
    $p = $o->new;       # Works if nfi option is true.

DIAGNOSTICS

Classes that contain user defined code can yield Perl errors and warnings. These messages are prefixed by one of the following phrases:

    Class class_name, member "name": In "<x>" code:
    Class class_name, method "name":

where "<x>" is one of "pre", "post", or "assert". See perldiag for an explanation of such messages. The message will include a line number that is relative to the lines in the erroneous code fragment, as well as the line number on which the class begins. For instance, suppose the file "stacks.pl" contains the following code:

    #! /bin/perl
    use warnings;
    use Class::Generate 'class';
    class Stack => [
        top_e    => { type => '$', private => 1, default => -1 },
        elements => { type => '@', private => 1, default => '[]' },
        '&push' => '$elements[++$top_e] = $_[0];',
        '&pop'  => '$top_e--;',
        '&top'  => 'return $elements[$top_e];'
    ];
    class Integer_Stack => [
        '&push' => q{die 'Not an integer' if $_[0] !~ /^-?\d+$/;
                     $self->SUPER:push($_[0]);} # Meant "::", not ":".
    ], -parent => 'Stack';

Executing this file yields:

    Subclass "Integer_Stack", method "push": syntax error at line 2,
     near "->SUPER:"
     at stacks.pl line 11

meaning the error occurs in the second line of the "push" method.

SEE ALSO

COPYRIGHT

BUGS

That "pre" and "post" code share the same name space can cause problems if the "check_code" option is true. The reason is that the "post" code is evaluated with a prepended copy of "pre" in which all newlines are replaced by spaces. This replacement ensures that an error message about "post" refers to the appropriate line number within "post". However, if the "pre" code contains the "<<" quotation form, Perl will probably complain about a syntax error; and if it contains a comment, Perl will ignore the first line of the "post" code. Note that this only affects code checking, not the package that's generated.

In the current implementation, if member "m" is an array, then within user-defined code, the test "if ( @m ) { ... }" does not work in hash-based classes unless @m is initialized. Use "$#m != -1" instead. Or specify "m" as explicitly empty:

    m => { type => '@', default => '[]' }

Hash members have an analogous bug. Use "scalar(&m_keys) != 0" to test if a hash member is empty in user-defined code.

The &equals and &copy functions do not understand multiple inheritance.

Member and method name substitution in code can be fooled if a member name is also declared as a variable. Unfortunately the "class" function doesn't detect this error. In the following class, the $f of $f[0] is mistaken for scalar member "f", not array variable @f:

    class Foo => {
        f => {
            type => '$',
            post => 'my @f;
                     $f[0] = $f;    # This causes an error.
                     ${f}[0] = $f;' # However, this works.
        }
    };

If a class declares a protected method "m", and one of its subclasses also declares "m", the subclass can't access the parent's version.

A subclass can declare a member "m" that overrides a parent's declaration of "m", but it can cause some logical inconsistencies and isn't recommended. Tne entire model of member overriding may change in some future version.

The "subclass" function doesn't test for circularity in inheritance hierarchies.

The "-allow_redefine" option is intended to let you add functionality to packages not declared using "Class::Generate". This rule isn't strictly enforced, but probably should be. If you redefine a class, you change the constructor, as well as the "copy" and "equals" methods. Consider the following:

    class Foo => [ mem1 => '$' ];
    class Foo => [ mem2 => '@' ], # Intends to add a member to Foo.
        -options => { allow_redefine => 1 };
    $o = new Foo;
    $o->mem1('this works');
    $o->mem2([qw(so does this)]);
    $p = $o->copy;                # But this doesn't copy mem1.
    $p = new Foo mem1 => 'x';     # And this fails.

Use inheritance instead.

The algorithm that adds a trailing semicolon to "pre" and "post" code uses a simple regular expression to test for a semicolon's presence. Please don't strain it by doing odd things like embedding comments:

    post => 'print "foo"  # This will fail, with an obscure error message.',
    post => 'print "foo"' # Use this form instead.

NOTES

In "pre" and "post" code, you can access method parameters via @_. You probably should not do so except for scalar members, though. For array members, the same code is inserted into m and "add_"m, and the code can't tell which method it's in. Even within method m, the code can't tell if it's looking at a reference or a value if $accept_refs is true.

The "UNIVERSAL::isa" function is used to determine if something is an array or hash reference. This presents possibilities for metaspecification functions.

The name "_cginfo" is reserved in all packages generated by "Class::Generate".

Emacs users will quickly discover that the form:

    class Foo => [ member_name => '$' ];

causes subsequent lines to be incorrectly indented. The reason is that perl-mode is confused by '$'. Use instead:

    class Foo => [ member_name => "\$" ];

This package clearly owes much to "Class::Struct". I thank its creators for their insights.

Speaking of which, unlike "Class::Struct", the "m" accessor for member "m" does not return a value when it is set. This is a deliberate design decision. If you would like that feature, you can simulate it for (scalar) member "m" by including "return $m;" as "post" code. However, you then short-circuit any assertion for member "m".

SUPPORT

  git clone https://github.com/shlomif/perl-Class-Generate

AUTHOR

BUGS

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.

COPYRIGHT AND LICENSE

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.