alphapapa / Matrix Client.el
#+TITLE: [[images/logo64.png]] matrix-client.el
[[https://matrix.to/#/#matrix-client.el:matrix.org][https://img.shields.io/matrix/matrix-client.el:matrix.org.svg?label=%23matrix-client.el:matrix.org]]
This is a fork of the [[http://doc.rix.si/projects/matrix.el.html][original matrix.el client]] with the intent of maintaining it further, fixing bugs, and providing long-term goals for the project.
-
Contents :PROPERTIES: :TOC: this :END:
- [[#installation][Installation]]
- [[#usage][Usage]]
- [[#commands][Commands]]
- [[#notifications-buffer][Notifications buffer]]
- [[#room-list][Room list]]
- [[#missing-features][Missing features]]
- [[#contributing][Contributing]]
-
Screenshots :PROPERTIES: :TOC: ignore :END:
[[images/notifications-buffer-and-room-list_spacemacs-dark.png]]
Of course, since it's Emacs, you can use any Emacs theme you like. Here's [[https://emacsthemes.com/themes/django-theme.html][django]] without scroll bars or fringes. Note the syntax highlighting in the pasted code, which respects the HTML sent by the client, rather than overriding it like Riot--for better or worse, you decide. =;)=
[[images/django.png]]
And here's the default Emacs theme:
[[images/frame-purpose-example.png]]
- Installation :PROPERTIES: :TOC: 0 :END:
There are two ways to use the client:
- In a separate Emacs instance as a "standalone client." This provides easy access to the dedicated-frame and other UI features, and it isolates the client from your main Emacs process (the main benefit of which is to avoid delays while processing large initial sync responses, which can take a little time, depending on how many rooms you're in and how large they are).
- In an existing Emacs process and configuration, like any other Emacs package.
Notes:
- This client is not available on MELPA. See [[https://github.com/alphapapa/matrix-client.el/issues/47][this discussion]] for more information.
- Emacs 26 or later is required.
** Standalone client
The standalone client is launched with the script =matrix-client-standalone.el.sh= ([[https://github.com/jgkamat/matrix-client-el/blob/master/matrix-client-standalone.el.sh][GitHub link]]). To use, download the script, make it executable, and run it separately--not from within Emacs. If any packages are missing, it uses Emacs's built-in =package.el= to install =quelpa= from MELPA, and =quelpa= then installs this client package and its dependencies. Then it runs the "standalone client" as a separate Emacs process.
The script accepts these options (use =--help= for full list):
- =--debug=: Enable
debug-on-errorin the Emacs session. - =--upgrade=: Upgrade the client to the latest version before connecting. (This also upgrades the script in the package directory, but any changes to it won't take effect until the next time it's run.)
The script doesn't load any standard Emacs user configuration files, so it's /almost/ like a clean Emacs config. However, it uses the default Emacs packages directory (e.g. =/.emacs.d/elpa=): all packages will be installed and read from there, which means that you can load any packages that you already have installed in Emacs, including themes (and after installation you can load the client in your main Emacs config, as well). It also loads and saves its own =user-init-file= at =/.config/matrix-client-standalone.el=, which preserves customized variables and faces; you can add your own code to it, just as you would to your regular Emacs =.emacs= or =init.el= file, which gives you a config mostly independent from your main Emacs config.
To make switching room buffers easy, the default completion settings are improved, and these key bindings are in effect by default:
- @@html:@@[email protected]@html:@@: Switch room buffer.
- @@html:@@[email protected]@html:@@: Show only =Notifications= buffer.
- @@html:@@M-/@@html:@@: Expand text before point with
hippie-expand. Helpful for the =/upload= command as it dynamically expands filename paths.
There's also a context menu available in the sidebar by right-clicking rooms.
Of course, all this is an unorthodox way of installing and using an Emacs package, so if you are uncomfortable with this method, please do inspect the code yourself, or use another installation method.
** Existing Emacs configuration
=matrix-client= is not available on MELPA, so it's recommended to install it with with [[https://github.com/quelpa/quelpa][Quelpa]].
- Install [[https://github.com/quelpa/quelpa][Quelpa]] and [[https://github.com/quelpa/quelpa-use-package][quelpa-use-package]] (which can be installed directly from MELPA).
- Add this form to your init file:
#+BEGIN_SRC emacs-lisp (use-package matrix-client :quelpa (matrix-client :fetcher github :repo "alphapapa/matrix-client.el" :files (:defaults "logo.png" "matrix-client-standalone.el.sh"))) #+END_SRC
After installation, upgrading can be done through =quelpa=, e.g. with [[https://github.com/alphapapa/unpackaged.el#upgrade-a-quelpa-use-package-forms-package][this command]].
** Manual installation
- Install all dependency packages, which are listed in the =Package-Requires= header in =matrix-client.el=.
- Put this repo's directory onto your
load-path, and veal(require 'matrix-client).
- Usage
If you don't already have a Matrix account, you can register on a [[https://www.hello-matrix.net/public_servers.php][public homeserver]] such as =matrix.org=. =matrix-client.el= doesn't currently support registration, but you can use another client like [[https://riot.im/app/#/register][Riot]] to register an account.
Then run the command matrix-client-connect or matrix-client-frame to connect. Customization options are available in the =matrix-client= group.
** Commands
- List room commands: =/help=
- Membership
- Join a room: =/join #room:server=
- Leave the current room: =/leave=
- List room users: =/who=
- Room settings
- Set room priority:
/priority - List or set user-tags: =/tags=
- Add user-tags: =/tag=
- Delete user-tags: =/untag=
- Set notification settings: =/notify=
- Note: Notification settings are local to Emacs and do not integrate with the API spec.
- Set room priority:
- Sending messages:
- Send Org-formatted messages: =/org=
-
Note: Sending Org-formatted messages is the default. You can disable it by changing the option
matrix-client-send-as-org-by-default, after which Org messages can be sent with the =/org= command. - You can send almost any Org syntax, including simple emphasis like bold and /italic/, one-line code blocks with =:= at the beginning of a line, code emphasis with =~=, even Org tables and complete =#+BEGIN_SRC lang ... #+END_SRC= blocks! Emacs will even send the code blocks colorized according to your theme, and other =matrix-client.el= users will see the colors!
- Press @@html:@@C-c '@@html:@@ (or whatever you may have bound =org-edit-special= to) to edit the current message in a dedicated Org buffer, then save it back to the room input line with @@html:@@C-x [email protected]@html:@@ (or whatever you may have bound =save-buffer= to).
-
Note: Sending Org-formatted messages is the default. You can disable it by changing the option
- Send unformatted messages: =/raw=
- When
matrix-client-send-as-org-by-defaultis enabled, this sends messages without Org formatting.
- When
- Send HTML messages: =/html=
- Send Org-formatted messages: =/org=
- Upload a file: =/upload PATH-OR-URL=, or drag-and-drop files or URLs onto the room buffer
- Enable pretty colors: =/rainbow=
- Other:
- Reply to messages: With point on a message, @@html:@@r@@html:@@, or @@html:@@[email protected]@html:@@ to reply with quote.
- Complete usernames and IDs: @@html:@@[email protected]@html:@@ (with point at prompt)
- Move point between messages: @@html:@@[email protected]@html:@@/@@html:@@[email protected]@html:@@
- Return point to input prompt: @@html:@@[email protected]@html:@@ (with point before prompt)
- Open room in a new frame: Middle-click or press @@html:@@@@html:@@ in the room list.
- Switch to the notifications buffer: @@html:@@C-c [email protected]@html:@@
- Show room list: =/rooms=
** Notifications buffer
The =Matrix Notifications= buffer displays notifications from all rooms, acting as a sort of meta-buffer. By setting a room's notifications to =always=, =silent=, or =silent-unless-mention=, you can monitor all messages from that room in the notifications buffer. Press @@html:@@C-c [email protected]@html:@@ from a room buffer to show the notifications buffer.
You can also reply to messages directly from the notifications buffer. Just as in a room's buffer, press @@html:@@[email protected]@html:@@/@@html:@@[email protected]@html:@@ to navigate between messages, then press @@html:@@r@@html:@@ on a message, type your reply, and send by pressing @@html:@@[email protected]@html:@@. Note that this only allows replies to messages; to send a non-reply message, do so from the room's buffer.
To jump to a message in the room's buffer, press @@html:@@[email protected]@html:@@ with point on the message.
Here's an example of following multiple, related conversations across multiple rooms in the notifications buffer:
[[images/notifications-buffer.png]]
** Room list
Open the room list by pressing @@html:@@C-c [email protected]@html:@@ or calling command =matrix-client-room-list=. Just like in the dedicated frame's room-list sidebar, you can click rooms to show their buffers, right-click rooms to change their settings, and middle-click rooms to open them in a new frame.
** Missing features
=matrix-client= is very usable, but it does not implement all Matrix features, so it may be necessary to perform some actions from Riot or another client.
- Invitations :: Room invitations are not currently supported, so they must be sent and accepted elsewhere (this could be fixed with a little work).
- Room encryption (E2EE) :: Room encryption is not supported, and it probably will not be supported natively, because =libolm= is not usable from Emacs. However, the [[https://github.com/matrix-org/pantalaimon][Pantalaimon]] E2EE proxy may be a good solution, and perhaps some integration for it could be added.
- Contributing
Contributions are welcome! Please feel free to submit an issue or pull request.
For discussion, feel free to join us in [[https://matrix.to/#/#matrix-client.el:matrix.org][#matrix-client.el:matrix.org]].
- Authors :PROPERTIES: :TOC: ignore :END:
- [[http://whatthefuck.computer/][Ryan Rix]]: The original author of =matrix-client=.
- [[https://github.com/alphapapa][Adam Porter]]: Rewrote most of the client and added new features.
- [[https://jgkamat.github.io/][Jay Kamat]]: Contributes maintenance and reviews.
- License :PROPERTIES: :TOC: ignore :END:
GPLv3.
- COMMENT Config :noexport: :PROPERTIES: :TOC: ignore :END:
** File-local variables