== Ruby vObject parser

image:https://img.shields.io/gem/v/vobject.svg["Gem Version", link="https://rubygems.org/gems/vobject"] image:https://github.com/riboseinc/ruby-vobject/workflows/macos/badge.svg["Build Status (macOS)", link="https://github.com/riboseinc/ruby-vobject/actions?workflow=macos"] image:https://github.com/riboseinc/ruby-vobject/workflows/ubuntu/badge.svg["Build Status (ubuntu)", link="https://github.com/riboseinc/ruby-vobject/actions?workflow=ubuntu"] image:https://github.com/riboseinc/ruby-vobject/workflows/windows/badge.svg["Build Status (Windows)", link="https://github.com/riboseinc/ruby-vobject/actions?workflow=windows"] image:https://codeclimate.com/github/riboseinc/ruby-vobject/badges/gpa.svg["Code Climate", link="https://codeclimate.com/github/riboseinc/ruby-vobject"] image:https://img.shields.io/github/issues-pr-raw/riboseinc/ruby-vobject.svg["Pull Requests", link="https://github.com/riboseinc/ruby-vobject/pulls"] image:https://img.shields.io/github/commits-since/riboseinc/ruby-vobject/latest.svg["Commits since latest",link="https://github.com/riboseinc/ruby-vobject/releases"]

The main purpose of the gem is to parse vObject formatted text into a ruby hash format. Currently there are two possibilities of vObjects, namely iCalendar (https://tools.ietf.org/html/rfc5545) and vCard (https://tools.ietf.org/html/rfc6350). This gem parses iCalendar objects and vCard objects in versions 3.0 and 4.0, together with any subsequent additions to those specifications in other RFCs (see below).

A secondary purpose is to create a normalised form of vObject (iCalendars and vCards version 4.0), which can be used to compare two vObject with minor formatting differences.

NOTE: This gem used to be named ruby-vobject (from versions 0.1.0 to 1.0.1), but for clarity purposes it is now simply called vobject (from version 1.0.2 onwards).

== Installation

Add this line to your application's Gemfile:

[source,ruby]

gem 'vobject'

And then execute:

[source,console]

$ bundle

Or install it yourself as:

[source,console]

$ gem install vobject

== Usage

[source,ruby]

require 'vcalendar' require 'JSON' require 'pp'

ics = File.read "spec/examples/vcalendar/timezones/America/Denver.ics"

parse VCalendar into native object structure, with strict validation

(raises exception on any deviation from the spec)

pp Vcalendar.parse(ics, true)

parse VCalendar into native object structure, without strict validation

(errors other than syntax errors are logged, but object still parses)

pp Vcalendar.parse(ics, false)

list any errors

pp Vcalendar.parse(ics, false).get_errors

convert VCalendar into Ruby hash

pp Vcalendar.parse(ics).to_hash

convert VCalendar into JSON

pp JSON.parse(Vcalendar.parse(ics).to_json)

convert VCalendar into VCalendar text

print Vcalendar.parse(ics).to_s

convert VCalendar into normalised VCalendar text

print Vcalendar.parse(ics).to_norm

[source,ruby]

require 'vcard' require 'JSON' require 'pp'

vcf = File.read "spec/examples/vcard/vcard3.vcf"

parse Vcard into native object structure (version 3), strict validation

pp Vcard.parse(vcf, '3.0', true)

parse Vcard into Ruby hash

pp Vcard.parse(vcf, '3.0', true).to_hash

parse Vcard into JSON

pp JSON.parse(Vcard.parse(vcf, '3.0', true).to_json)

parse Vcard into VCard text

print Vcard.parse(vcf, '3.0', true).to_s vcf = File.read "spec/examples/vcard/example61.vcf"

parse Vcard into native object structure (version 4), lax validation

pp Vcard.parse(vcf, '4.0', false)

list any errors

pp Vcard.parse(vcf, '4.0', false).get_errors

• Recognises all of VCard v3.0, Vcard v4.0, and Vcalendar v2.0
• Components, properties, and parameters are all objects. ** Each type of component is a distinct object.
• The parameters of a property are represented as an array of parameter objects.
• If a property has multiple values, given on separate lines, they are represented as an array of value properties. Each value hash may have its own parameters.
• The values of properties are also typed objects.
• Objects can be parsed from text files.
• Objects can be populated from hashes of property value objects.
• Objects can be converted to Ruby hashes with native property value types (.to_hash), JSON objects with the same value types (.to_json), and round-tripped back to ICAL/VCARD string representations (.to_s).
• The normalised form of vObjects (.to_norm) applies normalising conventions to the string representation; most notably presenting elements of a vCard in sorted order. ** Normalisation follows the draft RFC draft-calconnect-vobject-and-normalization.
• Validation can be strict or lax. If strict, an exception is raised on any syntax error, type mismatch, or other mismatch to the specification, such as mandatory elements. If lax, an exception is still raised on syntax errors, but other issues are listed in an error field of the resulting object.
• Normalisation follows the draft RFC draft-calconnect-vobject-and-normalization.

Running spec:

[source,console]

bundle exec rspec

== Implementation

This gem is implemented using https://github.com/luikore/rsec[Rsec], a very fast PEG grammar based on StringScanner.

== Coverage

This tool is intended as a reference implementation, and it is very strict in its conformance: it requires all rules for parameter coocurrence, property typing, parameter typing, permitted properties within components, etc. to be met by objects.

The tool only parses one object at a time, and does not parse vObject streams.

This tool supports v2.0 iCal as specified in RFC 5545, and as updated in RFC 5546 (registry for values of METHOD and REQUEST-STATUS), RFC 6868 (caret escapes for parameter values), RFC 7529 (non-Gregorian Calendars), RFC 7953 (VAVAILABILITY component), and RFC 7986 (new properties).

This tool supports v3.0 vCard as specified in RFC 2425 and RFC 2426, and as updated in RFC 2739 (calendar attributes) and RFC 4770 (extensions for Instant Messaging). It allows for the VCARD 2.1 style specification of PREF parameters in RFC 2739.

This tool supports v4.0 vCard as specified in RFC 6350, and as updated in RFC 6868 (parameter encoding), RFC 6474 (place of birth, place and date of death), RFC 6715 (OMA CAB extensions), and RF 6473 (KIND:application).

== Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/riboseinc/vobject. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the http://contributor-covenant.org[Contributor Covenant] code of conduct.

== License

The gem is available as open source under the terms of the http://opensource.org/licenses/MIT[MIT License].