Calcard

https://github.com/stalwartlabs/calcard
Admin
Calcard is a Rust library for parsing, generating, and converting calendaring and contact data...
Tokens:48,530
Snippets:261
Trust Score:9.5
Update:5 months ago
Show doc for...
Tokens:
Raw
### Convert DTSTART with TZID parameter

Source: https://github.com/stalwartlabs/calcard/blob/main/resources/jscalendar/007_date.txt

Converts iCalendar DTSTART with a TZID parameter to Calcard JSON 'start' and 'timeZone' properties.

```icalendar
DTSTART;TZID=Europe/Berlin:20240921T105302
```

```json
{
"start": "2024-09-21T10:53:02",
"timeZone": "Europe/Berlin"
}
```

--------------------------------

### Convert RFC VALARM Example to JSON Alert

Source: https://github.com/stalwartlabs/calcard/blob/main/resources/jscalendar/003_alert.txt

Converts a standard iCalendar VALARM example from RFC to a JSON alert object. This includes properties like UID, TRIGGER, ACTION, and DESCRIPTION.

```json
"alerts": {
  "k1": {
    "@type": "Alert",
    "iCalendar": {
      "name": "valarm",
      "properties": [
        [
          "description",
          {},
          "unknown",
          "Breakfast meeting"
        ],
        [
          "uid",
          {},
          "unknown",
          "04DC2968-6468-4B92-BC09-5A17D7D3D4E"
        ]
      ]
    },
    "trigger": {
      "@type": "OffsetTrigger",
      "offset": "-PT30M"
    },
    "action": "display"
  }
}
```

--------------------------------

### Convert DTSTART with UTC time

Source: https://github.com/stalwartlabs/calcard/blob/main/resources/jscalendar/007_date.txt

Converts iCalendar DTSTART with UTC time (Z suffix) to Calcard JSON 'start' and 'timeZone' properties.

```icalendar
DTSTART:20240921T105302Z
```

```json
{
"start": "2024-09-21T10:53:02",
"timeZone": "Etc/UTC"
}
```

--------------------------------

### Create iCalendar Entries with Parameters in Rust

Source: https://context7.com/stalwartlabs/calcard/llms.txt

This example shows how to construct iCalendar entries using the `ICalendarEntry` struct. It demonstrates adding properties like `DTSTART`, `ATTENDEE`, and `SUMMARY`, along with their respective parameters such as `tzid`, `cn`, `rsvp`, and `language`. Ensure you have the necessary imports for `ICalendarEntry`, `ICalendarProperty`, `ICalendarParameter`, and `ICalendarValue`.

```rust
use calcard::icalendar::{
    ICalendarEntry,
    ICalendarProperty,
    ICalendarParameter,
    ICalendarValue
};

// Create a DTSTART entry with timezone parameter
let dtstart = ICalendarEntry::new(ICalendarProperty::Dtstart)
    .with_param(ICalendarParameter::tzid("America/New_York".to_string()))
    .with_value("20240515T143000".to_string());

// Create an ATTENDEE entry with multiple parameters
let attendee = ICalendarEntry::new(ICalendarProperty::Attendee)
    .with_param(ICalendarParameter::cn("John Doe".to_string()))
    .with_param(ICalendarParameter::rsvp(true))
    .with_value("mailto:john@example.com".to_string());

// Create a SUMMARY with language parameter
let summary = ICalendarEntry::new(ICalendarProperty::Summary)
    .with_param(ICalendarParameter::language("en-US".to_string()))
    .with_value("Weekly Team Sync".to_string());

println!("Created calendar entries");
```

--------------------------------

### Convert DTSTART with floating time

Source: https://github.com/stalwartlabs/calcard/blob/main/resources/jscalendar/007_date.txt

Converts iCalendar DTSTART with floating time (no timezone info) to Calcard JSON 'start' property with null 'timeZone'.

```icalendar
DTSTART:20240921T105302
```

```json
{
"start": "2024-09-21T10:53:02",
"timeZone": null
}
```

--------------------------------

### Event with Physical and Virtual Locations (JSON)

Source: https://github.com/stalwartlabs/calcard/blob/main/resources/jscalendar/010_complete.txt

Represents an event with a main physical location and an additional parking location, alongside a virtual streaming location. Ensure all required fields like title, start time, and duration are provided.

```json
{
  "@type": "Event",
  "title": "Live from Music Bowl: The Band",
  "description": "Go see the biggest music event ever!",
  "locale": "en",
  "start": "2020-07-04T17:00:00",
  "timeZone": "America/New_York",
  "duration": "PT3H",
  "mainLocationId": "c0503d30-8c50-4372-87b5-7657e8e0fedd",
  "locations": {
    "c0503d30-8c50-4372-87b5-7657e8e0fedd": {
      "name": "The Music Bowl",
      "description": "Music Bowl, Central Park, New York",
      "coordinates": "geo:40.7829,-73.9654"
    },
    "ee42e41e-1046-4489-9760-c0b85f0dc176": {
      "name": "BAZ Parking, 9 West 57th Street, New York",
      "coordinates": "geo:40.7637,-73.9748",
      "locationTypes": {
        "parking": true
      }
    }
  },
  "virtualLocations": {
    "vloc1": {
      "name": "Free live Stream from Music Bowl",
      "uri": "https://stream.example.com/the_band_2020"
    }
  }
}
```

--------------------------------

### Convert RFC6350 N and FN to JSON (Variant 5)

Source: https://github.com/stalwartlabs/calcard/blob/main/resources/jscontact/015_rfc6350.txt

Converts RFC6350 N and FN properties for a name with a surname starting with a preposition ('d''). Demonstrates handling of such cases.

```vcard
FN:Chistine d'Aboville
N;SORT-AS="Aboville,Christine";JSCOMPS=";;1":d'Aboville;Christine;;;;;
```

```json
"name": {
    "components": [
      {
        "kind": "surname",
        "value": "d'Aboville"
      },
      {
        "kind": "given",
        "value": "Christine"
      }
    ],
    "full": "Chistine d'Aboville",
    "sortAs": {
      "given": "Christine",
      "surname": "Aboville"
    }
  }
```

--------------------------------

### Convert DUE with DATE value type and DTSTART

Source: https://github.com/stalwartlabs/calcard/blob/main/resources/jscalendar/007_date.txt

Converts iCalendar DUE and DTSTART with VALUE=DATE to Calcard JSON 'due' and 'start' properties, setting 'showWithoutTime' to true and 'timeZone' to null for a VTODO.

```icalendar
BEGIN:VTODO
DTSTART;VALUE=DATE:20250220
DUE;VALUE=DATE:20250221
```

```json
{
"@type": "Task",
"start": "2025-02-20T00:00:00",
"due": "2025-02-21T00:00:00",
"timeZone": null,
"showWithoutTime": true,
"iCalendar": {
        "convertedProperties": {
          "due": {
            "parameters": {
              "value": "DATE"
            }
          },
          "start": {
            "parameters": {
              "value": "DATE"
            }
          }
        },
        "name": "vtodo"
}
}
```

--------------------------------

### Convert DTSTART with value type DATE

Source: https://github.com/stalwartlabs/calcard/blob/main/resources/jscalendar/007_date.txt

Converts iCalendar DTSTART with VALUE=DATE to Calcard JSON 'start' property, setting 'showWithoutTime' to true and 'timeZone' to null.

```icalendar
DTSTART;VALUE=DATE:20240921
```

```json
{
"start": "2024-09-21T00:00:00",
"timeZone": null,
"showWithoutTime": true,
      "iCalendar": {
        "convertedProperties": {
          "start": {
            "parameters": {
              "value": "DATE"
            }
          }
        },
        "name": "vevent"
}
}
```

--------------------------------

### Convert VEVENT recurrence instances to JSON

Source: https://github.com/stalwartlabs/calcard/blob/main/resources/jscalendar/008_recurrence.txt

Demonstrates how multiple VEVENT entries with RECURRENCE-ID and DTSTART are converted into separate JSON event objects, each with its recurrence ID and start time.

```icalendar
BEGIN:VCALENDAR
BEGIN:VEVENT
UID:F4257E1D-5461-4EF6-840F-9DFC653EB559
RECURRENCE-ID;TZID=Europe/Berlin:20240202T140000
DTSTART;TZID=Europe/Berlin:20240202T160000
END:VEVENT
BEGIN:VEVENT
UID:F4257E1D-5461-4EF6-840F-9DFC653EB559
RECURRENCE-ID;TZID=Europe/Berlin:20240103T140000
DTSTART;TZID=Europe/Berlin:20240103T170000
END:VEVENT
END:VCALENDAR
```

```json
{
  "@type": "Group",
  "entries": [
    {
      "@type": "Event",
      "recurrenceId": "2024-02-02T14:00:00",
      "recurrenceIdTimeZone": "Europe/Berlin",
      "start": "2024-02-02T16:00:00",
      "timeZone": "Europe/Berlin",
      "uid": "F4257E1D-5461-4EF6-840F-9DFC653EB559"
    },
    {
      "@type": "Event",
      "recurrenceId": "2024-01-03T14:00:00",
      "recurrenceIdTimeZone": "Europe/Berlin",
      "start": "2024-01-03T17:00:00",
      "timeZone": "Europe/Berlin",
      "uid": "F4257E1D-5461-4EF6-840F-9DFC653EB559"
    }
  ]
}
```

--------------------------------

### Convert RFC9555 GRAMGENDER and PRONOUNS to vCard Properties

Source: https://github.com/stalwartlabs/calcard/blob/main/resources/jscontact/004_gender.txt

Converts RFC9555 GRAMGENDER and PRONOUNS properties into a vCard property list format. This example shows how preferences and property IDs are mapped.

```text
GRAMGENDER:NEUTER
PRONOUNS;PREF=2;PROP-ID=k1:they/them
PRONOUNS;PREF=1;PROP-ID=k2:xe/xir
```

--------------------------------

### Convert VCALENDAR with VTIMEZONE to JSON

Source: https://github.com/stalwartlabs/calcard/blob/main/resources/jscalendar/009_icalcomponent.txt

Converts a full VCALENDAR object, including VTIMEZONE definitions and VEVENTs, into a structured JSON format. This example highlights the parsing of timezone rules and event details.

```go
BEGIN:VCALENDAR
METHOD:PUBLISH
X-WR-TIMEZONE:America/Vancouver
PRODID:-//Apple Inc.//iCal 3.0//EN
CALSCALE:GREGORIAN
X-WR-CALNAME:weekly
VERSION:2.0
X-WR-RELCALID:967F55F6-968E-49EF-A050-DAF6DB680D39
X-APPLE-CALENDAR-COLOR:#F57802
BEGIN:VTIMEZONE
TZID:America/Vancouver
BEGIN:DAYLIGHT
TZOFFSETFROM:-0800
TZOFFSETTO:-0700
DTSTART:20070311T020000
RRULE:FREQ=YEARLY;BYMONTH=3;BYDAY=2SU
TZNAME:PDT
END:DAYLIGHT
BEGIN:STANDARD
TZOFFSETFROM:-0700
TZOFFSETTO:-0800
DTSTART:20071104T020000
RRULE:FREQ=YEARLY;BYMONTH=11;BYDAY=1SU
TZNAME:PST
END:STANDARD
END:VTIMEZONE
BEGIN:VEVENT
SEQUENCE:7
DESCRIPTION:It will pay the bills.
UID:CFE00EC6-AB4A-4FCE-A32F-6076BA1D8578
TRANSP:OPAQUE
URL;VALUE=URI:http://www.worklessparty.org/
DTSTART;TZID=America/Vancouver:20090309T090000
DTSTAMP:20090310T034303Z
SUMMARY:Go to work.
CREATED:20090310T033824Z
DTEND;TZID=America/Vancouver:20090309T170000
RRULE:FREQ=WEEKLY;INTERVAL=1
END:VEVENT
END:VCALENDAR
> convert
{
  "@type": "Group",
  "entries": [
    {
      "@type": "Event",
      "created": "2009-03-10T03:38:24Z",
      "description": "It will pay the bills.",
      "duration": "PT8H",
      "freeBusyStatus": "busy",
      "iCalendar": {
        "convertedProperties": {
          "duration": {
            "name": "dtend"
          }
        },
        "name": "vevent",
        "properties": [
          [
            "url",
            {},
            "unknown",
            "http://www.worklessparty.org/"
          ]
        ]
      },
      "method": "publish",
      "recurrenceRule": {
        "frequency": "weekly",
        "interval": 1
      },
      "sequence": 7,
      "start": "2009-03-09T09:00:00",
      "timeZone": "America/Vancouver",
      "title": "Go to work.",
      "uid": "CFE00EC6-AB4A-4FCE-A32F-6076BA1D8578",
      "updated": "2009-03-10T03:43:03Z"
    }
  ],
  "iCalendar": {
    "components": [
      [
        "vtimezone",
        [
          [
            "tzid",
            {},
            "unknown",
            "America/Vancouver"
          ]
        ],
        [
          [
            "daylight",
            [
              [
                "dtstart",
                {},
                "unknown",
                "20070311T020000"
              ],
              [
                "tzname",
                {},
                "unknown",
                "PDT"
              ],
              [
                "tzoffsetfrom",
                {},
                "unknown",
                "-0800"
              ],
              [
                "tzoffsetto",
                {},
                "unknown",
                "-0700"
              ],
              [
                "rrule",
                {},
                "unknown",
                "FREQ=YEARLY;BYDAY=2SU;BYMONTH=3"
              ]
            ],
            []
          ],
          [
            "standard",
            [
              [
                "dtstart",
                {},
                "unknown",
                "20071104T020000"
              ],
              [
                "tzname",
                {},
                "unknown",
                "PST"
              ],
              [
                "tzoffsetfrom",
                {},
                "unknown",
                "-0700"
              ],
              [
                "tzoffsetto",
                {},
                "unknown",
                "-0800"
              ],
              [
                "rrule",
                {},
                "unknown",
                "FREQ=YEARLY;BYDAY=1SU;BYMONTH=11"
              ]
            ],
            []
          ]
        ]
      ]
    ],
    "name": "vcalendar",
    "properties": [
      [
        "x-apple-calendar-color",
        {},
        "unknown",
        "#F57802"
      ],
      [
        "x-wr-calname",
        {},
        "unknown",
        "weekly"
      ],
      [
        "x-wr-relcalid",
        {},
        "unknown",
        "967F55F6-968E-49EF-A050-DAF6DB680D39"
      ],
      [
        "x-wr-timezone",
        {},
        "unknown",
        "America/Vancouver"
      ]
    ]
  }
}
```

--------------------------------

### iCalendar with Non-IANA Timezones

Source: https://github.com/stalwartlabs/calcard/blob/main/resources/jscalendar/007_date.txt

Demonstrates an iCalendar event with explicit timezone IDs for start, end, and recurrence exclusion dates. This shows how Calcard parses and normalizes these.

```icalendar
BEGIN:VCALENDAR
BEGIN:VEVENT
UID:0000001
SUMMARY:Treasure Hunting
DTSTART;TZID="(UTC-05:00) Eastern Time (US and Canada)":20150706T120000
DTEND;TZID=America/Los_Angeles:20150706T130000
RRULE:FREQ=DAILY;COUNT=10
EXDATE;TZID=America/Los_Angeles:20150708T120000
EXDATE;TZID=America/Los_Angeles:20150710T120000
END:VEVENT
END:VCALENDAR
```

--------------------------------

### iCalendar with Multiple Timezones and RDATE

Source: https://github.com/stalwartlabs/calcard/blob/main/resources/jscalendar/007_date.txt

Illustrates an iCalendar with multiple events and a todo item, each potentially using different timezones for start, end, recurrence, and due dates. Includes RDATE entries with TZIDs.

```icalendar
BEGIN:VCALENDAR
DESCRIPTION:We leave the timezones out but we use common names so that they are added.
BEGIN:VEVENT
DTSTART;TZID=America/New_York;VALUE=DATE-TIME:20140829T080000
DTEND;TZID=America/Los_Angeles;VALUE=DATE-TIME:20140829T080000
RDATE;TZID=Europe/Berlin:20240913T120000
SUMMARY:an event with a custom tz name
END:VEVENT
BEGIN:VEVENT
RECURRENCE-ID;TZID=Europe/Moscow:20190309T020000
END:VEVENT
BEGIN:VTODO
DUE;TZID=Asia/Singapore;VALUE=DATE-TIME:20140829T080000
END:VTODO
BEGIN:VEVENT
RDATE;TZID=Mexico/General:20190309T020000
RDATE;TZID=America/Noronha:20190309T020000
DTSTAMP:19920901T130000Z
END:VEVENT
END:VCALENDAR
```

--------------------------------

### Run Test Suite

Source: https://github.com/stalwartlabs/calcard/blob/main/README.md

Execute the library's test suite using Cargo. The `--all-features` flag ensures all features are tested.

```bash
$ cargo test --all-features
```

--------------------------------

### Create and Serialize VCard Entries

Source: https://context7.com/stalwartlabs/calcard/llms.txt

Demonstrates creating formatted name and phone number entries for a vCard, including parameters, and then serializing the vCard to version 4.0. Ensure all necessary imports are included.

```rust
use calcard::vcard::{
    VCard,
    VCardEntry,
    VCardProperty,
    VCardParameter,
    VCardValue,
    VCardVersion
};

let mut vcard = VCard::default();

// Create a formatted name entry
let fn_entry = VCardEntry {
    group: None,
    name: VCardProperty::Fn,
    params: vec![],
    values: vec![VCardValue::Text("Dr. Jane Smith".to_string())],
};
vcard.entries.push(fn_entry);

// Create a phone entry with type parameter
let tel_entry = VCardEntry {
    group: None,
    name: VCardProperty::Tel,
    params: vec![
        VCardParameter::type_value(calcard::vcard::VCardType::Work),
        VCardParameter::type_value(calcard::vcard::VCardType::Voice),
    ],
    values: vec![VCardValue::Text("+1-555-000-1234".to_string())],
};
vcard.entries.push(tel_entry);

// Serialize the vCard
let mut output = String::new();
vcard.write_to(&mut output, VCardVersion::V4_0).unwrap();
println!("{}", output);
```

--------------------------------

### Run Test Suite with MIRI

Source: https://github.com/stalwartlabs/calcard/blob/main/README.md

Run the test suite with MIRI for memory safety checks. This requires the nightly toolchain.

```bash
$ cargo +nightly miri test --all-features
```

--------------------------------

### Convert TITLE with ALTID to RFC6350 (No Localizations)

Source: https://github.com/stalwartlabs/calcard/blob/main/resources/jscontact/015_rfc6350.txt

Demonstrates the conversion of TITLE properties with ALTID and language parameters to RFC6350 format when no explicit localizations are present in the input.

```text
TITLE;PROP-ID=k1;ALTID=1;LANGUAGE=fr:Patron
TITLE;PROP-ID=k2;ALTID=2;LANGUAGE=en:Boss
LANGUAGE:fr
```

--------------------------------

### Convert Simple JSPROP Property

Source: https://github.com/stalwartlabs/calcard/blob/main/resources/jscontact/012_unknown.txt

Demonstrates the conversion of a simple unknown property to JSPROP format.

```text
"someUnknownProperty": true
JSPROP;JSPTR="someUnknownProperty":true
```

--------------------------------

### Convert DTEND with DATE value type

Source: https://github.com/stalwartlabs/calcard/blob/main/resources/jscalendar/007_date.txt

Converts iCalendar DTEND with VALUE=DATE to Calcard JSON. Sets 'showWithoutTime' to true and uses 'duration' and 'start' properties.

```icalendar
DTSTART;VALUE=DATE:20240102
DTEND;VALUE=DATE:20240107
```

```json
{
"start": "2024-01-02T00:00:00",
"timeZone": null,
"duration": "P5D",
"showWithoutTime": true,
"iCalendar": {
    "name": "vevent",
    "convertedProperties": {
          "duration": {
            "name": "dtend",
            "parameters": {
              "value": "DATE"
            }
          },
          "start": {
            "parameters": {
              "value": "DATE"
            }
          }
    }
}
}
```

--------------------------------

### Parse JSCalendar JSON in Rust

Source: https://github.com/stalwartlabs/calcard/blob/main/README.md

Parse a JSCalendar JSON string using the `JSCalendar::parse` method. This example demonstrates parsing a group with nested events and tasks.

```rust
let input = r#"{ 
                    "@type": "Group",
                    "uid": "bf0ac22b-4989-4caf-9ebd-54301b4ee51a",
                    "updated": "2020-01-15T18:00:00Z",
                    "title": "A simple group",
                    "entries": [{
                        "@type": "Event",
                        "uid": "a8df6573-0474-496d-8496-033ad45d7fea",
                        "updated": "2020-01-02T18:23:04Z",
                        "title": "Some event",
                        "start": "2020-01-15T13:00:00",
                        "timeZone": "America/New_York",
                        "duration": "PT1H"
                    },
                    {
                        "@type": "Task",
                        "uid": "2a358cee-6489-4f14-a57f-c104db4dc2f2",
                        "updated": "2020-01-09T14:32:01Z",
                        "title": "Do something"
                    }]
                }"#;

let jscalendar = JSCalendar::<String, String>::parse(input).unwrap();
println!("Parsed JSCalendar: {}", jscalendar.to_string_pretty());
```

--------------------------------

### Convert N with ALTID and Language to JSON

Source: https://github.com/stalwartlabs/calcard/blob/main/resources/jscontact/015_rfc6350.txt

Illustrates the conversion of N (name) properties with ALTID and language parameters into a structured JSON format, including localizations.

```text
N;ALTID=1;LANGUAGE=jp:<U+5C71><U+7530>;<U+592A><U+90CE>;;;
N;ALTID=1;LANGUAGE=en:Yamada;Taro;;;
```

```json
{
  "language": "jp",
  "localizations": {
    "en": {
      "name/components": [
        {
          "kind": "surname",
          "value": "Yamada"
        },
        {
          "kind": "given",
          "value": "Taro"
        }
      ]
    }
  },
  "name": {
    "components": [
      {
        "kind": "surname",
        "value": "<U+5C71><U+7530>"
      },
      {
        "kind": "given",
        "value": "<U+592A><U+90CE>"
      }
    ]
  },
  "vCard": {
    "convertedProperties": {
      "localizations/en/name~1components": {
        "parameters": {
          "altid": "1"
        }
      },
      "name/components": {
        "parameters": {
          "altid": "1",
          "language": "jp"
        }
      }
    }
  }
}
```

--------------------------------

### Convert Multiple N with ALTID to JSON

Source: https://github.com/stalwartlabs/calcard/blob/main/resources/jscontact/015_rfc6350.txt

Demonstrates handling multiple N properties with the same ALTID but different languages, converting them into a JSON structure with localizations.

```text
N;ALTID=1;LANGUAGE=jp:<U+5C71><U+7530>;<U+592A><U+90CE>;;;
N;ALTID=1;LANGUAGE=en:Yamada;Taro;;;
N;ALTID=1;LANGUAGE=en:Smith;John;;;
```

```json
{
  "language": "en",
  "localizations": {
    "jp": {
      "name/components": [
        {
          "kind": "surname",
          "value": "<U+5C71><U+7530>"
        },
        {
          "kind": "given",
          "value": "<U+592A><U+90CE>"
        }
      ]
    }
  },
  "name": {
    "components": [
      {
        "kind": "surname",
        "value": "Yamada"
      },
      {
        "kind": "given",
        "value": "Taro"
      }
    ]
  },
  "vCard": {
    "convertedProperties": {
      "localizations/jp/name~1components": {
        "parameters": {
          "altid": "1"
        }
      },
      "name/components": {
        "parameters": {
          "altid": "1",
          "language": "en"
        }
      }
    },
    "properties": [
      [
        "n",
        {
          "altid": "1",
          "language": "en"
        },
        "unknown",
        [
          "Smith",
          "John",
          "",
          "",
          ""
        ]
      ]
    ]
  }
}
```

--------------------------------

### Convert RFC9553 directories to ORG-DIRECTORY format

Source: https://github.com/stalwartlabs/calcard/blob/main/resources/jscontact/014_rfc9553.txt

Converts directory entries and directories to the ORG-DIRECTORY format. The PREF property is included if present.

```json
"directories": {
  "dir1": {
    "kind": "entry",
    "uri": "https://dir.example.com/addrbook/jdoe/Jean%20Dupont.vcf"
  },
  "dir2": {
    "kind": "directory",
    "uri": "ldap://ldap.example/o=Example%20Tech,ou=Engineering",
    "pref": 1
  }
}
```

```text
SOURCE;PROP-ID=dir1:https://dir.example.com/addrbook/jdoe/Jean%20Dupont.vcf
ORG-DIRECTORY;PREF=1;PROP-ID=dir2:ldap://ldap.example/o=Example%20Tech,ou=E
 ngineering
```

--------------------------------

### Convert ROLE to RFC6350

Source: https://github.com/stalwartlabs/calcard/blob/main/resources/jscontact/015_rfc6350.txt

Demonstrates the conversion of a simple ROLE property with a language parameter to its RFC6350 representation.

```text
ROLE;LANGUAGE=tr:hoca
```

```json
{
  "titles": {
    "k1": {
      "kind": "role",
      "name": "hoca"
    }
  },
  "vCard": {
    "convertedProperties": {
      "titles/k1/name": {
        "parameters": {
          "language": "tr"
        }
      }
    }
  }
}
```

--------------------------------

### Convert Simple Event JSON to VEVENT

Source: https://github.com/stalwartlabs/calcard/blob/main/resources/jscalendar/010_complete.txt

Converts a simple JSCalendar Event JSON object to an iCalendar VEVENT format. Includes title, start time, time zone, and duration.

```json
{
  "@type": "Event",
  "uid": "a8df6573-0474-496d-8496-033ad45d7fea",
  "updated": "2020-01-02T18:23:04Z",
  "title": "Some event",
  "start": "2020-01-15T13:00:00",
  "timeZone": "America/New_York",
  "duration": "PT1H"
}
```

```icalendar
BEGIN:VEVENT
SUMMARY:Some event
DTSTART;TZID=America/New_York:20200115T130000
DURATION:PT1H
UID:a8df6573-0474-496d-8496-033ad45d7fea
DTSTAMP:20200102T182304Z
END:VEVENT
END:VCALENDAR
```

--------------------------------

### Convert TITLE with PROP-ID and ALTID to RFC6350

Source: https://github.com/stalwartlabs/calcard/blob/main/resources/jscontact/015_rfc6350.txt

Shows the conversion of TITLE properties that include PROP-ID, ALTID, and language parameters.

```text
TITLE;PROP-ID=k1;ALTID=1;LANGUAGE=fr:Patron
TITLE;PROP-ID=k1;ALTID=1;LANGUAGE=en:Boss
LANGUAGE:fr
```

--------------------------------

### JSON Conversion of iCalendar with Mixed Timezones

Source: https://github.com/stalwartlabs/calcard/blob/main/resources/jscalendar/007_date.txt

The JSON output corresponding to the complex iCalendar example, showing how Calcard maps various timezone specifications, including RDATEs and RECURRENCE-ID, to JSON properties.

```json
{
  "@type": "Group",
  "description": "We leave the timezones out but we use common names so that they are added.",
  "entries": [
    {
      "@type": "Event",
      "duration": "PT3H",
      "endTimeZone": "America/Los_Angeles",
      "iCalendar": {
        "convertedProperties": {
          "duration": {
            "name": "dtend"
          },
          "recurrenceOverrides/2024-09-13T06:00:00": {
            "parameters": {
              "tzid": "Europe/Berlin"
            }
          }
        },
        "name": "vevent"
      },
      "recurrenceOverrides": {
        "2024-09-13T06:00:00": {}
      },
      "start": "2014-08-29T08:00:00",
      "timeZone": "America/New_York",
      "title": "an event with a custom tz name"
    },
    {
      "@type": "Task",
      "due": "2014-08-29T08:00:00",
      "timeZone": "Asia/Singapore"
    },
    {
      "@type": "Event",
      "iCalendar": {
        "convertedProperties": {
          "recurrenceOverrides/2019-03-08T22:00:00": {
            "parameters": {
              "tzid": "America/Noronha"
            }
          },
          "recurrenceOverrides/2019-03-09T02:00:00": {
            "parameters": {
              "tzid": "Mexico/General"
            }
          }
        },
        "name": "vevent"
      },
      "recurrenceOverrides": {
        "2019-03-08T22:00:00": {},
        "2019-03-09T02:00:00": {}
      },
      "timeZone": "Mexico/General",
      "updated": "1992-09-01T13:00:00Z"
    },
    {
      "@type": "Event",
      "recurrenceId": "2019-03-09T02:00:00",
      "recurrenceIdTimeZone": "Europe/Moscow",
      "timeZone": "Europe/Moscow"
    }
  ]
}
```

--------------------------------

### Convert Unknown Property with Parameters

Source: https://github.com/stalwartlabs/calcard/blob/main/resources/jscontact/012_unknown.txt

Demonstrates the conversion of an unknown vCard property with parameters into a structured JSON format.

```json
"vCard": {
    "properties": [
      [
        "x-foo",
        {
          "group": "item1",
          "x-bar": "Hello"
        },
        "unknown",
        "World!"
      ]
    ]
}
```

--------------------------------

### Recurring Event with Overrides (JSON)

Source: https://github.com/stalwartlabs/calcard/blob/main/resources/jscalendar/010_complete.txt

Defines a recurring event with specific overrides for individual occurrences, including changes to title, start time, duration, and location. The 'excluded' flag can be used to cancel an occurrence.

```json
{
  "@type": "Event",
  "title": "Calculus I",
  "start": "2020-01-08T09:00:00",
  "timeZone": "Europe/London",
  "duration": "PT1H30M",
  "uid": "ee42e41e-1046-4489-9760-c0b85f0dc176",
  "locations": {
    "mlab": {
      "name": "Math lab room 1",
      "description": "Math Lab I, Department of Mathematics"
    }
  },
  "recurrenceRule": {
    "frequency": "weekly",
    "until": "2020-06-24T09:00:00"
  },
  "recurrenceOverrides": {
    "2020-01-07T14:00:00": {
      "title": "Introduction to Calculus I (optional)"
    },
    "2020-04-01T09:00:00": {
      "excluded": true
    },
    "2020-06-25T09:00:00": {
      "title": "Calculus I Exam",
      "start": "2020-06-25T10:00:00",
      "duration": "PT2H",
      "locations": {
        "auditorium": {
          "name": "Big Auditorium",
          "description": "Big Auditorium, Other Road"
        }
      }
    }
  }
}
```

--------------------------------

### Convert RFC9553 media to various formats

Source: https://github.com/stalwartlabs/calcard/blob/main/resources/jscontact/014_rfc9553.txt

Converts different media types (photo, logo, sound) to their respective RFC9553 formats. Ensures correct kind and URI are used.

```json
"media": {
  "res45": {
    "kind": "sound",
    "uri": "CID:JOHNQ.part8.19960229T080000.xyzMail@example.com"
  },
  "res47": {
    "kind": "logo",
    "uri": "https://www.example.com/pub/logos/abccorp.jpg"
  },
  "res1": {
    "kind": "photo",
    "uri": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAASABIAAD/4..."
  }
}
```

```text
PHOTO;PROP-ID=res1:data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAASABIAAD/4...
LOGO;PROP-ID=res47:https://www.example.com/pub/logos/abccorp.jpg
SOUND;PROP-ID=res45:CID:JOHNQ.part8.19960229T080000.xyzMail@example.com
```

--------------------------------

### Convert Event with End Time Zone JSON to VEVENT

Source: https://github.com/stalwartlabs/calcard/blob/main/resources/jscalendar/010_complete.txt

Converts a JSCalendar Event JSON object with distinct start and end time zones to an iCalendar VEVENT. Handles location information and duration.

```json
{
  "@type": "Event",  
  "title": "Flight XY51 to Tokyo",
  "start": "2020-04-01T09:00:00",
  "timeZone": "Europe/Berlin",
  "endTimeZone": "Asia/Tokyo",
  "duration": "PT10H30M",
  "mainLocationId": "1",
  "locations": {
    "1": {
      "name": "Frankfurt Airport (FRA)"
    },
    "2": {
      "name": "Narita International Airport (NRT)"
    }
  }
}
```

```icalendar
BEGIN:VCALENDAR
BEGIN:VEVENT
LOCATION;JSID=1;DERIVED=TRUE:Frankfurt Airport (FRA)
SUMMARY:Flight XY51 to Tokyo
DTEND;TZID=Asia/Tokyo:20200402T023000
DTSTART;TZID=Europe/Berlin:20200401T090000
BEGIN:VLOCATION
NAME:Narita International Airport (NRT)
JSID:2
END:VLOCATION
END:VEVENT
END:VCALENDAR
```

```json
{
  "@type": "Event",  
  "title": "Flight XY51 to Tokyo",
  "start": "2020-04-01T09:00:00",
  "timeZone": "Europe/Berlin",
  "endTimeZone": "Asia/Tokyo",
  "duration": "PT10H30M",
  "mainLocationId": "1",
  "locations": {
    "1": {
      "@type": "Location",
      "name": "Frankfurt Airport (FRA)"
    },
    "2": {
      "@type": "Location",
      "name": "Narita International Airport (NRT)",
      "iCalendar": {
            "name": "vlocation"
        }
    }
  },
  "iCalendar": {
        "convertedProperties": {
          "duration": {
            "name": "dtend"
          }
        },
        "name": "vevent"
  }
}
```

--------------------------------

### Convert RFC9553 name and localizations (Cyrillic)

Source: https://github.com/stalwartlabs/calcard/blob/main/resources/jscontact/014_rfc9553.txt

Converts a name with Cyrillic localizations to RFC9553 N and LANGUAGE formats. Demonstrates handling of titles and different scripts.

```json
"name": {
    "components": [
      { "kind": "title", "value": "Mr." },
      { "kind": "given", "value": "Ivan" },
      { "kind": "given2", "value": "Petrovich" },
      { "kind": "surname", "value": "Vasiliev" }
    ]
},
"localizations": {
    "uk-Cyrl": {
      "name": {
        "components": [
          { "kind": "title", "value": "г-н" },
          { "kind": "given", "value": "Иван" },
          { "kind": "given2", "value": "Петрович" },
          { "kind": "surname", "value": "Васильев" }
        ]
      }
    }
}
```

```text
N;JSCOMPS=";3;1;2;0":Vasiliev;Ivan;Petrovich;Mr.;;;;
N;JSCOMPS=";3;1;2;0";LANGUAGE=uk-Cyrl:Васильев;Иван;Петров
 ич;г-н;;;;
```

--------------------------------

### Convert TITLE with ALTID to JSON

Source: https://github.com/stalwartlabs/calcard/blob/main/resources/jscontact/015_rfc6350.txt

Demonstrates the conversion of TITLE properties with ALTID and language parameters into a JSON structure, including localizations.

```text
TITLE;ALTID=1;LANGUAGE=fr:Patron
TITLE;ALTID=1;LANGUAGE=en:Boss
```

```json
{
  "language": "fr",
  "localizations": {
    "en": {
      "titles/k1/name": "Boss"
    }
  },
  "titles": {
    "k1": {
      "kind": "title",
      "name": "Patron"
    }
  },
  "vCard": {
    "convertedProperties": {
      "localizations/en/titles~1k1~1name": {
        "parameters": {
          "altid": "1"
        }
      },
      "titles/k1/name": {
        "parameters": {
          "altid": "1",
          "language": "fr"
        }
      }
    }
  }
}
```

--------------------------------

### Convert Floating-Time Event with Recurrence JSON to VEVENT

Source: https://github.com/stalwartlabs/calcard/blob/main/resources/jscalendar/010_complete.txt

Converts a JSCalendar Event JSON object with a floating start time (no time zone specified) and recurrence rule to an iCalendar VEVENT. Handles daily recurrence.

```json
{
  "@type": "Event",
  "title": "Yoga",
  "start": "2020-01-01T07:00:00",
  "duration": "PT30M",
  "timeZone": null,
  "recurrenceRule": {
    "frequency": "daily"
  }
}
```

```icalendar
BEGIN:VCALENDAR
BEGIN:VEVENT
SUMMARY:Yoga
DTSTART:20200101T070000
DURATION:PT30M

```

--------------------------------

### Convert HOBBY to JSON

Source: https://github.com/stalwartlabs/calcard/blob/main/resources/jscontact/016_rfc6715.txt

Converts RFC6715 HOBBY entries to a JSON object. Each entry is mapped to a 'kind', 'level', 'listAs', and 'value' in the JSON.

```json
"personalInfo": {
    "k1": {
      "kind": "hobby",
      "level": "high",
      "listAs": 1,
      "value": "reading"
    },
    "k2": {
      "kind": "hobby",
      "level": "high",
      "listAs": 2,
      "value": "sewing"
    }
}
```

--------------------------------

### Convert Multiple TITLE with PROP-ID and ALTID to RFC6350

Source: https://github.com/stalwartlabs/calcard/blob/main/resources/jscontact/015_rfc6350.txt

Shows the conversion of multiple TITLE properties with PROP-ID, ALTID, and language parameters, specifying the primary language.

```text
TITLE;PROP-ID=k1;ALTID=1;LANGUAGE=en:Boss
TITLE;PROP-ID=k2;ALTID=2;LANGUAGE=en:Chief vCard Evangelist
TITLE;PROP-ID=k1;ALTID=1;LANGUAGE=fr:Patron
LANGUAGE:en
```

--------------------------------

### Convert SOURCE Property to String

Source: https://github.com/stalwartlabs/calcard/blob/main/resources/jscontact/001_general.txt

Converts an RFC9555 SOURCE property to a string format with a PROP-ID.

```text
SOURCE;PROP-ID=k1:https://dir.example.com/addrbook/jdoe/Jean%20Dupont.vcf
```

--------------------------------

### Convert Multiple RFC9555 N Properties to JSON

Source: https://github.com/stalwartlabs/calcard/blob/main/resources/jscontact/003_names.txt

Demonstrates handling multiple N (Name) properties, converting the first into a JSON name object and the second into the vCard properties list.

```text
N:Doe;Jane;;;;;
N:Perez;Juana;;;;;
> convert
"name": {
    "components": [
      {
        "kind": "surname",
        "value": "Doe"
      },
      {
        "kind": "given",
        "value": "Jane"
      }
    ]
  },
  "vCard": {
    "properties": [
      [
        "n",
        {},
        "unknown",
        [
          "Perez",
          "Juana",
          "",
          "",
          "",
          "",
          ""
        ]
      ]
    ]
  }
> convert
N:Perez;Juana;;;;;
N;JSCOMPS=";0;1":Doe;Jane;;;;;
```

--------------------------------

### Convert Email with Unknown Parameter

Source: https://github.com/stalwartlabs/calcard/blob/main/resources/jscontact/012_unknown.txt

Shows the conversion of an email address with an unknown parameter (X-FOO) into a structured JSON representation, including the original parameter.

```json
"emails": {
  "k1": {
    "address": "jane_doe@example.com"
  }
},
"vCard": {
    "convertedProperties": {
      "emails/k1/address": {
        "parameters": {
          "x-foo": "Bar"
        }
      }
    }
}
EMAIL;PROP-ID=k1;X-FOO=Bar:jane_doe@example.com
```

--------------------------------

### Convert EXPERTISE to JSON

Source: https://github.com/stalwartlabs/calcard/blob/main/resources/jscontact/016_rfc6715.txt

Converts RFC6715 EXPERTISE entries to a JSON object. Each entry is mapped to a 'kind', 'level', 'listAs', and 'value' in the JSON.

```json
"personalInfo": {
    "k1": {
      "kind": "expertise",
      "level": "low",
      "listAs": 2,
      "value": "chinese literature"
    },
    "k2": {
      "kind": "expertise",
      "level": "high",
      "listAs": 1,
      "value": "chemistry"
    }
}
```

--------------------------------

### Convert ROLE with PROP-ID to RFC6350

Source: https://github.com/stalwartlabs/calcard/blob/main/resources/jscontact/015_rfc6350.txt

Shows the conversion of a ROLE property that includes a PROP-ID and language parameter.

```text
ROLE;PROP-ID=k1;LANGUAGE=tr:hoca
```

--------------------------------

### Convert N with multiple given names and credentials to JSON

Source: https://github.com/stalwartlabs/calcard/blob/main/resources/jscontact/017_rfc9554.txt

Converts a N property with multiple given names and credentials to a JSON object. This demonstrates handling multiple values for the same component kind.

```text
N:Stevenson;John;Philip,Paul;Dr.;Jr.,M.D.,A.C.P.;;Jr.
```

```json
"name": {
    "components": [
      {
        "kind": "surname",
        "value": "Stevenson"
      },
      {
        "kind": "given",
        "value": "John"
      },
      {
        "kind": "given2",
        "value": "Philip"
      },
      {
        "kind": "given2",
        "value": "Paul"
      },
      {
        "kind": "title",
        "value": "Dr."
      },
      {
        "kind": "credential",
        "value": "M.D."
      },
      {
        "kind": "credential",
        "value": "A.C.P."
      },
      {
        "kind": "generation",
        "value": "Jr."
      }
    ]
}
```

--------------------------------

### Convert RFC6350 SOURCE to JSON (Variant)

Source: https://github.com/stalwartlabs/calcard/blob/main/resources/jscontact/015_rfc6350.txt

Converts RFC6350 SOURCE property with a PROP-ID parameter to JSON. Demonstrates handling of property identifiers.

```vcard
SOURCE;PROP-ID=k1:http://directory.example.com/addressbooks/jdoe/Jean%20Dupo
 nt.vcf
```

```json
"directories": {
    "k1": {
      "kind": "entry",
      "uri": "http://directory.example.com/addressbooks/jdoe/Jean%20Dupont.vcf"
    }
  },
  "vCard": {
    "convertedProperties": {
      "directories/k1/uri": {
        "parameters": {
          "prop-id": "k1"
        }
      }
    }
}
```

--------------------------------

### Convert JSON to HOBBY

Source: https://github.com/stalwartlabs/calcard/blob/main/resources/jscontact/016_rfc6715.txt

Converts JSON objects representing HOBBY to RFC6715 format. The 'kind', 'level', 'listAs', and 'value' are translated into RFC6715 tags.

```rfc6715
HOBBY;LEVEL=HIGH;INDEX=1;PROP-ID=k1:reading
HOBBY;LEVEL=HIGH;INDEX=2;PROP-ID=k2:sewing
```

--------------------------------

### iCalendar with Non-IANA TZID Parameter

Source: https://github.com/stalwartlabs/calcard/blob/main/resources/jscalendar/007_date.txt

Shows an iCalendar DTSTART property using a non-IANA timezone identifier as a TZID parameter. This demonstrates handling of custom or Windows-specific timezone names.

```icalendar
DTSTART;TZID="W. Europe Standard Time":20241121T105302
```

--------------------------------

### Convert PHOTO Property to String

Source: https://github.com/stalwartlabs/calcard/blob/main/resources/jscontact/001_general.txt

Converts an RFC9555 PHOTO property to a string format with a PROP-ID.

```text
PHOTO;PROP-ID=k1:https://www.example.com/pub/photos/jqpublic.gif
```
Tokens:
Raw