vcard package - code.pfad.fr/gopim/vcard
import "code.pfad.fr/gopim/vcard"
Package vcard implements the vCard format, as defined in [RFC 6350]. For usage examples refer to [New] to create a vCard and [NewDecoder] to read an existing vCard.
RFC 6350
Basically, a vCard consists of a list of properties:
- each [Property] has a name (see the `Property_` constants for the well-known names) and a [PropertyValue]
- furthermore each Property can be refined by Parameters (to indicates metadata, see `Parameter_`)
License and credits
Code is available under the MIT license.
Large inspiration has been taken from the [emersion/go-vcard] package (available under MIT).
emersion/go-vcard
Constants
const (
MIMEType = "text/vcard"
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.
Types
type Data
type Data struct {
Properties []Property
// contains filtered or unexported fields
}
Data represents a vCard
func New
func New(version Version, properties ...Property) Data
New creates a new vCard (a ProductID property is added, if not provided)
Example
names := vcard.Names{}.
WithFamilyName("Public").
WithGivenName("John").
WithAdditionalName("Quinlan", "Paul").
WithHonorificPrefix("Mr.").
WithHonorificSuffix("Esq.")
d := vcard.New(
vcard.Version3,
vcard.Property{
Name: vcard.Property_FormattedName,
Value: names.FormattedName(),
},
names.ToProperty(),
vcard.Timestamp(time.Date(1996, 10, 22, 14, 00, 00, 0, time.UTC)).ToProperty(vcard.Property_Revision),
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:3.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
func (d Data) Categories() []string
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) Kind
func (d Data) Kind() Kind
Kind of object the vCard represents rfc6350#section-6.1.4
func (Data) Names
func (d Data) Names() (n Names, ok bool)
Names returns the preferred names. rfc6350#section-6.2.2
func (*Data) PropertyDelete
func (d *Data) PropertyDelete(name string)
PropertyDelete removes all properties with the given name
func (Data) PropertyFirst
func (d Data) PropertyFirst(name string) (p Property, ok bool)
func (Data) PropertyPreferred
func (d Data) PropertyPreferred(name string) (p Property, ok bool)
PropertyPreferred returns the property with the highest preference
func (Data) Timestamp
func (d Data) Timestamp(name string) (time.Time, bool)
Timestamp return the timestamp of the preferred property (like [Property_Revision]). rfc6350#section-6.7.4
func (Data) Validate
func (d Data) Validate(extended bool) error
Validate checks if the properties fields have values that can be properly encoded into a vCard. If extended is true, more checks are performed (cardinality).
func (Data) Version
func (d Data) Version() Version
type Decoder
type Decoder struct {
// contains filtered or unexported fields
}
A Decoder parses vcard.[Data]
func NewDecoder
func NewDecoder(r io.Reader) Decoder
NewDecoder creates a new Decoder reading vcard.[Data] from an io.Reader.
Example
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
func (Decoder) Decode
func (dec Decoder) Decode() (Data, error)
Decode parses a single vcard.[Data].
type Encoder
type Encoder struct {
// contains filtered or unexported fields
}
An Encoder encodes [Data] in the vCard format.
func NewEncoder
func NewEncoder(w io.Writer) Encoder
NewEncoder creates a new Encoder. See [New] for a usage example.
func (Encoder) Encode
func (enc Encoder) Encode(d Data) error
Encode write a single [Data] in the vCard format to the underlying io.Writer
type Kind
Kind is a data kind.
const (
Kind_Individual Kind = "individual"
Kind_Group Kind = "group"
Kind_Organization Kind = "org"
Kind_Location Kind = "location"
)
func (Kind) IsKnown
func (k Kind) IsKnown() bool
func (Kind) ToProperty
func (k Kind) ToProperty() Property
type Names
type Names struct {
FamilyName []string
GivenName []string
AdditionalName []string
HonorificPrefix []string
HonorificSuffix []string
}
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 (n Names) ToProperty() Property
func (Names) WithAdditionalName
func (n Names) WithAdditionalName(s ...string) Names
func (Names) WithFamilyName
func (n Names) WithFamilyName(s ...string) Names
func (Names) WithGivenName
func (n Names) WithGivenName(s ...string) Names
func (Names) WithHonorificPrefix
func (n Names) WithHonorificPrefix(s ...string) Names
func (Names) WithHonorificSuffix
func (n Names) WithHonorificSuffix(s ...string) Names
type OrganizationLevels
type OrganizationLevels []string
func (OrganizationLevels) ToProperty
func (ol OrganizationLevels) ToProperty() Property
type Parameter
type Parameter struct {
Name string
Values []string
}
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
func (p Property) ParameterValues(name string) []string
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
func (p Property) Preference() uint8
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
func (p Property) WithPreference(i uint8) Property
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
func (Property) WithValue
func (p Property) WithValue(v string) 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 (pv PropertyValue) Names() Names
func (PropertyValue) OrganizationLevels
func (pv PropertyValue) OrganizationLevels() OrganizationLevels
func (PropertyValue) SplitTexts
func (pv PropertyValue) SplitTexts() []string
SplitTexts returns the value parts of a [Property], split by comma (each part being unescaped). Guaranteed to have a len > 0
func (PropertyValue) String
func (pv PropertyValue) String() string
String returns the raw value
func (PropertyValue) Timestamp
func (pv PropertyValue) Timestamp() (time.Time, error)
type Sex
Sex is an object's biological sex.
const (
Sex_Unspecified Sex = ""
Sex_Female Sex = "F"
Sex_Male Sex = "M"
Sex_Other Sex = "O"
Sex_None Sex = "N"
Sex_Unknown Sex = "U"
)
func (Sex) IsKnown
func (s Sex) IsKnown() bool
func (Sex) ToGenderProperty
func (s Sex) ToGenderProperty(identity string) Property
rfc6350#section-6.2.7
type Timestamp
func (Timestamp) ToProperty
func (t Timestamp) ToProperty(name string) Property
type Version
const (
Version2_1 Version = "2.1"
Version3 Version = "3.0" // recommended
Version4 Version = "4.0" // iOS has encoding issues with 4.0 vcards (2025)
)
Files
decoder.go
encoder.go
vcard.go
Forge
https://codeberg.org/pfad.fr/gopim-vcard
git clone
https://codeberg.org/pfad.fr/gopim-vcard.git
git@codeberg.org:pfad.fr/gopim-vcard.git