/ 
Text-vFile-0.5
River stage zero No dependents
/ Text::vFile::Base

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