Another approach to building a date conversion tool

Following up on an idea mentioned here, this post describes how to build, deploy, and run a date conversion tool built with Emacs, Lisp, and Docker.

Build from Emacs

As you may recall, I discussed the idea of developing a date conversion tool with Emacs, Lisp, and deploying the resulting software with Docker. However, I dismissed it because I wanted my tool to (1) have no third party dependencies – in that scenario, Emacs – (2) support cross-compilation out of the box, and (3) be deployed as a self-contained binary executable, i.e. to not depend on a runtime such as the Java VM or a docker engine on the target system.

Nevertheless, once voiced, I couldn’t quite leave this intruiging idea (it involves Emacs and Lisp after all) unimplemented – in fact, who could?

Emacs provides the calendar functions¹ that we need for our tool. Usually, these functions are called only indirectly from Emacs’ builtin calendar.² Since we want to perform date conversions directly from the command line (and not from inside Emacs), we write a Lisp script that:

• loads the Emacs Lisp libraries providing the calendar and date parsing functions,
• takes the (Gregorian) date specified by the user, or the current date otherwise,
• parses and validates the date,
• returns an error if the date is invalid, and
• converts the date and prints the results to the terminal.

The script displayed below (and named calcal.el) does exactly that:

;; -*- mode: Lisp; lexical-binding: t; indent-tabs-mode: nil; -*-
(require 'calendar)
(require 'parse-time)

;; Extract month, day and year from a date parse result list (as produced by
;; parse-time-string). Returns nil if any date element is nil.
(defun extract-mdy (parse-list)
  "Extract date components from parse results of parse-time-string"
  (list ;; order of date components is month-day-year
   (nth 4 parse-list)
   (nth 3 parse-list)
   (nth 5 parse-list)))

;; Parse a ISO 8601-formatted string. Return a list with month, day and year
;; components on success, and nil otherwise
(defun parse-date (date-string)
  "Parse an ISO 8601-formatted date string. 
On success, returns a list of the form (year month day), or nil otherwise"
  (let ((parsed-date (extract-mdy (parse-time-string date-string))))
    (if (and
         (not (member nil parsed-date)) ;; no date element should be nil
         (> (nth 0 parsed-date)) ;; month should be a positive integer
         (> (nth 1 parsed-date))) ;; day should be a positive integer
        parsed-date
        nil)))

;; Print date conversion results to screen
(defun print-dates (string-list)
  "Print dates computed by calendar.el's calendar-other-dates"
  (message "\n%s\n" 
           "The dates below were computed with Emacs' calendar functions.")
  (mapc 'message string-list))

;; main conversion function
(defun main (args)
  ;; If no argument is provided, main converts the current date
  ;; If arguments were passed, main parses the first argument and uses the
  ;; resulting date for date conversion. If the first argument cannot be
  ;; parsed to a date, main returns an error message.
  (if (> (length args) 0)
      (let ((parsed-date (parse-date (elt args 0))))
        (if parsed-date ;; if parsed-date is not nil
            (print-dates (calendar-other-dates parsed-date))
            (message "Invalid date. Specify date as yyyy-mm-dd.")))
      (print-dates (calendar-other-dates (calendar-current-date)))))

;; run main function
(main argv)

To display the calendar dates corresponding to the 29th of August 2022 (Gregorian),³ we would simply run emacs --script path/to/calcal.el 2022-08-29, producing the following output:

The dates below were computed with Emacs' calendar functions.

Day 241 of 2022; 124 days remaining in the year
ISO date: Day 1 of week 35 of 2022
Julian date: August 16, 2022
Astronomical (Julian) day number (at noon UTC): 2459821.0
Fixed (RD) date: 738396
Hebrew date (before sunset): Elul 2, 5782
Persian date: Sahrivar 7, 1401
Islamic date (before sunset): Safar 1, 1444
Bahá’í date: Asmá’ 10, 179
Chinese date: Cycle 78, year 39 (Ren-Yin), month 8 (Ji-You), day 3 (Jia-Yin)
Coptic date: Misra 23, 1738
Ethiopic date: Nahas 23, 2014
French Revolutionary date: Duodi 12 Fructidor an 230 de la Révolution, jour du Fenouil
Mayan date: Long count = 13.0.9.14.18; tzolkin = 6 Etznab; haab = 11 Mol

Deployment

Assuming an unix-like operating system on the target computer with Emacs installed, one way of deploying the date converter consists of obtaining the Lisp script and either:

1. call the script directly with emacs --script path/to/calcal.el, or,
2. install the script, and later on call it like a regular command line utility. This requires abstracting away calcal.el’s location and the direct call to Emacs. To do so,
   • add #!/usr/bin/env emacs --script to the top of the Lisp script
   • make calcal.el executable, e.g. with chmod +x
   • place calcal.el on your $PATH (or modify $PATH accordingly)

Although neither option is overly complicated to implement, in both cases the user has to deal with matters well beyond calling a command line tool: make sure Emacs is installed, memorize file paths; edit files, modify the $PATH environment variable, change file permissions.⁴ Clearly, it would be much easier to deploy an utility whose components are packaged in a single unit – or, using the appropriate term, container – and which runs independently of the underlying operating system.

As chance would have it, this is essentially how Docker works.⁵ Containers package software components like application code, libraries, and dependencies⁶ into one unit of software, which can then be executed on any platform supported by the respective container engine.

Below listing defines the container of our date conversion tool. As discussed earlier, it consists of Emacs (emacs-nox) and the Lisp script calcal.el.

# This is calcal-emacs' Dockerfile
FROM alpine:latest
RUN apk add emacs-nox
COPY calcal.el /calcal.el
ENTRYPOINT ["emacs", "--script", "calcal.el"]

One might wonder why we include an Alpine Linux distribution in the container as well. To answer this question, let us look a bit more closely at how OS-level virtualization/containerization techniques like Docker work.

Containers share the resources provided by the operating system (more precisely, the kernel). For resource allocation and isolation, Docker uses two features of the Linux kernel, cgroups and kernel namespaces (this is why, on Windows and MacOS, Docker runs a virtual machine with Linux, which in turn powers the containers).

In the case of the approaches discussed above, we implicitly rely on the operating system’s user space to provide the means to run the script, e.g. a shell. In the Docker case, the engine only provides kernel resources such as CPU and memory to our container, which is not sufficient to run calcal.el (no shell, no libraries on which the shell and Emacs depend, etc.).⁷ Therefore, we add an Alpine Linux user space, supplying the required dependencies.⁸

After building our calcal-emacs container,⁹ we may run it with sudo docker run calcal-emacs 2022-08-29,¹⁰ printing to stdout the same output we obtained from invoking calcal.el with Emacs:

The dates below were computed with Emacs' calendar functions.

Day 241 of 2022; 124 days remaining in the year
ISO date: Day 1 of week 35 of 2022
Julian date: August 16, 2022
Astronomical (Julian) day number (at noon UTC): 2459821.0
Fixed (RD) date: 738396
Hebrew date (before sunset): Elul 2, 5782
Persian date: Sahrivar 7, 1401
Islamic date (before sunset): Safar 1, 1444
Bahá’í date: Asmá’ 10, 179
Chinese date: Cycle 78, year 39 (Ren-Yin), month 8 (Ji-You), day 3 (Jia-Yin)
Coptic date: Misra 23, 1738
Ethiopic date: Nahas 23, 2014
French Revolutionary date: Duodi 12 Fructidor an 230 de la Révolution, jour du Fenouil
Mayan date: Long count = 13.0.9.14.18; tzolkin = 6 Etznab; haab = 11 Mol

We may feel quite content, having successfully built and run a containerized date conversion tool. Yet we shouldn’t forget about actually deploying the container to target machines. There are two distribution options:

1. Use a container registry such as DockerHub, Quay, or Google Container Registry, or run your own registry server (for more details, see the docker documentation)
2. Save your container to a tar archive, and distribute the archive

To keep matters simple (which – I believe – the first option does not), we shall distribute calcal-emacs as a tarball. Docker provides the save command to write a container to an archive, and load to restore a container from such an archive.¹¹ To create a (gzip-compressed) container tarball, call sudo docker save calcal-emacs:latest | gzip > calcal-emacs.tar.gz. For distribution, simply copy the archive to the target machine, and restore the container with sudo load < calcal-emacs.tar.gz.

Concluding remarks

In what I intended to be a short follow-up post, I described how to build, deploy and run a containerized date converter built from Emacs and custom Lisp functions.

Note: For this post’s accompanying code, see https://git.staudtlex.de/blog/date-conversion-with-emacs.