.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Text::vCard 3pm"
.TH Text::vCard 3pm "2014-06-13" "perl v5.18.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Text::vCard \- Edit and create vCards (RFC 2426)
.SH "WARNING"
.IX Header "WARNING"
vCard and vCard::AddressBook are built on top of this module and provide
a more intuitive user interface.  Please try those modules first.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&  use Text::vCard;
\&  my $cards
\&      = Text::vCard\->new( { \*(AqasData_node\*(Aq => $objects_node_from_asData, } );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
A vCard is an electronic business card.
.PP
This package is for a single vCard (person / record / set of address
information). It provides an \s-1API\s0 to editing and creating vCards, or supplied
a specific piece of the Text::vFile::asData results it generates a vCard 
with that content.
.PP
You should really use Text::vCard::Addressbook as this handles creating
vCards from an existing file for you.
.SH "METHODS"
.IX Header "METHODS"
.SS "\fInew()\fP"
.IX Subsection "new()"
.Vb 1
\&  use Text::vCard;
\&
\&  my $new_vcard = Text::vCard\->new();
\&
\&  my $existing_vcard
\&      = Text::vCard\->new( { \*(AqasData_node\*(Aq => $objects_node_from_asData, } );
.Ve
.SS "\fIadd_node()\fP"
.IX Subsection "add_node()"
.Vb 1
\&  my $address = $vcard\->add_node( { \*(Aqnode_type\*(Aq => \*(AqADR\*(Aq, } );
.Ve
.PP
This creates a new address (a Text::vCard::Node object) in the vCard
which you can then call the address methods on. See below for what options are available.
.PP
The node_type parameter must conform to the vCard spec format (e.g. \s-1ADR\s0 not address)
.SS "\fIget()\fP"
.IX Subsection "get()"
The following method allows you to extract the contents from the vCard.
.PP
.Vb 2
\&  # get all elements
\&  $nodes = $vcard\->get(\*(Aqtel\*(Aq);
\&
\&  # Just get the home address
\&  my $nodes = $vcard\->get(
\&      {   \*(Aqnode_type\*(Aq => \*(Aqaddresses\*(Aq,
\&          \*(Aqtypes\*(Aq     => \*(Aqhome\*(Aq,
\&      }
\&  );
\&
\&  # get all phone number that matches several types
\&  my @types = qw(work home);
\&  my $nodes = $vcard\->get(
\&      {   \*(Aqnode_type\*(Aq => \*(Aqtel\*(Aq,
\&          \*(Aqtypes\*(Aq     => \e@types,
\&      }
\&  );
.Ve
.PP
Either an array or array ref is returned, containing
Text::vCard::Node objects.  If there are no results of 'node_type'
undef is returned.
.PP
Supplied with a scalar or an array ref the methods
return a list of nodes of a type, where relevant. If any
of the elements is the preferred element it will be
returned as the first element of the list.
.SS "\fIget_simple_type()\fP"
.IX Subsection "get_simple_type()"
The following method is a convenience wrapper for accessing simple elements.
.PP
.Vb 1
\&  $value = $vcard\->get_simple_type( \*(Aqemail\*(Aq, [ \*(Aqinternet\*(Aq, \*(Aqwork\*(Aq ] );
.Ve
.PP
If multiple elements match, then only the first is returned.  If the object
isn't found, or doesn't have a simple value, then undef is returned.
.PP
The argument type may be omitted, it can be a scalar, or it can be an
array reference if multiple types are selected.
.SS "nodes"
.IX Subsection "nodes"
.Vb 1
\&  my $addresses = $vcard\->get( { \*(Aqnode_type\*(Aq => \*(Aqaddress\*(Aq } );
\&
\&  my $first_address = $addresses\->[0];
\&
\&  # get the value
\&  print $first_address\->street();
\&
\&  # set the value
\&  $first_address\->street(\*(AqBarney Rubble\*(Aq);
\&
\&  # See if it is part of a group
\&  if ( $first_address\->group() ) {
\&      print \*(AqGroup: \*(Aq . $first_address\->group();
\&  }
.Ve
.PP
According to the \s-1RFC\s0 the following 'simple' nodes should only have one
element, this is not enforced by this module, so for example you can
have multiple \s-1URL\s0's if you wish.
.SS "simple nodes"
.IX Subsection "simple nodes"
For simple nodes, you can also access the first node in the following way:
.PP
.Vb 3
\&  my $fn = $vcard\->fullname();
\&  # or setting
\&  $vcard\->fullname(\*(Aqnew name\*(Aq);
.Ve
.PP
The node will be automatically created if it does not exist and you
supplied a value.  undef is returned if the node does not
exist. Simple nodes can be called as all upper or all lowercase method
names.
.PP
.Vb 10
\&  vCard Spec: \*(Aqsimple\*(Aq    Alias
\&  \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-    \-\-\-\-\-\-\-\-
\&  FN                      fullname
\&  BDAY                    birthday
\&  MAILER
\&  TZ                      timezone
\&  TITLE 
\&  ROLE 
\&  NOTE 
\&  PRODID 
\&  REV 
\&  SORT\-STRING 
\&  UID
\&  URL 
\&  CLASS
\&  EMAIL
\&  NICKNAME
\&  PHOTO
\&  version (lowercase only)
.Ve
.SS "more complex vCard nodes"
.IX Subsection "more complex vCard nodes"
.Vb 9
\&  vCard Spec    Alias           Methods on object
\&  \-\-\-\-\-\-\-\-\-\-    \-\-\-\-\-\-\-\-\-\-      \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
\&  N             name (depreciated as conflicts with rfc, use moniker)
\&  N             moniker            \*(Aqfamily\*(Aq,\*(Aqgiven\*(Aq,\*(Aqmiddle\*(Aq,\*(Aqprefixes\*(Aq,\*(Aqsuffixes\*(Aq
\&  ADR           addresses       \*(Aqpo_box\*(Aq,\*(Aqextended\*(Aq,\*(Aqstreet\*(Aq,\*(Aqcity\*(Aq,\*(Aqregion\*(Aq,\*(Aqpost_code\*(Aq,\*(Aqcountry\*(Aq
\&  GEO                           \*(Aqlat\*(Aq,\*(Aqlong\*(Aq
\&  TEL           phones
\&  LABELS
\&  ORG                           \*(Aqname\*(Aq,\*(Aqunit\*(Aq (unit is a special case and will return an array reference)
\&
\&  my $addresses = $vcard\->get( { \*(Aqnode_type\*(Aq => \*(Aqaddresses\*(Aq } );
\&  foreach my $address ( @{$addresses} ) {
\&      print $address\->street();
\&  }
\&
\&  # Setting values on an address element
\&  $addresses\->[0]\->street(\*(AqThe burrows\*(Aq);
\&  $addresses\->[0]\->region(\*(AqWimbeldon common\*(Aq);
\&
\&  # Checking an address is a specific type
\&  $addresses\->[0]\->is_type(\*(Aqfax\*(Aq);
\&  $addresses\->[0]\->add_types(\*(Aqhome\*(Aq);
\&  $addresses\->[0]\->remove_types(\*(Aqwork\*(Aq);
.Ve
.SS "\fIget_group()\fP"
.IX Subsection "get_group()"
.Vb 6
\&  my $group_name = \*(Aqitem1\*(Aq;
\&  my $node_type  = \*(AqX\-ABLABEL\*(Aq;
\&  my $of_group   = $vcard\->get_group( $group_name, $node_type );
\&  foreach my $label ( @{$of_group} ) {
\&      print $label\->value();
\&  }
.Ve
.PP
This method takes one or two arguments. The group name
(accessible on any node object by using \f(CW$node\fR\->\fIgroup()\fR \- not
all nodes will have a group, indeed most vcards do not seem
to use it) and optionally the types of node you with to 
have returned.
.PP
Either an array or array reference is returned depending
on the calling context, if there are no matches it will
be empty.
.SH "BINARY METHODS"
.IX Header "BINARY METHODS"
These methods allow access to what are potentially binary values such
as a photo or sound file. Binary values will be correctly encoded and
decoded to/from base 64.
.PP
\&\s-1API\s0 still to be finalised.
.SS "\fIphoto()\fP"
.IX Subsection "photo()"
.SS "\fIsound()\fP"
.IX Subsection "sound()"
.SS "\fIkey()\fP"
.IX Subsection "key()"
.SS "\fIlogo()\fP"
.IX Subsection "logo()"
.SS "get_lookup"
.IX Subsection "get_lookup"
This method is used internally to lookup those nodes which have
multiple elements, e.g. \s-1GEO\s0 has lat and long, N (name) has family,
given, middle etc.
.PP
If you wish to extend this package (for custom attributes), overload
this method in your code:
.PP
.Vb 4
\&  sub my_lookup {
\&      return \e%my_lookup;
\&  }
\&  *Text::vCard::get_lookup = \e&my_lookup;
.Ve
.PP
This has not been tested yet.
.SS "\fIget_of_type()\fP"
.IX Subsection "get_of_type()"
.Vb 1
\&  my $list = $vcard\->get_of_type( $node_type, \e@types );
.Ve
.PP
It is probably easier just to use the \fIget()\fR method, which inturn calls
this method.
.SS "as_string"
.IX Subsection "as_string"
Returns the vCard as a string.
.SH "AUTHOR"
.IX Header "AUTHOR"
Leo Lapworth, LLAP@cuckoo.org
Eric Johnson (kablamo), github ~!at!~ iijo dot org
.SH "Repository (git)"
.IX Header "Repository (git)"
http://github.com/ranguard/text\-vcard, git://github.com/ranguard/text\-vcard.git
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright (c) 2005\-2010 Leo Lapworth. All rights reserved.
This program is free software; you can redistribute
it and/or modify it under the same terms as Perl itself.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Text::vCard::Addressbook, Text::vCard::Node,
vCard vCard, vCard::AddressBook vCard::AddressBook,