Naiveical

Naiveical lets you create and modify VCALENDAR and VCARD files, as well as extract specific parts of it. It does not parse the icalendar file but rather works directly with the pure text of the icalendar. As such it does not prevent you from doing stupid things, such as embedding elements into each other that have no meaning.

The advantage of this approach is to keep the vcalendar and vcard text as close to the original as possible, with only modifying the changed parts.

Rationale

In principle, you have two approaches to modify icalendar texts. You can either parse the icalendar file into its attributes and values and then recreate the updated icalendar file. However, the problem there is that the specifications allow to add vendor-specific attributes. These often get lost while parsing/re-creating of the icalendar text. This is the reason we choose here to do a naive approach by simply modifying the icalendar text directly, while keeping the rest of the text as-is.

Installation

The package available in Hex and can be installed by adding naiveical to your list of dependencies in mix.exs:

def deps do
  [
    {:naiveical, "~> 0.1.1"}
  ]
end

Documentation

Available at HexDocs.

Example of VCALENDAR CREATION

Creation of those files is handled with Creator.Icalendar and Creator.Vcard

Create a new vcalendar:

ical = Naiveical.Creator.Icalendar.create_vcalendar()

Create a new vtodo:

dtstart = DateTime.now!("Etc/UTC")
due = DateTime.now!("Etc/UTC")
todo = Naiveical.Creator.Icalendar.create_vtodo("vtodo example", dtstart, due)

Create a new valert:

alarm = Naiveical.Creator.Icalendar.create_valarm("Ring the bell", "-PT15M")
alarm2 = Naiveical.Creator.Icalendar.create_valarm("Ring the bell", "-PT5M")

Assemble all together:

      {:ok, todo} = Naiveical.Modificator.insert_into(todo, alarm, "VTODO")
      {:ok, todo} = Naiveical.Modificator.insert_into(todo, alarm2, "VTODO")
      {:ok, ical} = Naiveical.Modificator.insert_into(ical, todo, "VCALENDAR")

Extract the summary content line:

  Naiveical.Extractor.extract_contentline_by_tag(ical, "SUMMARY")
  {_tag, _attr, due_str} = Naiveical.Extractor.extract_contentline_by_tag(ical, "DUE")
  Naiveical.Helpers.parse_datetime(due_str)

Change the summary:

  updated_ical = Naiveical.Modificator.change_value(ical, "summary", "my updated summary")

Extract the alerts:

      valarms = Naiveical.Extractor.extract_sections_by_tag(ical, "VALARM")

Example of creating VCARD

Explanation

Creation of VCARD is possible passing multiple options for components when calling the function Naiveical.Creator.Vcard.create_vcard/2, or by merging all together with Naiveical.Modificator.insert_into/3 Creating with components options is supported without adding additional params to component. To create with additional component params use dedicated function for each component and pass there additional options. Each component has VCARD FORMAT reference for options.

EXAMPLES

With options

Create a new vcard

 Naiveical.Creator.Vcard.create_vcard("uid-12345", display_name: "User Test", email: "user@example.org", tel: "123456") 

With individual component creation

Create empty vcard

vcard = Naiveical.Creator.Vcard.create_vcard("uid-12345") 

Create email

email = Naiveical.Creator.Vcard.create_email("user@example.org", type: "work", pref: 1, label: "some label") 

Create telephone

tel = Naiveical.Creator.Vcard.create_telephone("123456789", type: "work")

Create name

name = Naiveical.Creator.Vcard.create_display_name("User", "Name") 

Assemble all together

  {:ok, vcard} = Naiveical.Modificator.insert_into(vcard, email, "VCARD")
  {:ok, vcard} = Naiveical.Modificator.insert_into(vcard, tel, "VCARD")
  {:ok, vcard} = Naiveical.Modificator.insert_into(vcard, name, "VCARD")

You can create multiple same components, and insert it like in the example above.

  email = Naiveical.Creator.Vcard.create_email("user@example.org", type: "work", pref: 1) 
  email = Naiveical.Creator.Vcard.create_email("user@example1.org", type: "home")
  email = Naiveical.Creator.Vcard.create_email("user@example2.org", type: "home", label: "new")

VTIMEZONE database

The VTIMEZONE database has been compiled by using the vzic utility.

Rationale

The difficulty in parsing the icalendar or vcard format is that it is difficult to write a library that can parse and re-create those
files without any data loss. As such it is best to keep the original files and work directly on the file. This makes working with the access of the individual fields more complicated but keeps the original file intact.