Documentation ¶
Overview ¶
Package vcard implements the vCard format, defined in RFC 6350.
For usage examples refer to New to create a vCard and NewDecoder to read a vCard.
License and credits ¶
Code is available under the MIT license.
Large inspiration has been taken from the emersion/go-vcard package (available under MIT).
Index ¶
- Constants
- type Data
- func (d Data) Categories() []string
- func (d Data) Gender() (sex Sex, identity PropertyValue)
- func (d Data) Kind() Kind
- func (d Data) Names() (n Names, ok bool)
- func (d *Data) PropertyDelete(name string)
- func (d Data) PropertyFirst(name string) (p Property, ok bool)
- func (d Data) PropertyPreferred(name string) (p Property, ok bool)
- func (d Data) Revision() time.Time
- func (d Data) Validate(extended bool) error
- func (d Data) Version() Version
- type Decoder
- type Encoder
- type Kind
- type Names
- func (n Names) FormattedName() PropertyValue
- func (n Names) ToProperty() Property
- func (n Names) WithAdditionalName(s ...string) Names
- func (n Names) WithFamilyName(s ...string) Names
- func (n Names) WithGivenName(s ...string) Names
- func (n Names) WithHonorificPrefix(s ...string) Names
- func (n Names) WithHonorificSuffix(s ...string) Names
- type OrganizationLevels
- type Parameter
- type ParameterType
- type Property
- type PropertyValue
- type Sex
- type Version
Examples ¶
Constants ¶
const ( MIMETypeWithoutCharset = "text/vcard" MIMEType = MIMETypeWithoutCharset + ";charset=UTF-8" Extension = "vcf" )
MIME type and file extension for vCard rfc6350#section-10.1
const ( // General Properties Property_Source = "SOURCE" Property_Kind = "KIND" Property_XML = "XML" // Identification Properties Property_FormattedName = "FN" Property_Name = "N" Property_Nickname = "NICKNAME" Property_Photo = "PHOTO" Property_Birthday = "BDAY" Property_Anniversary = "ANNIVERSARY" Property_Gender = "GENDER" // Delivery Addressing Properties Property_Address = "ADR" // Communications Properties Property_Telephone = "TEL" Property_Email = "EMAIL" Property_IMPP = "IMPP" // Instant Messaging and Presence Protocol Property_Language = "LANG" // Geographical Properties Property_Timezone = "TZ" Property_Geolocation = "GEO" // Organizational Properties Property_Title = "TITLE" Property_Role = "ROLE" Property_Logo = "LOGO" Property_Organization = "ORG" Property_Member = "MEMBER" Property_Related = "RELATED" // Explanatory Properties Property_Categories = "CATEGORIES" Property_Note = "NOTE" Property_ProductID = "PRODID" Property_Revision = "REV" Property_Sound = "SOUND" Property_UID = "UID" Property_ClientPIDMap = "CLIENTPIDMAP" Property_URL = "URL" // Security Properties Property_Key = "KEY" // Calendar Properties Property_FreeOrBusyURL = "FBURL" Property_CalendarAddressURI = "CALADRURI" Property_CalendarURI = "CALURI" )
Card property names.
const ( Parameter_Language = "LANGUAGE" Parameter_Value = "VALUE" Parameter_Preference = "PREF" Parameter_AltID = "ALTID" Parameter_PID = "PID" Parameter_Type = "TYPE" // see [ParameterType] Parameter_MediaType = "MEDIATYPE" Parameter_CalendarScale = "CALSCALE" Parameter_SortAs = "SORT-AS" // values are case-sensitive Parameter_Geolocation = "GEO" Parameter_Timezone = "TZ" )
Parameter names.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Data ¶
type Data struct { Properties []Property // contains filtered or unexported fields }
Data represents a vCard
func New ¶
New creates a new vCard 4.0 (a ProductID property is added, if missing)
Example ¶
package main import ( "bytes" "fmt" "log" "strings" "time" "code.pfad.fr/gopim/vcard" ) func main() { names := vcard.Names{}. WithFamilyName("Public"). WithGivenName("John"). WithAdditionalName("Quinlan", "Paul"). WithHonorificPrefix("Mr."). WithHonorificSuffix("Esq.") d := vcard.New( vcard.Property{ Name: vcard.Property_FormattedName, Value: names.FormattedName(), }, names.ToProperty(), vcard.Revision(time.Date(1996, 10, 22, 14, 00, 00, 0, time.UTC)), vcard.Property{ Name: vcard.Property_UID, Value: vcard.NewPropertyTexts("123"), }, vcard.OrganizationLevels{"ABC, Inc.", "North American Division"}.ToProperty(), vcard.Property{ Name: vcard.Property_Email, Value: vcard.NewPropertyTexts("jqpublic@xyz.example.com"), }.WithType(vcard.ParameterType_Work), vcard.Property{ Name: vcard.Property_Telephone, Value: vcard.NewPropertyTexts("tel:+1-418-656-9254;ext=102"), }.WithValue("uri").WithType(vcard.ParameterType_Work, vcard.ParameterType_Voice).WithPreference(1), vcard.Property{ Name: vcard.Property_Telephone, Value: vcard.NewPropertyTexts("tel:+1-418-262-6501"), }.WithValue("uri").WithType(vcard.ParameterType_Work, vcard.ParameterType_Cell, vcard.ParameterType_Voice, vcard.ParameterType_Video, vcard.ParameterType_Text), ) var buf bytes.Buffer err := vcard.NewEncoder(&buf).Encode(d) if err != nil { log.Fatal(err) } fmt.Println(strings.ReplaceAll(buf.String(), "\r\n", "\n")) }
Output: BEGIN:VCARD VERSION:4.0 FN:Mr. John Q. Public\, Esq. N:Public;John;Quinlan,Paul;Mr.;Esq. REV:19961022T140000Z UID:123 ORG:ABC\, Inc.;North American Division EMAIL;TYPE=work:jqpublic@xyz.example.com TEL;VALUE=uri;TYPE="work,voice";PREF=1:tel:+1-418-656-9254;ext=102 TEL;VALUE=uri;TYPE="work,cell,voice,video,text":tel:+1-418-262-6501 PRODID:-//GoPim//code.pfad.fr/gopim/vcard (devel)//EN END:VCARD
func (Data) Categories ¶
Category information about the vCard, also known as "tags". rfc6350#section-6.7.1
func (Data) Gender ¶
func (d Data) Gender() (sex Sex, identity PropertyValue)
Sex and gender identity. rfc6350#section-6.2.7
func (*Data) PropertyDelete ¶
PropertyDelete removes all properties with the given name
func (Data) PropertyPreferred ¶
PropertyPreferred returns the property with the highest preference
type Decoder ¶
type Decoder struct {
// contains filtered or unexported fields
}
A Decoder parses vcard.Data
func NewDecoder ¶
NewDecoder creates a new Decoder reading vcard.Data from an io.Reader.
Example ¶
package main import ( "fmt" "log" "os" "code.pfad.fr/gopim/vcard" ) func main() { f, err := os.Open("testdata/rfc_example/7.2.4_boss.vcf") if err != nil { log.Fatal(err) } defer f.Close() d, err := vcard.NewDecoder(f).Decode() if err != nil { log.Fatal(err) } p, ok := d.PropertyPreferred(vcard.Property_FormattedName) fmt.Println(ok, p.Value.SplitTexts()[0]) p, ok = d.PropertyPreferred(vcard.Property_Telephone) fmt.Println(ok, p.Value.SplitTexts()[0]) }
Output: true J. Doe true tel:+1-555-555-5555
type Encoder ¶
type Encoder struct {
// contains filtered or unexported fields
}
An Encoder encodes Data in the vCard format.
func NewEncoder ¶
NewEncoder creates a new Encoder. See New for a usage example.
type Names ¶
type Names struct { FamilyName []string GivenName []string AdditionalName []string HonorificPrefix []string HonorificSuffix []string }
func (Names) FormattedName ¶
func (n Names) FormattedName() PropertyValue
FormattedName returns a likely representation of the formatted name (skipping empty elements):
HonorificPrefix[0] GivenName[0] AdditionalName[0][0]. FamilyName[0], HonorificSuffix[0]
func (Names) ToProperty ¶
func (Names) WithAdditionalName ¶
func (Names) WithFamilyName ¶
func (Names) WithGivenName ¶
func (Names) WithHonorificPrefix ¶
func (Names) WithHonorificSuffix ¶
type OrganizationLevels ¶
type OrganizationLevels []string
func (OrganizationLevels) ToProperty ¶
func (ol OrganizationLevels) ToProperty() Property
type ParameterType ¶
type ParameterType string
ParameterType is for Parameter_Type.
const ( // Generic ParameterType_Home ParameterType = "home" ParameterType_Work ParameterType = "work" // For FieldTelephone ParameterType_Text ParameterType = "text" ParameterType_Voice ParameterType = "voice" // Default ParameterType_Fax ParameterType = "fax" ParameterType_Cell ParameterType = "cell" ParameterType_Video ParameterType = "video" ParameterType_Pager ParameterType = "pager" ParameterType_TextPhone ParameterType = "textphone" // For FieldRelated ParameterType_Contact ParameterType = "contact" ParameterType_Acquaintance ParameterType = "acquaintance" ParameterType_Friend ParameterType = "friend" ParameterType_Met ParameterType = "met" ParameterType_CoWorker ParameterType = "co-worker" ParameterType_Colleague ParameterType = "colleague" ParameterType_CoResident ParameterType = "co-resident" ParameterType_Neighbor ParameterType = "neighbor" ParameterType_Child ParameterType = "child" ParameterType_Parent ParameterType = "parent" ParameterType_Sibling ParameterType = "sibling" ParameterType_Spouse ParameterType = "spouse" ParameterType_Kin ParameterType = "kin" ParameterType_Muse ParameterType = "muse" ParameterType_Crush ParameterType = "crush" ParameterType_Date ParameterType = "date" ParameterType_Sweetheart ParameterType = "sweetheart" ParameterType_Me ParameterType = "me" ParameterType_Agent ParameterType = "agent" ParameterType_Emergency ParameterType = "emergency" )
Known parameter types
func (ParameterType) IsKnown ¶
func (p ParameterType) IsKnown() bool
type Property ¶
type Property struct { Group string Name string Value PropertyValue Parameters []Parameter }
func (Property) ParameterValues ¶
ParameterValues returns the parameter values, as stored.
Note that according to rfc6350: Parameter values that are not explicitly defined as being case-sensitive are case-insensitive. (only SORT-AS is defined as case-sensitive).
func (Property) Preference ¶
Preference indicate that the corresponding instance of a property is preferred by the vCard author. Lower values correspond to a higher level of preference, with 1 being most preferred. 101 indicates an error parsing the value, 102 indicates no value
func (Property) Types ¶
func (p Property) Types() []ParameterType
func (Property) WithPreference ¶
WithPreference sets the preference between 1 and 100. Lower values correspond to a higher level of preference, with 1 being most preferred.
func (Property) WithType ¶
func (p Property) WithType(pt ...ParameterType) Property
type PropertyValue ¶
type PropertyValue string
PropertyValue stores the raw value of a Property.
func NewPropertyTexts ¶
func NewPropertyTexts(texts ...string) PropertyValue
NewPropertyTexts creates a new PropertyValue after escaping each text (backslash, newline, comma) and joining by comma.
func (PropertyValue) Names ¶
func (fv PropertyValue) Names() Names
func (PropertyValue) OrganizationLevels ¶
func (fv PropertyValue) OrganizationLevels() OrganizationLevels
func (PropertyValue) SplitTexts ¶
func (fv PropertyValue) SplitTexts() []string
SplitTexts returns the value parts of a Property, split by comma (each part being unescaped). Guaranteed to have a len > 0
type Sex ¶
type Sex string
Sex is an object's biological sex.
func (Sex) ToProperty ¶
func (s Sex) ToProperty(identity PropertyValue) Property