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.

CONVENIENCE METHODS

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

@split = $self->split_value($line [, $delimiter]);

This method returns a array ref containing the $line elements split by the delimiter, but ignores escaped delimiters. If no $delimiter is supplied then a comma "," is used by default.

SUPPORT

For technical support please email to jlawrenc@cpan.org ... for faster service please include "Text::vFile" and "help" in your subject line.

AUTHOR

 Jay J. Lawrence - jlawrenc@cpan.org
 Infonium Inc., Canada
 http://www.infonium.ca/

COPYRIGHT

Copyright (c) 2003 Jay J. Lawrence, Infonium Inc. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.

ACKNOWLEDGEMENTS

SEE ALSO