VCard parser and generator

This is a simple VCard parser and generator extracted from Hellotext. It implements the VCard 3.0 specification. It supports all of the cases we want to use in Hellotext.

Add this line to your application's Gemfile:

gem 'valerie'

Or install it yourself as:

gem install valerie

Parsing a VCard is as simple as passing a VCard string, like

data = "BEGIN:VCARD\r\nVERSION:3.0\r\nPRODID:-//Hellotext www.hellotext.com//EN\r\nN:Rosenbaum;Shira;;;\r\nTEL;:+598 00 000 00\r\nEND:VCARD"
Valerie::Card.parse(data)

You usually start by initializing a new Card object.

card = Valerie::Card.new

According to the VCard 3.0 specification, some types of properties can have multiple values. From the specs, Valerie supports the following properties:

• EMAIL: for email addresses
• TEL: for telephone numbers
• ADR: for addresses

Aside from these, every other support property supports a single value.

To set the name property for the VCard, you can use the Card#name= setter. It accepts two types of arguments,

A hash that contains the following

{
  first_name: 'Shira',
  last_name: 'Rosenbaum',
  middle_name: 'M',
  prefix: 'Ms.',
  suffix: 'PhD'
}

Or an array with the following order [first_name, last_name, middle_name, prefix, suffix].

card.name = %w[Shira Rosenbaum M Ms. PhD]

To set the Gender of the card you can, set it value Card#gender=, this accepts one of the following constants: male, female, other, none and unknown. Passing another value raises an ArgumentError.

card.gender = 'female'

The birthday can be set via Card#birthday=. It accepts any object that responds to strftime, otherwise it stores the to_s version of the value.

card.birthday = Date.new(1999, 11, 4)

The organization can be an tuple of [organization_name, department], or a hash of {organization: 'organization_name', department: 'department'}. When a string value is passed, only the organization_name is set.

card.organization = %w[Hellotext Engineering]
card.organization = { organization: 'Hellotext', department: 'Engineering' }
card.organization = 'Hellotext'

The card exposes methods to adding the respective collectable properties. Email, telephone and address.

Adding an email,

card.emails.add('user@domain.com')

Or a telephone number,

card.phones.add('+598 00 000 00')

Or an address,

card.addresses.add(
  {
    post_office_box: 'PO Box 123',
    extended_address: 'Suite 123',
    street_address: '123 Main St',
    locality: 'Anytown',
    region: 'CA',
    postal_code: '12345',
    country: 'United States'
  }
)

Emails, phones and addresses are ordered. They can include an optional position argument to specify their order when the profile has multiple values. Whenever you add a new value, a default position argument is picked and the value is appended as the last element.

To specify the position, you can pass the position argument as a keyword argument. Unlike arrays the position is 1-based and not 0-based.

card.emails.add('user@domain.com')
card.emails.add('user@domain2.com', position: 1) # inserts the email as the first element

Emails, phones and addresses can have types. The types are defined in the VCard 3.0 specification. To specify the type of one of these properties, you can pass the types argument as a keyword argument.

card.emails.add('user@domain.com', type: 'work')
card.emails.add('user@domain.com', type: %w[work internet])

You can configure the following properties of the card.

• prodid: The product id of the card. This defaults to 'Valerie www.hellotext.com'.
• version: The version of the card. This defaults to '3.0'.
• language: The language of the card. This defaults to 'en'.

Valerie.configure do |config|
  config.product = 'Valerie www.hellotext.com'
  config.version = '3.0'
  config.language = 'en'
end

This code is released under the MIT License. See the LICENSE file for more information.

• VCardigan

Contributions are welcome. Please follow the steps below to contribute.

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request