Re: [Evolution-hackers] How do I use S-Expressions on Evolution Data Server’s ECal API?

[Milan Crha <mcrha redhat com>]

On Wed, 2022-03-09 at 02:36 +0100, contact ultrasonicmadness org wrote:
> I think the 'occur-in-time-range' command might be relevant to what
> I’m trying to do, but I’m not sure what isodate_from_time_t is doing
> or how the return value from it is formatted. Is there documentation
> on this or a list of commands that I’m missing?

        Hi,
you are right, there is not much information about the way constructing
the S-Expressions in the Evolution(-data-server). The easiest is to
search the existing code and check what it does, just as you did. The
`occur-in-time-range` is what you want, as you figured. The list of
possible expressions is here:
https://gitlab.gnome.org/GNOME/evolution-data-server/-/blob/gnome-41/src/calendar/libedata-cal/e-cal-backend-sexp.c#L1311
when you search for the respective functions in that list, they contain
a comment about their syntax.
There are some common symbols defined here:
https://gitlab.gnome.org/GNOME/evolution-data-server/-/blob/gnome-41/src/libedataserver/e-sexp.c#L1476
with a little bit information about builtin common s-expressions:
https://gitlab.gnome.org/GNOME/evolution-data-server/-/blob/gnome-41/src/libedataserver/e-sexp.c#L21

With respect of the isodate_from_time_t(), the easiest is to just call
that function (you did not say what programming language you use,
though using introspection you should have this function available
too). It's defined here:
https://gitlab.gnome.org/GNOME/evolution-data-server/-/blob/gnome-41/src/calendar/libecal/e-cal-time-util.c#L631

Quick examples:

To get list of events occurring between 2022-02-27 and 2022-04-10 for
Europe/Prague timezone you use this S-Expression:

   (occur-in-time-range? (make-time "20220227T230000Z")
    (make-time "20220410T000000Z") "Europe/Prague")

To get events, which occur in the same time range as above and contain
word "orange" in the Summary you use:

   (and (occur-in-time-range? (make-time "20220227T230000Z")
    (make-time "20220410T000000Z") "Europe/Prague")
    (contains? "summary" "orange"))

To get events, which occur in the same time range as above and not
contain word "bad" in the Summary you use:

   (and (occur-in-time-range? (make-time "20220227T230000Z")
    (make-time "20220410T000000Z") "Europe/Prague")
    (not (contains? "summary" "bad")))

You can get more complicated expressions. If you want to debug it any
further, then I suggest to place a breakpoint into
cal_data_model_update_full_filter() and see what `filter` it constructs
there:
https://gitlab.gnome.org/GNOME/evolution/-/blob/gnome-41/src/calendar/gui/e-cal-data-model.c#L805
You can create quite complicated expressing with the Evolution GUI.

Hope it helps.

        Bye,
        Milan