NAME

Text::vFile::Base - Base class for most of the functional classes based on the vCard/vCalendar etc spec. Most of the hard work in breaking apart lines of data happens using methods in here.

SYNOPSIS

 package Text::vFoo;

 use Text::vFile::Base;
 use vars qw(@ISA);
 push @ISA, qw(Text::vCard::Base);

 # Tell vFile that BEGIN:VFOO line creates one of these objects
 $Text::vFile::classMap{'VCARD'}=__PACKAGE__;

 # Then you will need to create a varHandler - although there are defaults to try
 # and get you going.
 #
 # As well you will need to define more exotic, type specific loaders
 #
 # And finally accessors are your responsibility

END USAGE

To tell your users how to use this module:

use Text::vFoo;
my $loader = Text::vFoo->loader( source => "youppi.vfoo" );

while (my $vfoo = $loader->next) {
    $vfoo->all_night;
}

# or even sexier

while (my $vfoo = <$loader> ) {
    $vfoo->all_night;
}

It may sound silly, but it should be mentioned. Just becase the user says:

my $loader = Text::vFoo->loader( );

Does not mean there will be any complaints if they try to load non-vfoo data. If the source has vcards in it - that's what they're going to get.

@objects = $class->load( key => value )

Calls the Text::vFile load routine. Should slurp all the objects and return as an array/array ref.

$loader = $class->loader( key => value )

Returns an object which can return back objects one at a time. Nice if you want to iterate through a stack of vcards at your leisure.

$object = class->new

Make a new object object that represents this vFile data being parsed.

DATA HANDLERS

varHandler

Returns a hash ref mapping the item label to a handler name. Ie:

{
     'FN'          => 'singleText',
     'NICKNAME'    => 'multipleText',
     'PHOTO'       => 'singleBinary',
     'BDAY'        => 'singleText',
     'ADR'         => 'ADR',           # Not really necessary
 };

By default if there is no explicit handler then the vFile loader will

- is there a method called  "load_NAME"?
- test does the item have type attributes or not
    - yes?   singleTextTyped
    - no?    singleText

typeDefault

Additional information where handlers require type info. Such as ADR - is this a home, postal, or whatever? If not supplied the RFC specifies what types they should default to.

 from vCard:

 {
    'ADR'     => [ qw(intl postal parcel work) ],
    'LABEL'   => [ qw(intl postal parcel work) ],
    'TEL'     => [ qw(voice) ],
    'EMAIL'   => [ qw(internet) ],
};

load_singleText

Loads a single text item with no processing other than unescape text

load_singleDate

Loads a date creating a DateTime::Format::ICal object. Thanks Dave!

load_singleDuration

Loads a data duration using DateTime::Format::ICal.

load_multipleText

This is text that is separated by commas. The text is then unescaped. An array of items is created.

load_singleTextType

Load text that has a type attribute. Each text of different type attributes will be handled independantly in as a hash entry. If no type attribute is supplied then the typeDefaults types will be used. A line can have multiple types. In the case where multiple types have the same value "_alias" indicators are created. The preferred type is stored in "_pref"

load_singleBinary

Not done as I don't have example data yet.