/ 
Class-Colon-0.01
River stage zero No dependents
/ Class::Colon

NAME

Class::Colon - Makes objects out of colon delimited records

SYNOPSIS

use Date;
use Class::Colon
    Person  => [ qw ( first middle family date_of_birth=Date=new ) ],
    Address => [ qw ( street city province code country          ) ];

Person->DELIM(qr/,/); # change from colon to comma for delimeter
my $names = Person->READ_FILE($file_name);
foreach my $name (@$names) {
    print $name->family, ",", $name->first, $name->middle, "\n";
}

open ADDRESS_FILE, "addresses.dat" or die "...\n";
my $addresses = Address->READ_HANDLE(*ADDRESS_FILE);
foreach my $address (@$addresses) {
    print $address->street . "\n"
    print $address->city . ", " . $address->province . "\n";
    print $address->country, "\n" if defined $address->country;
}

DESCRIPTION

To turn your colon delimited file into a list of objects, use Class::Colon, giving it the name you want to use for the class and a list of column names which will become attributes of the objects in the class. List the names in the order they appear in the input. Missing fields will be set to undef. Extra fields will be ignored. Use lower case names for the fields.

Most fields will be simple scalars, but if one of the fields should be an object, its entry should be of the form

attribute_name=package_name=constructor_name

as shown above for date_of_birth which is of type Date whose constructor is new. In above example, I could have omitted the constructor name, since new is the default.

You may objectify as many different record types as you like in one use statement. You may have multiple use statements throughout your program or module. If you are using this package from another package, you should worry a little about namespace collision. There is only one list of classes made by this package. The names must be unique or Bad Things will happen. Feel free to include your module name in the names of the fabricated classes as in:

package YourModule;
use Class::Colon YourModule::Person => [ qw( field names here ) ];

You wouldn't have to use the double colon, but it makes sense to me.

If your delimiter is not colon, call DELIM on your class before calling READ_FILE. Pass it a pattern in the form qr/$your_delim_here/. It must be a regular expression, using qr is the easiest way to make that happen.

ABSTRACT

This module objectifies colon separated data files into objects.

EXPORT

None, this is object oriented.

METHODS

There are currently only a few methods. There is one class method READ_FILE (for each key in the hash you passed to use). There is also a dual get/set accessor for each field. Finally, there is a DELIM method which allows you to set the delimiter. This can be any valid pattern (regex), but it applies to all fields in the file. You may not use DELIM as the name of one of your fields. In fact, you should consider every ALL_CAPS name reserved. I may use those to support other configurations in the future.

In addition to retrieving the attributes through accessor methods, you could peek directly at the data. It is stored in a hash so the following are equivalent:

my $country = $address->country();

and

my $country = $address->{country};

Using this fact might make some things neater in your code (like print statements. It also saves a tiny amount of time. Yet, our OO teachers will smack our hands, if they hear about this little arrangement. I have no plans to change the implementation, but they tell me never to make such promises.

At this point there are no output methods. That may change in the future.

DELIM

Call this through one of the names you supplied in your use statement. Pass it a pattern in the form qr/$delim/. For example, you could say

Person->DELIM(qr/;/);

to change the delimiter from colon to semi-colon for Person.

READ_FILE and READ_HANDLE

Call these mehtods through one of the names you supplied in your use statement.

Both READ_FILE and READ_HANDLE return an array reference with one element for each line in your input file. All lines are represented even if they are blank or start with #. The array elements are objects of the same type as the name you used to call the method. Think of these as super constructors, instead of making one object at a time, they make as many as they can from your input.

READ_FILE takes the name of a file, which it opens and reads.

READ_HANDLE takes a handle open for reading.

accessors

For each attribute you name in your use statement, there is a corresponding dual get/set accessor. The names of the accessors are the same as the names you used (how convenient).

BUGS and OMISSIONS

There are no output methods.

Quotes are not special. If a colon (or the DELIM of your choice) is inside quotes, it still counts as a field separator.

AUTHOR

Phil Crow, <philcrow2000@yahoo.com>

COPYRIGHT AND LICENSE

Copyright 2003 by Phil Crow, all rights reserved.

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