README.adoc
== 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].