As a version control system, git keeps a copy of any file deleted from the current working tree in its history, forever.

To search for files that were deleted but are still accessible in the history, you can run git log and filter on deletions:

git log --diff-filter=D --summary

Usually, that is exactly what one expects and not a problem at all. But at some point one might have committed a very large file, a bunch of temporary files or files containing sensitive information. So, how to get rid of these for good?

As an example, when I was still using Apple OSX, I sometimes included those .DS_Store meta information files that the OS scatters across the file system. No reason to keep them accumulating in the repository’s history:

git filter-repo --invert-paths --path '.DS_Store' --use-base-name

--use-base-name matches on file base names instead of full paths and --invert-paths keeps anything not matching. To match a pattern, you can use instead

git filter-repo --invert-paths --path-glob '*/*.jpg'

which removes all files with the jpg extension from any path.

If you entered sensitive information into text or source files that you don’t want to delete entirely, you can even replace those passwords or explicit language with something safe to push to the outside world! Look for any mention of those unwanted strings of text in any commit first:

git log -SMyPassword -c

This searches for any mention of “MyPassword” in any commit. Should the command return any results, you can use git-filter-repo to replace the sensitive string with something else. Create a file expresions.txt which contains the desired translations:

MyPassword ==> ***REMOVED***

Even regular expressions are allowed if you prefix the line with regex:. Then apply the replacements:

git filter-repo --replace-text expressions.txt

In case you have used a different commit author name or email address from the one you want to see publicly, you can permanently change it across all commits quite easily. First, you have to create a file containing the mapping of the old to the new name/email. This file follows the mailmap format. For adjustments to only the email address, use for example:

<proper@email.example.com> <commit@email.example.com>

If you called this file mailmap.txt, then simply execute

git filter-repo --mailmap mailmap.txt

to make the changes.

git-filter-repo is a powerful tool to clean up a git repository once you decide to make your private project public and share it with others. Your cleaned repository will end up with a rewritten history that is incompatible with previous incarnations – so keep that in mind should you already have a public copy out there!

Comments? Leave them as reply to the post on Mastodon.

Tags: git, programming

Since my web skills have been rusting for more than 10 years, I was pleasantly surprised about the amount of options and the level of support in all major browsers for external fonts. Even self-hosting is little more than dropping in a single file or two into your web host’s file structure and adding a bit of CSS! I found this blog entry on opensource.com very helpful.

Concerning the actual fonts, that is a bit more tricky. Not so much because they are difficult to find though: even with the requirement of having an open font license, there is a ton of choice. A good starting point for me was another blog post on opensource.com. The challenge was more to find the “right” font that I like and that suits the blog. Here, my very general interest in fonts is quickly overwhelmed by the amount of variables: one font might look interesting in the headlines but produces flow text that is tiring to read. Another produces odd-looking results when rendering special characters common in various European languages such as ’ü’ or ’å’.

A very useful in my trial-and-error phase was the “Inspector” tool of Firefox (opened by right-clicking somewhere on the page and selecting “Inspect Element”). Any change to any font property is updated in real-time and allows to compare results easily. Even fonts with variable weights can be smoothly adjusted with a little slider widget!

Some really promising candidates I found at the league of moveable type who provide open, high-quality fonts in various formats. Not just that, they have a ton of material on typography including articles and even a podcast!

So for now I changed to Fanwood by Barry Schwartz.

Tags: blog

The entry point to our chat bot will be a function that we register on the messageReceived signal. Each message by Jami for any account and any conversation will be passed on to this function as well as the account it was received via and the conversation that the message is part of.

To keep things modular, this function needs only to serve two purposes:

1. Filter out any unwanted messaging activity. Most importantly, this includes messages that were sent by the chat bot account(s) to avoid ending in an infinite loop reacting to our own messages. But the user might want to limit the chat bot to certain local accounts.
2. Distinguish the type of message (text, file transfer, internal) and pass it on to the appropriate function for further processing or ignore it.

Below is the definition for the function – we will walk through the various branches step-by-step.

 1: 
 2: (defun jami-bot--messageReceived-handler (account conversation msg)
 3:   "Handle messages from Jami's `messageReceived' D-Bus signal.
 4: 
 5:   ACCOUNT and CONVERSATION are the corresponding ids to which the
 6:   MSG belongs to. The latter contains additional fields such as
 7:   `author' and `body'. The field `type' is used to identify which
 8:   function to call for further processing."
 9:   ;; make sure we are not reacting to messages sent from our own local
10:   ;; account(s) or accounts we are not to monitor
11:   (unless jami-bot--jami-local-account-ids
12:     (jami-bot--refresh-accountid-list))
13:   (let ((author (cadr (assoc "author" msg)))
14:         (type (cadr (assoc "type" msg))))
15:     (when (or
16:            (and jami-bot-account-user-names
17:                  ;; account id should match a user name to be monitored
18:                  (member (car (rassoc account jami-bot--jami-local-account-ids))
19:                          jami-bot-account-user-names)
20:                  ;; .. but msg should not be authored by ourselves
21:                  (not (member author jami-bot-account-user-names)))
22:             ;; no account filter: check msg not from local account
23:            (and (not jami-bot-account-user-names)
24:                 (not (assoc author jami-bot--jami-local-account-ids))))
25:       (message "jami-bot received %s message from %s on account %s." type author account)
26:       (pcase type
27:         ("text/plain"
28:          (jami-bot--process-text-message
29:           account
30:           conversation
31:           msg))
32:         ("application/data-transfer+json"
33:          (jami-bot--process-data-transfer
34:           account
35:           conversation
36:           msg))
37:         ;; ignore merges of the conversation; usually transparent to the user
38:         ;; anyway
39:         ("merge" (ignore))
40:         ;; ignore new members joining
41:         ("member" (ignore))
42:         (_
43:          (jami-bot--process-unknown-type
44:           account
45:           conversation
46:           msg))))))
47: 
48: (defun jami-bot--process-unknown-type (account conversation msg)
49: "Handle messages of unknown type by sending an error message as reply.
50: 
51:   ACCOUNT and CONVERSATION are the corresponding ids to which the
52:   MSG belongs to."
53:   (let ((type (cadr (assoc "type" msg))))
54:     (message "Error: received message with unkonwn type: %s" type)
55:     (jami-bot-reply-to-message
56:      account
57:      conversation
58:      msg
59:      (format "Unknown message type: %s" type))))

The first part of jami-bot--messageReceived-handler handles the filtering. Any messages from local accounts are ignored to avoid feedback loops created when responding to our own replies. In case several local Jami accounts are present, one can limit jami-bot to only react to messages to specific accounts:

(defvar jami-bot-account-user-names nil
  "List of account user names that `jami-bot' handles messages for.

        If set to nil then `jami-bot' will react to any message
        send to a local account. The user name is also sometimes
        referred to as address in Jami and should be a 40
        character has such as
        \"badac18e13ec1a6e1266600e457859afebfb9c46\".")

This has to be the full user name (I think sometimes referred to as address in Jami), that is to say the full hash, for example:

(setq jami-bot-account-user-names '("badac18e13ec1a6e1266600e457859afebfb9c46"))

To make it easier to enter these, here is a little interactive helper function that allows to pick a user from the list of local accounts:

(defun jami-bot-select-and-insert-local-account ()
  "Prompt user for a local Jami user account and insert id at position."
  (interactive)
  (jami-bot--refresh-accountid-list)
  (insert (completing-read "Pick a account user name to insert: " jami-bot--jami-local-account-ids)))

From line 25 onward, the different message types are distinguished. While text and file transfer are handled in separate functions, the internal messages merge (when the conversation is synced after it diverged due to a loss of connectivity) and member (when someone is added to a conversation) are ignored. Anything else will be sent to jami-bot--process-unknown-type defined on line 47. In that case, a warning will be added to the conversation, mentioning the unknown type.

The actual registration of the handler on the bus for the messageReceived signal is done by a helper function:

 1: (defun jami-bot-register ()
 2:   "Ping the Jami daemon and register `jami-bot' handler for receiving messages."
 3:   (interactive)
 4:   (or (dbus-ping :session "cx.ring.Ring")
 5:       (error "Jami Daemon (jamid) not available through dbus. Please check Jami installation"))
 6:   (dbus-register-signal :session "cx.ring.Ring"
 7:                       "/cx/ring/Ring/ConfigurationManager"
 8:                       "cx.ring.Ring.ConfigurationManager"
 9:                       "messageReceived"
10:                       #'jami-bot--messageReceived-handler))

Pinging the Jami D-Bus service on line 4 verifies not only that Jami is installed correctly and registered on D-Bus but also has the side effect of starting the daemon if it is not already running. Therefore, this helper function is useful should you ever need to restart the Jami daemon: simply run killall jamid on the terminal and call M-x jami-bot-register in Emacs to start it up again.

Now that our chat bot can receive messages, let us start to react to them. We start with text messages.

To make the conversations with the bot a little more interesting, I want to be able to issue simple commands via text messages. Any message starting with an exclamation mark and a single word will be interpreted as a command and forwarded to a specific function. An example would be the !help command which will respond with the list of available commands.

To make this easily extensible, I define an alist that maps commands with the function that processes them:

(defvar jami-bot-command-function-alist
  '(("!ping" . jami-bot--command-function-ping)
    ("!help" . jami-bot--command-function-help))
  "Alist mapping command strings in message body to functions to be executed.

Each command needs to start with an exclamation mark '!' and
consist of a single (lowercase) word. The corresponding function needs to accept
the account id, the conversation id and the message alist as
arguments and return a string (that is sent as reply to the original message).")

Of course, some actions should also be taken if there is no command given at all. For those cases, I define an abnormal hook that the user can set arbitrary functions to process. Abnormal means that the functions will be called with arguments, as they will need the account, conversation and actual message to process.

(defvar jami-bot-text-message-functions nil
  "A list of functions that will be called when processing a plain text message.

Functions must take the ACCOUNT and CONVERSATION ids as well as
the actual MSG as arguments. Their return value will be ignored.")

Every text message is forwarded from jami-bot--messageReceived-handler on line 27 processed by jami-bot--process-text-message below.

 1: (defun jami-bot--process-text-message (account conversation msg)
 2:   "Process plain text messages and parse the message body for commands.
 3: 
 4:   ACCOUNT and CONVERSATION are the corresponding ids to which the
 5:   message MSG belongs to. Messages containing commands must start
 6:   with an exclamation mark (\"!\") followed by the single-word
 7:   command. Each command is mapped to a function via
 8:   `jami-bot-command-function-alist' which will be executed when
 9:   the command is received.
10: 
11:   If the message does not start with an exclamation mark, the
12:   abnormal hook `jami-bot-text-message-functions' will be run for
13:   further processing."
14:   (let ((body (cadr (assoc-string "body" msg))))
15:     ;; check for criteria handling first line of body as command
16:     ;;  - string starts with '!' and is a single word
17:     (if (string-prefix-p "!" body)
18:         ;; command in msg body
19:         (let*
20:             ((cmd (downcase (substring body 0 (string-match-p "[^[:word:]!]" body))))
21:              (fcn (cdr (assoc-string cmd jami-bot-command-function-alist))))
22:           ;; remove the command from the message body
23:           (setcdr (assoc-string "body" msg)
24:                   (list (string-trim-left (string-remove-prefix cmd body))))
25:           (if fcn
26:             ;; call function and reply with return value
27:             (jami-bot-reply-to-message
28:              account
29:              conversation
30:              msg
31:              (funcall fcn account conversation msg))
32:             ;; no matching command defined:
33:             ;; report error as reply to msg
34:             (jami-bot-reply-to-message
35:              account
36:              conversation
37:              msg
38:              (format "Unknown command: %s" cmd))))
39:       ;; not a command in msg body: run hook instead
40:       (run-hook-with-args 'jami-bot-text-message-functions
41:                           account conversation msg))))

If a command prefix was found in the message and a matching handler defined, then the function will be called on line 25 and the functions return value be sent as a reply. Otherwise, a reply will be sent with “unknown command”. In case there was no command in the message, we might still want to do something with it and provide a hook on line 40.

Now we can define a couple of functions that react to commands.

The simplest command processor is the ping command that replies to a message with pong! (and any part of the original message after the command keyword):

(defun jami-bot--command-function-ping (_account _conversation msg)
  "Return the string 'pong!' followed by the message's body.

Example for a basic jami bot command handling function. Acts on MSG
received via _ACCOUNT in _CONVERSATION. The latter two are unused."
  (let ((body (cadr (assoc-string "body" msg))))
    (format "pong! %s" body)))

A little more useful is the help command that lists all available commands and their docstring:

(defun jami-bot--command-function-help (_account _conversation _msg)
  "Return a summary of available commands.

Acts on _MSG received via _ACCOUNT in _CONVERSATION, none of
which are used."
  (let (result)
    (dolist (cmd jami-bot-command-function-alist (string-join result "\n"))
      (push (concat "- " (car cmd) " :: "
                    (car (split-string (documentation (cdr cmd)) "\n"))) result))))

If one sends a file via Jami, e.g. an image, the message contains the file name and a file id but no actual data. This has to be retrieved by downloading it before we can continue processing it. So for this simple handler, we define a variable path to store files in (jami-bot-download-path) and a function jami-bot--process-data-transfer to download the file and run a hook for additional handling.

(defvar jami-bot-download-path "~/jami/"
"Path in which to store files downloaded from conversations.

Will be created if not existing yet.")

 1: (defun jami-bot--process-data-transfer (account conversation msg)
 2:   "Process data transfer from received messages.
 3: 
 4:   Downloads files to the path given by `jami-bot-download-path'
 5:   and calls the abnormal hook `jami-bot-data-transfer-functions'
 6:   for further processing. ACCOUNT and CONVERSATION are the
 7:   corresponding ids to which the message MSG belongs to."
 8:   (let* ((id (cadr (assoc-string "id" msg)))
 9:          (fileid (cadr (assoc-string "fileId" msg)))
10:          (filename (cadr (assoc-string "displayName" msg)))
11:          (dlpath (file-name-as-directory
12:                   (expand-file-name jami-bot-download-path)))
13:          (dlname (concat dlpath (format-time-string "%Y%m%d-%H%M") "_" filename)))
14:     (unless (file-directory-p dlpath) (make-directory dlpath 't))
15:     (message "jami-bot: downloading file %s" dlname)
16:     (jami-bot--dbus-cfgmgr-call-method "downloadFile" account conversation id fileid dlname)
17:     (run-hook-with-args 'jami-bot-data-transfer-functions account conversation msg dlname)))

This so far takes care of transferring the file to local storage. If desired, the user can process the data further by adding a hook which is run on line 17:

(defvar jami-bot-data-transfer-functions nil
  "A list of functions that will be called when processing a data transfer message.

Functions must take the ACCOUNT and CONVERSATION ids as well as
the actual MSG and the local downloaded file name, DLNAME, as
arguments. Their return value will be ignored.")

The final puzzle pieces still missing are the support functions that help with the D-Bus interaction and with keeping track of local Jami accounts.

As all D-Bus calls necessary for the chat bot are part of Jami’s ConfigurationManager interface, and mostly concerned with sending messages, we can factorize the constant bits of these calls into three helper functions:

 1: (defun jami-bot--dbus-cfgmgr-call-method (method &rest args)
 2:   "Call Jami ConfigurationManager dbus METHOD with arguments ARGS."
 3:   (apply #'dbus-call-method `(:session
 4:                     "cx.ring.Ring"
 5:                     "/cx/ring/Ring/ConfigurationManager"
 6:                     "cx.ring.Ring.ConfigurationManager"
 7:                     ,method ,@(when args args))))
 8: 
 9: (defun jami-bot-send-message (account conversation text &optional reply)
10:   "Add TEXT to CONVERSATION via ACCOUNT. REPLY specifies a message id."
11:   (jami-bot--dbus-cfgmgr-call-method "sendMessage"
12:                                      account
13:                                      conversation
14:                                      text
15:                                      `(,@(if reply reply ""))
16:                                      :int32 0))
17: 
18: (defun jami-bot-reply-to-message (account conversation msg text)
19:   "Add TEXT as a reply to MSG in CONVERSATION via ACCOUNT."
20:   (let ((id (cadr (assoc-string "id" msg))))
21:     (jami-bot-send-message account conversation text id)))

If you are not familiar with the special marker shown on line 7 then you can read about how to use the special marker to construct argument lists in a previous blog post.

Finally, we can cache local accounts in a variable and set up a function to update these:

(defvar jami-bot--jami-local-account-ids nil
  "List of `jami' local accounts user ids and name pairs.

Caches output of dbus-methods 'getAccountList' and
'getAccountDetails'. For internal use in `jami-bot'.")

(defun jami-bot--refresh-accountid-list ()
  "Update cached values of known local account ids.

The values are stored in `jami-bot--jami-local-account-ids'."
  (let ((accounts (jami-bot--dbus-cfgmgr-call-method
                   "getAccountList")))
    (let ((value))
      (dolist (acc accounts)
        (push (cons (cadr (assoc-string
                           "Account.username"
                           (jami-bot--dbus-cfgmgr-call-method
                            "getAccountDetails"
                            acc))) acc)
              value))
      (setq jami-bot--jami-local-account-ids value)))
  jami-bot--jami-local-account-ids)

If you have read this far, you likely have already ideas how you could use this code to scratch an old itch of yours or you might have other comments – please get in touch, I would love to hear them!

My personal need was, as mentioned before, straightforward note-taking on the go: pop out the mobile phone, send a message to Emacs and have that thought transferred directly into my second brain.

I wrote another blog post detailing the code and usage thereof: Note-taking on the go: Capturing messages and images sent via Jami in Org mode

Tags: emacs, jami, programming, lisp

This uses the foreseen mechanism in vertico to modify the sorting of matches, vertico-sort-override-function. Unfortunately, the function called by this hook is only provided with a list of file names without any absolute path needed to actually locate them. Retrieving the modification times is therefore not straightforward.

hanno/vertico-sort-by-mtime therefore starts by deriving the current path from the minibuffer prompt which (of course) displays it for the user. Using this, it gets the modification timestamp for each of the candidates displayed and returns a sorted list.

This certainly feels a little hacky even though it works fine and is probably robust enough. Still, as the marginalia annotations displayed besides the files already have the modification times, I am sure there is a more elegant way to get to this information. One drawback is that it is fairly slow when there are lots of files; in that case, using dired and its built-in sorting might be quicker and more comfortable.

If you have a clever idea how to improve this or should you have encounted any issues, get in touch and let me know!

This code is loosely based on the very helpful examples in the vertico wiki and took inspiration from this post addressing the same problem (but missing the issue with the current directory path).

Tags: emacs, lisp

The animation shows how one initiates a multi-message capture from within the Jami messenger app – that is, a capture process that consists of several messages and can include even images and other files. The process is started by sending the command !start followed by the title of the capture. Every command consists of an exclamation mark and a single word, for example: !help which shows the available commands or !today which captures the remainder of the message as a todo entry scheduled today. Everything else is treated as a normal message (and captured verbatim).

On the other side of the chat is jami-bot running within Emacs on my local computer. It responds to each of my messages to indicate how it was processed.

Once the multi-message capture session is started, every following message is simply added. This includes images which will be downloaded and stored locally on my computer. A reference in the form of a link will be included in the notes.

Putting down the phone and opening the computer again, I will see something like this on the screen:

On the left is the capture buffer which includes the individual messages and the image I sent shown inline. Additional meta information like the capture date is also included. Files sent separately as a single message, such as the screenshot in the next entry, are captured as links to the locally downloaded file and tagged as FILE. In principle, further automatic processing (e.g. OCR) could easily be integrated. In clear text, the first example capture looks like this:

* Demonstration of a multi-message capture :)
:PROPERTIES:
:CREATED: [2023-04-10 Mon 18:26]
:END:
This is the first line to be added.
But there can more!
#+ATTR_ORG: :width 400
[[../../jami/20230410-1826_image1_1.png]]
Like cute cat pictures 😻
That's it!

Any received file will also be added to the variable org-stored-links and can then be easily inserted as link in any Org mode document using C-c C-l. For me, this has become the easiest and quickest way to transfer specific files from my mobile phone to my computer and into my notes.

Jami is a distributed and private messenger that is part of the GNU project and mainly developed by Savoir-faire Linux. Private in this context does not only refer to the fact that messages, calls and video chats are encrypted, but that you need to provide essentially no personal information to create a Jami account. Distributed means that you can have encrypted (group) chats without requiring any server to exchange them through – which even works between devices on the same local network while the internet is down.

Jami is easy to deploy on most OS and is available for different mobile devices as well. That coupled with that fact that it was rather straightforward to interface from Emacs made it a ideal candidate for this experiment.

However, Jami has some rougher edges from a user’s perspective (that is to say, my personal one). While the mobile Android client has improved significantly over the past years, it still might quietly fail to sync up with other clients. In those cases, only a restart of the App seems to help reliably. Other quirks can be slightly annoying at times: pasting from the clipboard, for example, wipes the current message draft on my Android client – and I tend to insert links as the last step of composing a message.

Similarly, also the desktop daemon, jamid, which runs in the background while jami-bot interacts with it, sometimes needs a friendly killall jamid followed by M-x jami-bot-register to re-initiate the service. In particular, network state changes, i.e. a temporary loss of connectivity seems to cause a drop from the Jami network which Jami does not recover quickly from.

One more thing to be aware of is that jami-bot only reacts to messages being received. So if the daemon (and/or the GUI app) is already running before jami-bot is registered and started, some messages might slip by unnoticed. Should you not yet have received them yet though, for example because the daemon lost the connection, you can simply follow the killall-and-register procedure outlined above and you will capture any missed messages.

Personally, I can live with these compromises.

One last thing to consider is security: I am not aware of any recent security audit of Jami. Either way, bugs affecting the security of the messenger likely exist. Personally, I assume that by disabling unneeded features such as phone and video calls on my account, disallowing connections with unknown accounts and limiting my accounts exposure will keep it sufficiently secure for me. Timely updates are a given of course. (org-)jami-bot should only marginally increase the attack surface as long as you use it with trusted devices and accounts and do not extend it with functions that directly execute parts of the message received as code. In case you discover any potential security risks with the code I provide or the way I interface with Jami, please let me know!

In any case, you should make your own threat model for your use case and situation.

That said, let’s look into setting things up!

We will need to have the Jami daemon, jamid, installed on the local system. On Debian, this can be done by simply running sudo apt install jami which will also install the GUI application. The latter is not strictly necessary but can be more comfortable to use during the account setup. The version installed through apt, however, is likely older than what is provided on the official Jami download pages – consider updating should you run into any connectivity issues later.

Jami is controlled by jami-bot via a protocol called D-Bus. If you are using a Linux-based system such as Ubuntu, you are almost certainly already running D-Bus and an Emacs with built-in support. If you are using Mac OSX, you need to install D-Bus first (as far as I know). Even MS Windows can run D-Bus. If you succeed with any of the latter options, please let me know – however, this is somewhat outside the scope of this post.

Then you will need to create a Jami account. The easiest is to make a completely new one only for jami-bot, even if you already have a Jami account. Simply use the GUI or, for more advanced users and/or headless machines, follow the steps outlined in the first post of this series. You also need to add any user that should be able to interact with jami-bot as a contact and have the request be accepted on the other side – only then can you start exchanging messages.

By default, jami-bot will react to any message sent to any local Jami account but will ignore message sent from local accounts (to avoid feedback loops). In case you have several local accounts and would like to limit jami-bot to only one of them, you can configure the variable jami-bot-account-user-names.

Once you have jami-bot and org-jami-bot configured, check that the account you want to send captures to is shown as present in Jami (indicated by a green dot in the profile). Send a simple command such as !help or !ping first. On the computer running jami-bot, you should see a message appear in the minibuffer indicating that the message was received. Shortly after, you should get a response via Jami.

After that, try a capture: simply send a text message (without starting it with an exclamation mark). You should see the response “captured” after only a moment. The message should be filed at the location you specified in your capture template (org-default-notes-file by default).

Try sending an image or starting a multi-message capture (by sending !start) next. If all works as intended, you might want to adjust or extend the format of the capture – so let us look into the code handling the captures!

This section is mostly for the curious or those that would like to extend org-jami-bot to scratch their own itch. If you want to go even deeper, a previous post explained jami-bot which might be useful in case you want to explore more of Jami’s functionality.

Note: the code discussed below is what I originally wrote – it probably has evolved since and the newest version will be hosted at this repository: https://gitlab.com/hperrey/org-jami-bot

One central function is the capture processor for any plain text message that is not a command:

 1: (defun org-jami-bot--capture-plain-messsage (account conversation msg)
 2:   "Capture body in MSG and replies to original message.
 3: 
 4: CONVERSATION and ACCOUNT specify the corresponding ids that the
 5: message belongs to."
 6:   (let* ((buf (format "*jami-capture-%s-%s*" account conversation))
 7:          (continue (get-buffer buf))
 8:          (body (cadr (assoc-string "body" msg)))
 9:          (lines (string-lines body))
10:          ;; use inactive timestamps
11:          (timefmt (concat "[" (substring (cdr org-time-stamp-formats) 1 -1) "]")))
12:     (with-current-buffer (get-buffer-create buf)
13:       (insert (if continue
14:                   ;; multi message capture
15:                   (concat body "\n")
16:                 ;; single message capture
17:                 (format "* %s\n:PROPERTIES:\n:CREATED: %s\n:END:\n%s"
18:                         (car lines) (format-time-string timefmt) (string-join (cdr lines) "\n"))))
19:       (jami-bot-reply-to-message
20:        account
21:        conversation
22:        msg
23:        (if continue
24:            "message added. Finish capture with \"!done\""
25:          (if (and (org-capture-string
26:                    (buffer-string)
27:                    org-jami-bot-capture-key)
28:                   (kill-buffer buf))
29:              "captured!"
30:            "error during org-capture :("))))))

It consists of three parts: starting on line 6 it sets up helper variables, from line 12 onward it sets up the text to be inserted into a capture buffer and after line 19 constructs the reply. The capture template is chosen according to the value of org-jami-bot-capture-key

(defvar org-jami-bot-capture-key "J"
  "Key for the org-capture template to call for Jami messages")

However, the actual capture (line 25) is only performed if the capture buffer did not already exist – if it did, the message has to be part of a multi-message capture process. In that case, the capture buffer will remain until killed by org-jami-bot--command-function-done (triggered by the !done command). This function, and the one to initiate such a multi-message capture and sets up the capture buffer, are defined below:

(defun org-jami-bot--command-function-start (account conversation msg)
  "Initiate a multi-message capture.

It starts with body in MSG by creating a capture buffer for
CONVERSATION and ACCOUNT.

Further plain text messages processed by
`org-jami-bot--capture-plain-messsage' or files received by
`org-jami-bot--capture-file' will be added to this capture
buffer. The actual capture needs to happen through a separate
function, e.g. `org-jami-bot--command-function-done'. Return a
reply string informing correspondent about how to finish capture
by sending '!done'."
  (let* ((buf (format "*jami-capture-%s-%s*" account conversation))
         (body (cadr (assoc-string "body" msg)))
         (lines (string-lines body))
         ;; use inactive timestamps
         (timefmt (concat "[" (substring (cdr org-time-stamp-formats) 1 -1) "]")))
    (with-current-buffer (get-buffer-create buf)
      (insert (if (string-empty-p buf)
                  (format "* Multi-message note capture %s\n:PROPERTIES:\n:CREATED: %s\n:END:\n"
                          (format-time-string timefmt) (format-time-string timefmt))
                (format "* %s\n:PROPERTIES:\n:CREATED: %s\n:END:\n%s"
                        (car lines) (format-time-string timefmt) (string-join (cdr lines) "\n"))))
      "Multi-message capture started. Finish capture with \"!done\"")))

(defun org-jami-bot--command-function-done (account conversation msg)
  "Finish multi-message capture and return a confirmation string.

        Requires a capture buffer set up for CONVERSATION and
        ACCOUNT, for example through
        `org-jami-bot--command-function-start'."
  (let* ((buf (format "*jami-capture-%s-%s*" account conversation))
         (continue (get-buffer buf))
         (body (cadr (assoc-string "body" msg))))
    (if continue
        (with-current-buffer (get-buffer-create buf)
          (if (and (org-capture-string
                    (buffer-string)
                    org-jami-bot-capture-key)
                   (kill-buffer buf))
              "capture finished!"
            "error during org-capture :("))
      "No capture to finish. Start multi-message capture with \"!start\"")))

Note that the command functions do not need to actually send the reply message: this is done by the jami-bot function that will perform the message processing and calls above functions.

Very similarly, we can also capture file transfers. The actual download is handled by jami-bot already, so we only need to capture a link and add that to org-stored-links:

(defun org-jami-bot--capture-file (account conversation msg dlname)
  "Capture downloaded file and reply to original message.

DLNAME specifies local file name downloaded from MSG in
CONVERSATION for jami ACCOUNT."
  (let* ((buf (format "*jami-capture-%s-%s*" account conversation))
         (continue (get-buffer buf))
         (displayname (cadr (assoc-string "displayName" msg)))
         ;; use inactive timestamps
         (timefmt (concat "[" (substring (cdr org-time-stamp-formats) 1 -1) "]")))
    (with-current-buffer (get-buffer-create buf)
      (insert (if continue
                  ;; multi message capture
                  (concat
                   "#+ATTR_ORG: :width 400\n"
                   (org-link-make-string (file-relative-name dlname)) "\n")
                ;; single message capture
                (format "* FILE %s :FILE:\n:PROPERTIES:\n:CREATED: %s\n:END:\n\n#+ATTR_ORG: :width 400\n%s\n"
                        (org-link-make-string (file-relative-name dlname) displayname)
                        (format-time-string timefmt)
                        (org-link-make-string (file-relative-name dlname)))))
      ;; store link for easy linking
      (push (list dlname displayname) org-stored-links)
      (jami-bot-reply-to-message
       account
       conversation
       msg
       (if continue
           "file added. Finish capture with \"!done\""
         (if (and (org-capture-string
                   (buffer-string)
                   org-jami-bot-capture-key)
                  (kill-buffer buf))
             "captured!"
           "error during org-capture :("))))))

Having a Jami bot running in Emacs has already helped me to dump notes, images and references into my second brain when my phone was the only digital device at hand.

I am also using syncthing and Orgzly on my mobile devices. However, sending a quick message !today buy oat milk or some such feels a lot more natural and quicker than first navigating to the right place, setting a date before even entering what I was thinking of.

And for such a simple todo entry this might be mostly a matter of taste. However, I will soon follow up with a post on how to use org-capture-ref to capture an URL – including bibliographic information in BibTeX format and tags. This has been a great way for me to reduce the number of open tabs on my phone and finally transfer those interesting links and articles into my notes without too much effort or yet another app.

Automatic archiving of web articles, text recognition in images or maybe even speech recognition from audio recordings – let me know what you come up with 😺

The instructions below are the summary of what is provided on Inform’s git repository pages. You will likely need the typical prerequisites for compiling code packaged for your flavor of distribution, e.g. build-essential on Debian-based systems¹. On my system, I already had everything installed that Inform needed. If you run into errors during the build process, you might have to look into missing dependencies.

To build Inform, we also need Inweb and Intest. Both are installed in similar fashion:

1: git clone https://github.com/ganelson/inweb.git
2: bash inweb/scripts/first.sh linux
3: inweb/Tangled/inweb -help
4: git clone https://github.com/ganelson/intest.git
5: bash intest/scripts/first.sh

The call to inweb on line 3 is just to test the compilation – if everything worked, you should see the help message of the Inweb CLI.

Once these two are in place, we can install Inform itself:

1: git clone https://github.com/ganelson/inform.git
2: cd inform/
3: bash scripts/first.sh
4: inblorb/Tangled/inblorb -help
5: ../intest/Tangled/intest inform7 -show Acidity

Again, the last lines are only for testing the installation. If everything went smoothly, we are ready to create our first project!

Let’s use one of the examples from the Inform documentation: A pot of petunias!

"Pot of Petunias"

Wide Open Field is a room. "A big field under a big sky. The clouds are puffy, the trees are handsome."

Some clouds and some trees are scenery in Wide Open Field. The description of the clouds is "That one looks like Yoda's head." The description of the trees is "You've never been much good at botany, so it's anyone's guess what kind they are."

A rock is in Wide Open Field. The description of the rock is "It looks like it's been here from the dawn of time."

The broken flower pot is a thing. The description of the broken flower pot is "It contains the remains of some abused petunias."

At 9:01 am:
    move the broken flower pot to the location;
    say "Quite unexpectedly, a flower pot falls from the sky and breaks open on the ground. Good thing you weren't standing six inches to the left.";
    set pronouns from the broken flower pot.

Test me with "x it / x it / x it".

Inform uses projects to store each story, its resources and build files in. In the following, I create the simple directory structure for the first project and set up some environmental variables to make it easier to adjust paths and such:

GAME_PROJECT="petunias"
GAME_PROJECT_DIR="$HOME/src/$GAME_PROJECT"

mkdir -p "$GAME_PROJECT_DIR/Source"

This creates a directory ~/src/petunias with a subfolder Source. Save the above story into a file story.ni in the Source folder.

As a last detail, each project should have a unique identifier. Create one using the uuid utility² (or use a python one-liner³) and store it in ~/src/petunias/uuid.txt:

UUID="$(uuid)"
echo -n $UUID > "$GAME_PROJECT_DIR/uuid.txt"
echo $UUID

03f452f8-c955-11ec-bd44-0019b808dd97

When editing manually, be sure that the uuid.txt file does not end in a line break or some parsers will break when reading the file!

Now we are ready to compile our story using Inform. The compilation will in fact consist of two steps: first, inform7 will translate the story’s source into Inform6 code. Then inform6 will be used to compile into one of the standard virtual machine codes used in interactive fiction: Glulx or Z-machine. The choice depends on which interpreter you (or your players) want to use.

This post is rather brief; a lot more details can be found in this very thorough description of the process on the interactive fiction forum. Despite some of the information there being slightly outdated, you will learn a lot about the different formats and options of the process reading it!

For convenience and slightly shorter commands, I define a variable to keep the path to the Inform source code:

ISRC="$HOME/src/inform"

Now compile the project with inform7:

"$ISRC/inform7/Tangled/inform7" -no-progress -external "$HOME/Inform" -project "$GAME_PROJECT_DIR/"

Inform 7 v10.1.0 has started.
I've now read your source text, which is 170 words long.
I've also read Basic Inform by Graham Nelson, which is 7691 words long.
I've also read English Language by Graham Nelson, which is 2328 words long.
I've also read Standard Rules by Graham Nelson, which is 32130 words long.

  The 170-word source text has successfully been translated. There were 1 room
    and 5 things.
Inform 7 has finished.

The -external switch is optional. The directory specified here is the default for additional external extensions and is it being created automatically when running Inform on a project (as we just did). If you’d rather see extensions stored elsewhere, simply adjust that path.

For a release version, add the -release switch. You can also add -debug for additional debugging features. For a full list of CLI options, run

"$ISRC/inform7/Tangled/inform7" --help

Check out the project’s folder: inform7 has just generated a bunch of files and folders.

Next step is the compilation of the just generated Inform6 code to (gl)ulx:

"$ISRC/inform6/Tangled/inform6" -E2wSDG "$GAME_PROJECT_DIR/Build/auto.inf" "$GAME_PROJECT_DIR/Build/output.ulx"

Inform 6.36 for Linux (24th January 2022)
In:  1 source code files             94387 syntactic lines
 81099 textual lines               2394870 characters (ISO 8859-1 Latin1)
Allocated:
  8818 symbols                     2885088 bytes of memory
Out:   Glulx story file 1.220501 (665K long):
    20 classes                          42 objects
   232 global vars                   86156 variable/array space
    96 verbs                           322 dictionary entries
   179 grammar lines (version 2)       251 grammar tokens (unlimited)
   101 actions                          37 attributes (maximum 56)
    39 common props (maximum 253)       18 individual props (unlimited)
133667 characters used in text      104309 bytes compressed (rate 0.780)
     0 abbreviations (maximum 64)     3230 routines (unlimited)
 81298 instructions of code          45940 sequence points
110080 bytes writable memory used   570368 bytes read-only memory used
680448 bytes used in machine    1073061376 bytes free in machine
Compiled with 3236 suppressed warnings
Completed in 2.00 seconds

The format is specified through the command line switches -E2wSDG; Change these to -E2w~S~DG for release version where debugging and strict testing is explicitly disabled (through the ~ character). Replacing G with v8 would compile to z8 instead for glulx. For a full list of options, run inform6 with --help or -h2 for general help or a compilation switch overview, respectively.

This created the file $GAME_PROJECT_DIR/Build/output.ulx. The next and final step is to package everything up into a standard IF game file.

Now it is time to combine the compiled game, meta information and potential media assets into one game file that can be easily distributed. The process is controlled by the file $GAME_PROJECT_DIR/Release.blurb and performed by inblorb which is part of the inform7 installation.

"$ISRC/inblorb/Tangled/inblorb" "$GAME_PROJECT_DIR/Release.blurb" "$GAME_PROJECT_DIR/Build/output.gblorb"
cp "$GAME_PROJECT_DIR/Build/output.gblorb" "$GAME_PROJECT_DIR/Release/Pot of Petunias.gblorb"

! inblorb 4 [executing on Sunday 1 May 2022 at 16:11.45]
! The blorb spell (safely protect a small object as though in a strong box).
Copy blorb to: [[/home/hanno/src/petunias/Release/Pot of Petunias.gblorb]]
! Completed: wrote blorb file with 1 picture(s), 0 sound(s)

Now it is finally time to play the game using your favorite interpreter! For example,

glulxe "$GAME_PROJECT_DIR/Release/Pot of Petunias.gblorb"

 Wide Open Field
──────────────────────────────────────────────────────


Pot of Petunias
An Interactive Fiction
Release 1 / Serial number 220501 / Inform 7 v10.1.0 / D

Wide Open Field
A big field under a big sky. The clouds are puffy, the trees are handsome.

You can see a rock here.

>

Have fun and happy hacking!

Tags: if, inform7

Whenever one has a problem to solve, someone else has probably already undertaken at least the first steps. Which is nice, as it turns out that getting calendar event handling right is not so easy.

There is org-caldav which seems to fit the bill perfectly: it offers direct CalDAV sync for org-mode. As the synchronization is handled within org-caldav itself, it needs to deal with conflict handling, deletions and storage of sync information internally. I was worried that any misconfiguration or user mistake could lead to loss of data (and missed meetings) and instead opted to set up a tool chain composed of specialized tools for each step.

The first building block is vdirsyncer, a command-line tool capable of synchronizing calendars and address books between a variety of servers and the local file system. It stores calendars locally in directories where each event is recorded in a single .ics file. These are human-readable plain text files containing all fields and their data. Interaction with the remote server only happens when triggered by running vdirsyncer. This makes it easy to track changes or make backups and safe to experiment with.

To interact with the local calendar and parse the data therein, another tool comes in handy: khal. This Python-based command allows to list, edit and create events either directly from the command-line or via an interactive text-based interface. khal is somewhat limited in what it can handle (in terms of supported fields in calendar events, for example), but for my purposes of managing one shared and one personal calendar it was ideal.

Adjusting the default upcoming event listing of khal slightly, one can quite easily get something that already resembles the org-mode syntax:

khal list --format "* {title} \n <{start-date} {start-time}-{end-time}> \n {location} \n {description}" --day-format "" today 10d

The output above shows the events in the coming 10 days from now. This gives us something to work with and means we don’t have to touch the .ics files directly.

Last but not least, org-mode comes with export functions to ics with many configurable options: org-icalendar-export-to-ics. This makes it possible to create new events from org-mode, export to ics and import to the local calendar store using khal import.

So I started playing with elisp to tie these components together and out came my very first Emacs package: khalel!

khalel provides a relatively thin wrapper around the above mentioned tools allowing to list, edit and create calendar events from within Emacs: Once installed, you can import upcoming events through M-x khalel-import-upcoming-events into an org-mode file, edit individual events with M-x khalel-edit-calendar-event or create new ones by starting org-capture (C-c c or M-x org-capture) and pressing e (default key) for a new calendar event. To synchronize with remote calendars simply call M-x khalel-run-vdirsyncer.

Along the way I discovered how easy org-mode makes it to wrap elisp code: If you visit the org file with the imported events, you will notice links below each event. Using these you can directly edit the corresponding calendar entry with a single click or trigger a synchronization and import. Sweet! :)

This is how the resulting org-mode agenda and the calendar file with the imported events looks like:

Now I have have all my events at hand and where they belong: in the org agenda :)

If you want to give the (rather young) code a shot, you can find it here: https://gitlab.com/hperrey/khalel. The code has also been submitted to melpa and awaits a review (which I am quite excited about!).

In the khalel repository you will also find more details on the configuration of vdirsyncer, khal and khalel as well as on the inherent limitations of this approach. If you do try this out, please share your experience with me! :)

Tags: emacs, pim, programming, lisp, org

These questions leave me no peace and are a central reason why I decided to increasingly dismiss Google’s offerings. The most difficult and yet most important is the choice of mobile phone: there are a only very few brands that do at least allow or even provide a Google-free operating system⁵. When last making this choice, I did not want the former option that would require unofficial hacks, despite some of these being rather mature all things considered. Luckily, there was and is again a better option for the latter in the shape of the Fairphone 2 and now Fairphone 3. I own the former since its first release in 2015/16 and am very fond of it. It runs Fairphone OpenOS which is based on the free and open parts of Android 7⁶. I run selected apps via direct download or through the F-Droid store⁷.

For all of the commonly-used Google services, I found replacements that often have one key feature seldom found in Google services: full offline support. This means that I, for example, download maps in OSMAnd (instead for Google Maps) and can access this anywhere, anytime without any internet connection. Since this usually covers the whole country I am interested in, I don’t have to be particularly selective beforehand. And whether I want to save on battery when out in the woods or want to look up an address while having no connection when traveling, OSMAnd is there for me. The same is true for my dictionary, music collection, podcasts, and notes. If you are looking for alternatives, switching.software and privacytools.io are very good sources.

That doesn’t mean that I have to manually synchronize anything. Syncthing runs on my desktop, phone and a Raspberry Pi at home and keeps data and music up-to-date whenever I am home. The Raspberry Pi also hosts my calendar and contacts and allows me to stream music to my stereo system via Bluetooth or WiFi (instead for whatever that Google thing is called). My browser of choice is Firefox (instead for Google Chrome) and the search engine I usually start with is DuckDuckGo.

As mail host, there are an abundance of services that I trust more than I trust or want to support Google. I both use my own domain and have accounts in techcollectives such as riseup.net, fripost.org and hcoop.net.

And today I logged into my Google account for the last time and deleted it.

Which, I have to admit, was a very pleasant user experience and went smoothly. Especially when compared to the hoops that Amazon makes one jump through deleting one’s account.

With all this in place, Google is far from being out of my life though: most of my friends store my contact details with Google, ring me from their Google phones, or receive my mails in their GMail accounts. But it doesn’t stop there: most websites embed Google-services such as Google Analytics or Google Ads which track me throughout my web journeys⁸. Even government online services use and require Google code to run on my machine when they use reCAPTCHA to ’make sure I am human’.

And that is just what is still obvious to see. Google also operates infrastructure that is much less visible but still yields data to them. For example, the university I work at has the students’ mail accounts hosted on Google’s servers. You could not tell this from their mail addresses, however.

So while I perceive the step to remove my direct ties with Google and to replace them with free and open software as a significant one to regain self-determined use of my devices, it does not remove Google from my digital life entirely. Google is here to stay and we as a society better find ways to deal with it and other IT monopolists without surrendering ourselves and our freedom.

Comments? Leave them as reply to the corresponding post on Mastodon.

Tags: degoogle, privacy, thoughts

Besides Emacs² and a system running D-Bus, we will need to have the Jami daemon, jamid, installed on the local system. On Debian, this can be done by simply running sudo apt install jami which will also install the GUI application. The latter is not strictly necessary but can be more comfortable to use during some of the steps. The version installed through apt, however, is likely older than what is provided on the official download pages – consider updating should you run into any connectivity issues later.

Another useful – but optional – tool is the graphical D-Bus debugger, D-Feet. If you feel that exploring long lists of D-Bus nodes via Elisp function calls is a little daunting (or tedious), this tool will allow you to click through to the information you want very quickly.

Emacs comes with its own D-Bus API which is documented quite well and includes several examples. This makes it easy to interact with any services on D-Bus through a simple Elisp function call. But first, the dbus package needs to be loaded:

(require 'dbus)

Now, we can already find out what services are available via D-Bus. Generally, there are two separate busses to consider: the system bus and the session bus. Anything started by the user would typically reside on the latter while the former has services such as network, power management and the like. As Jami is a service started by the user, it is found on the session bus. dbus-list-names can list anything registered there:

(dbus-list-names :session )

I needed to shorten the list considerably despite my system running a rather lightweight desktop environment only. So you might see a considerably longer list. You find things like my terminal program (org.xfce.Terminal5) or the currently running Firefox profile (org.mozilla.firefox.ZGVmYXVsdC1lc3I_). What I am looking for is cx.ring.Ring which is Jami – the messenger was called “GNU Ring” until not so long ago and the API has not been updated yet.

Alternatively, you can also check whether or not a service is registered by pinging it:

(dbus-ping :session "cx.ring.Ring")

On my system, this actually has the side effect of starting the Jami daemon (jamid) even if it was not running before. The daemon is what is running in the background and handling all interactions with the various network connections Jami establishes to allow messages, calls and video chats. So it is essential for using Jami and even the GUI builds upon it. If this command returns nil, check your Jami installation and that jamid is running.

Let us take a closer look into the Jami D-Bus interface. It is structured into a number of interfaces that correspond to different aspects of the messenger:

(dbus-introspect-get-all-nodes :session "cx.ring.Ring" "/cx/ring/Ring")

The different names indicate what each node does, e.g. handling calls, video or plugins. This feature of being able to list parts of the API and even – as we will see later – find the arguments expected by methods is called introspection and a nice feature of D-Bus. It is similar to how Emacs allows you to explore its functions and variables from within the running software. So if you, for example, wonder how to use the function dbus-introspect-get-all-nodes, you can from within Emacs press C-h f to open the help for functions, write dbus-introspect-get-all-nodes (or use tab-complete) and press enter to see the signature, a short explanation and the source code to the function. The former is (dbus-introspect-get-all-nodes BUS SERVICE PATH). The session was already explained above. The service consists of a name separated by dots while the path denotes an object on the D-Bus separated by slashes like a path on a filesystem. For the examples below, the service is always cx.ring.Ring.

Despite the ability for introspection in D-Bus, it will likely be necessary to look into the API as defined in the Jami source code. You can find these in the jami-daemon/bin/dbus/cx.ring.Ring.ConfigurationManager.xml file in the Jami source repository. This document includes helpful documentation for many of the nodes, i.e. methods and signals. There is only so much one can guess from the node’s name alone. I have unfortunately not found a way to retrieve these additional docstrings from within D-Bus – so having the above file open as a reference is useful for the following exercise.

Of the above mentioned interfaces, only the ConfigurationManager is needed in the beginning. While it would be cool to automatically answer calls and e..g record and transcribe them, I have not yet had the time to dig into the CallManager sufficiently. But the methods and signals of the ConfigurationManager will already allow us to create an account, add a contact and receive and send messages.

Now let us put the newly created account to use and start a chat with another Jami user. For that, we will need to know the full address such as, for example, badac18e13ec1a6e1266600e457859afebfb9c46. As this is error prone to type in and tedious to spell out, the GUI application allows you to scan a QR code from your friend’s phone instead. Alternatively, you can register a name on the network that is easier to remember but must be unique. Let us assume that the person we would like to contact has done so and search for the user name on the network.

For any account, you can list the available conversations:

(dbus-call-method :session
                  "cx.ring.Ring"
                  "/cx/ring/Ring/ConfigurationManager"
                  "cx.ring.Ring.ConfigurationManager"
                  "getConversations"
                  "d362747388cf970f")

To see who is a member of the conversation, use getConversationMembers and provide account and conversation as arguments:

(dbus-call-method :session
                  "cx.ring.Ring"
                  "/cx/ring/Ring/ConfigurationManager"
                  "cx.ring.Ring.ConfigurationManager"
                  "getConversationMembers"
                  "d362747388cf970f"
                  "70bcc0ce73be4091b5e159dc22d6cc5bb4e1a252")

Knowing its ID, we can send a message to a conversation via sendMessage:

(dbus-call-method :session
                  "cx.ring.Ring"
                  "/cx/ring/Ring/ConfigurationManager"
                  "cx.ring.Ring.ConfigurationManager"
                  "sendMessage"
                  "d362747388cf970f"
                  "70bcc0ce73be4091b5e159dc22d6cc5bb4e1a252"
                  "this is the first line of the message\nThis is the second line"
                  ""
                  :int32 0)

The last two arguments are the commitId and the flag. The former is used to refer to an existing message (a commit since git is used behind the scenes to manage conversation data). In the above example, we are sending a single, new message, so the commitId is empty and the flag set to 0. If a commitId would have been given, then this would have been sent as a reply to that message instead. If the flag is set to ’1’ then this would have been an edit to an existing message.

You can find out the id of a previous message by searching for it. I have, however, not looked much into that feature. Alternatively, one can wait for a signal that a new message arrived (messageReceived) and retrieve both message and its id from a registered handler. As a more trivial example, we can dump the meta information and contents of the message to the minibuffer and *Messages* buffer:

(defun my-messageReceived-handler (account conversation message)
  (message "jami received msg: account: %s, conversation: %s, msg: %s" account conversation message))

(dbus-register-signal :session "cx.ring.Ring" "/cx/ring/Ring/ConfigurationManager" "cx.ring.Ring.ConfigurationManager" "messageReceived" #'my-messageReceived-handler)

Some example messages:

jami received msg: account: d362747388cf970f, conversation: 70bcc0ce73be4091b5e159dc22d6cc5bb4e1a252, msg: ((author b8e0350a62caf0173d18e0d1256a8cf2ea88e75b) (body Test!) (id f23a3db43597ad1bdd7e8027cd3e6ca2f4ad7820) (linearizedParent d899f9926e8bedc907b85e6f60bf0f03672c5881) (parents d899f9926e8bedc907b85e6f60bf0f03672c5881) (timestamp 1678032406) (type text/plain))

jami received msg: account: d362747388cf970f, conversation: 70bcc0ce73be4091b5e159dc22d6cc5bb4e1a252, msg: ((author b8e0350a62caf0173d18e0d1256a8cf2ea88e75b) (displayName IMG_{20230304115628.jpg}) (fileId 15af639ad4cab741e15717cb867cb613f0e8c4ff_{3740082762842406.jpg}) (id 15af639ad4cab741e15717cb867cb613f0e8c4ff) (linearizedParent eab0a2c8e2f1ca5f7de8991375dafb8962178cae) (parents eab0a2c8e2f1ca5f7de8991375dafb8962178cae) (sha3sum 457c749572575f6827b2ae0860d065911adc959a0d57d4ccc47ab26cc93e7c07a01122e28344ee7745aca8ea85216ba6c6aba8cf42aaaebd68ff33fa6ad66929) (tid 3740082762842406) (timestamp 1678033015) (totalSize 2971303) (type application/data-transfer+json))

In the first example, we have received a simple text (’Test!’). The message contains, amongst others, fields for the author, message id, and timestamp. In the second example, the message is a file transfer with additional fields such as the id and fileId. Knowing these, we can download the file to the local machine using downloadFile:

(dbus-introspect-get-method :session "cx.ring.Ring" "/cx/ring/Ring/ConfigurationManager" "cx.ring.Ring.ConfigurationManager" "downloadFile")

Following the example above, this could be:

(dbus-call-method :session "cx.ring.Ring" "/cx/ring/Ring/ConfigurationManager" "cx.ring.Ring.ConfigurationManager" "downloadFile" "d362747388cf970f" "70bcc0ce73be4091b5e159dc22d6cc5bb4e1a252" "15af639ad4cab741e15717cb867cb613f0e8c4ff" "15af639ad4cab741e15717cb867cb613f0e8c4ff_3740082762842406.jpg" "/home/hanno/tmp/jami.jpg")

Timestamps are given in seconds and can be converted into calendrical information using decode-time:

(decode-time 1678032925)

(25 15 17 5 3 2023 0 nil 3600)

The values are (SECONDS MINUTES HOUR DAY MONTH YEAR DOW DST UTCOFF), respectively.

To save some keystrokes, we can define a helper routine with all the constant parts:

(defun jami-dbus-call-cfgmgr-method (method &rest args)
  "Call jami D-Bus METHOD on the cfgmgr interface with arguments ARGS."
  (apply #'dbus-call-method `(:session
                    "cx.ring.Ring"
                    "/cx/ring/Ring/ConfigurationManager"
                    "cx.ring.Ring.ConfigurationManager"
                    ,method ,@(when args args))))

That means that sending a message would become:

(jami-dbus-call-cfgmgr-method "sendMessage"
                              "d362747388cf970f"
                              "70bcc0ce73be4091b5e159dc22d6cc5bb4e1a252"
                              "this is the first line of the message\nThis is the second line"
                              ""
                              :int32 0)

Or, with yet another helper function, we can get this even shorter:

(defun jami-send-message (account conversation text &optional reply)
  "Add TEXT to CONVERSATION via ACCOUNT. REPLY optionally specifies
a message id."
  (jami-dbus-call-cfgmgr-method "sendMessage"
                                account
                                conversation
                                text
                                `(,@(if reply reply ""))
                                :int32 0))

Which would allow to send a message with a call to:

(jami-send-message "d362747388cf970f"
                   "70bcc0ce73be4091b5e159dc22d6cc5bb4e1a252"
                   "this is the first line of the message\nThis is the second line")

D-Bus is a powerful tool to interact with services running on the system. Its introspection mechanism provides a lot of the necessary information to use this API – however, additional documentation is almost a must, especially when dealing with more complex arguments to methods. Accessing services on D-Bus from Emacs is easy enough, though converting different data types took me some trial and error.

Jami is unusual as it exposes most if not all important functions via D-Bus. In fact, in Jami’s case, D-Bus is the best-supported API to write clients with. Despite the sparse documentation outside the API definition, the API is simple enough and Jami can be scripted with only a few lines of code to do text messaging from within Emacs!

While this post does not really drive that last point home, the next one in this series will demonstrate a Jami chat bot written in Elisp!

Tags: emacs, programming, jami, lisp, dbus