diff --git a/docs/examples.md b/docs/examples.md index 6f4d2e5..c1d4479 100644 --- a/docs/examples.md +++ b/docs/examples.md @@ -234,3 +234,43 @@ cat calendar1.ics calendar2.ics | ics-query at 2024-08 - - ```shell wget -qO- 'https://example.com/calendar.ics' | ics-query at 2024-08 - - ``` + +## Working with jCal + +`ics-query` reads and writes iCalendar data in the RFC 5545 `.ics` format. +If your workflow uses jCal JSON, convert between `.ics` and jCal with +[`ical2jcal`](https://pypi.org/project/ical2jcal/). jCal is the JSON +representation of iCalendar defined by +[RFC 7265](https://www.rfc-editor.org/rfc/rfc7265). + +Install the converter: + +```shell +python -m pip install ical2jcal +``` + +Convert an `.ics` file to jCal: + +```shell +ical2jcal calendar.ics calendar.jcal +``` + +Convert jCal back to `.ics` before querying it: + +```shell +jcal2ical calendar.jcal calendar.ics +ics-query at 2024-08 calendar.ics - +``` + +You can also pipe the conversion into `ics-query`: + +```shell +jcal2ical calendar.jcal - | ics-query between 2024-08-01 +7d - - +``` + +After querying, convert valid calendar output back to jCal: + +```shell +ics-query at --as-calendar 2024-08 calendar.ics result.ics +ical2jcal result.ics result.jcal +``` diff --git a/docs/overview.md b/docs/overview.md index ea4565e..5f0ca0d 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -39,6 +39,7 @@ Start is inclusive. End is exclusive. - [icalendar-events-cli](https://github.com/waldbaer/icalendar-events-cli#readme) — another command line implementation of `recurring-ical-events` - [icalBuddy](https://hasseg.org/icalBuddy/) +- [ical2jcal](https://pypi.org/project/ical2jcal/) — convert between iCalendar `.ics` files and RFC 7265 jCal JSON - [Blog Post](https://opencollective.com/open-web-calendar/updates/calendar-calculation-on-the-command-line-ics-query) - [#icsquery on mastodon](https://toot.wales/tags/icsquery) - [Homebrew tap for ics-query](https://github.com/niccokunzmann/homebrew-tap) diff --git a/docs/reference.md b/docs/reference.md index aa82317..0cef923 100644 --- a/docs/reference.md +++ b/docs/reference.md @@ -18,6 +18,20 @@ These options apply to all commands. | `--available-timezones` | List all available timezone names and exit. | | `--license` | Show the license and exit. | +## jCal conversion + +`ics-query` accepts RFC 5545 iCalendar input. To use RFC 7265 jCal JSON, +convert the file with [`ical2jcal`](https://pypi.org/project/ical2jcal/) +before or after running `ics-query`. + +```shell +ical2jcal calendar.ics calendar.jcal +jcal2ical calendar.jcal calendar.ics +``` + +See the [ical2jcal documentation](https://pycalendar.github.io/ical2jcal/) +for the full command reference. + ## ics-query at ``` diff --git a/ics_query/cli.py b/ics_query/cli.py index 489059e..221f7a8 100644 --- a/ics_query/cli.py +++ b/ics_query/cli.py @@ -421,6 +421,17 @@ def cli(): (4) Do not mix `-c VEVENT` and others with `-c VALARM` or you might not know if the alarm or the component is inside the time span. + \b + jCal + ---- + + ics-query reads and writes RFC 5545 iCalendar data. To use RFC 7265 jCal JSON, + convert files with the ical2jcal package: + + \b + https://pypi.org/project/ical2jcal/ + https://pycalendar.github.io/ical2jcal/ + """ # noqa: D301