-
Notifications
You must be signed in to change notification settings - Fork 9
/
Copy pathREADME.Rmd
125 lines (94 loc) · 4.23 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
---
output: github_document
---
<!-- badges: start -->
[](https://github.com/ATFutures/calendar/actions)
[](https://www.r-pkg.org:443/pkg/calendar)
[](https://lifecycle.r-lib.org/articles/stages.html)
[](https://app.codecov.io/github/ATFutures/calendar?branch=master)
<!-- README.md is generated from README.Rmd. Please edit that file -->
[](https://CRAN.R-project.org/package=calendar)
<!-- badges: end -->
```{r setup, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
```
# calendar
The goal of calendar is to make it easy to create, read, write, and work with iCalander (`.ics`, `.ical` or similar) files, and the scheduling data they represent, in R.
iCalendar is an open standard for
"exchanging calendar and scheduling information between users and computers"
described at [icalendar.org](https://icalendar.org/) (the full spec can be found in a
plain text file [here](https://www.rfc-editor.org/rfc/rfc5545.txt)).
Recently the UK Government endorsed the iCal format in a [publication](https://www.gov.uk/government/publications/open-standards-for-government/exchange-of-calendar-events) for the 'Open Standards for Government' series.
[An example .ics file](https://www.gov.uk/bank-holidays/england-and-wales.ics) is provided by the .gov.uk domain, which shows holidays in England and Wales.
## Installation
```{r install-cran, eval=FALSE}
install.packages("calendar")
```
Or install the cutting edge from GitHub
```{r, message=FALSE, results='hide'}
devtools::install_github("ATFutures/calendar")
```
```{r}
library(calendar)
```
<!-- You can install the released version of calendar from [CRAN](https://CRAN.R-project.org) with: -->
<!-- ``` r -->
<!-- install.packages("calendar") -->
<!-- ``` -->
## Example
A minimal example representing the contents of an iCalendar file is provided in the dataset `ical_example`, which is loaded when the package is attached.
This is what iCal files look like:
```{r min-example}
ical_example
```
Relevant fields can be found and extracted as follows:
```{r}
which(ic_find(ical_example, "TSTAMP"))
ic_extract(ical_example, "TSTAMP")
```
A larger example shows all national holidays in England and Wales.
It can be read-in as follows:
```{r example}
ics_file <- system.file("extdata", "england-and-wales.ics", package = "calendar")
ics_raw = readLines(ics_file)
head(ics_raw) # check it's in the ICS format
```
A list representation of the calendar can be created using `ic_list()` as follows:
```{r}
ics_list = ic_list(ics_raw)
ics_list[1:2]
```
A data frame representing the calendar can be created as follows (work in progress):
```{r}
ics_df = ic_read(ics_file) # read it in
head(ics_df) # check the results
```
What class is each column?
```{r cars}
vapply(ics_df, class, character(1))
```
## Trying on calendars 'in the wild'
To make the package robust we test on a wide range of ical formats.
Here's an example from my work calendar, for example:
```{r}
my_cal = ic_dataframe(ical_outlook)
my_cal$SUMMARY[1]
# calculate the duration of the European R users meeting event:
my_cal$`DTEND;VALUE=DATE`[1] - my_cal$`DTSTART;VALUE=DATE`[1]
```
<!-- An example from the wild: -->
```{r, echo=FALSE, eval=FALSE}
my_cal = ic_read("https://outlook.office365.com/owa/calendar/[email protected]/32e1cb4137f4414b8d7644453ec4b10414316826143036893453/calendar.ics")
attributes(my_cal)$ical
# head(my_cal[c("DESCRIPTION", "SUMMARY", "DTSTART", "DTEND", "STATUS", "SEQUENCE", "LOCATION")])
```
## Related projects
- A Python package for working with ics files: https://github.com/ics-py/ics-py
- A JavaScript package by Mozilla: https://github.com/kewisch/ical.js
- Ruby library: https://github.com/icalendar/icalendar
- The ical R package on CRAN for reading .ics files: https://github.com/petermeissner/ical