Class | Vcard::Vcard |
In: |
lib/vcard/vcard.rb
|
Parent: | DirectoryInfo |
A vCard, a specialization of a directory info object.
The vCard format is specified by:
This implements vCard 3.0, but it is also capable of working with vCard 2.1 if used with care.
All line values can be accessed with Vcard#value, Vcard#values, or even by iterating through Vcard#lines. Line types that don‘t have specific support and non-standard line types ("X-MY-SPECIAL", for example) will be returned as a String, with any base64 or quoted-printable encoding removed.
Specific support exists to return more useful values for the standard vCard types, where appropriate.
The wrapper functions (birthday, nicknames, emails, etc.) exist partially as an API convenience, and partially as a place to document the values returned for the more complex types, like PHOTO and EMAIL.
For types that do not sensibly occur multiple times (like BDAY or GEO), sometimes a wrapper exists only to return a single line, using value. However, if you find the need, you can still call values to get all the lines, and both the singular and plural forms will eventually be implemented.
For more information see:
vCards are usually transmitted in files with .vcf extensions.
Create a vCard 3.0 object with the minimum required fields, plus any fields you want in the card (they can also be added later).
Decode a collection of vCards into an array of Vcard objects.
card can be either a String or an IO object.
Since vCards are self-delimited (by a BEGIN:vCard and an END:vCard), multiple vCards can be concatenated into a single directory info object. They may or may not be related. For example, AddressBook.app (the OS X contact manager) will export multiple selected cards in this format.
Input data will be converted from unicode if it is detected. The heuristic is based on the first bytes in the string:
If you know that you have only one vCard, then you can decode that single vCard by doing something like:
vcard = Vcard.decode(card_data).first
Note: Should the import encoding be remembered, so that it can be reencoded in the same format?
The value of the field named name, optionally limited to fields of type type. If no match is found, nil is returned, if multiple matches are found, the first match to have one of its type values be "PREF" (preferred) is returned, otherwise the first match is returned.
FIXME - this will become an alias for value.
The GEO value, an Array of two Floats, +[ latitude, longitude]+. North of the equator is positive latitude, east of the meridian is positive longitude. See RFC2445 for more info, there are lots of special cases and RFC2445"s description is more complete thant RFC2426.
Return an Array of KEY Line#value, or yield each Line#value if a block is given. A wrapper around values("KEY").
KEY is a public key or authentication certificate associated with the object that the vCard represents. It is not commonly used, but could contain a X.509 or PGP certificate.
See Attachment for a description of the value.
Return an Array of LOGO Line#value, or yield each Line#value if a block is given. A wrapper around values("LOGO").
LOGO is a graphic image of a logo associated with the object the vCard represents. Its not common, but would probably be equivalent to the logo on a printed card.
See Attachment for a description of the value.
Make changes to a vCard.
Yields a Vcard::Vcard::Maker that can be used to modify this vCard.
The N and FN as a Name object.
N is required for a vCards, this raises InvalidEncodingError if there is no N so it cannot return nil.
Return an Array of PHOTO Line#value, or yield each Line#value if a block is given. A wrapper around values("PHOTO").
PHOTO is an image or photograph information that annotates some aspect of the object the vCard represents. Commonly there is one PHOTO, and it is a photo of the person identified by the vCard.
See Attachment for a description of the value.
Return an Array of SOUND Line#value, or yield each Line#value if a block is given. A wrapper around values("SOUND").
SOUND is digital sound content information that annotates some aspect of the vCard. By default this type is used to specify the proper pronunciation of the name associated with the vCard. It is not commonly used. Also, note that there is no mechanism available to specify that the SOUND is being used for anything other than the default.
See Attachment for a description of the value.
Return the Line#value for a specific name, and optionally for a specific type.
If no line with the name (and, optionally, type) exists, nil is returned.
If multiple lines exist, the order of preference is:
If multiple lines are equally preferred, then the first line will be returned.
This is most useful when looking for a line that can not occur multiple times, or when the line can occur multiple times, and you want to pick the first preferred line of a specific type. See values if you need to access all the lines.
Note that the type field parameter is used for different purposes by the various kinds of vCard lines, but for the addressing lines (ADR, LABEL, TEL, EMAIL) it is has a reasonably consistent usage. Each addressing line can occur multiple times, and a type of "pref" indicates that a particular line is the preferred line. Other type values tend to indicate some information about the location ("home", "work", …) or some detail about the address ("cell", "fax", "voice", …). See the methods for the specific types of line for information about supported types and their meaning.
The VERSION multiplied by 10 as an Integer. For example, a VERSION:2.1 vCard would have a version of 21, and a VERSION:3.0 vCard would have a version of 30.
VERSION is required for a vCard, this raises InvalidEncodingError if there is no VERSION so it cannot return nil.