.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) .\" .\" 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 >0, 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 .\" ======================================================================== .\" .IX Title "vCard 3pm" .TH vCard 3pm "2021-01-03" "perl v5.32.0" "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" vCard \- Read, write, and edit vCards .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use vCard; \& \& # create the object \& my $vcard = vCard\->new; \& \& # these methods load vCard data \& # (see method documentation for details) \& $vcard\->load_file($filename); \& $vcard\->load_string($string); \& $vcard\->load_hashref($hashref); \& \& # simple getters/setters \& $vcard\->full_name(\*(AqBruce Banner, PhD\*(Aq); \& $vcard\->title(\*(AqResearch Scientist\*(Aq); \& $vcard\->photo(\*(Aqhttp://example.com/bbanner.gif\*(Aq); \& \& # complex getters/setters \& $vcard\->phones([ \& { type => [\*(Aqwork\*(Aq, \*(Aqtext\*(Aq], number => \*(Aq651\-290\-1234\*(Aq, preferred => 1 }, \& { type => [\*(Aqhome\*(Aq], number => \*(Aq651\-290\-1111\*(Aq } \& ]); \& $vcard\->email_addresses([ \& { type => [\*(Aqwork\*(Aq], address => \*(Aqbbanner@ssh.secret.army.mil\*(Aq }, \& { type => [\*(Aqhome\*(Aq], address => \*(Aqbbanner@timewarner.com\*(Aq }, \& ]); \& \& # these methods output data in vCard format \& my $file = $vcard\->as_file($filename); # writes to $filename \& my $string = $vcard\->as_string; # returns a string .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" A vCard is a digital business card. vCard and vCard::AddressBook provide an \&\s-1API\s0 for parsing, editing, and creating vCards. .PP This module is built on top of Text::vCard. It provides a more intuitive user interface. .PP To handle an address book with several vCard entries in it, start with vCard::AddressBook and then come back to this module. .PP Note that the vCard \s-1RFC\s0 requires \fBversion()\fR and \fBfull_name()\fR. This module does not check or warn if these conditions have not been met. .SH "ENCODING AND UTF\-8" .IX Header "ENCODING AND UTF-8" See the '\s-1ENCODING AND UTF\-8\s0' section of vCard::AddressBook. .SH "METHODS" .IX Header "METHODS" .SS "load_hashref($hashref)" .IX Subsection "load_hashref($hashref)" \&\f(CW$hashref\fR should look like this: .PP .Vb 10 \& full_name => \*(AqBruce Banner, PhD\*(Aq, \& given_names => [\*(AqBruce\*(Aq], \& family_names => [\*(AqBanner\*(Aq], \& title => \*(AqResearch Scientist\*(Aq, \& photo => \*(Aqhttp://example.com/bbanner.gif\*(Aq, \& phones => [ \& { type => [\*(Aqwork\*(Aq], number => \*(Aq651\-290\-1234\*(Aq, preferred => 1 }, \& { type => [\*(Aqcell\*(Aq], number => \*(Aq651\-290\-1111\*(Aq }, \& }, \& addresses => [ \& { type => [\*(Aqwork\*(Aq], ... }, \& { type => [\*(Aqhome\*(Aq], ... }, \& ], \& email_addresses => [ \& { type => [\*(Aqwork\*(Aq], address => \*(Aqbbanner@shh.secret.army.mil\*(Aq }, \& { type => [\*(Aqhome\*(Aq], address => \*(Aqbbanner@timewarner.com\*(Aq }, \& ], .Ve .PP Returns \f(CW$self\fR in case you feel like chaining. .SS "load_file($filename)" .IX Subsection "load_file($filename)" Returns \f(CW$self\fR in case you feel like chaining. .SS "load_string($string)" .IX Subsection "load_string($string)" Returns \f(CW$self\fR in case you feel like chaining. This method assumes \f(CW$string\fR is decoded (but not \s-1MIME\s0 decoded). .SS "\fBas_string()\fP" .IX Subsection "as_string()" Returns the vCard as a string. .SS "as_file($filename)" .IX Subsection "as_file($filename)" Write data in vCard format to \f(CW$filename\fR. .PP Dies if not successful. .SH "SIMPLE GETTERS/SETTERS" .IX Header "SIMPLE GETTERS/SETTERS" These methods accept and return strings. .SS "\fBversion()\fP" .IX Subsection "version()" Version number of the vcard. Defaults to '4.0' .SS "\fBfull_name()\fP" .IX Subsection "full_name()" A person's entire name as they would like to see it displayed. .SS "\fBtitle()\fP" .IX Subsection "title()" A person's position or job. .SS "\fBphoto()\fP" .IX Subsection "photo()" This should be a link. Accepts a string or a \s-1URI\s0 object. This method always returns a \s-1URI\s0 object. .PP \&\s-1TODO:\s0 handle binary images using the data uri schema .SS "\fBbirthday()\fP" .IX Subsection "birthday()" .SS "\fBtimezone()\fP" .IX Subsection "timezone()" .SH "COMPLEX GETTERS/SETTERS" .IX Header "COMPLEX GETTERS/SETTERS" These methods accept and return array references rather than simple strings. .SS "\fBfamily_names()\fP" .IX Subsection "family_names()" Accepts/returns an arrayref of family names (aka surnames). .SS "\fBgiven_names()\fP" .IX Subsection "given_names()" Accepts/returns an arrayref. .SS "\fBother_names()\fP" .IX Subsection "other_names()" Accepts/returns an arrayref of names which don't qualify as family_names or given_names. .SS "\fBhonorific_prefixes()\fP" .IX Subsection "honorific_prefixes()" Accepts/returns an arrayref. eg \f(CW\*(C`[ \*(AqDr.\*(Aq ]\*(C'\fR .SS "\fBhonorific_suffixes()\fP" .IX Subsection "honorific_suffixes()" Accepts/returns an arrayref. eg \f(CW\*(C`[ \*(AqJr.\*(Aq, \*(AqMD\*(Aq ]\*(C'\fR .SS "\fBphones()\fP" .IX Subsection "phones()" Accepts/returns an arrayref that looks like: .PP .Vb 4 \& [ \& { type => [\*(Aqwork\*(Aq], number => \*(Aq651\-290\-1234\*(Aq, preferred => 1 }, \& { type => [\*(Aqcell\*(Aq], number => \*(Aq651\-290\-1111\*(Aq }, \& ] .Ve .SS "\fBaddresses()\fP" .IX Subsection "addresses()" Accepts/returns an arrayref that looks like: .PP .Vb 10 \& [ \& { type => [\*(Aqwork\*(Aq], street => \*(AqMain St\*(Aq, preferred => 0 }, \& { type => [\*(Aqhome\*(Aq], \& pobox => 1234, \& extended => \*(Aqasdf\*(Aq, \& street => \*(AqArmy St\*(Aq, \& city => \*(AqDesert Base\*(Aq, \& region => \*(Aq\*(Aq, \& post_code => \*(Aq\*(Aq, \& country => \*(AqUSA\*(Aq, \& preferred => 1, \& }, \& ] .Ve .SS "\fBemail_addresses()\fP" .IX Subsection "email_addresses()" Accepts/returns an arrayref that looks like: .PP .Vb 4 \& [ \& { type => [\*(Aqwork\*(Aq], address => \*(Aqbbanner@ssh.secret.army.mil\*(Aq }, \& { type => [\*(Aqhome\*(Aq], address => \*(Aqbbanner@timewarner.com\*(Aq, preferred => 1 }, \& ] .Ve .SH "AUTHOR" .IX Header "AUTHOR" Eric Johnson (kablamo), github ~!at!~ iijo dot org .SH "ACKNOWLEDGEMENTS" .IX Header "ACKNOWLEDGEMENTS" Thanks to Foxtons for making this module possible by donating a significant amount of developer time.