hiro/ement.el
1
0
Fork 0
mirror of https://github.com/vale981/ement.el synced 2025-03-05 17:21:41 -05:00
Code Issues Projects Releases Packages Wiki Activity Actions
ement.el/README.org
Adam Porter 9234dfe9be Merge: Add: Show reactions 
Squashed commit of the following:

commit 1f393d7dde
Author: Adam Porter <adam@alphapapa.net>
Date:   Thu Jul 22 10:48:19 2021 -0500

    Comment: TODOs

commit 7e039a7b4f
Author: Adam Porter <adam@alphapapa.net>
Date:   Thu Jul 22 10:48:08 2021 -0500

    WIP: Docstring for handler lambdas

commit 441c23113c
Author: Adam Porter <adam@alphapapa.net>
Date:   Thu Jul 22 10:40:58 2021 -0500

    WIP: Don't insert reaction events as nodes

    This seems to work well.  However, the event-processing needs some
    refactoring, because the logic is now spread across a few places.

commit 4fdf0ddf37
Author: Adam Porter <adam@alphapapa.net>
Date:   Thu Jul 22 10:30:28 2021 -0500

    WIP: Key face, and fix help-echo

    Remaining issue is that reactions still insert empty events in the
    buffer.

commit 5f700ccc16
Author: Adam Porter <adam@alphapapa.net>
Date:   Thu Jul 22 09:30:18 2021 -0500

    WIP: Fix: Use pushnew to avoid duplicating reactions

commit a40a6e6bc1
Author: Adam Porter <adam@alphapapa.net>
Date:   Wed Jul 21 20:17:32 2021 -0500

    WIP: And in -retro-callback

    A bug now is that, every time a room's buffer is created anew, the
    reactions are duplicated.

commit dbfec18e45
Author: Adam Porter <adam@alphapapa.net>
Date:   Wed Jul 21 19:49:47 2021 -0500

    WIP: Call -room---process-events in -room--buffer

    This almost seems to work, in that reactions from old timeline
    events are displayed when the buffer is made...or not?  It seems to
    work in some cases, but not in others, like when retro-loading...

    The big issue now is that the reaction events cause blank events to be
    inserted into the buffer.  Fixing that will require conditionally
    inserting events, which probably means moving message event handling
    into the defevent macro, which will require some more refactoring...

commit 81757536f2
Author: Adam Porter <adam@alphapapa.net>
Date:   Wed Jul 21 17:02:29 2021 -0500

    WIP: Add: Reactions

    It works for newly received reactions, but after initial sync,
    reactions that happened in the past are not displayed.  I think it's
    because the related events aren't found in the room's timeline, but I
    tried to fix that, and it still doesn't work.

    I'm guessing there are some assumptions that I'm making wrongly, or
    something that I don't understand about how the server sends events.
    We may have to save a list of certain types of events and process them
    after all other events have been processed.  Ugh.

    The good news is that EWOC makes it pretty easy and reliable to update
    messages in the buffer.
2021-07-22 10:48:41 -05:00

6.3 KiB
Raw Blame History

ement.el

Ement.el is a new Matrix client for Emacs. It's basic at the moment, but it can be used to send and read messages.

Screenshots

The message formatting is customizeable (e.g. the timestamp can be displayed in the left or right margin).

/hiro/ement.el/media/commit/9234dfe9be39cb1260024fe0ad6ea625fef87306/images/screenshot2.png

Timestamp headers are displayed where a certain amount of time passes between events.

/hiro/ement.el/media/commit/9234dfe9be39cb1260024fe0ad6ea625fef87306/images/screenshot3.png

Rationale

Why write a new Emacs Matrix client when there is already matrix-client.el, by the same author, no less? A few reasons:

  • matrix-client uses an older version of the Matrix spec, r0.3.0, with a few elements of r0.4.0 grafted in. Bringing it up to date with the current version of the spec, r0.6.1, would be more work than to begin with the current version. Ement.el targets r0.6.1 from the beginning.
  • matrix-client was developed without the intention of publishing it to, e.g. MELPA or ELPA. It has several dependencies, and its code does not always install or compile cleanly due to macro-expansion issues (apparently depending on the user's Emacs config). Ement.el is designed to have minimal dependencies outside of Emacs (currently only one, plz, which could be imported into the project), and every file is linted and compiles cleanly using makem.sh.
  • matrix-client uses EIEIO, probably unnecessarily, since few, if any, of the benefits of EIEIO are realized in it. Ement.el uses structs instead.
  • matrix-client uses bespoke code for inserting messages into buffers, which works pretty well, but has a few minor bugs which are difficult to track down. Ement.el uses Emacs's built-in (and perhaps little-known) ewoc library, which makes it much simpler and more reliable to insert and update messages in buffers, and enables the development of advanced UI features more easily.
  • matrix-client was, to a certain extent, designed to imitate other messaging apps. The result is, at least when used with the matrix-client-frame command, fairly pleasing to use, but isn't especially "Emacsy." Ement.el is intended to better fit into Emacs's paradigms.
  • matrix-client's long name makes for long symbol names, which makes for tedious, verbose code. ement is easy to type and makes for concise, readable code.
  • The author has learned much since writing matrix-client and hopes to write simpler, more readable, more maintainable code in Ement.el. It's hoped that this will enable others to contribute more easily.

However, note that matrix-client is a more mature client and is very reliable in the author's experience. While Ement.el is intended to reach feature parity with it and eventually surpass it, that will take some time, so matrix-client remains a good choice.

Installation

Quelpa

The recommended way to install is with quelpa-use-package, like this:

  ;; Install and load `quelpa-use-package'.
  (package-install 'quelpa-use-package)
  (require 'quelpa-use-package)

  ;; Install `plz' HTTP library (not on MELPA yet).
  (use-package plz
    :quelpa (plz :fetcher github :repo "alphapapa/plz.el"))

  ;; Install Ement.
  (use-package ement
    :quelpa (ement :fetcher github :repo "alphapapa/ement.el"))

Straight

Using Straight, it's also very simple:

  ;; Install `plz' HTTP library (not on MELPA yet).
  (use-package plz
    :straight (plz :fetcher github :repo "alphapapa/plz.el"))

  ;; Install Ement.
  (use-package ement
    :straight (ement :fetcher github :repo "alphapapa/ement.el"))

Manual

If you want to install it manually, it's simple enough, but you should know what you're doing, and you're on your own.

Usage

  1. Call command ement-connect to connect.
  2. Wait for initial sync to complete (which can take a few moments–initial sync JSON requests can be large).

  3. Use these commands:

    • ement-view-room to select a room buffer to view, with completion.
    • ement-list-rooms to view the list of joined rooms.

In a room buffer:

  • RET sends a message.
  • S-RET sends a reply to the message at point.
  • TAB / <backtab> moves between messages.
  • v views an event's source.
  • g syncs new messages (not necessary if auto sync is enabled; see below).
  • r selects another room.
  • R shows the room list.
  • M-v or using the scroll wheel at the top of the buffer loads older messages.

Tips

  • You can customize settings in the ement group.

    • Set ement-auto-sync to sync new messages automatically.

Displaying symbols and emojis

Emacs may not display certain symbols and emojis well by default. Based on this question and answer, you may find that the simplest way to fix this is to install an appropriate font, like Noto Emoji, and then use this Elisp code:

  (setf use-default-font-for-symbols nil)
  (set-fontset-font t 'unicode "Noto Emoji" nil 'append)

Changelog

0.1-pre

Yet to be released.

COMMENT Credits

Development

Bug reports, feature requests, suggestions — oh my!

License

GPLv3