Skip to content

Latest commit

 

History

History
241 lines (209 loc) · 7.83 KB

README.org

File metadata and controls

241 lines (209 loc) · 7.83 KB
Raw

./doc/guile-ics.png

Guile-ICS

https://github.com/artyom-poptsov/guile-ics/workflows/GNU%20Guile%202.2/badge.svg https://github.com/artyom-poptsov/guile-ics/workflows/GNU%20Guile%203.0/badge.svg

Guile-ICS is an iCalendar (RFC 5545) and vCard (RFC 6350) parser for GNU Guile.

License

Guile-ICS is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. Please see COPYING file for the terms of GNU General Public License.

The logo (guile-ics.svg and rasterised versions) is distributed under terms of Creative Commons Attribution-ShareAlike 4.0 International license.

Requirements

  • GNU Guile, version 2.0.12 or later
  • Guile-SMC, version 0.6.0 or later
  • Guile-DSV, version 0.5.1 or later – only required for the DSV converters; the rest of Guile-ICS will work without this library.

Build-time dependencies

  • GNU Guile development files (something with dev suffix, e.g. guile-3.0-dev on Ubuntu GNU/Linux)
  • texinfo
  • make
  • automake
  • autoconf
  • help2man

Installation

GNU Guix

$ guix install guile-ics

To install the latest (unstable) version directly from the repository, run:

$ guix build -f ./guix.scm
$ guix package -f ./guix.scm

Manual

$ git clone https://github.com/artyom-poptsov/guile-ics.git
$ cd guile-ics
$ autoreconf -vif
$ ./configure
$ make -j$(nproc)
$ sudo make install

Usage

Reading and printing iCalendar data

Let’s suppose you have a file named example.ics with the following content:

BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//hacksw/handcal//NONSGML v1.0//EN
BEGIN:VEVENT
UID:19970610T172345Z-AF23B2@example.com
DTSTAMP:19970610T172345Z
DTSTART:19970714T170000Z
DTEND:19970715T040000Z
SUMMARY:Bastille Day Party
END:VEVENT
END:VCALENDAR

The following example shows how to parse the file:

(use-modules (ics))

(let* ((port       (open-input-file "example.ics"))
       (ics-object (car (ics->scm port))))
  (ics-pretty-print ics-object #:show-types? #t))

The code produces the following output:

BEGIN: VCALENDAR
  PRODID (TEXT): -//hacksw/handcal//NONSGML v1.0//EN
  VERSION (TEXT): 2.0
  BEGIN: VEVENT
    SUMMARY (TEXT): Bastille Day Party
    DTEND (DATE-TIME): 19970715T040000Z
    DTSTART (DATE-TIME): 19970714T170000Z
    DTSTAMP (DATE-TIME): 19970610T172345Z
    UID (TEXT): 19970610T172345Z-AF23B2@example.com
  END: VEVENT
END: VCALENDAR

Describing iCalendar/vCard data

Now let’s take a look on the ics-object structure more closely:

(use-modules (ics))

(let* ((port       (open-input-file "example.ics"))
       (ics-object (car (ics->scm port))))
  (ics-describe ics-object))

After we run the code we will see the following:

;;;  VCALENDAR                                             
;;;      PRODID (TEXT: Text type: RFC5545, 3.3.11)
;;;         -//hacksw/handcal//NONSGML v1.0//EN
;;;      VERSION (TEXT: Text type: RFC5545, 3.3.11)
;;;         2.0
;;;      VEVENT                                                
;;;          UID (TEXT: Text type: RFC5545, 3.3.11)
;;;             19970610T172345Z-AF23B2@example.com
;;;          DTSTAMP (DATE-TIME: Date-Time type: RFC5545, 3.3.5)
;;;             19970610T172345Z
;;;          DTSTART (DATE-TIME: Date-Time type: RFC5545, 3.3.5)
;;;             19970714T170000Z
;;;          DTEND (DATE-TIME: Date-Time type: RFC5545, 3.3.5)
;;;             19970715T040000Z
;;;          SUMMARY (TEXT: Text type: RFC5545, 3.3.11)
;;;             Bastille Day Party

As can be seen from the example, the <ics-object> with name VCALENDAR has two properties of type TEXT (PRODID, and VERSION) and has one an only VEVENT component. The ics-describe method may be handy in REPL mode to get information about iCalendar objects. Now let’s get the value of SUMMARY property that belongs to the VEVENT component:

(use-modules (ics)
             (ics type object)
             (ics type property))

(let* ((port       (open-input-file "example.ics"))
       (ics-object (car (ics->scm port)))
       (vevent     (car (ics-object-components ics-object))))
  (display
   (ics-property-value (ics-object-property-ref vevent "SUMMARY")))
  (newline))

When run, the example prints the following:

Bastille Day Party

For more usage examples, see examples directory.

ics tool

Usage ics [command] [options]

The default behaviour of the program is to read iCalendar/vCard stream from
stdin and handle it according to the specified options.

Commands:
  print          Print the input iCalendar data in various formats.
                 This is the default action if no command is provided.
  describe       Describe the input iCalendar data in the human-readable
                 form.
  convert        Convert data to the vCard/iCalendar format.
  help           Print this help message.

Options:
  --help, -h                 Print this message and exit.
  --version                  Print Guile-ICS version.

For each command there's '--help' option (or '-h' for short) that prints a help
message for the given command.

print

This command allows to print iCalendar/vCard data in various formats:

$ ics print tests/example.ics 
BEGIN: VCALENDAR
    PRODID (TEXT): -//hacksw/handcal//NONSGML v1.0//EN
    VERSION (TEXT): 2.0
    BEGIN: VEVENT
        UID (TEXT): 19970610T172345Z-AF23B2@example.com
        DTSTAMP (DATE-TIME): 19970610T172345
        DTSTART (DATE-TIME): 19970714T170000
        DTEND (DATE-TIME): 19970715T040000
        SUMMARY (TEXT): Bastille Day Party
    END: VEVENT
END: VCALENDAR

describe

$ ics describe tests/example.ics
;;;  VCALENDAR                                             
;;;      PRODID (TEXT: Text type: RFC5545, 3.3.11)
;;;         -//hacksw/handcal//NONSGML v1.0//EN
;;;      VERSION (TEXT: Text type: RFC5545, 3.3.11)
;;;         2.0
;;;      VEVENT                                                
;;;          UID (TEXT: Text type: RFC5545, 3.3.11)
;;;             19970610T172345Z-AF23B2@example.com
;;;          DTSTAMP (DATE-TIME: Date-Time type: RFC5545, 3.3.5)
;;;             19970610T172345Z
;;;          DTSTART (DATE-TIME: Date-Time type: RFC5545, 3.3.5)
;;;             19970714T170000Z
;;;          DTEND (DATE-TIME: Date-Time type: RFC5545, 3.3.5)
;;;             19970715T040000Z
;;;          SUMMARY (TEXT: Text type: RFC5545, 3.3.11)
;;;             Bastille Day Party

convert

This command allows to convert input data into iCalendar/vCard format.

Let’s say we have the following data:

ORG,TITLE,FN,EMAIL
Example Organisation,Programmer,Eva Luator,eva@example.org
Example Organisation,Programmer,Random J. Hacker,rjh@example.org

Then we can convert it to vCard as follows:

$ ics convert test.csv
BEGIN:VCARD
EMAIL:eva@example.org
FN:Eva Luator
TITLE:Programmer
ORG:Example Organisation
END:VCARD

BEGIN:VCARD
EMAIL:rjh@example.org
FN:Random J. Hacker
TITLE:Programmer
ORG:Example Organisation
END:VCARD