Good signature from 066DAFCB81E42C40 GNU ELPA Signing Agent (2019) <elpasign@elpa.gnu.org> (trust undefined) created at 2023-05-16T05:05:02-0400 using RSA

;;; Directory Local Variables
;;; For more information see (info "(emacs) Directory Variables")
((emacs-lisp-mode . ((fill-column . 90)
		     (indent-tabs-mode . nil))))

.github/
images/
LICENSE
Makefile
makem.sh
NOTES.org
screenshots/

# * test.yml --- Test Emacs packages using makem.sh on GitHub Actions
# URL: https://github.com/alphapapa/makem.sh
# Version: 0.4.2
# * Commentary:
# Based on Steve Purcell's examples at
# <https://github.com/purcell/setup-emacs/blob/master/.github/workflows/test.yml>,
# <https://github.com/purcell/package-lint/blob/master/.github/workflows/test.yml>.
# * License:
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
# You should have received a copy of the GNU General Public License
# along with this program.  If not, see <https://www.gnu.org/licenses/>.
# * Code:
name: "CI"
on:
  pull_request:
  push:
    # Comment out this section to enable testing of all branches.
    branches:
      - master
jobs:
  build:
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        emacs_version:
          - 26.3
          - 27.1
          - 28.2
          - snapshot
    steps:
    - uses: purcell/setup-emacs@master
      with:
        version: ${{ matrix.emacs_version }}
    - uses: actions/checkout@v2
    - name: Initialize sandbox
      run: |
        SANDBOX_DIR=$(mktemp -d) || exit 1
        echo "SANDBOX_DIR=$SANDBOX_DIR" >> $GITHUB_ENV
        ./makem.sh -vv --sandbox=$SANDBOX_DIR --install-deps --install-linters
    # The "all" rule is not used, because it treats compilation warnings
    # as failures, so linting and testing are run as separate steps.
    - name: Lint
      # NOTE: Uncomment this line to treat lint failures as passing
      #       so the job doesn't show failure.
      # continue-on-error: true
      run: ./makem.sh -vv --sandbox=$SANDBOX_DIR lint
    - name: Test
      if: always()  # Run test even if linting fails.
      run: ./makem.sh -vv --sandbox=$SANDBOX_DIR test
# Local Variables:
# eval: (outline-minor-mode)
# End:

			       ━━━━━━━━━━
				EMENT.EL
			       ━━━━━━━━━━
[https://elpa.gnu.org/packages/ement.svg]
Ement.el is a Matrix client for Emacs.  It aims to be simple, fast,
featureful, and reliable.
Feel free to join us in the chat room:
[https://img.shields.io/matrix/ement.el:matrix.org.svg?label=%23ement.el:matrix.org]
[https://elpa.gnu.org/packages/ement.svg]
<https://elpa.gnu.org/packages/ement.html>
[https://img.shields.io/matrix/ement.el:matrix.org.svg?label=%23ement.el:matrix.org]
<https://matrix.to/#/#ement.el:matrix.org>
1 Installation
══════════════
1.1 GNU ELPA
────────────
  Ement.el is published in [GNU ELPA], so it may be installed in Emacs
  with the command `M-x package-install RET ement RET'.  This is the
  recommended way to install Ement.el, as it will install the current
  stable release.
[GNU ELPA] <http://elpa.gnu.org/>
1.2 GNU Guix
────────────
  Ement.el is also available in [GNU Guix] as `emacs-ement'.
[GNU Guix] <https://guix.gnu.org/>
1.3 Debian
──────────
  Ement.el is also available in Debian as [elpa-ement].
[elpa-ement] <https://packages.debian.org/elpa-ement>
1.4 Git master
──────────────
  The `master' branch of the Git repository is intended to be usable at
  all times; only minor bugs are expected to be found in it before a new
  stable release is made.  To install from this, it is recommended to
  use [quelpa-use-package], like this:
  ┌────
  │ ;; Install and load `quelpa-use-package'.
  │ (package-install 'quelpa-use-package)
  │ (require 'quelpa-use-package)
  │ 
  │ ;; Install Ement.
  │ (use-package ement
  │   :quelpa (ement :fetcher github :repo "alphapapa/ement.el"))
  └────
  One might also use systems like [Straight] (which is also used by
  [DOOM]) to install from Git, but the author cannot offer support for
  them.
[quelpa-use-package] <https://github.com/quelpa/quelpa-use-package>
[Straight] <https://github.com/radian-software/straight.el>
[DOOM] <https://github.com/doomemacs/doomemacs>
1.5 Manual
──────────
  Ement.el is intended to be installed with Emacs's package system,
  which will ensure that the required autoloads are generated, etc.  If
  you choose to install it manually, you're on your own.
2 Usage
═══════
  • 
  • 
  • 
  1. Call command `ement-connect' to connect.  Multiple sessions are
     supported, so you may call the command again to connect to another
     account.
  2. Wait for initial sync to complete (which can take a few
     moments–initial sync JSON requests can be large).
  3. Use these commands (room-related commands may be called with
     universal prefix to prompt for the room):
     • `ement-list-rooms' to view the list of joined rooms.
     • `ement-view-room' to view a room's buffer, selected with
       completion.
     • `ement-create-room' to create a new room.
     • `ement-create-space' to create a space.
     • `ement-invite-user' to invite a user to a room.
     • `ement-join-room' to join a room.
     • `ement-leave-room' to leave a room.
     • `ement-forget-room' to forget a room.
     • `ement-tag-room' to toggle a tag on a room (including
       favorite/low-priority status).
     • `ement-list-members' to list members in a room.
     • `ement-send-direct-message' to send a direct message to a user
       (in an existing direct room, or creating a new one
       automatically).
     • `ement-room-edit-message' to edit a message at point.
     • `ement-room-send-file' to send a file.
     • `ement-room-send-image' to send an image.
     • `ement-room-set-topic' to set a room's topic.
     • `ement-room-occur' to search in a room's known events.
     • `ement-room-override-name' to override a room's display name.
     • `ement-ignore-user' to ignore a user (or with interactive prefix,
       un-ignore).
     • `ement-room-set-message-format' to set a room's message format
       buffer-locally.
     • `ement-room-toggle-space' to toggle a room's membership in a
       space (a way to group rooms in Matrix).
     • `ement-directory' to view a room directory.
     • `ement-directory-search' to search a room directory.
  4. Use these special buffers to see events from multiple rooms (you
     can also reply to messages from these buffers!):
     • See all new events that mention you in the `*Ement Mentions*'
       buffer.
     • See all new events in rooms that have open buffers in the `*Ement
       Notifications*' buffer.
2.1 Bindings
────────────
  These bindings are common to all of the following buffer types:
  ⁃ Switch to a room buffer: `M-g M-r'
  ⁃ Switch to the room list buffer: `M-g M-l'
  ⁃ Switch to the mentions buffer: `M-g M-m'
  ⁃ Switch to the notifications buffer: `M-g M-n'
2.1.1 Room buffers
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌
  ⁃ Show command menu: `?'
  *Movement*
  ⁃ Next event: `TAB'
  ⁃ Previous event: `<backtab>'
  ⁃ Scroll up and mark read: `SPC'
  ⁃ Scroll down: `S-SPC'
  ⁃ Jump to fully-read marker: `M-SPC'
  ⁃ Load older messages: at top of buffer, scroll contents up
    (i.e. `S-SPC', `M-v' or `mwheel-scroll')
  *Switching*
  ⁃ List rooms: `M-g M-l'
  ⁃ Switch to other room: `M-g M-r'
  ⁃ Switch to mentions buffer: `M-g M-m'
  ⁃ Switch to notifications buffer: `M-g M-n'
  ⁃ Quit window: `q'
  *Messages*
  ⁃ Write message: `RET'
  ⁃ Write reply to event at point (when region is active, only quote
    marked text) : `S-RET'
  ⁃ Compose message in buffer: `M-RET' (while writing in minibuffer:
    `C-c ')' (Use command `ement-room-compose-org' to activate Org mode
    in the compose buffer.)
  ⁃ Edit message: `<insert>'
  ⁃ Delete message: `C-k'
  ⁃ Send reaction to event at point, or send same reaction at point: `s
    r'
  ⁃ Send emote: `s e'
  ⁃ Send file: `s f'
  ⁃ Send image: `s i'
  ⁃ View event source: `v'
  ⁃ Complete members and rooms at point: `C-M-i' (standard
    `completion-at-point' command).  (Type an `@' prefix for a member
    mention, a `#' prefix for a room alias, or a `!' prefix for a room
    ID.)
  *Images*
  ⁃ Toggle scale of image (between fit-to-window and thumbnail):
    `mouse-1'
  ⁃ Show image in new buffer at full size: `double-mouse-1'
  *Users*
  ⁃ Send direct message: `u RET'
  ⁃ Invite user: `u i'
  ⁃ Ignore user: `u I'
  *Room*
  ⁃ Occur search in room: `M-s o'
  ⁃ List members: `r m'
  ⁃ Set topic: `r t'
  ⁃ Set message format: `r f'
  ⁃ Set notification rules: `r n'
  ⁃ Override display name: `r N'
  ⁃ Tag/untag room: `r T'
  *Room membership*
  ⁃ Create room: `R c'
  ⁃ Join room: `R j'
  ⁃ Leave room: `R l'
  ⁃ Forget room: `R F'
  ⁃ Toggle room's spaces: `R s'
  *Other*
  ⁃ Sync new messages (not necessary if auto sync is enabled; with
    prefix to force new sync): `g'
2.1.2 Room list buffer
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌
  ⁃ Show buffer of room at point: `RET'
  ⁃ Show buffer of next unread room: `SPC'
  ⁃ Move between room names: `TAB' / `<backtab>'
  ⁃ Kill room's buffer: `k'
  ⁃ Toggle room's membership in a space: `s'
2.1.3 Directory buffers
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌
  ⁃ View/join a room: `RET' / `mouse-1'
  ⁃ Load next batch of rooms: `+'
2.1.4 Mentions/notifications buffers
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌
  ⁃ Move between events: `TAB' / `<backtab>'
  ⁃ Go to event at point in its room buffer: `RET'
  ⁃ Write reply to event at point (shows the event in its room while
    writing) : `S-RET'
2.2 Tips
────────
  ⁃ Desktop notifications are enabled by default for events that mention
    the local user.  They can also be shown for all events in rooms with
    open buffers.
  ⁃ Send messages in Org mode format by customizing the option
    `ement-room-send-message-filter' (which enables Org format by
    default), or by calling `ement-room-compose-org' in a compose buffer
    (which enables it for a single message).  Then Org-formatted
    messages are automatically converted and sent as HTML-formatted
    messages (with the Org syntax as the plain-text fallback).  You can
    send syntax such as:
    • Bold, italic, underline, strikethrough
    • Links
    • Tables
    • Source blocks (including results with `:exports both')
    • Footnotes (okay, that might be pushing it, but you can!)
    • And, generally, anything that Org can export to HTML
  ⁃ Starting in the room list buffer, by pressing `SPC' repeatedly, you
    can cycle through and read all rooms with unread buffers.  (If a
    room doesn't have a buffer, it will not be included.)
  ⁃ Room buffers and the room-list buffer can be bookmarked in Emacs,
    i.e. using `C-x r m'.  This is especially useful with [Burly]: you
    can arrange an Emacs frame with several room buffers displayed at
    once, use `burly-bookmark-windows' to bookmark the layout, and then
    you can restore that layout and all of the room buffers by opening
    the bookmark, rather than having to manually arrange them every time
    you start Emacs or change the window configuration.
  ⁃ Images and other files can be uploaded to rooms using drag-and-drop.
  ⁃ Mention members by typing a `@' followed by their displayname or
    Matrix ID.  (Members' names and rooms' aliases/IDs may be completed
    with `completion-at-point' commands.)
  ⁃ You can customize settings in the `ement' group.
    • *Note:* `setq' should not be used for certain options, because it
       will not call the associated setter function.  Users who have an
       aversion to the customization system may experience problems.
[Burly] <https://github.com/alphapapa/burly.el>
2.2.1 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)
  └────
[this question and answer]
<https://emacs.stackexchange.com/questions/62049/override-the-default-font-for-emoji-characters>
[Noto Emoji] <https://www.google.com/get/noto/#emoji-zsye>
2.3 Encrypted room support through Pantalaimon
──────────────────────────────────────────────
  Ement.el doesn't support encrypted rooms natively, but it can be used
  transparently with the E2EE-aware reverse proxy daemon [Pantalaimon].
  After configuring it according to its documentation, call
  `ement-connect' with the appropriate hostname and port, like:
  ┌────
  │ (ement-connect :uri-prefix "http://localhost:8009")
  └────
[Pantalaimon] <https://github.com/matrix-org/pantalaimon/>
3 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' does not use Matrix's lazy-loading feature (which
    was added to the specification later), so initial sync requests can
    take a long time for the server to process and can be large
    (sometimes tens of megabytes of JSON for the client to process!).
    Ement.el uses lazy-loading, which significantly improves
    performance.
  • `matrix-client' automatically makes buffers for every room a user
    has joined, even if the user doesn't currently want to watch a room.
    Ement.el opens room buffers on-demand, improving performance by not
    having to insert events into buffers for rooms the user isn't
    watching.
  • `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.
  Note that, while `matrix-client' remains usable, and probably will for
  some time to come, Ement.el has now surpassed it in every way.  The
  only reason to choose `matrix-client' instead is if one is using an
  older version of Emacs that isn't supported by Ement.el.
[matrix-client.el] <https://github.com/alphapapa/matrix-client.el>
[makem.sh] <https://github.com/alphapapa/makem.sh>
4 Changelog
═══════════
4.1 0.9.2
─────────
  *Fixes*
  ⁃ Restore position in room list when refreshing.
  ⁃ Completion in minibuffer.
4.2 0.9.1
─────────
  *Fixes*
  ⁃ Error in `ement-room-list' command upon initial sync.
4.3 0.9
───────
  *Additions*
  ⁃ Option `ement-room-timestamp-header-align' controls how timestamp
    headers are aligned in room buffers.
  ⁃ Option `ement-room-view-hook' runs functions when `ement-room-view'
    is called.  (By default, it refreshes the room list buffer.)
  ⁃ In the room list, middle-clicking a room which has a buffer closes
    its buffer.
  ⁃ Basic support for video events.  (Thanks to [Arto Jantunen].)
  *Changes*
  ⁃ Using new option `ement-room-timestamp-header-align', timestamp
    headers default to right-aligned.  (With default settings, this
    keeps them near message timestamps and makes for a cleaner
    appearance.)
  *Fixes*
  ⁃ Recognition of certain MXID or displayname forms in outgoing
    messages when linkifying (aka "pilling") them.
  ⁃ Unreadable room avatar images no longer cause errors.  (Fixes
    [#147].  Thanks to [@jgarte] for reporting.)
  ⁃ Don't error in `ement-room-list' when no rooms are joined.  (Fixes
    [#123].  Thanks to [@Kabouik] and [Omar Antolín Camarena] for
    reporting.)
  ⁃ Enable member/room completion in compose buffers.  (Fixes [#115].
    Thanks to Thanks to [Justus Piater] and [Caleb Chase] for
    reporting.)
[Arto Jantunen] <https://github.com/viiru->
[#147] <https://github.com/alphapapa/ement.el/issues/147>
[@jgarte] <https://github.com/jgarte>
[#123] <https://github.com/alphapapa/ement.el/issues/123>
[@Kabouik] <https://github.com/Kabouik>
[Omar Antolín Camarena] <https://github.com/oantolin>
[#115] <https://github.com/alphapapa/ement.el/issues/115>
[Justus Piater] <https://github.com/piater>
[Caleb Chase] <https://github.com/chasecaleb>
4.4 0.8.3
─────────
  *Fixes*
  ⁃ Avoid use of `pcase''s `(map :KEYWORD)' form.  (This can cause a
    broken installation on older versions of Emacs that have an older
    version of the `map' library loaded, such as Emacs 27.2 included in
    Debian 11.  Since there's no way to force Emacs to actually load the
    version of `map' required by this package before installing it
    (which would naturally happen upon restarting Emacs), we can only
    avoid using such forms while these versions of Emacs are widely
    used.)
4.5 0.8.2
─────────
  *Fixes*
  ⁃ Deduplicate grouped membership events.
4.6 0.8.1
─────────
  Added missing changelog entry (of course).
4.7 0.8
───────
  *Additions*
  ⁃ Command `ement-create-space' creates a new space.
  ⁃ Command `ement-room-toggle-space' toggles a room's membership in a
    space (a way to group rooms in Matrix).
  ⁃ Visibility of sections in the room list is saved across sessions.
  ⁃ Command `ement-room-list-kill-buffer' kills a room's buffer from the
    room list.
  ⁃ Set `device_id' and `initial_device_display_name' upon login
    (e.g. `Ement.el: username@hostname').  ([#134].  Thanks to [Arto
    Jantunen] for reporting.)
  *Changes*
  ⁃ Room-related commands may be called interactively with a universal
    prefix to prompt for the room/session (allowing to send events or
    change settings in rooms other than the current one).
  ⁃ Command `ement-room-list' reuses an existing window showing the room
    list when possible.  ([#131].  Thanks to [Jeff Bowman] for
    suggesting.)
  ⁃ Command `ement-tag-room' toggles tags (rather than adding by default
    and removing when called with a prefix).
  ⁃ Default room grouping now groups "spaced" rooms separately.
  *Fixes*
  ⁃ Message format filter works properly when writing replies.
  ⁃ Improve insertion of sender name headers when using the "Elemental"
    message format.
  ⁃ Prompts in commands `ement-leave-room' and `ement-forget-room'.
[#134] <https://github.com/alphapapa/ement.el/issues/134>
[Arto Jantunen] <https://github.com/viiru->
[#131] <https://github.com/alphapapa/ement.el/issues/131>
[Jeff Bowman] <https://github.com/jeffbowman>
4.8 0.7
───────
  *Additions*
  ⁃ Command `ement-room-override-name' sets a local override for a
    room's display name.  (Especially helpful for 1:1 rooms and bridged
    rooms.  See [MSC3015].)
  *Changes*
  ⁃ Improve display of room tombstones (displayed at top and bottom of
    buffer, and new room ID is linked to join).
  ⁃ Use descriptive prompts in `ement-leave-room' and
    `ement-forget-room' commands.
  *Fixes*
  ⁃ Command `ement-view-space' when called from a room buffer.  (Thanks
    to [Richard Brežák] for reporting.)
  ⁃ Don't call `display-buffer' when reverting room list buffer.  (Fixes
    [#121].  Thanks to [mekeor] for reporting.)
  ⁃ Retry sync for network timeouts.  (Accidentally broken in v0.6.)
  *Internal*
  ⁃ Function `ement-put-account-data' accepts `:room' argument to put on
    a room's account data.
[MSC3015]
<https://github.com/matrix-org/matrix-spec-proposals/pull/3015#issuecomment-1451017296>
[Richard Brežák] <https://github.com/MagicRB>
[#121] <https://github.com/alphapapa/ement.el/issues/121>
[mekeor] <https://github.com/mekeor>
4.9 0.6
───────
  *Additions*
  ⁃ Command `ement-view-space' to view a space's rooms in a directory
    buffer.
  *Changes*
  ⁃ Improve `ement-describe-room' command (formatting, bindings).
  *Fixes*
  ⁃ Retry sync for HTTP 502 "Bad Gateway" errors.
  ⁃ Formatting of unban events.
  ⁃ Update password authentication according to newer Matrix spec.
    (Fixes compatibility with Conduit servers.  [#66].  Thanks to
    [Travis Peacock], [Arto Jantunen], and [Stephen D].)
  ⁃ Image scaling issues.  (Thanks to [Visuwesh].)
[#66] <https://github.com/alphapapa/ement.el/issues/66>
[Travis Peacock] <https://github.com/tpeacock19>
[Arto Jantunen] <https://github.com/viiru->
[Stephen D] <https://github.com/scd31>
[Visuwesh] <https://github.com/vizs>
4.10 0.5.2
──────────
  *Fixes*
  ⁃ Apply `ement-initial-sync-timeout' properly (important for when the
    homeserver is slow to respond).
4.11 0.5.1
──────────
  *Fixes*
  ⁃ Autoload `ement-directory' commands.
  ⁃ Faces in `ement-directory' listings.
4.12 0.5
────────
  *Additions*
  ⁃ Present "joined-and-left" and "rejoined-and-left" membership event
    pairs as such.
  ⁃ Process and show rooms' canonical alias events.
  *Changes*
  ⁃ The [taxy.el]-based room list, with programmable, smart grouping, is
    now the default `ement-room-list'.  (The old,
    `tabulated-list-mode'-based room list is available as
    `ement-tabulated-room-list'.)
  ⁃ When selecting a room to view with completion, don't offer spaces.
  ⁃ When selecting a room with completion, empty aliases and topics are
    omitted instead of being displayed as nil.
  *Fixes*
  ⁃ Use of send-message filter when replying.
  ⁃ Replies may be written in compose buffers.
[taxy.el] <https://github.com/alphapapa/taxy.el>
4.13 0.4.1
──────────
  *Fixes*
  ⁃ Don't show "curl process interrupted" message when updating a read
    marker's position again.
4.14 0.4
────────
  *Additions*
  ⁃ Option `ement-room-unread-only-counts-notifications', now enabled by
    default, causes rooms' unread status to be determined only by their
    notification counts (which are set by the server and depend on
    rooms' notification settings).
  ⁃ Command `ement-room-set-notification-state' sets a room's
    notification state (imitating Element's user-friendly presets).
  ⁃ Room buffers' Transient menus show the room's notification state
    (imitating Element's user-friendly presets).
  ⁃ Command `ement-set-display-name' sets the user's global displayname.
  ⁃ Command `ement-room-set-display-name' sets the user's displayname in
    a room (which is also now displayed in the room's Transient menu).
  ⁃ Column `Notifications' in the `ement-taxy-room-list' buffer shows
    rooms' notification state.
  ⁃ Option `ement-interrupted-sync-hook' allows customization of how
    sync interruptions are handled.  (Now, by default, a warning is
    displayed instead of merely a message.)
  *Changes*
  ⁃ When a room's read receipt is updated, the room's buffer is also
    marked as unmodified.  (In concert with the new option, this makes
    rooms' unread status more intuitive.)
  *Fixes*
  ⁃ Binding of command `ement-forget-room' in room buffers.
  ⁃ Highlighting of `@room' mentions.
4.15 0.3.1
──────────
  *Fixes*
  ⁃ Room unread status (when the last event in a room is sent by the
    local user, the room is considered read).
4.16 0.3
────────
  *Additions*
  ⁃ Command `ement-directory' shows a server's room directory.
  ⁃ Command `ement-directory-search' searches a server's room directory.
  ⁃ Command `ement-directory-next' fetches the next batch of rooms in a
    directory.
  ⁃ Command `ement-leave-room' accepts a `FORCE-P' argument
    (interactively, with prefix) to leave a room without prompting.
  ⁃ Command `ement-forget-room' accepts a `FORCE-P' argument
    (interactively, with prefix) to also leave the room, and to forget
    it without prompting.
  ⁃ Option `ement-notify-mark-frame-urgent-predicates' marks the frame
    as urgent when (by default) a message mentions the local user or
    "@room" and the message's room has an open buffer.
  *Changes*
  ⁃ Minor improvements to date/time headers.
  *Fixes*
  ⁃ Command `ement-describe-room' for rooms without topics.
  ⁃ Improve insertion of old messages around existing timestamp headers.
  ⁃ Reduce D-Bus notification system check timeout to 2 seconds (from
    the default of 25).
  ⁃ Compatibility with Emacs 27.
4.17 0.2.1
──────────
  *Fixes*
  ⁃ Info manual export filename.
4.18 0.2
────────
  *Changes*
  ⁃ Read receipts are re-enabled.  (They're now implemented with a
    global idle timer rather than `window-scroll-functions', which
    sometimes caused a strange race condition that could cause Emacs to
    become unresponsive or crash.)
  ⁃ When determining whether a room is considered unread, non-message
    events like membership changes, reactions, etc. are ignored.  This
    fixes a bug that caused certain rooms that had no message events
    (like some bridged rooms) to appear as unread when they shouldn't
    have.  But it's unclear whether this is always preferable (e.g. one
    might want a member leaving a room to cause it to be marked unread),
    so this is classified as a change rather than simply a fix, and more
    improvements may be made to this in the future.  (Fixes [#97].
    Thanks to [Julien Roy] for reporting and testing.)
  ⁃ The `ement-taxy-room-list' view no longer automatically refreshes
    the list if the region is active in the buffer.  (This allows the
    user to operate on multiple rooms without the contents of the buffer
    changing before completing the process.)
  *Fixes*
  ⁃ Links to only rooms (as opposed to links to events in rooms) may be
    activated to join them.
  ⁃ Read receipts mark the last completely visible event (rather than
    one that's only partially displayed).
  ⁃ Prevent error when a room avatar image fails to load.
[#97] <https://github.com/alphapapa/ement.el/issues/97>
[Julien Roy] <https://github.com/MrRoy>
4.19 0.1.4
──────────
  *Fixed*
  ⁃ Info manual directory headers.
4.20 0.1.3
──────────
  *Fixed*
  ⁃ Temporarily disable sending of read receipts due to an unusual bug
    that could cause Emacs to become unresponsive.  (The feature will be
    re-enabled in a future release.)
4.21 0.1.2
──────────
  *Fixed*
  ⁃ Function `ement-room-sync' correctly updates room-list buffers.
    (Thanks to [Visuwesh].)
  ⁃ Only send D-Bus notifications when supported.  (Fixes [#83].  Thanks
    to [Tassilo Horn].)
[Visuwesh] <https://github.com/vizs>
[#83] <https://github.com/alphapapa/ement.el/issues/83>
[Tassilo Horn] <https://github.com/tsdh>
4.22 0.1.1
──────────
  *Fixed*
  ⁃ Function `ement-room-scroll-up-mark-read' selects the correct room
    window.
  ⁃ Option `ement-room-list-avatars' defaults to what function
    `display-images-p' returns.
4.23 0.1
────────
  After almost two years of development, the first tagged release.
  Submitted to GNU ELPA.
5 Development
═════════════
  Bug reports, feature requests, suggestions — /oh my/!
5.1 Copyright Assignment
────────────────────────
  Ement.el is published in GNU ELPA and is considered part of GNU Emacs.
  Therefore, cumulative contributions of more than 15 lines of code
  require that the author assign copyright of such contributions to the
  FSF.  Authors who are interested in doing so may contact
  [assign@gnu.org] to request the appropriate form.
[assign@gnu.org] <mailto:assign@gnu.org>
5.2 Matrix spec in Org format
─────────────────────────────
  An Org-formatted version of the Matrix spec is available in the
  [meta/spec] branch.
[meta/spec] <https://github.com/alphapapa/ement.el/tree/meta/spec>
6 License
═════════
  GPLv3

#+TITLE: Ement.el
#+PROPERTY: LOGGING nil
# Export options.
#+OPTIONS: broken-links:t *:t
# Info export options.
#+EXPORT_FILE_NAME: ement.texi
#+TEXINFO_DIR_CATEGORY: Emacs
#+TEXINFO_DIR_TITLE: Ement: (ement)
#+TEXINFO_DIR_DESC: Matrix client for Emacs
# Note: This readme works with the org-make-toc <https://github.com/alphapapa/org-make-toc> package, which automatically updates the table of contents.
#+HTML: <img src="images/logo-128px.png" align="right">
# ELPA badge image.
[[https://elpa.gnu.org/packages/ement.html][https://elpa.gnu.org/packages/ement.svg]]
Ement.el is a Matrix client for Emacs.  It aims to be simple, fast, featureful, and reliable.
Feel free to join us in the chat room: [[https://matrix.to/#/#ement.el:matrix.org][https://img.shields.io/matrix/ement.el:matrix.org.svg?label=%23ement.el:matrix.org]]
* Contents                                                         :noexport:
:PROPERTIES:
:TOC:      :include siblings
:END:
:CONTENTS:
- [[#installation][Installation]]
- [[#usage][Usage]]
  - [[#bindings][Bindings]]
  - [[#tips][Tips]]
  - [[#encrypted-room-support-through-pantalaimon][Encrypted room support through Pantalaimon]]
- [[#rationale][Rationale]]
- [[#changelog][Changelog]]
- [[#development][Development]]
:END:
* Screenshots                                                      :noexport:
:PROPERTIES:
:ID:       d818f690-5f22-4eb0-83e1-4d8ce16c9e5b
:END:
The default formatting style resembles IRC clients, with each message being prefixed by the username (which enables powerful Emacs features, like using Occur to show all messages from or mentioning a user).  Alternative, built-in styles include an Element-like one with usernames above groups of messages, as well as a classic, no-margins IRC style.  Messages may be optionally displayed with unique colors for each user (with customizeable contrast), making it easier to follow conversations.  Timestamp headers are optionally displayed where a certain amount of time passes between events, as well as where the date changes.
[[images/ement-for-twim.png]]
/Two rooms shown in side-by-side buffers, showing inline images, reactions, date/time headings, room avatars, and messages colored by user (using the modus-vivendi Emacs theme)./
[[images/emacs-with-fully-read-line.png]]
/#emacs:libera.chat showing colored text from IRC users, replies with quoted parts, messages colored by user, addressed usernames colored by their user color, highlighted mentions, and the fully-read marker line (using the modus-vivendi Emacs theme)./
[[images/screenshot5.png]]
/Four rooms shown at once, with messages colored by user, in the default Emacs theme./
[[images/screenshot2.png]]
/A room at the top in the "Elemental" display style, with sender names displayed over groups of messages, and only self-messages in an alternate color.  The lower window shows an earlier version of the rooms list./
[[images/reactions.png]]
/Reactions displayed as color emojis (may need [[#displaying-symbols-and-emojis][proper Emacs configuration]])./
* Installation
:PROPERTIES:
:TOC:      :depth 0
:END:
** GNU ELPA
Ement.el is published in [[http://elpa.gnu.org/][GNU ELPA]], so it may be installed in Emacs with the command ~M-x package-install RET ement RET~.  This is the recommended way to install Ement.el, as it will install the current stable release.
** GNU Guix
Ement.el is also available in [[https://guix.gnu.org/][GNU Guix]] as ~emacs-ement~.
** Debian
Ement.el is also available in Debian as [[https://packages.debian.org/elpa-ement][elpa-ement]].
** Git master
The ~master~ branch of the Git repository is intended to be usable at all times; only minor bugs are expected to be found in it before a new stable release is made.  To install from this, it is recommended to use [[https://github.com/quelpa/quelpa-use-package][quelpa-use-package]], like this:
#+BEGIN_SRC elisp
  ;; Install and load `quelpa-use-package'.
  (package-install 'quelpa-use-package)
  (require 'quelpa-use-package)
  ;; Install Ement.
  (use-package ement
    :quelpa (ement :fetcher github :repo "alphapapa/ement.el"))
#+END_SRC
One might also use systems like [[https://github.com/radian-software/straight.el][Straight]] (which is also used by [[https://github.com/doomemacs/doomemacs][DOOM]]) to install from Git, but the author cannot offer support for them.
** Manual
Ement.el is intended to be installed with Emacs's package system, which will ensure that the required autoloads are generated, etc.  If you choose to install it manually, you're on your own.
* Usage
:PROPERTIES:
:TOC:      :include descendants :depth 1
:END:
:CONTENTS:
- [[#bindings][Bindings]]
- [[#tips][Tips]]
- [[#encrypted-room-support-through-pantalaimon][Encrypted room support through Pantalaimon]]
:END:
1. Call command ~ement-connect~ to connect.  Multiple sessions are supported, so you may call the command again to connect to another account.
2. Wait for initial sync to complete (which can take a few moments--initial sync JSON requests can be large).
3. Use these commands (room-related commands may be called with universal prefix to prompt for the room):
   - ~ement-list-rooms~ to view the list of joined rooms.
   - ~ement-view-room~ to view a room's buffer, selected with completion.
   - ~ement-create-room~ to create a new room.
   - ~ement-create-space~ to create a space.
   - ~ement-invite-user~ to invite a user to a room.
   - ~ement-join-room~ to join a room.
   - ~ement-leave-room~ to leave a room.
   - ~ement-forget-room~ to forget a room.
   - ~ement-tag-room~ to toggle a tag on a room (including favorite/low-priority status).
   - ~ement-list-members~ to list members in a room.
   - ~ement-send-direct-message~ to send a direct message to a user (in an existing direct room, or creating a new one automatically).
   - ~ement-room-edit-message~ to edit a message at point.
   - ~ement-room-send-file~ to send a file.
   - ~ement-room-send-image~ to send an image.
   - ~ement-room-set-topic~ to set a room's topic.
   - ~ement-room-occur~ to search in a room's known events.
   - ~ement-room-override-name~ to override a room's display name.
   - ~ement-ignore-user~ to ignore a user (or with interactive prefix, un-ignore).
   - ~ement-room-set-message-format~ to set a room's message format buffer-locally.
   - ~ement-room-toggle-space~ to toggle a room's membership in a space (a way to group rooms in Matrix).
   - ~ement-directory~ to view a room directory.
   - ~ement-directory-search~ to search a room directory.
4. Use these special buffers to see events from multiple rooms (you can also reply to messages from these buffers!):
   - See all new events that mention you in the =*Ement Mentions*= buffer.
   - See all new events in rooms that have open buffers in the =*Ement Notifications*= buffer.
** Bindings
These bindings are common to all of the following buffer types:
+ Switch to a room buffer: ~M-g M-r~
+ Switch to the room list buffer: ~M-g M-l~
+ Switch to the mentions buffer: ~M-g M-m~
+ Switch to the notifications buffer: ~M-g M-n~
*** Room buffers
+ Show command menu: ~?~
[[images/transient.png]]
*Movement*
+ Next event: ~TAB~
+ Previous event: ~<backtab>~
+ Scroll up and mark read: ~SPC~
+ Scroll down: ~S-SPC~
+ Jump to fully-read marker: ~M-SPC~
+ Load older messages: at top of buffer, scroll contents up (i.e. ~S-SPC~, ~M-v~ or ~mwheel-scroll~)
*Switching*
+ List rooms: ~M-g M-l~
+ Switch to other room: ~M-g M-r~
+ Switch to mentions buffer: ~M-g M-m~
+ Switch to notifications buffer: ~M-g M-n~
+ Quit window: ~q~
*Messages*
+ Write message: ~RET~
+ Write reply to event at point (when region is active, only quote marked text) : ~S-RET~
+ Compose message in buffer: ~M-RET~ (while writing in minibuffer: ~C-c ')~ (Use command ~ement-room-compose-org~ to activate Org mode in the compose buffer.)
+ Edit message: ~<insert>~
+ Delete message: ~C-k~
+ Send reaction to event at point, or send same reaction at point: ~s r~
+ Send emote: ~s e~
+ Send file: ~s f~
+ Send image: ~s i~
+ View event source: ~v~
+ Complete members and rooms at point: ~C-M-i~ (standard ~completion-at-point~ command).  (Type an ~@~ prefix for a member mention, a ~#~ prefix for a room alias, or a ~!~ prefix for a room ID.)
*Images*
+  Toggle scale of image (between fit-to-window and thumbnail): ~mouse-1~
+  Show image in new buffer at full size: ~double-mouse-1~
*Users*
+ Send direct message: ~u RET~
+ Invite user: ~u i~
+ Ignore user: ~u I~
*Room*
+ Occur search in room: ~M-s o~
+ List members: ~r m~
+ Set topic: ~r t~
+ Set message format: ~r f~
+ Set notification rules: ~r n~
+ Override display name: ~r N~
+ Tag/untag room: ~r T~
*Room membership*
+ Create room: ~R c~
+ Join room: ~R j~
+ Leave room: ~R l~
+ Forget room: ~R F~
+ Toggle room's spaces: ~R s~
*Other*
+ Sync new messages (not necessary if auto sync is enabled; with prefix to force new sync): ~g~
*** Room list buffer
+ Show buffer of room at point: ~RET~
+ Show buffer of next unread room: ~SPC~
+ Move between room names: ~TAB~ / ~<backtab>~
+ Kill room's buffer: ~k~
+ Toggle room's membership in a space: ~s~
*** Directory buffers
+ View/join a room: ~RET~ / ~mouse-1~
+ Load next batch of rooms: ~+~
*** Mentions/notifications buffers
+ Move between events: ~TAB~ / ~<backtab>~
+ Go to event at point in its room buffer: ~RET~
+ Write reply to event at point (shows the event in its room while writing) : ~S-RET~
** Tips
# TODO: Show sending messages in Org format.
+ Desktop notifications are enabled by default for events that mention the local user.  They can also be shown for all events in rooms with open buffers.
+ Send messages in Org mode format by customizing the option ~ement-room-send-message-filter~ (which enables Org format by default), or by calling ~ement-room-compose-org~ in a compose buffer (which enables it for a single message).  Then Org-formatted messages are automatically converted and sent as HTML-formatted messages (with the Org syntax as the plain-text fallback).  You can send syntax such as:
  - Bold, italic, underline, strikethrough
  - Links
  - Tables
  - Source blocks (including results with ~:exports both~)
  - Footnotes (okay, that might be pushing it, but you can!)
  - And, generally, anything that Org can export to HTML
+ Starting in the room list buffer, by pressing ~SPC~ repeatedly, you can cycle through and read all rooms with unread buffers.  (If a room doesn't have a buffer, it will not be included.)
+ Room buffers and the room-list buffer can be bookmarked in Emacs, i.e. using =C-x r m=.  This is especially useful with [[https://github.com/alphapapa/burly.el][Burly]]: you can arrange an Emacs frame with several room buffers displayed at once, use =burly-bookmark-windows= to bookmark the layout, and then you can restore that layout and all of the room buffers by opening the bookmark, rather than having to manually arrange them every time you start Emacs or change the window configuration.
+ Images and other files can be uploaded to rooms using drag-and-drop.
+ Mention members by typing a ~@~ followed by their displayname or Matrix ID.  (Members' names and rooms' aliases/IDs may be completed with ~completion-at-point~ commands.)
+ You can customize settings in the ~ement~ group.
  - *Note:* ~setq~ should not be used for certain options, because it will not call the associated setter function.  Users who have an aversion to the customization system may experience problems.
*** Displaying symbols and emojis
Emacs may not display certain symbols and emojis well by default.  Based on [[https://emacs.stackexchange.com/questions/62049/override-the-default-font-for-emoji-characters][this question and answer]], you may find that the simplest way to fix this is to install an appropriate font, like [[https://www.google.com/get/noto/#emoji-zsye][Noto Emoji]], and then use this Elisp code:
#+BEGIN_SRC elisp
  (setf use-default-font-for-symbols nil)
  (set-fontset-font t 'unicode "Noto Emoji" nil 'append)
#+END_SRC
** Encrypted room support through Pantalaimon
Ement.el doesn't support encrypted rooms natively, but it can be used transparently with the E2EE-aware reverse proxy daemon [[https://github.com/matrix-org/pantalaimon/][Pantalaimon]].  After configuring it according to its documentation, call ~ement-connect~ with the appropriate hostname and port, like:
#+BEGIN_SRC elisp
  (ement-connect :uri-prefix "http://localhost:8009")
#+END_SRC
* Rationale
Why write a new Emacs Matrix client when there is already [[https://github.com/alphapapa/matrix-client.el][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~ does not use Matrix's lazy-loading feature (which was added to the specification later), so initial sync requests can take a long time for the server to process and can be large (sometimes tens of megabytes of JSON for the client to process!).  Ement.el uses lazy-loading, which significantly improves performance.
- ~matrix-client~ automatically makes buffers for every room a user has joined, even if the user doesn't currently want to watch a room.  Ement.el opens room buffers on-demand, improving performance by not having to insert events into buffers for rooms the user isn't watching.
- ~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 [[https://github.com/alphapapa/makem.sh][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.
Note that, while ~matrix-client~ remains usable, and probably will for some time to come, Ement.el has now surpassed it in every way.  The only reason to choose ~matrix-client~ instead is if one is using an older version of Emacs that isn't supported by Ement.el.
* Changelog
:PROPERTIES:
:TOC:      :depth 0
:END:
** 0.9.2
*Fixes*
+ Restore position in room list when refreshing.
+ Completion in minibuffer.
** 0.9.1
*Fixes*
+ Error in ~ement-room-list~ command upon initial sync.
** 0.9
*Additions*
+ Option ~ement-room-timestamp-header-align~ controls how timestamp headers are aligned in room buffers.
+ Option ~ement-room-view-hook~ runs functions when ~ement-room-view~ is called.  (By default, it refreshes the room list buffer.)
+ In the room list, middle-clicking a room which has a buffer closes its buffer.
+ Basic support for video events.  (Thanks to [[https://github.com/viiru-][Arto Jantunen]].)
*Changes*
+ Using new option ~ement-room-timestamp-header-align~, timestamp headers default to right-aligned.  (With default settings, this keeps them near message timestamps and makes for a cleaner appearance.)
*Fixes*
+ Recognition of certain MXID or displayname forms in outgoing messages when linkifying (aka "pilling") them.
+ Unreadable room avatar images no longer cause errors.  (Fixes [[https://github.com/alphapapa/ement.el/issues/147][#147]].  Thanks to [[https://github.com/jgarte][@jgarte]] for reporting.)
+ Don't error in ~ement-room-list~ when no rooms are joined.  (Fixes [[https://github.com/alphapapa/ement.el/issues/123][#123]].  Thanks to [[https://github.com/Kabouik][@Kabouik]] and [[https://github.com/oantolin][Omar Antolín Camarena]] for reporting.)
+ Enable member/room completion in compose buffers.  (Fixes [[https://github.com/alphapapa/ement.el/issues/115][#115]].  Thanks to Thanks to [[https://github.com/piater][Justus Piater]] and [[https://github.com/chasecaleb][Caleb Chase]] for reporting.)
** 0.8.3
*Fixes*
+ Avoid use of ~pcase~'s ~(map :KEYWORD)~ form.  (This can cause a broken installation on older versions of Emacs that have an older version of the ~map~ library loaded, such as Emacs 27.2 included in Debian 11.  Since there's no way to force Emacs to actually load the version of ~map~ required by this package before installing it (which would naturally happen upon restarting Emacs), we can only avoid using such forms while these versions of Emacs are widely used.)
** 0.8.2
*Fixes*
+ Deduplicate grouped membership events.
** 0.8.1
Added missing changelog entry (of course).
** 0.8
*Additions*
+ Command ~ement-create-space~ creates a new space.
+ Command ~ement-room-toggle-space~ toggles a room's membership in a space (a way to group rooms in Matrix).
+ Visibility of sections in the room list is saved across sessions.
+ Command ~ement-room-list-kill-buffer~ kills a room's buffer from the room list.
+ Set ~device_id~ and ~initial_device_display_name~ upon login (e.g. =Ement.el: username@hostname=).  ([[https://github.com/alphapapa/ement.el/issues/134][#134]].  Thanks to [[https://github.com/viiru-][Arto Jantunen]] for reporting.)
*Changes*
+ Room-related commands may be called interactively with a universal prefix to prompt for the room/session (allowing to send events or change settings in rooms other than the current one).
+ Command ~ement-room-list~ reuses an existing window showing the room list when possible.  ([[https://github.com/alphapapa/ement.el/issues/131][#131]].  Thanks to [[https://github.com/jeffbowman][Jeff Bowman]] for suggesting.)
+ Command ~ement-tag-room~ toggles tags (rather than adding by default and removing when called with a prefix).
+ Default room grouping now groups "spaced" rooms separately.
*Fixes*
+ Message format filter works properly when writing replies.
+ Improve insertion of sender name headers when using the "Elemental" message format.
+ Prompts in commands ~ement-leave-room~ and ~ement-forget-room~.
** 0.7
*Additions*
+ Command ~ement-room-override-name~ sets a local override for a room's display name.  (Especially helpful for 1:1 rooms and bridged rooms.  See [[https://github.com/matrix-org/matrix-spec-proposals/pull/3015#issuecomment-1451017296][MSC3015]].)
*Changes*
+ Improve display of room tombstones (displayed at top and bottom of buffer, and new room ID is linked to join).
+ Use descriptive prompts in ~ement-leave-room~ and ~ement-forget-room~ commands.
*Fixes*
+ Command ~ement-view-space~ when called from a room buffer.  (Thanks to [[https://github.com/MagicRB][Richard Brežák]] for reporting.)
+ Don't call ~display-buffer~ when reverting room list buffer.  (Fixes [[https://github.com/alphapapa/ement.el/issues/121][#121]].  Thanks to [[https://github.com/mekeor][mekeor]] for reporting.)
+ Retry sync for network timeouts.  (Accidentally broken in v0.6.) 
*Internal*
+ Function ~ement-put-account-data~ accepts ~:room~ argument to put on a room's account data.
** 0.6
*Additions*
+ Command ~ement-view-space~ to view a space's rooms in a directory buffer.
*Changes*
+ Improve ~ement-describe-room~ command (formatting, bindings).
*Fixes*
+ Retry sync for HTTP 502 "Bad Gateway" errors.
+ Formatting of unban events.
+ Update password authentication according to newer Matrix spec.  (Fixes compatibility with Conduit servers.  [[https://github.com/alphapapa/ement.el/issues/66][#66]].  Thanks to [[https://github.com/tpeacock19][Travis Peacock]], [[https://github.com/viiru-][Arto Jantunen]], and [[https://github.com/scd31][Stephen D]].)
+ Image scaling issues.  (Thanks to [[https://github.com/vizs][Visuwesh]].)
** 0.5.2
*Fixes*
+ Apply ~ement-initial-sync-timeout~ properly (important for when the homeserver is slow to respond).
** 0.5.1
*Fixes*
+ Autoload ~ement-directory~ commands.
+ Faces in ~ement-directory~ listings.
** 0.5
*Additions*
+ Present "joined-and-left" and "rejoined-and-left" membership event pairs as such.
+ Process and show rooms' canonical alias events.
*Changes*
+ The [[https://github.com/alphapapa/taxy.el][taxy.el]]-based room list, with programmable, smart grouping, is now the default ~ement-room-list~.  (The old, ~tabulated-list-mode~-based room list is available as ~ement-tabulated-room-list~.)
+ When selecting a room to view with completion, don't offer spaces.
+ When selecting a room with completion, empty aliases and topics are omitted instead of being displayed as nil.
*Fixes*
+ Use of send-message filter when replying.
+ Replies may be written in compose buffers.
** 0.4.1
*Fixes*
+ Don't show "curl process interrupted" message when updating a read marker's position again.
** 0.4
*Additions*
+ Option ~ement-room-unread-only-counts-notifications~, now enabled by default, causes rooms' unread status to be determined only by their notification counts (which are set by the server and depend on rooms' notification settings).
+ Command ~ement-room-set-notification-state~ sets a room's notification state (imitating Element's user-friendly presets).
+ Room buffers' Transient menus show the room's notification state (imitating Element's user-friendly presets).
+ Command ~ement-set-display-name~ sets the user's global displayname.
+ Command ~ement-room-set-display-name~ sets the user's displayname in a room (which is also now displayed in the room's Transient menu).
+ Column ~Notifications~ in the ~ement-taxy-room-list~ buffer shows rooms' notification state.
+ Option ~ement-interrupted-sync-hook~ allows customization of how sync interruptions are handled.  (Now, by default, a warning is displayed instead of merely a message.)
*Changes*
+ When a room's read receipt is updated, the room's buffer is also marked as unmodified.  (In concert with the new option, this makes rooms' unread status more intuitive.)
*Fixes*
+ Binding of command ~ement-forget-room~ in room buffers.
+ Highlighting of ~@room~ mentions.
** 0.3.1
*Fixes*
+ Room unread status (when the last event in a room is sent by the local user, the room is considered read).
** 0.3
*Additions*
+ Command ~ement-directory~ shows a server's room directory.
+ Command ~ement-directory-search~ searches a server's room directory.
+ Command ~ement-directory-next~ fetches the next batch of rooms in a directory.
+ Command ~ement-leave-room~ accepts a ~FORCE-P~ argument (interactively, with prefix) to leave a room without prompting.
+ Command ~ement-forget-room~ accepts a ~FORCE-P~ argument (interactively, with prefix) to also leave the room, and to forget it without prompting.
+ Option ~ement-notify-mark-frame-urgent-predicates~ marks the frame as urgent when (by default) a message mentions the local user or "@room" and the message's room has an open buffer.
*Changes*
+ Minor improvements to date/time headers.
*Fixes*
+ Command ~ement-describe-room~ for rooms without topics.
+ Improve insertion of old messages around existing timestamp headers.
+ Reduce D-Bus notification system check timeout to 2 seconds (from the default of 25).
+ Compatibility with Emacs 27.
** 0.2.1
*Fixes*
+ Info manual export filename.
** 0.2
*Changes*
+ Read receipts are re-enabled.  (They're now implemented with a global idle timer rather than ~window-scroll-functions~, which sometimes caused a strange race condition that could cause Emacs to become unresponsive or crash.)
+ When determining whether a room is considered unread, non-message events like membership changes, reactions, etc. are ignored.  This fixes a bug that caused certain rooms that had no message events (like some bridged rooms) to appear as unread when they shouldn't have.  But it's unclear whether this is always preferable (e.g. one might want a member leaving a room to cause it to be marked unread), so this is classified as a change rather than simply a fix, and more improvements may be made to this in the future.  (Fixes [[https://github.com/alphapapa/ement.el/issues/97][#97]].  Thanks to [[https://github.com/MrRoy][Julien Roy]] for reporting and testing.)
+ The ~ement-taxy-room-list~ view no longer automatically refreshes the list if the region is active in the buffer.  (This allows the user to operate on multiple rooms without the contents of the buffer changing before completing the process.)
*Fixes*
+ Links to only rooms (as opposed to links to events in rooms) may be activated to join them.
+ Read receipts mark the last completely visible event (rather than one that's only partially displayed).
+ Prevent error when a room avatar image fails to load.
** 0.1.4
*Fixed*
+ Info manual directory headers.
** 0.1.3
*Fixed*
# + Read receipt-sending function was called too many times when scrolling.
# + Send read receipts even when the last receipt is outside the range of retrieved events.
+ Temporarily disable sending of read receipts due to an unusual bug that could cause Emacs to become unresponsive.  (The feature will be re-enabled in a future release.)
** 0.1.2
*Fixed*
+ Function ~ement-room-sync~ correctly updates room-list buffers.  (Thanks to [[https://github.com/vizs][Visuwesh]].)
+ Only send D-Bus notifications when supported.  (Fixes [[https://github.com/alphapapa/ement.el/issues/83][#83]].  Thanks to [[https://github.com/tsdh][Tassilo Horn]].)
** 0.1.1
*Fixed*
+ Function ~ement-room-scroll-up-mark-read~ selects the correct room window.
+ Option ~ement-room-list-avatars~ defaults to what function ~display-images-p~ returns.
** 0.1
After almost two years of development, the first tagged release.  Submitted to GNU ELPA.
* Development
:PROPERTIES:
:TOC:      :include this :ignore descendants
:END:
Bug reports, feature requests, suggestions — /oh my/!
** Copyright Assignment
:PROPERTIES:
:TOC:      :ignore (this)
:END:
Ement.el is published in GNU ELPA and is considered part of GNU Emacs.  Therefore, cumulative contributions of more than 15 lines of code require that the author assign copyright of such contributions to the FSF.  Authors who are interested in doing so may contact [[mailto:assign@gnu.org][assign@gnu.org]] to request the appropriate form.
** Matrix spec in Org format
:PROPERTIES:
:TOC:      :ignore (this)
:END:
An Org-formatted version of the Matrix spec is available in the [[https://github.com/alphapapa/ement.el/tree/meta/spec][meta/spec]] branch.
* License
:PROPERTIES:
:TOC:      :ignore (this)
:END:
GPLv3
* COMMENT Config                                                   :noexport:
:PROPERTIES:
:TOC:      :ignore (this descendants)
:END:
# NOTE: The #+OPTIONS: and other keywords did not take effect when in this section (perhaps due to file size or to changes in Org), so they were moved to the top of the file.
** File-local variables
# Local Variables:
# eval: (require 'org-make-toc)
# before-save-hook: org-make-toc
# org-export-with-properties: ()
# org-export-with-title: t
# End:

This is the file .../info/dir, which contains the
topmost node of the Info hierarchy, called (dir)Top.
The first time you invoke Info you start off looking at this node.

File: dir,	Node: Top	This is the top of the INFO tree
  This (the Directory node) gives a menu of major topics.
  Typing "q" exits, "H" lists all Info commands, "d" returns here,
  "h" gives a primer for first-timers,
  "mEmacs<Return>" visits the Emacs manual, etc.
  In Emacs, you can click mouse button 2 on a menu item or cross reference
  to select it.
* Menu:
Emacs
* Ement: (ement).               Matrix client for Emacs.

;;; ement-api.el --- Matrix API library              -*- lexical-binding: t; -*-
;; Copyright (C) 2022  Free Software Foundation, Inc.
;; Author: Adam Porter <adam@alphapapa.net>
;; Maintainer: Adam Porter <adam@alphapapa.net>
;; This program is free software; you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation, either version 3 of the License, or
;; (at your option) any later version.
;; This program is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;; GNU General Public License for more details.
;; You should have received a copy of the GNU General Public License
;; along with this program.  If not, see <https://www.gnu.org/licenses/>.
;;; Commentary:
;;
;;; Code:
;;;; Debugging
;; NOTE: Uncomment this form and `emacs-lisp-byte-compile-and-load' the file to enable
;; `ement-debug' messages.  This is commented out by default because, even though the
;; messages are only displayed when `warning-minimum-log-level' is `:debug' at runtime, if
;; that is so at expansion time, the expanded macro calls format the message and check the
;; log level at runtime, which is not zero-cost.
;; (eval-and-compile
;;   (setq-local warning-minimum-log-level nil)
;;   (setq-local warning-minimum-log-level :debug))
;;;; Requirements
(require 'json)
(require 'url-parse)
(require 'url-util)
(require 'plz)
(require 'ement-macros)
(require 'ement-structs)
;;;; Variables
;;;; Customization
;;;; Commands
;;;; Functions
(cl-defun ement-api (session endpoint
                             &key then data params queue
                             (content-type "application/json")
                             (data-type 'text)
                             (else #'ement-api-error) (method 'get)
                             ;; FIXME: What's the right term for the URL part after "/_matrix/"?
                             (endpoint-category "client")
                             (json-read-fn #'json-read)
                             ;; NOTE: Hard to say what the default timeouts
                             ;; should be.  Sometimes the matrix.org homeserver
                             ;; can get slow and respond a minute or two later.
                             (connect-timeout 10) (timeout 60)
                             (version "r0"))
  "Make API request on SESSION to ENDPOINT.
The request automatically uses SESSION's server, URI prefix, and
access token.
These keyword arguments are passed to `plz', which see: THEN,
DATA (passed as BODY), QUEUE (passed to `plz-queue', which see),
DATA-TYPE (passed as BODY-TYPE), ELSE, METHOD,
JSON-READ-FN (passed as AS), CONNECT-TIMEOUT, TIMEOUT.
Other arguments include PARAMS (used as the URL's query
parameters), ENDPOINT-CATEGORY (added to the endpoint URL), and
VERSION (added to the endpoint URL).
Note that most Matrix requests expect JSON-encoded data, so
usually the DATA argument should be passed through
`json-encode'."
  (declare (indent defun))
  (pcase-let* (((cl-struct ement-session server token) session)
               ((cl-struct ement-server uri-prefix) server)
               ((cl-struct url type host portspec) (url-generic-parse-url uri-prefix))
               (path (format "/_matrix/%s/%s/%s" endpoint-category version endpoint))
               (query (url-build-query-string params))
               (filename (concat path "?" query))
               (url (url-recreate-url
                     (url-parse-make-urlobj type nil nil host portspec filename nil data t)))
               (headers (ement-alist "Content-Type" content-type))
               (plz-args))
    (when token
      ;; Almost every request will require a token (only a few, like checking login flows, don't),
      ;; so we simplify the API by using the token automatically when the session has one.
      (push (cons "Authorization" (concat "Bearer " token)) headers))
    (setf plz-args (list method url :headers headers :body data :body-type data-type
                         :as json-read-fn :then then :else else
                         :connect-timeout connect-timeout :timeout timeout :noquery t))
    ;; Omit `then' from debugging because if it's a partially applied
    ;; function on the session object, which may be very large, it
    ;; will take a very long time to print into the warnings buffer.
    ;;  (ement-debug (current-time) method url headers)
    (if queue
        (plz-run
         (apply #'plz-queue queue plz-args))
      (apply #'plz plz-args))))
(define-error 'ement-api-error "Ement API error" 'error)
(defun ement-api-error (plz-error)
  "Signal an Ement API error for PLZ-ERROR."
  ;; This feels a little messy, but it seems to be reasonable.
  (pcase-let* (((cl-struct plz-error response
                           (message plz-message) (curl-error `(,curl-exit-code . ,curl-message)))
                plz-error)
               (status (when (plz-response-p response)
                         (plz-response-status response)))
               (body (when (plz-response-p response)
                       (plz-response-body response)))
               (json-object (when body
                              (ignore-errors
                                (json-read-from-string body))))
               (error-message (format "%S: %s"
                                      (or curl-exit-code status)
                                      (or (when json-object
                                            (alist-get 'error json-object))
                                          curl-message
                                          plz-message))))
    (signal 'ement-api-error (list error-message))))
;;;; Footer
(provide 'ement-api)
;;; ement-api.el ends here

;;; ement-autoloads.el --- automatically extracted autoloads  -*- lexical-binding: t -*-
;;
;;; Code:
(add-to-list 'load-path (directory-file-name
                         (or (file-name-directory #$) (car load-path))))

;;;### (autoloads nil "ement" "ement.el" (0 0 0 0))
;;; Generated autoloads from ement.el
(autoload 'ement-connect "ement" "\
Connect to Matrix with USER-ID and PASSWORD, or using SESSION.
Interactively, with prefix, ignore a saved session and log in
again; otherwise, use a saved session if `ement-save-sessions' is
enabled and a saved session is available, or prompt to log in if
not enabled or available.
If USERID or PASSWORD are not specified, the user will be
prompted for them.
If URI-PREFIX is specified, it should be the prefix of the
server's API URI, including protocol, hostname, and optionally
the port, e.g.
  \"https://matrix-client.matrix.org\"
  \"http://localhost:8080\"
\(fn &key USER-ID PASSWORD URI-PREFIX SESSION)" t nil)
(register-definition-prefixes "ement" '("ement-"))
;;;***

;;;### (autoloads nil "ement-api" "ement-api.el" (0 0 0 0))
;;; Generated autoloads from ement-api.el
(register-definition-prefixes "ement-api" '("ement-api-error"))
;;;***

;;;### (autoloads nil "ement-directory" "ement-directory.el" (0 0
;;;;;;  0 0))
;;; Generated autoloads from ement-directory.el
(autoload 'ement-directory "ement-directory" "\
View the public room directory on SERVER with SESSION.
Show up to LIMIT rooms.  Interactively, with prefix, prompt for
server and LIMIT.
SINCE may be a next-batch token.
\(fn &key SERVER SESSION SINCE (LIMIT 100))" t nil)
(autoload 'ement-directory-search "ement-directory" "\
View public rooms on SERVER matching QUERY.
QUERY is a string used to filter results.
\(fn QUERY &key SERVER SESSION SINCE (LIMIT 1000))" t nil)
(autoload 'ement-view-space "ement-directory" "\
View child rooms in SPACE on SESSION.
SPACE may be a room ID or an `ement-room' struct.
\(fn SPACE SESSION)" t nil)
(register-definition-prefixes "ement-directory" '("ement-directory-"))
;;;***

;;;### (autoloads nil "ement-lib" "ement-lib.el" (0 0 0 0))
;;; Generated autoloads from ement-lib.el
(register-definition-prefixes "ement-lib" '("ement-"))
;;;***

;;;### (autoloads nil "ement-macros" "ement-macros.el" (0 0 0 0))
;;; Generated autoloads from ement-macros.el
(register-definition-prefixes "ement-macros" '("ement-"))
;;;***

;;;### (autoloads nil "ement-notify" "ement-notify.el" (0 0 0 0))
;;; Generated autoloads from ement-notify.el
(register-definition-prefixes "ement-notify" '("ement-notify"))
;;;***

;;;### (autoloads nil "ement-room" "ement-room.el" (0 0 0 0))
;;; Generated autoloads from ement-room.el
(register-definition-prefixes "ement-room" '("ement-"))
;;;***

;;;### (autoloads nil "ement-room-list" "ement-room-list.el" (0 0
;;;;;;  0 0))
;;; Generated autoloads from ement-room-list.el
(autoload 'ement-room-list--after-initial-sync "ement-room-list" "\
Call `ement-room-list', ignoring arguments.
To be called from `ement-after-initial-sync-hook'.
\(fn &rest IGNORE)" nil nil)
(defalias 'ement-list-rooms 'ement-room-list)
(autoload 'ement-room-list "ement-room-list" "\
Show a buffer listing Ement rooms, grouped with Taxy KEYS.
After showing it, its window is selected.  The buffer is named
BUFFER-NAME and is shown with DISPLAY-BUFFER-ACTION; or if
DISPLAY-BUFFER-ACTION is nil, the buffer is not displayed.
\(fn &key (BUFFER-NAME \"*Ement Room List*\") (KEYS ement-room-list-default-keys) (DISPLAY-BUFFER-ACTION \\='((display-buffer-reuse-window display-buffer-same-window))))" t nil)
(autoload 'ement-room-list-auto-update "ement-room-list" "\
Automatically update the Taxy room list buffer.
+Does so when variable `ement-room-list-auto-update' is non-nil.
+To be called in `ement-sync-callback-hook'.
\(fn SESSION)" nil nil)
(register-definition-prefixes "ement-room-list" '("ement-room-list-"))
;;;***

;;;### (autoloads nil "ement-tabulated-room-list" "ement-tabulated-room-list.el"
;;;;;;  (0 0 0 0))
;;; Generated autoloads from ement-tabulated-room-list.el
(autoload 'ement-tabulated-room-list "ement-tabulated-room-list" "\
Show buffer listing joined rooms.
Calls `pop-to-buffer-same-window'.  Interactively, with prefix,
call `pop-to-buffer'.
\(fn &rest IGNORE)" t nil)
(autoload 'ement-tabulated-room-list-auto-update "ement-tabulated-room-list" "\
Automatically update the room list buffer.
Does so when variable `ement-tabulated-room-list-auto-update' is non-nil.
To be called in `ement-sync-callback-hook'.
\(fn SESSION)" nil nil)
(register-definition-prefixes "ement-tabulated-room-list" '("ement-tabulated-room-list-"))
;;;***

;;;### (autoloads nil nil ("ement-pkg.el" "ement-structs.el") (0
;;;;;;  0 0 0))
;;;***

;; Local Variables:
;; version-control: never
;; no-byte-compile: t
;; no-update-autoloads: t
;; coding: utf-8
;; End:
;;; ement-autoloads.el ends here

;;; ement-directory.el --- Public room directory support                       -*- lexical-binding: t; -*-
;; Copyright (C) 2022  Free Software Foundation, Inc.
;; Author: Adam Porter <adam@alphapapa.net>
;; Maintainer: Adam Porter <adam@alphapapa.net>
;; This program is free software; you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation, either version 3 of the License, or
;; (at your option) any later version.
;; This program is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;; GNU General Public License for more details.
;; You should have received a copy of the GNU General Public License
;; along with this program.  If not, see <https://www.gnu.org/licenses/>.
;;; Commentary:
;; This library provides support for viewing and searching public room directories on
;; Matrix homeservers.
;; To make rendering the list flexible and useful, we'll use `taxy-magit-section'.
;;; Code:
;;;; Requirements
(require 'ement)
(require 'ement-room-list)
(require 'taxy)
(require 'taxy-magit-section)
;;;; Variables
(defvar ement-directory-mode-map
  (let ((map (make-sparse-keymap)))
    (define-key map (kbd "RET") #'ement-directory-RET)
    (define-key map [mouse-1] #'ement-directory-mouse-1)
    (define-key map (kbd "+") #'ement-directory-next)
    map))
(defgroup ement-directory nil
  "Options for room directories."
  :group 'ement)
;;;; Mode
(define-derived-mode ement-directory-mode magit-section-mode "Ement-Directory"
  :global nil)
(defvar-local ement-directory-etc nil
  "Alist storing information in `ement-directory' buffers.")
;;;;; Keys
(eval-and-compile
  (taxy-define-key-definer ement-directory-define-key
    ement-directory-keys "ement-directory-key" "FIXME: Docstring."))
;; TODO: Other keys like guest_can_join, world_readable, etc.  (Last-updated time would be
;; nice, but the server doesn't include that in the results.)
(ement-directory-define-key joined-p ()
  (pcase-let (((map ('room_id id)) item)
              ((map session) ement-directory-etc))
    (when (cl-find id (ement-session-rooms session)
                   :key #'ement-room-id :test #'equal)
      "Joined")))
(ement-directory-define-key size (&key < >)
  (pcase-let (((map ('num_joined_members size)) item))
    (cond ((and < (< size <))
           (format "< %s members" <))
          ((and > (> size >))
           (format "> %s members" >)))))
(ement-directory-define-key space-p ()
  "Groups rooms that are themselves spaces."
  (pcase-let (((map ('room_type type)) item))
    (when (equal "m.space" type)
      "Spaces")))
(defcustom ement-directory-default-keys
  '((joined-p)
    (space-p)
    ((size :> 10000))
    ((size :> 1000))
    ((size :> 100))
    ((size :> 10))
    ((size :< 11)))
  "Default keys."
  :type 'sexp)
;;;; Columns
(defvar-local ement-directory-room-avatar-cache (make-hash-table)
  ;; Use a buffer-local variable so that the cache is cleared when the buffer is closed.
  "Hash table caching room avatars for the `ement-directory' room list.")
(eval-and-compile
  (taxy-magit-section-define-column-definer "ement-directory"))
;; TODO: Fetch avatars (with queueing and async updating/insertion?).
(ement-directory-define-column #("✓" 0 1 (help-echo "Joined")) ()
  (pcase-let (((map ('room_id id)) item)
              ((map session) ement-directory-etc))
    (if (cl-find id (ement-session-rooms session)
                 :key #'ement-room-id :test #'equal)
        "✓"
      " ")))
(ement-directory-define-column "Name" (:max-width 25)
  (pcase-let* (((map name ('room_type type)) item)
               (face (pcase type
                       ("m.space" 'ement-room-list-space)
                       (_ 'ement-room-list-name))))
    (propertize (or name "[unnamed]")
                'face face)))
(ement-directory-define-column "Alias" (:max-width 25)
  (pcase-let (((map ('canonical_alias alias)) item))
    (or alias "")))
(ement-directory-define-column "Size" ()
  (pcase-let (((map ('num_joined_members size)) item))
    (number-to-string size)))
(ement-directory-define-column "Topic" (:max-width 50)
  (pcase-let (((map topic) item))
    (if topic
        (replace-regexp-in-string "\n" " | " topic nil t)
      "")))
(ement-directory-define-column "ID" ()
  (pcase-let (((map ('room_id id)) item))
    id))
(unless ement-directory-columns
  ;; TODO: Automate this or document it
  (setq-default ement-directory-columns
                '("Name" "Alias" "Size" "Topic" "ID")))
;;;; Commands
;; TODO: Pagination of results.
;;;###autoload
(cl-defun ement-directory (&key server session since (limit 100))
  "View the public room directory on SERVER with SESSION.
Show up to LIMIT rooms.  Interactively, with prefix, prompt for
server and LIMIT.
SINCE may be a next-batch token."
  (interactive (let* ((session (ement-complete-session :prompt "Search on session: "))
                      (server (if current-prefix-arg
                                  (read-string "Search on server: " nil nil
                                               (ement-server-name (ement-session-server session)))
                                (ement-server-name (ement-session-server session))))
                      (args (list :server server :session session)))
                 (when current-prefix-arg
                   (cl-callf plist-put args
                     :limit (read-number "Limit number of rooms: " 100)))
                 args))
  (pcase-let ((revert-function (lambda (&rest _ignore)
                                 (interactive)
                                 (ement-directory :server server :session session :limit limit)))
              (endpoint "publicRooms")
              (params (list (list "limit" limit))))
    (when since
      (cl-callf append params (list (list "since" since))))
    (ement-api session endpoint :params params
      :then (lambda (results)
              (pcase-let (((map ('chunk rooms) ('next_batch next-batch)
                                ('total_room_count_estimate remaining))
                           results))
                (ement-directory--view rooms :append-p since
                  :buffer-name (format "*Ement Directory: %s*" server)
                  :root-section-name (format "Ement Directory: %s" server)
                  :init-fn (lambda ()
                             (setf (alist-get 'server ement-directory-etc) server
                                   (alist-get 'session ement-directory-etc) session
                                   (alist-get 'next-batch ement-directory-etc) next-batch
                                   (alist-get 'limit ement-directory-etc) limit)
                             (setq-local revert-buffer-function revert-function)
                             (when remaining
                               ;; FIXME: The server seems to report all of the rooms on
                               ;; the server as remaining even when searching for a
                               ;; specific term like "emacs".
                               ;; TODO: Display this in a more permanent place (like a
                               ;; header or footer).
                               (message
                                (substitute-command-keys
                                 "%s rooms remaining (use \\[ement-directory-next] to fetch more)")
                                remaining)))))))
    (ement-message "Listing %s rooms on %s..." limit server)))
;;;###autoload
(cl-defun ement-directory-search (query &key server session since (limit 1000))
  "View public rooms on SERVER matching QUERY.
QUERY is a string used to filter results."
  (interactive (let* ((session (ement-complete-session :prompt "Search on session: "))
                      (server (if current-prefix-arg
                                  (read-string "Search on server: " nil nil
                                               (ement-server-name (ement-session-server session)))
                                (ement-server-name (ement-session-server session))))
                      (query (read-string (format "Search for rooms on %s matching: " server)))
                      (args (list query :server server :session session)))
                 (when current-prefix-arg
                   (cl-callf plist-put (cdr args)
                     :limit (read-number "Limit number of rooms: " 1000)))
                 args))
  ;; TODO: Handle "include_all_networks" and "third_party_instance_id".  See § 10.5.4.
  (pcase-let* ((revert-function (lambda (&rest _ignore)
                                  (interactive)
                                  (ement-directory-search query :server server :session session)))
               (endpoint "publicRooms")
               (data (rassq-delete-all nil
                                       (ement-alist "limit" limit
                                                    "filter" (ement-alist "generic_search_term" query)
                                                    "since" since))))
    (ement-api session endpoint :method 'post :data (json-encode data)
      :then (lambda (results)
              (pcase-let (((map ('chunk rooms) ('next_batch next-batch)
                                ('total_room_count_estimate remaining))
                           results))
                (ement-directory--view rooms :append-p since
                  :buffer-name (format "*Ement Directory: \"%s\" on %s*" query server)
                  :root-section-name (format "Ement Directory: \"%s\" on %s" query server)
                  :init-fn (lambda ()
                             (setf (alist-get 'server ement-directory-etc) server
                                   (alist-get 'session ement-directory-etc) session
                                   (alist-get 'next-batch ement-directory-etc) next-batch
                                   (alist-get 'limit ement-directory-etc) limit
                                   (alist-get 'query ement-directory-etc) query)
                             (setq-local revert-buffer-function revert-function)
                             (when remaining
                               (message
                                (substitute-command-keys
                                 "%s rooms remaining (use \\[ement-directory-next] to fetch more)")
                                remaining)))))))
    (ement-message "Searching for %S on %s..." query server)))
(defun ement-directory-next ()
  "Fetch next batch of results in `ement-directory' buffer."
  (interactive)
  (pcase-let (((map next-batch query limit server session) ement-directory-etc))
    (unless next-batch
      (user-error "No more results"))
    (if query
        (ement-directory-search query :server server :session session :limit limit :since next-batch)
      (ement-directory :server server :session session :limit limit :since next-batch))))
(defun ement-directory-mouse-1 (event)
  "Call `ement-directory-RET' at EVENT."
  (interactive "e")
  (mouse-set-point event)
  (call-interactively #'ement-directory-RET))
(defun ement-directory-RET ()
  "View or join room at point, or cycle section at point."
  (interactive)
  (cl-etypecase (oref (magit-current-section) value)
    (null nil)
    (list (pcase-let* (((map ('name name) ('room_id room-id)) (oref (magit-current-section) value))
                       ((map session) ement-directory-etc)
                       (room (cl-find room-id (ement-session-rooms session)
                                      :key #'ement-room-id :test #'equal)))
            (if room
                (ement-view-room room session)
              ;; Room not joined: prompt to join.  (Don't use the alias in the prompt,
              ;; because multiple rooms might have the same alias, e.g. when one is
              ;; upgraded or tombstoned.)
              (when (yes-or-no-p (format "Join room \"%s\" <%s>? " name room-id))
                (ement-join-room room-id session)))))
    (taxy-magit-section (call-interactively #'magit-section-cycle))))
;;;; Functions
(cl-defun ement-directory--view (rooms &key init-fn append-p
                                       (buffer-name "*Ement Directory*")
                                       (root-section-name "Ement Directory")
                                       (keys ement-directory-default-keys)
                                       (display-buffer-action '(display-buffer-same-window)))
  "View ROOMS in an `ement-directory-mode' buffer.
ROOMS should be a list of rooms from an API request.  Calls
INIT-FN immediately after activating major mode.  Sets
BUFFER-NAME and ROOT-SECTION-NAME, and uses
DISPLAY-BUFFER-ACTION.  KEYS are a list of `taxy' keys.  If
APPEND-P, add ROOMS to buffer rather than replacing existing
contents.  To be called by `ement-directory-search'."
  (declare (indent defun))
  (let (column-sizes window-start)
    (cl-labels ((format-item
                 ;; NOTE: We use the buffer-local variable `ement-directory-etc' rather
                 ;; than a closure variable because the taxy-magit-section struct's format
                 ;; table is not stored in it, and we can't reuse closures' variables.
                 ;; (It would be good to store the format table in the taxy-magit-section
                 ;; in the future, to make this cleaner.)
                 (item) (gethash item (alist-get 'format-table ement-directory-etc)))
                ;; NOTE: Since these functions take an "item" (which is a [room session]
                ;; vector), they're prefixed "item-" rather than "room-".
                (size
                 (item) (pcase-let (((map ('num_joined_members size)) item))
                          size))
                (t<nil (a b) (and a (not b)))
                (t>nil (a b) (and (not a) b))
                (make-fn (&rest args)
                         (apply #'make-taxy-magit-section
                                :make #'make-fn
                                :format-fn #'format-item
                                ;; FIXME: Should we reuse `ement-room-list-level-indent' here?
                                :level-indent ement-room-list-level-indent
                                ;; :visibility-fn #'visible-p
                                ;; :heading-indent 2
                                :item-indent 2
                                ;; :heading-face-fn #'heading-face
                                args)))
      (with-current-buffer (get-buffer-create buffer-name)
        (unless (eq 'ement-directory-mode major-mode)
          ;; Don't obliterate buffer-local variables.
          (ement-directory-mode))
        (when init-fn
          (funcall init-fn))
        (pcase-let* ((taxy (if append-p
                               (alist-get 'taxy ement-directory-etc)
                             (make-fn
                              :name root-section-name
                              :take (taxy-make-take-function keys ement-directory-keys))))
                     (taxy-magit-section-insert-indent-items nil)
                     (inhibit-read-only t)
                     (pos (point))
                     (section-ident (when (magit-current-section)
                                      (magit-section-ident (magit-current-section))))
                     (format-cons))
          (setf taxy (thread-last taxy
                                  (taxy-fill (cl-coerce rooms 'list))
                                  (taxy-sort #'> #'size)
                                  (taxy-sort* #'string> #'taxy-name))
                (alist-get 'taxy ement-directory-etc) taxy
                format-cons (taxy-magit-section-format-items
                             ement-directory-columns ement-directory-column-formatters taxy)
                (alist-get 'format-table ement-directory-etc) (car format-cons)
                column-sizes (cdr format-cons)
                header-line-format (taxy-magit-section-format-header
                                    column-sizes ement-directory-column-formatters)
                window-start (if (get-buffer-window buffer-name)
                                 (window-start (get-buffer-window buffer-name))
                               0))
          (delete-all-overlays)
          (erase-buffer)
          (save-excursion
            (taxy-magit-section-insert taxy :items 'first
              ;; :blank-between-depth bufler-taxy-blank-between-depth
              :initial-depth 0))
          (goto-char pos)
          (when (and section-ident (magit-get-section section-ident))
            (goto-char (oref (magit-get-section section-ident) start)))))
      (display-buffer buffer-name display-buffer-action)
      (when (get-buffer-window buffer-name)
        (set-window-start (get-buffer-window buffer-name) window-start))
      ;; NOTE: In order for `bookmark--jump-via' to work properly, the restored buffer
      ;; must be set as the current buffer, so we have to do this explicitly here.
      (set-buffer buffer-name))))
;;;; Spaces
;; Viewing spaces and the rooms in them.
;;;###autoload
(defun ement-view-space (space session)
  ;; TODO: Use this for spaces instead of `ement-view-room' (or something like that).
  ;; TODO: Display space's topic in the header or something.
  "View child rooms in SPACE on SESSION.
SPACE may be a room ID or an `ement-room' struct."
  ;; TODO: "from" query parameter.
  (interactive (ement-complete-room :predicate #'ement--room-space-p
                 :prompt "Space: "))
  (pcase-let* ((id (cl-typecase space
                     (string space)
                     (ement-room (ement-room-id space))))
               (endpoint (format "rooms/%s/hierarchy" id))
               (revert-function (lambda (&rest _ignore)
                                  (interactive)
                                  (ement-view-space space session))))
    (ement-api session endpoint :version "v1"
      :then (lambda (results)
              (pcase-let (((map rooms ('next_batch next-batch))
                           results))
                (ement-directory--view rooms ;; :append-p since
                  ;; TODO: Use space's alias where possible.
                  :buffer-name (format "*Ement Directory: space \"%s\"" id)
                  :root-section-name (format "*Ement Directory: space \"%s\"" id)
                  :init-fn (lambda ()
                             (setf (alist-get 'session ement-directory-etc) session
                                   (alist-get 'next-batch ement-directory-etc) next-batch
                                   ;; (alist-get 'limit ement-directory-etc) limit
                                   (alist-get 'space ement-directory-etc) space)
                             (setq-local revert-buffer-function revert-function)
                             ;; TODO: Handle next batches.
                             ;; (when remaining
                             ;;   (message
                             ;;    (substitute-command-keys
                             ;;     "%s rooms remaining (use \\[ement-directory-next] to fetch more)")
                             ;;    remaining))
                             )))))))
;;;; Footer
(provide 'ement-directory)
;;; ement-directory.el ends here

;;; ement-lib.el --- Library of Ement functions      -*- lexical-binding: t; -*-
;; Copyright (C) 2022  Free Software Foundation, Inc.
;; Author: Adam Porter <adam@alphapapa.net>
;; Maintainer: Adam Porter <adam@alphapapa.net>
;; This program is free software; you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation, either version 3 of the License, or
;; (at your option) any later version.
;; This program is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;; GNU General Public License for more details.
;; You should have received a copy of the GNU General Public License
;; along with this program.  If not, see <https://www.gnu.org/licenses/>.
;;; Commentary:
;; This library provides functions used in other Ement libraries.  It exists so they may
;; be required where needed, without causing circular dependencies.
;;; Code:
;;;; Requirements
(eval-when-compile
  (require 'eieio)
  (require 'ewoc)
  (require 'pcase)
  (require 'subr-x)
  
  (require 'taxy-magit-section)
  (require 'ement-macros))
(require 'cl-lib)
(require 'color)
(require 'map)
(require 'xml)
(require 'ement-api)
(require 'ement-structs)
;;;; Variables
(defvar ement-sessions)
(defvar ement-users)
(defvar ement-ewoc)
(defvar ement-room)
(defvar ement-session)
(defvar ement-room-buffer-name-prefix)
(defvar ement-room-buffer-name-suffix)
(defvar ement-room-leave-kill-buffer)
(defvar ement-room-prism)
(defvar ement-room-prism-color-adjustment)
(defvar ement-room-prism-minimum-contrast)
(defvar ement-room-unread-only-counts-notifications)
;;;; Function declarations
;; Instead of using top-level `declare-function' forms (which can easily become obsolete
;; if not kept with the code that needs them), this allows the use of `(declare (function
;; ...))' forms in each function definition, so that if a function is moved or removed,
;; the `declare-function' goes with it.
;; TODO: Propose this upstream.
(eval-and-compile
  (defun ement--byte-run--declare-function (_name _args &rest values)
    "Return a `declare-function' form with VALUES.
Allows the use of a form like:
  (declare (function FN FILE ...))
inside of a function definition, effectively keeping its
`declare-function' form inside the function definition, ensuring
that stray such forms don't remain if the function is removed."
    `(declare-function ,@values))
  (cl-pushnew '(function ement--byte-run--declare-function) defun-declarations-alist :test #'equal)
  (cl-pushnew '(function ement--byte-run--declare-function) macro-declarations-alist :test #'equal))
;;;; Compatibility
;; These workarounds should be removed when they aren't needed.
;;;;; Emacs 28 color features.
;; Copied from Emacs 28.  See <https://github.com/alphapapa/ement.el/issues/99>.
;; FIXME: Remove this workaround when possible.
(eval-and-compile
  (unless (boundp 'color-luminance-dark-limit)
    (defconst ement--color-luminance-dark-limit 0.325
      "The relative luminance below which a color is considered 'dark'.
A 'dark' color in this sense provides better contrast with white
than with black; see `color-dark-p'.
This value was determined experimentally.")))
(defalias 'ement--color-dark-p
  (if (fboundp 'color-dark-p)
      'color-dark-p
    (lambda (rgb)
      "Whether RGB is more readable against white than black.
RGB is a 3-element list (R G B), each component in the range [0,1].
This predicate can be used both for determining a suitable (black or white)
contrast colour with RGB as background and as foreground."
      (unless (<= 0 (apply #'min rgb) (apply #'max rgb) 1)
        (error "RGB components %S not in [0,1]" rgb))
      ;; Compute the relative luminance after gamma-correcting (assuming sRGB),
      ;; and compare to a cut-off value determined experimentally.
      ;; See https://en.wikipedia.org/wiki/Relative_luminance for details.
      (let* ((sr (nth 0 rgb))
             (sg (nth 1 rgb))
             (sb (nth 2 rgb))
             ;; Gamma-correct the RGB components to linear values.
             ;; Use the power 2.2 as an approximation to sRGB gamma;
             ;; it should be good enough for the purpose of this function.
             (r (expt sr 2.2))
             (g (expt sg 2.2))
             (b (expt sb 2.2))
             (y (+ (* r 0.2126) (* g 0.7152) (* b 0.0722))))
        (< y ement--color-luminance-dark-limit)))))
;;;; Functions
;;;;; Commands
(cl-defun ement-create-room
    (session &key name alias topic invite direct-p creation-content
             (then (lambda (data)
                     (message "Created new room: %s" (alist-get 'room_id data))))
             (visibility 'private))
  "Create new room on SESSION.
Then call function THEN with response data.  Optional string
arguments are NAME, ALIAS, and TOPIC.  INVITE may be a list of
user IDs to invite.  If DIRECT-P, set the \"is_direct\" flag in
the request.  CREATION-CONTENT may be an alist of extra keys to
include with the request (see Matrix spec)."
  ;; TODO: Document other arguments.
  ;; SPEC: 10.1.1.
  (declare (indent defun))
  (interactive (list (ement-complete-session)
		     :name (read-string "New room name: ")
		     :alias (read-string "New room alias (e.g. \"foo\" for \"#foo:matrix.org\"): ")
		     :topic (read-string "New room topic: ")
		     :visibility (completing-read "New room visibility: " '(private public))))
  (cl-labels ((given-p
	       (var) (and var (not (string-empty-p var)))))
    (pcase-let* ((endpoint "createRoom")
		 (data (ement-aprog1
			   (ement-alist "visibility" visibility)
			 (when (given-p alias)
			   (push (cons "room_alias_name" alias) it))
			 (when (given-p name)
			   (push (cons "name" name) it))
			 (when (given-p topic)
			   (push (cons "topic" topic) it))
			 (when invite
			   (push (cons "invite" invite) it))
			 (when direct-p
			   (push (cons "is_direct" t) it))
                         (when creation-content
                           (push (cons "creation_content" creation-content) it)))))
      (ement-api session endpoint :method 'post :data (json-encode data)
        :then then))))
(cl-defun ement-create-space
    (session &key name alias topic
             (then (lambda (data)
                     (message "Created new space: %s" (alist-get 'room_id data))))
             (visibility 'private))
  "Create new space on SESSION.
Then call function THEN with response data.  Optional string
arguments are NAME, ALIAS, and TOPIC."
  (declare (indent defun))
  (interactive (list (ement-complete-session)
		     :name (read-string "New space name: ")
		     :alias (read-string "New space alias (e.g. \"foo\" for \"#foo:matrix.org\"): ")
		     :topic (read-string "New space topic: ")
		     :visibility (completing-read "New space visibility: " '(private public))))
  (ement-create-room session :name name :alias alias :topic topic :visibility visibility
    :creation-content (ement-alist "type" "m.space") :then then))
(defun ement-room-leave (room session &optional force-p)
  "Leave ROOM on SESSION.
If FORCE-P, leave without prompting.  ROOM may be an `ement-room'
struct, or a room ID or alias string."
  ;; TODO: Rename `room' argument to `room-or-id'.
  (interactive
   (ement-with-room-and-session
     :prompt-form (ement-complete-room :prompt "Leave room: ")
     (list ement-room ement-session)))
  (cl-etypecase room
    (ement-room)
    (string (setf room (ement-afirst (or (equal room (ement-room-canonical-alias it))
                                         (equal room (ement-room-id it)))
                         (ement-session-rooms session)))))
  (when (or force-p (yes-or-no-p (format "Leave room %s? " (ement--format-room room))))
    (pcase-let* (((cl-struct ement-room id) room)
                 (endpoint (format "rooms/%s/leave" (url-hexify-string id))))
      (ement-api session endpoint :method 'post :data ""
        :then (lambda (_data)
                (when ement-room-leave-kill-buffer
                  ;; NOTE: This generates a symbol and sets its function value to a lambda
                  ;; which removes the symbol from the hook, removing itself from the hook.
                  ;; TODO: When requiring Emacs 27, use `letrec'.
                  (let* ((leave-fn-symbol (gensym (format "ement-leave-%s" room)))
                         (leave-fn (lambda (_session)
                                     (remove-hook 'ement-sync-callback-hook leave-fn-symbol)
                                     ;; FIXME: Probably need to unintern the symbol.
                                     (when-let ((buffer (map-elt (ement-room-local room) 'buffer)))
                                       (when (buffer-live-p buffer)
                                         (kill-buffer buffer))))))
                    (setf (symbol-function leave-fn-symbol) leave-fn)
                    (add-hook 'ement-sync-callback-hook leave-fn-symbol)))
                (ement-message "Left room: %s" (ement--format-room room)))
        :else (lambda (plz-error)
                (pcase-let* (((cl-struct plz-error response) plz-error)
                             ((cl-struct plz-response status body) response)
                             ((map error) (json-read-from-string body)))
                  (pcase status
                    (429 (error "Unable to leave room %s: %s" room error))
                    (_ (error "Unable to leave room %s: %s %S" room status plz-error)))))))))
(defalias 'ement-leave-room #'ement-room-leave)
(defun ement-forget-room (room session &optional force-p)
  "Forget ROOM on SESSION.
If FORCE-P (interactively, with prefix), prompt to leave the room
when necessary, and forget the room without prompting."
  (interactive
   (ement-with-room-and-session
     :prompt-form (ement-complete-room :prompt "Forget room: ")
     (list ement-room ement-session current-prefix-arg)))
  (pcase-let* (((cl-struct ement-room id display-name status) room)
               (endpoint (format "rooms/%s/forget" (url-hexify-string id))))
    (pcase status
      ('join (if (and force-p
                      (yes-or-no-p (format "Leave and forget room %s? (WARNING: You will not be able to rejoin the room to access its content.) "
                                           (ement--format-room room))))
                 (progn
                   ;; TODO: Use `letrec'.
                   (let* ((forget-fn-symbol (gensym (format "ement-forget-%s" room)))
                          (forget-fn (lambda (_session)
                                       (when (equal 'leave (ement-room-status room))
                                         (remove-hook 'ement-sync-callback-hook forget-fn-symbol)
                                         ;; FIXME: Probably need to unintern the symbol.
                                         (ement-forget-room room session 'force)))))
                     (setf (symbol-function forget-fn-symbol) forget-fn)
                     (add-hook 'ement-sync-callback-hook forget-fn-symbol))
                   (ement-leave-room room session 'force))
               (user-error "Room %s is joined (must be left before forgetting)"
                           (ement--format-room room))))
      ('leave (when (or force-p (yes-or-no-p (format "Forget room \"%s\" (%s)? " display-name id)))
                (ement-api session endpoint :method 'post :data ""
                  :then (lambda (_data)
                          ;; NOTE: The spec does not seem to indicate that the action of forgetting
                          ;; a room is synced to other clients, so it seems that we need to remove
                          ;; the room from the session here.
                          (setf (ement-session-rooms session)
                                (cl-remove room (ement-session-rooms session)))
                          ;; TODO: Indicate forgotten in footer in room buffer.
                          (ement-message "Forgot room: %s." (ement--format-room room)))))))))
(defun ement-ignore-user (user-id session &optional unignore-p)
  "Ignore USER-ID on SESSION.
If UNIGNORE-P (interactively, with prefix), un-ignore USER."
  (interactive (list (ement-complete-user-id)
                     (ement-complete-session)
                     current-prefix-arg))
  (pcase-let* (((cl-struct ement-session account-data) session)
               ;; TODO: Store session account-data events in an alist keyed on type.
               ((map ('content (map ('ignored_users ignored-users))))
                (cl-find "m.ignored_user_list" account-data
                         :key (lambda (event) (alist-get 'type event)) :test #'equal)))
    (if unignore-p
        ;; Being map keys, the user IDs have been interned by `json-read'.
        (setf ignored-users (map-delete ignored-users (intern user-id)))
      ;; Empty maps are used to list ignored users.
      (setf (map-elt ignored-users user-id) nil))
    (ement-put-account-data session "m.ignored_user_list" (ement-alist "ignored_users" ignored-users)
      :then (lambda (data)
              (ement-debug "PUT successful" data)
              (message "Ement: User %s %s." user-id (if unignore-p "unignored" "ignored"))))))
(defun ement-invite-user (user-id room session)
  "Invite USER-ID to ROOM on SESSION.
Interactively, with prefix, prompt for room and session,
otherwise use current room."
  ;; SPEC: 10.4.2.1.
  (interactive
   (ement-with-room-and-session
     (list (ement-complete-user-id) ement-room ement-session)))
  (pcase-let* ((endpoint (format "rooms/%s/invite"
                                 (url-hexify-string (ement-room-id room))))
               (data (ement-alist "user_id" user-id) ))
    (ement-api session endpoint :method 'post :data (json-encode data)
      ;; TODO: Handle error codes.
      :then (lambda (_data)
              (message "User %s invited to room \"%s\" (%s)" user-id
                       (ement-room-display-name room)
                       (ement-room-id room))))))
(defun ement-list-members (room session bufferp)
  "Show members of ROOM on SESSION.
Interactively, with prefix, prompt for room and session,
otherwise use current room.  If BUFFERP (interactively, with
prefix), or if there are many members, show in a new buffer;
otherwise show in echo area."
  (interactive
   (ement-with-room-and-session
     (list ement-room ement-session current-prefix-arg)))
  (pcase-let* (((cl-struct ement-room members (local (map fetched-members-p))) room)
               (list-members
                (lambda (&optional _)
                  (cond ((or bufferp (> (hash-table-count members) 51))
                         ;; Show in buffer.
                         (let* ((buffer (get-buffer-create (format "*Ement members: %s*" (ement-room-display-name room))))
                                (members (cl-sort (cl-loop for user being the hash-values of members
                                                           for id = (ement-user-id user)
                                                           for displayname = (ement--user-displayname-in room user)
                                                           collect (cons displayname id))
                                                  (lambda (a b) (string-collate-lessp a b nil t)) :key #'car))
                                (displayname-width (cl-loop for member in members
                                                            maximizing (string-width (car member))))
                                (format-string (format "%%-%ss <%%s>" displayname-width)))
                           (with-current-buffer buffer
                             (erase-buffer)
                             (save-excursion
                               (dolist (member members)
                                 (insert (format format-string (car member) (cdr member)) "\n"))))
                           (pop-to-buffer buffer)))
                        (t
                         ;; Show in echo area.
                         (message "Members of %s (%s): %s" (ement--room-display-name room)
                                  (hash-table-count members)
                                  (string-join (map-apply (lambda (_id user)
                                                            (ement--user-displayname-in room user))
                                                          members)
                                               ", ")))))))
    (if fetched-members-p
        (funcall list-members)
      (ement--get-joined-members room session
        :then list-members))
    (message "Listing members of %s..." (ement--format-room room))))
(defun ement-send-direct-message (session user-id message)
  "Send a direct MESSAGE to USER-ID on SESSION.
Uses the latest existing direct room with the user, or creates a
new one automatically if necessary."
  ;; SPEC: 13.23.2.
  (interactive
   (let* ((session (ement-complete-session))
	  (user-id (ement-complete-user-id))
	  (message (read-string "Message: ")))
     (list session user-id message)))
  (if-let* ((seen-user (gethash user-id ement-users))
	    (existing-direct-room (ement--direct-room-for-user seen-user session)))
      (progn
        (ement-send-message existing-direct-room session :body message)
        (message "Message sent to %s <%s> in room %S <%s>."
                 (ement--user-displayname-in existing-direct-room seen-user)
                 user-id
                 (ement-room-display-name existing-direct-room) (ement-room-id existing-direct-room)))
    ;; No existing room for user: make new one.
    (message "Creating new room for user %s..." user-id)
    (ement-create-room session :direct-p t :invite (list user-id)
      :then (lambda (data)
              (let* ((room-id (alist-get 'room_id data))
	             (room (or (cl-find room-id (ement-session-rooms session)
                                        :key #'ement-room-id)
		               ;; New room hasn't synced yet: make a temporary struct.
		               (make-ement-room :id room-id)))
                     (direct-rooms-account-data-event-content
                      ;; FIXME: Make account-data a map.
                      (alist-get 'content (cl-find-if (lambda (event)
                                                        (equal "m.direct" (alist-get 'type event)))
                                                      (ement-session-account-data session)))))
                ;; Mark new room as direct: add the room to the account-data event, then
                ;; put the new account data to the server.  (See also:
                ;; <https://github.com/matrix-org/matrix-react-sdk/blob/919aab053e5b3bdb5a150fd90855ad406c19e4ab/src/Rooms.ts#L91>).
                (setf (map-elt direct-rooms-account-data-event-content user-id) (vector room-id))
                (ement-put-account-data session "m.direct" direct-rooms-account-data-event-content)
                ;; Send message to new room.
                (ement-send-message room session :body message)
                (message "Room \"%s\" created for user %s.  Sending message..."
	                 room-id user-id))))))
(defun ement-tag-room (tag room session)
  "Toggle TAG for ROOM on SESSION."
  (interactive
   (ement-with-room-and-session
     (let* ((prompt (format "Toggle tag (%s): " (ement--format-room ement-room)))
            (default-tags
              (ement-alist (propertize "Favourite"
                                       'face (when (ement--room-tagged-p "m.favourite" ement-room)
                                               'transient-value))
                           "m.favourite"
                           (propertize "Low-priority"
                                       'face (when (ement--room-tagged-p "m.lowpriority" ement-room)
                                               'transient-value))
                           "m.lowpriority"))
            (input (completing-read prompt default-tags))
            (tag (alist-get input default-tags (concat "u." input) nil #'string=)))
       (list tag ement-room ement-session))))
  (pcase-let* (((cl-struct ement-session user) session)
               ((cl-struct ement-user (id user-id)) user)
               ((cl-struct ement-room (id room-id)) room)
               (endpoint (format "user/%s/rooms/%s/tags/%s"
                                 (url-hexify-string user-id) (url-hexify-string room-id) (url-hexify-string tag)))
               (method (if (ement--room-tagged-p tag room) 'delete 'put)))
    ;; TODO: "order".
    ;; FIXME: Removing a tag on a left room doesn't seem to work (e.g. to unfavorite a room after leaving it, but not forgetting it).
    (ement-api session endpoint :version "v3" :method method :data (pcase method ('put "{}"))
      :then (lambda (_)
              (ement-message "%s tag %S on %s"
                             (pcase method
                               ('delete "Removed")
                               ('put "Added"))
                             tag (ement--format-room room)) ))))
(defun ement-set-display-name (display-name session)
  "Set DISPLAY-NAME for user on SESSION.
Sets global displayname."
  (interactive
   (let* ((session (ement-complete-session))
          (display-name (read-string "Set display-name to: " nil nil
                                     (ement-user-displayname (ement-session-user session)))))
     (list display-name session)))
  (pcase-let* (((cl-struct ement-session user) session)
               ((cl-struct ement-user (id user-id)) user)
               (endpoint (format "profile/%s/displayname" (url-hexify-string user-id))))
    (ement-api session endpoint :method 'put :version "v3"
      :data (json-encode (ement-alist "displayname" display-name))
      :then (lambda (_data)
              (message "Ement: Display name set to %S for <%s>" display-name
                       (ement-user-id (ement-session-user session)))))))
(defun ement-room-set-display-name (display-name room session)
  "Set DISPLAY-NAME for user in ROOM on SESSION.
Interactively, with prefix, prompt for room and session,
otherwise use current room.  Sets the name only in ROOM, not
globally."
  (interactive
   (ement-with-room-and-session
     (let* ((prompt (format "Set display-name in %S to: "
                            (ement--format-room ement-room)))
            (display-name (read-string prompt nil nil
                                       (ement-user-displayname (ement-session-user ement-session)))))
       (list display-name ement-room ement-session))))
  ;; NOTE: This does not seem to be documented in the spec, so we imitate the
  ;; "/myroomnick" command in SlashCommands.tsx from matrix-react-sdk.
  (pcase-let* (((cl-struct ement-room state) room)
               ((cl-struct ement-session user) session)
               ((cl-struct ement-user id) user)
               (member-event (cl-find-if (lambda (event)
                                           (and (equal id (ement-event-state-key event))
                                                (equal "m.room.member" (ement-event-type event))
                                                (equal "join" (alist-get 'membership (ement-event-content event)))))
                                         state)))
    (cl-assert member-event)
    (setf (alist-get 'displayname (ement-event-content member-event)) display-name)
    (ement-put-state room "m.room.member" id (ement-event-content member-event) session
      :then (lambda (_data)
              (message "Ement: Display name set to %S for <%s> in %S" display-name
                       (ement-user-id (ement-session-user session))
                       (ement--format-room room))))))
;;;;;; Describe room
(defvar ement-describe-room-mode-map
  (let ((map (make-sparse-keymap)))
    (define-key map (kbd "q") #'quit-window)
    map)
  "Keymap for `ement-describe-room-mode' buffers.")
(define-derived-mode ement-describe-room-mode read-only-mode
  "Ement-Describe-Room" "Major mode for `ement-describe-room' buffers.")
(defun ement-describe-room (room session)
  "Describe ROOM on SESSION.
Interactively, with prefix, prompt for room and session,
otherwise use current room."
  (interactive (ement-with-room-and-session (list ement-room ement-session)))
  (cl-labels ((heading (string)
                       (propertize (or string "") 'face 'font-lock-builtin-face))
              (id (string)
                  (propertize (or string "") 'face 'font-lock-constant-face))
              (member<
               (a b) (string-collate-lessp (car a) (car b) nil t)))
    (pcase-let* (((cl-struct ement-room (id room-id) avatar display-name canonical-alias members timeline status topic
                             (local (map fetched-members-p)))
                  room)
                 ((cl-struct ement-session user) session)
                 ((cl-struct ement-user (id user-id)) user)
                 (inhibit-read-only t))
      (if (not fetched-members-p)
          ;; Members not fetched: fetch them and re-call this command.
          (ement--get-joined-members room session
            :then (lambda (_) (ement-room-describe room session)))
        (with-current-buffer (get-buffer-create (format "*Ement room description: %s*" (or display-name canonical-alias room-id)))
          (let ((inhibit-read-only t))
            (erase-buffer)
            ;; We avoid looping twice by doing a bit more work here and
            ;; returning a cons which we destructure.
            (pcase-let* ((`(,member-pairs . ,name-width)
                          (cl-loop for user being the hash-values of members
                                   for formatted = (ement--format-user user room session)
                                   for id = (format "<%s>" (id (ement-user-id user)))
                                   collect (cons formatted id)
                                   into pairs
                                   maximizing (string-width id) into width
                                   finally return (cons (cl-sort pairs #'member<) width)))
                         ;; We put the MXID first, because users may use Unicode characters
                         ;; in their displayname, which `string-width' does not always
                         ;; return perfect results for, and putting it last prevents
                         ;; alignment problems.
                         (spec (format "%%-%ss %%s" name-width)))
              (save-excursion
                (insert "\"" (propertize (or display-name canonical-alias room-id) 'face 'font-lock-doc-face) "\"" " is a room "
                        (propertize (pcase status
                                      ('invite "invited")
                                      ('join "joined")
                                      ('leave "left")
                                      (_ (symbol-name status)))
                                    'face 'font-lock-comment-face)
                        " on session <" (id user-id) ">.\n\n"
                        (heading "Avatar: ") (or avatar "") "\n\n"
                        (heading "ID: ") "<" (id room-id) ">" "\n"
                        (heading "Alias: ") "<" (id canonical-alias) ">" "\n\n"
                        (heading "Topic: ") (propertize (or topic "[none]") 'face 'font-lock-comment-face) "\n\n"
                        (heading "Retrieved events: ") (number-to-string (length timeline)) "\n"
                        (heading "  spanning: ")
                        (format-time-string "%Y-%m-%d %H:%M:%S"
                                            (/ (ement-event-origin-server-ts
                                                (car (cl-sort (copy-sequence timeline) #'< :key #'ement-event-origin-server-ts)))
                                               1000))
                        (heading " to ")
                        (format-time-string "%Y-%m-%d %H:%M:%S\n\n"
                                            (/ (ement-event-origin-server-ts
                                                (car (cl-sort (copy-sequence timeline) #'> :key #'ement-event-origin-server-ts)))
                                               1000))
                        (heading "Members") " (" (number-to-string (hash-table-count members)) "):\n")
                (pcase-dolist (`(,formatted . ,id) member-pairs)
                  (insert "  " (format spec id formatted) "\n")))))
          (unless (eq major-mode 'ement-describe-room-mode)
            ;; Without this check, activating the mode again causes a "Cyclic keymap
            ;; inheritance" error.
            (ement-describe-room-mode))
          (pop-to-buffer (current-buffer)))))))
(defalias 'ement-room-describe #'ement-describe-room)
;;;;;; Push rules
;; NOTE: Although v1.4 of the spec is available and describes setting the push rules using
;; the "v3" API endpoint, the Element client continues to use the "r0" endpoint, which is
;; slightly different.  This implementation will follow Element's initially, because the
;; spec is not simple, and imitating Element's requests will make it easier.
(defun ement-room-notification-state (room session)
  "Return notification state for ROOM on SESSION.
Returns one of nil (meaning default rules are used), `all-loud',
`all', `mentions-and-keywords', or `none'."
  ;; Following the implementation of getRoomNotifsState() in RoomNotifs.ts in matrix-react-sdk.
  ;; TODO: Guest support (in which case the state should be `all').
  ;; TODO: Store account data as a hash table of event types.
  (let ((push-rules (cl-find-if (lambda (alist)
                                  (equal "m.push_rules" (alist-get 'type alist)))
                                (ement-session-account-data session))))
    (cl-labels ((override-mute-rule-for-room-p
                 ;; Following findOverrideMuteRule() in RoomNotifs.ts.
                 (room) (when-let ((overrides (map-nested-elt push-rules '(content global override))))
                          (cl-loop for rule in overrides
                                   when (and (alist-get 'enabled rule)
                                             (rule-for-room-p rule room))
                                   return rule)))
                (rule-for-room-p
                 ;; Following isRuleForRoom() in RoomNotifs.ts.
                 (rule room) (and (/= 1 (length (alist-get 'conditions rule)))
                                  (pcase-let* ((condition (elt (alist-get 'conditions rule) 0))
                                               ((map kind key pattern) condition))
                                    (and (equal "event_match" kind)
                                         (equal "room_id" key)
                                         (equal (ement-room-id room) pattern)))))
                (mute-rule-p
                 (rule) (and (= 1 (length (alist-get 'actions rule)))
                             (equal "dont_notify" (elt (alist-get 'actions rule) 0))))
                (tweak-rule-p
                 (type rule) (pcase-let (((map ('actions `[,action ,alist])) rule))
                               (and (equal "notify" action)
                                    (equal type (alist-get 'set_tweak alist))))))
      ;; If none of these match, nil is returned, meaning that the default rule is used
      ;; for the room.
      (if (override-mute-rule-for-room-p room)
          'none
        (when-let ((room-rule (cl-find-if (lambda (rule)
                                            (equal (ement-room-id room) (alist-get 'rule_id rule)))
                                          (map-nested-elt push-rules '(content global room)))))
          (cond ((not (alist-get 'enabled room-rule))
                 ;; NOTE: According to comment in getRoomNotifsState(), this assumes that
                 ;; the default is to notify for all messages, which "will be 'wrong' for
                 ;; one to one rooms because they will notify loudly for all messages."
                 'all)
                ((mute-rule-p room-rule)
                 ;; According to comment, a room-level mute still allows mentions to
                 ;; notify.
                 'mentions-and-keywords)
                ((tweak-rule-p "sound" room-rule) 'all-loud)))))))
(defun ement-room-set-notification-state (state room session)
  "Set notification STATE for ROOM on SESSION.
Interactively, with prefix, prompt for room and session,
otherwise use current room.  STATE may be nil to set the rules to
default, `all', `mentions-and-keywords', or `none'."
  ;; This merely attempts to reproduce the behavior of Element's simple notification
  ;; options.  It does not attempt to offer all of the features defined in the spec.  And,
  ;; yes, it is rather awkward, having to sometimes* make multiple requests of different
  ;; "kinds" to set the rules for a single room, but that is how the API works.
  ;;
  ;; * It appears that Element only makes multiple requests of different kinds when
  ;; strictly necessary, but coding that logic now would seem likely to be a waste of
  ;; time, given that Element doesn't even use the latest version of the spec yet.  So
  ;; we'll just do the "dumb" thing and always send requests of both "override" and
  ;; "room" kinds, which appears to Just Work™.
  ;;
  ;; TODO: Match rules to these user-friendly notification states for presentation.  See
  ;; <https://github.com/matrix-org/matrix-react-sdk/blob/8c67984f50f985aa481df24778078030efa39001/src/RoomNotifs.ts>.
  ;; TODO: Support `all-loud' ("all_messages_loud").
  (interactive
   (ement-with-room-and-session
     (let* ((prompt (format "Set notification rules for %s: " (ement--format-room ement-room)))
            (available-states (ement-alist "Default" nil
                                           "All messages" 'all
                                           "Mentions and keywords" 'mentions-and-keywords
                                           "None" 'none))
            (selected-rule (completing-read prompt (mapcar #'car available-states) nil t))
            (state (alist-get selected-rule available-states nil nil #'equal)))
       (list state ement-room ement-session))))
  (cl-labels ((set-rule (kind rule queue message-fn)
                        (pcase-let* (((cl-struct ement-room (id room-id)) room)
                                     (rule-id (url-hexify-string room-id))
                                     (endpoint (format "pushrules/global/%s/%s" kind rule-id))
                                     (method (if rule 'put 'delete))
                                     (then (if rule
                                               ;; Setting rules requires PUTting the rules, then making a second
                                               ;; request to enable them.
                                               (lambda (_data)
                                                 (ement-api session (concat endpoint "/enabled") :queue queue :version "r0"
                                                   :method 'put :data (json-encode (ement-alist 'enabled t))
                                                   :then message-fn))
                                             message-fn)))
                          (ement-api session endpoint :queue queue :method method :version "r0"
                            :data (json-encode rule)
                            :then then
                            :else (lambda (plz-error)
                                    (pcase-let* (((cl-struct plz-error response) plz-error)
                                                 ((cl-struct plz-response status) response))
                                      (pcase status
                                        (404 (pcase rule
                                               (`nil
                                                ;; Room already had no rules, so none being found is not an
                                                ;; error.
                                                nil)
                                               (_ ;; Unexpected error: re-signal.
                                                (ement-api-error plz-error))))
                                        (_ ;; Unexpected error: re-signal.
                                         (ement-api-error plz-error)))))))))
    (pcase-let* ((available-states
                  (ement-alist
                   nil (ement-alist
                        "override" nil
                        "room" nil)
                   'all (ement-alist
                         "override" nil
                         "room" (ement-alist
                                 'actions (vector "notify" (ement-alist
                                                            'set_tweak "sound"
                                                            'value "default"))))
                   'mentions-and-keywords (ement-alist
                                           "override" nil
                                           "room" (ement-alist
                                                   'actions (vector "dont_notify")))
                   'none (ement-alist
                          "override" (ement-alist
                                      'actions (vector "dont_notify")
                                      'conditions (vector (ement-alist
                                                           'kind "event_match"
                                                           'key "room_id"
                                                           'pattern (ement-room-id room))))
                          "room" nil)))
                 (kinds-and-rules (alist-get state available-states nil nil #'equal)))
      (cl-loop with queue = (make-plz-queue :limit 1)
               with total = (1- (length kinds-and-rules))
               for count from 0
               for message-fn = (if (equal count total)
                                    (lambda (_data)
                                      (message "Set notification rules for room: %s" (ement--format-room room)))
                                  #'ignore)
               for (kind . state) in kinds-and-rules
               do (set-rule kind state queue message-fn)))))
;;;;; Public functions
;; These functions could reasonably be called by code in other packages.
(cl-defun ement-put-state
    (room type key data session
          &key (then (lambda (response-data)
                       (ement-debug "State data put on room" response-data data room session))))
  "Put state event of TYPE with KEY and DATA on ROOM on SESSION.
DATA should be an alist, which will become the JSON request
body."
  (declare (indent defun))
  (pcase-let* ((endpoint (format "rooms/%s/state/%s/%s"
                                 (url-hexify-string (ement-room-id room))
                                 type key)))
    (ement-api session endpoint :method 'put :data (json-encode data)
      ;; TODO: Handle error codes.
      :then then)))
(defun ement-message (format-string &rest args)
  "Call `message' on FORMAT-STRING prefixed with \"Ement: \"."
  ;; TODO: Use this function everywhere we use `message'.
  (apply #'message (concat "Ement: " format-string) args))
(cl-defun ement-upload (session &key data filename then else
                                (content-type "application/octet-stream"))
  "Upload DATA with FILENAME to content repository on SESSION.
THEN and ELSE are passed to `ement-api', which see."
  (declare (indent defun))
  (ement-api session "upload" :method 'post :endpoint-category "media"
    ;; NOTE: Element currently uses "r0" not "v3", so so do we.
    :params (when filename
              (list (list "filename" filename)))
    :content-type content-type :data data :data-type 'binary
    :then then :else else))
(cl-defun ement-complete-session (&key (prompt "Session: "))
  "Return an Ement session selected with completion."
  (cl-etypecase (length ement-sessions)
    ((integer 1 1) (cdar ement-sessions))
    ((integer 2 *) (let* ((ids (mapcar #'car ement-sessions))
                          (selected-id (completing-read prompt ids nil t)))
                     (alist-get selected-id ement-sessions nil nil #'equal)))
    (otherwise (user-error "No active sessions.  Call `ement-connect' to log in"))))
(declare-function ewoc-locate "ewoc")
(defun ement-complete-user-id ()
  "Return a user-id selected with completion.
Selects from seen users on all sessions.  If point is on an
event, suggests the event's sender as initial input.  Allows
unseen user IDs to be input as well."
  (cl-labels ((format-user (user)
                           ;; FIXME: Per-room displaynames are now stored in room structs
                           ;; rather than user structs, so to be complete, this needs to
                           ;; iterate over all known rooms, looking for the user's
                           ;; displayname in that room.
                           (format "%s <%s>"
                                   (ement-user-displayname user)
				   (ement-user-id user))))
    (let* ((display-to-id
	    (cl-loop for key being the hash-keys of ement-users
		     using (hash-values value)
		     collect (cons (format-user value) key)))
           (user-at-point (when (equal major-mode 'ement-room-mode)
                            (when-let ((node (ewoc-locate ement-ewoc)))
                              (when (ement-event-p (ewoc-data node))
                                (format-user (ement-event-sender (ewoc-data node)))))))
	   (selected-user (completing-read "User: " (mapcar #'car display-to-id)
                                           nil nil user-at-point)))
      (or (alist-get selected-user display-to-id nil nil #'equal)
	  selected-user))))
(cl-defun ement-put-account-data
    (session type data &key room
             (then (lambda (received-data)
                     ;; Handle echoed-back account data event (the spec does not explain this,
                     ;; but see <https://github.com/matrix-org/matrix-react-sdk/blob/675b4271e9c6e33be354a93fcd7807253bd27fcd/src/settings/handlers/AccountSettingsHandler.ts#L150>).
                     ;; FIXME: Make session account-data a map instead of a list of events.
                     (if room
                         (push received-data (ement-room-account-data room))
                       (push received-data (ement-session-account-data session)))
                     ;; NOTE: Commenting out this ement-debug form because a bug in Emacs
                     ;; causes this long string to be interpreted as the function's
                     ;; docstring and cause a too-long-docstring warning.
                     ;; (ement-debug "Account data put and received back on session %s:  PUT(json-encoded):%S  RECEIVED:%S"
                     ;;              (ement-user-id (ement-session-user session)) (json-encode data) received-data)
                     )))
  "Put account data of TYPE with DATA on SESSION.
If ROOM, put it on that room's account data.  Also handle the
echoed-back event."
  (declare (indent defun))
  (pcase-let* (((cl-struct ement-session (user (cl-struct ement-user (id user-id)))) session)
               (room-part (if room (format "/rooms/%s" (ement-room-id room)) ""))
               (endpoint (format "user/%s%s/account_data/%s" (url-hexify-string user-id) room-part type)))
    (ement-api session endpoint :method 'put :data (json-encode data)
      :then then)))
(defun ement-redact (event room session &optional reason)
  "Redact EVENT in ROOM on SESSION, optionally for REASON."
  (pcase-let* (((cl-struct ement-event (id event-id)) event)
               ((cl-struct ement-room (id room-id)) room)
               (endpoint (format "rooms/%s/redact/%s/%s"
                                 room-id event-id (ement--update-transaction-id session)))
               (content (ement-alist "reason" reason)))
    (ement-api session endpoint :method 'put :data (json-encode content)
      :then (lambda (_data)
              (message "Event %s redacted." event-id)))))
;;;;; Inline functions
(defsubst ement--user-color (user)
  "Return USER's color, setting it if necessary.
USER is an `ement-user' struct."
  (or (ement-user-color user)
      (setf (ement-user-color user)
            (ement--prism-color (ement-user-id user)))))
;;;;; Private functions
;; These functions aren't expected to be called by code in other packages (but if that
;; were necessary, they could be renamed accordingly).
;; (defun ement--room-routing (room)
;;   "Return a list of servers to route to ROOM through."
;;   ;; See <https://spec.matrix.org/v1.2/appendices/#routing>.
;;   ;; FIXME: Ensure highest power level user is at least level 50.
;;   ;; FIXME: Ignore servers blocked due to server ACLs.
;;   ;; FIXME: Ignore servers which are IP addresses.
;;   (cl-labels ((most-powerful-user-in
;;                (room))
;;               (servers-by-population-in
;;                (room))
;;               (server-of (user)))
;;     (let (first-server-by-power-level)
;;       (delete-dups
;;        (remq nil
;;              (list
;;               ;; 1.
;;               (or (when-let ((user (most-powerful-user-in room)))
;;                     (setf first-server-by-power-level t)
;;                     (server-of user))
;;                   (car (servers-by-population-in room)))
;;               ;; 2.
;;               (if first-server-by-power-level
;;                   (car (servers-by-population-in room))
;;                 (cl-second (servers-by-population-in room)))
;;               ;; 3.
;;               (cl-third (servers-by-population-in room))))))))
(defun ement--room-space-p (room)
  "Return non-nil if ROOM is a space."
  (equal "m.space" (ement-room-type room)))
(defun ement--room-in-space-p (room space)
  "Return non-nil if ROOM is in SPACE on SESSION."
  ;; We could use `ement---room-spaces', but since that returns rooms by looking them up
  ;; by ID in the session's rooms list, this is more efficient.
  (pcase-let* (((cl-struct ement-room (id parent-id) (local (map children))) space)
               ((cl-struct ement-room (id child-id) (local (map parents))) room))
    (or (member parent-id parents)
        (member child-id children))))
(defun ement--room-spaces (room session)
  "Return list of ROOM's parent spaces on SESSION."
  ;; NOTE: This only looks in the room's parents list; it doesn't look in every space's children
  ;; list.  This should be good enough, assuming we add to the lists correctly elsewhere.
  (pcase-let* (((cl-struct ement-session rooms) session)
               ((cl-struct ement-room (local (map parents))) room))
    (cl-remove-if-not (lambda (session-room-id)
                        (member session-room-id parents))
                      rooms :key #'ement-room-id)))
(cl-defun ement--prism-color (string &key (contrast-with (face-background 'default nil 'default)))
  "Return a computed color for STRING.
The color is adjusted to have sufficient contrast with the color
CONTRAST-WITH (by default, the default face's background).  The
computed color is useful for user messages, generated room
avatars, etc."
  ;; TODO: Use this instead of `ement-room--user-color'.  (Same algorithm ,just takes a
  ;; string as argument.)
  ;; TODO: Try using HSV somehow so we could avoid having so many strings return a
  ;; nearly-black color.
  (cl-labels ((relative-luminance
               ;; Copy of `modus-themes-wcag-formula', an elegant
               ;; implementation by Protesilaos Stavrou.  Also see
               ;; <https://en.wikipedia.org/wiki/Relative_luminance> and
               ;; <https://www.w3.org/TR/WCAG20/#relativeluminancedef>.
               (rgb) (cl-loop for k in '(0.2126 0.7152 0.0722)
                              for x in rgb
                              sum (* k (if (<= x 0.03928)
                                           (/ x 12.92)
                                         (expt (/ (+ x 0.055) 1.055) 2.4)))))
              (contrast-ratio
               ;; Copy of `modus-themes-contrast'; see above.
               (a b) (let ((ct (/ (+ (relative-luminance a) 0.05)
                                  (+ (relative-luminance b) 0.05))))
                       (max ct (/ ct))))
              (increase-contrast
               (color against target toward)
               (let ((gradient (cdr (color-gradient color toward 20)))
                     new-color)
                 (cl-loop do (setf new-color (pop gradient))
                          while new-color
                          until (>= (contrast-ratio new-color against) target)
                          ;; Avoid infinite loop in case of weirdness
                          ;; by returning color as a fallback.
                          finally return (or new-color color)))))
    (let* ((id string)
           (id-hash (float (+ (abs (sxhash id)) ement-room-prism-color-adjustment)))
           ;; TODO: Wrap-around the value to get the color I want.
           (ratio (/ id-hash (float most-positive-fixnum)))
           (color-num (round (* (* 255 255 255) ratio)))
           (color-rgb (list (/ (float (logand color-num 255)) 255)
                            (/ (float (lsh (logand color-num 65280) -8)) 255)
                            (/ (float (lsh (logand color-num 16711680) -16)) 255)))
           (contrast-with-rgb (color-name-to-rgb contrast-with)))
      (when (< (contrast-ratio color-rgb contrast-with-rgb) ement-room-prism-minimum-contrast)
        (setf color-rgb (increase-contrast color-rgb contrast-with-rgb ement-room-prism-minimum-contrast
                                           (color-name-to-rgb
                                            ;; Ideally we would use the foreground color,
                                            ;; but in some themes, like Solarized Dark,
                                            ;; the foreground color's contrast is too low
                                            ;; to be effective as the value to increase
                                            ;; contrast against, so we use white or black.
                                            (pcase contrast-with
                                              ((or `nil "unspecified-bg")
                                               ;; The `contrast-with' color (i.e. the
                                               ;; default background color) is nil.  This
                                               ;; probably means that we're displaying on
                                               ;; a TTY.
                                               (if (fboundp 'frame--current-backround-mode)
                                                   ;; This function can tell us whether
                                                   ;; the background color is dark or
                                                   ;; light, but it was added in Emacs
                                                   ;; 28.1.
                                                   (pcase (frame--current-backround-mode (selected-frame))
                                                     ('dark "white")
                                                     ('light "black"))
                                                 ;; Pre-28.1: Since faces' colors may be
                                                 ;; "unspecified" on TTY frames, in which
                                                 ;; case we have nothing to compare with, we
                                                 ;; assume that the background color of such
                                                 ;; a frame is black and increase contrast
                                                 ;; toward white.
                                                 "white"))
                                              (_
                                               ;; The `contrast-with` color is usable: test it.
                                               (if (ement--color-dark-p (color-name-to-rgb contrast-with))
                                                   "white" "black")))))))
      (apply #'color-rgb-to-hex (append color-rgb (list 2))))))
(cl-defun ement--format-user (user &optional (room ement-room) (session ement-session))
  "Format `ement-user' USER for ROOM on SESSION.
ROOM defaults to the value of `ement-room'."
  (let ((face (cond ((equal (ement-user-id (ement-session-user session))
                            (ement-user-id user))
                     'ement-room-self)
                    (ement-room-prism
                     `(:inherit ement-room-user :foreground ,(or (ement-user-color user)
                                                                 (setf (ement-user-color user)
                                                                       (ement--prism-color user)))))
                    (t 'ement-room-user))))
    ;; FIXME: If a membership state event has not yet been received, this
    ;; sets the display name in the room to the user ID, and that prevents
    ;; the display name from being used if the state event arrives later.
    (propertize (ement--user-displayname-in room user)
                'face face
                'help-echo (ement-user-id user))))
(cl-defun ement--format-body-mentions
    (body room &key (template "<a href=\"https://matrix.to/#/%s\">%s</a>"))
  "Return string for BODY with mentions in ROOM linkified with TEMPLATE.
TEMPLATE is a format string in which the first \"%s\" is replaced
with the user's MXID and the second with the displayname.  A
mention is qualified by an \"@\"-prefixed displayname or
MXID (optionally suffixed with a colon), or a colon-suffixed
displayname, followed by a blank, question mark, comma, or
period, anywhere in the body."
  ;; Examples:
  ;; "@foo: hi"
  ;; "@foo:matrix.org: hi"
  ;; "foo: hi"
  ;; "@foo and @bar:matrix.org: hi"
  ;; "foo: how about you and @bar ..."
  (declare (indent defun))
  (cl-labels ((members-having-displayname
               ;; Iterating over the hash table values isn't as efficient as a hash
               ;; lookup, but in most rooms it shouldn't be a problem.
               (name members) (cl-loop for user being the hash-values of members
                                       when (equal name (ement--user-displayname-in room user))
                                       collect user)))
    (pcase-let* (((cl-struct ement-room members) room)
                 (regexp (rx (or bos bow (1+ blank))
                             (or (seq (group
                                       ;; Group 1: full @-prefixed MXID.
                                       "@" (group
                                            ;; Group 2: displayname.  (NOTE: Does not work
                                            ;; with displaynames containing spaces.)
                                            (1+ (seq (optional ".") alnum)))
                                       (optional ":" (1+ (seq (optional ".") alnum))))
                                      (or ":" eow eos (syntax punctuation)))
                                 (seq (group
                                       ;; Group 3: MXID username or displayname.
                                       (1+ (not blank)))
                                      ":" (1+ blank)))))
                 (pos 0) (replace-group) (replacement))
      (while (setf pos (string-match regexp body pos))
        (if (setf replacement
                  (or (when-let (member (gethash (match-string 1 body) members))
                        ;; Found user ID: use it as replacement.
                        (setf replace-group 1)
                        (format template (match-string 1 body)
                                (ement--xml-escape-string (ement--user-displayname-in room member))))
                      (when-let* ((name (or (when (match-string 2 body)
                                              (setf replace-group 1)
                                              (match-string 2 body))
                                            (prog1 (match-string 3 body)
                                              (setf replace-group 3))))
                                  (members (members-having-displayname name members))
                                  (member (when (= 1 (length members))
                                            ;; If multiple members are found with the same
                                            ;; displayname, do nothing.
                                            (car members))))
                        ;; Found displayname: use it and MXID as replacement.
                        (format template (ement-user-id member)
                                (ement--xml-escape-string name)))))
            (progn
              ;; Found member: replace and move to end of replacement.
              (setf body (replace-match replacement t t body replace-group))
              (let ((difference (- (length replacement) (length (match-string 0 body)))))
                (setf pos (if (/= 0 difference)
                              ;; Replacement of a different length: adjust POS accordingly.
                              (+ pos difference)
                            (match-end 0)))))
          ;; No replacement: move to end of match.
          (setf pos (match-end 0))))))
  body)
(defun ement--event-mentions-room-p (event &rest _ignore)
  "Return non-nil if EVENT mentions \"@room\"."
  (pcase-let (((cl-struct ement-event (content (map body))) event))
    (when body
      (string-match-p (rx (or space bos) "@room" eow) body))))
(cl-defun ement-complete-room (&key session (predicate #'identity)
                                    (prompt "Room: ") (suggest t))
  "Return a (room session) list selected from SESSION with completion.
If SESSION is nil, select from rooms in all of `ement-sessions'.
When SUGGEST, suggest current buffer's room (or a room at point
in a room list buffer) as initial input (i.e. it should be set to
nil when switching from one room buffer to another).  PROMPT may
override the default prompt.  PREDICATE may be a function to
select which rooms are offered; it is also applied to the
suggested room."
  (declare (indent defun))
  (pcase-let* ((sessions (if session
                             (list session)
                           (mapcar #'cdr ement-sessions)))
               (name-to-room-session
                (cl-loop for session in sessions
                         append (cl-loop for room in (ement-session-rooms session)
                                         when (funcall predicate room)
                                         collect (cons (ement--format-room room 'topic)
                                                       (list room session)))))
               (names (mapcar #'car name-to-room-session))
               (selected-name (completing-read
                               prompt names nil t
                               (when suggest
                                 (when-let ((suggestion (ement--room-at-point)))
                                   (when (or (not predicate)
                                             (funcall predicate suggestion))
                                     (ement--format-room suggestion 'topic)))))))
    (alist-get selected-name name-to-room-session nil nil #'string=)))
(cl-defun ement-send-message (room session
                                   &key body formatted-body replying-to-event filter then)
  "Send message to ROOM on SESSION with BODY and FORMATTED-BODY.
THEN may be a function to call after the event is sent
successfully.  It is called with keyword arguments for ROOM,
SESSION, CONTENT, and DATA.
REPLYING-TO-EVENT may be an event the message is
in reply to; the message will reference it appropriately.
FILTER may be a function through which to pass the message's
content object before sending (see,
e.g. `ement-room-send-org-filter')."
  (declare (indent defun))
  (cl-assert (not (string-empty-p body)))
  (cl-assert (or (not formatted-body) (not (string-empty-p formatted-body))))
  (pcase-let* (((cl-struct ement-room (id room-id)) room)
               (endpoint (format "rooms/%s/send/m.room.message/%s" (url-hexify-string room-id)
                                 (ement--update-transaction-id session)))
               (formatted-body (when formatted-body
                                 (ement--format-body-mentions formatted-body room)))
               (content (ement-aprog1
                            (ement-alist "msgtype" "m.text"
                                         "body" body)
                          (when formatted-body
                            (push (cons "formatted_body" formatted-body) it)
                            (push (cons "format" "org.matrix.custom.html") it))))
               (then (or then #'ignore)))
    (when filter
      (setf content (funcall filter content room)))
    (when replying-to-event
      (setf content (ement--add-reply content replying-to-event room)))
    (ement-api session endpoint :method 'put :data (json-encode content)
      :then (apply-partially then :room room :session session
                             ;; Data is added when calling back.
                             :content content :data))))
(defalias 'ement--button-buttonize
  ;; FIXME: This doesn't set the mouse-face to highlight, and it doesn't use the
  ;; default-button category.  Neither does `button-buttonize', of course, but why?
  (if (version< emacs-version "28.1")
      (lambda (string callback &optional data)
        "Make STRING into a button and return it.
When clicked, CALLBACK will be called with the DATA as the
function argument.  If DATA isn't present (or is nil), the button
itself will be used instead as the function argument."
        (propertize string
                    'face 'button
                    'button t
                    'follow-link t
                    'category t
                    'button-data data
                    'keymap button-map
                    'action callback))
    #'button-buttonize))
(defun ement--add-reply (data replying-to-event room)
  "Return DATA adding reply data for REPLYING-TO-EVENT in ROOM.
DATA is an unsent message event's data alist."
  ;; SPEC: <https://matrix.org/docs/spec/client_server/r0.6.1#id351> "13.2.2.6.1  Rich replies"
  ;; FIXME: Rename DATA.
  (pcase-let* (((cl-struct ement-event (id replying-to-event-id)
                           content (sender replying-to-sender))
                replying-to-event)
               ((cl-struct ement-user (id replying-to-sender-id)) replying-to-sender)
               ((map ('body replying-to-body) ('formatted_body replying-to-formatted-body)) content)
               (replying-to-sender-name (ement--user-displayname-in ement-room replying-to-sender))
               (quote-string (format "> <%s> %s\n\n" replying-to-sender-name replying-to-body))
               (reply-body (alist-get "body" data nil nil #'string=))
               (reply-formatted-body (alist-get "formatted_body" data nil nil #'string=))
               (reply-body-with-quote (concat quote-string reply-body))
               (reply-formatted-body-with-quote
                (format "<mx-reply>
  <blockquote>
    <a href=\"https://matrix.to/#/%s/%s\">In reply to</a>
    <a href=\"https://matrix.to/#/%s\">%s</a>
    <br />
    %s
  </blockquote>
</mx-reply>
%s"
                        (ement-room-id room) replying-to-event-id replying-to-sender-id replying-to-sender-name
                        ;; TODO: Encode HTML special characters.  Not as straightforward in Emacs as one
                        ;; might hope: there's `web-mode-html-entities' and `org-entities'.  See also
                        ;; <https://emacs.stackexchange.com/questions/8166/encode-non-html-characters-to-html-equivalent>.
                        (or replying-to-formatted-body replying-to-body)
                        (or reply-formatted-body reply-body))))
    ;; NOTE: map-elt doesn't work with string keys, so we use `alist-get'.
    (setf (alist-get "body" data nil nil #'string=) reply-body-with-quote
          (alist-get "formatted_body" data nil nil #'string=) reply-formatted-body-with-quote
          data (append (ement-alist "m.relates_to"
                                    (ement-alist "m.in_reply_to"
                                                 (ement-alist "event_id" replying-to-event-id))
                                    "format" "org.matrix.custom.html")
                       data))
    data))
(defun ement--direct-room-for-user (user session)
  "Return last-modified direct room with USER on SESSION, if one exists."
  ;; Loosely modeled on the Element function findDMForUser in createRoom.ts.
  (cl-labels ((membership-event-for-p
               (event user) (and (equal "m.room.member" (ement-event-type event))
                                 (equal (ement-user-id user) (ement-event-state-key event))))
              (latest-membership-for
               (user room)
               (when-let ((latest-membership-event
                           (car
                            (cl-sort
                             ;; I guess we need to check both state and timeline events.
                             (append (cl-remove-if-not (lambda (event)
                                                         (membership-event-for-p event user))
                                                       (ement-room-state room))
                                     (cl-remove-if-not (lambda (event)
                                                         (membership-event-for-p event user))
                                                       (ement-room-timeline room)))
                             (lambda (a b)
                               ;; Sort latest first so we can use the car.
                               (> (ement-event-origin-server-ts a)
                                  (ement-event-origin-server-ts b)))))))
                 (alist-get 'membership (ement-event-content latest-membership-event))))
              (latest-event-in
               (room) (car
                       (cl-sort
                        (append (ement-room-state room)
                                (ement-room-timeline room))
                        (lambda (a b)
                          ;; Sort latest first so we can use the car.
                          (> (ement-event-origin-server-ts a)
                             (ement-event-origin-server-ts b)))))))
    (let* ((direct-rooms (cl-remove-if-not
                          (lambda (room)
                            (ement--room-direct-p room session))
                          (ement-session-rooms session)))
           (direct-joined-rooms
            ;; Ensure that the local user is still in each room.
            (cl-remove-if-not
             (lambda (room)
               (equal "join" (latest-membership-for (ement-session-user session) room)))
             direct-rooms))
           ;; Since we don't currently keep a member list for each room, we look in the room's
           ;; join events to see if the user has joined or been invited.
           (direct-rooms-with-user
            (cl-remove-if-not
             (lambda (room)
               (member (latest-membership-for user room) '("invite" "join")))
             direct-joined-rooms)))
      (car (cl-sort direct-rooms-with-user
                    (lambda (a b)
                      (> (latest-event-in a) (latest-event-in b))))))))
(defun ement--event-replaces-p (a b)
  "Return non-nil if event A replaces event B.
That is, if event A replaces B in their
\"m.relates_to\"/\"m.relations\" and \"m.replace\" metadata."
  (pcase-let* (((cl-struct ement-event (id a-id)
                           (content (map ('m.relates_to
                                          (map ('rel_type a-rel-type)
                                               ('event_id a-replaces-event-id))))))
                a)
               ((cl-struct ement-event (id b-id)
                           ;; Not sure why this ends up in the unsigned key, but it does.
                           (unsigned (map ('m.relations
                                           (map ('m.replace
                                                 (map ('event_id b-replaced-by-event-id))))))))
                b))
    (or (and (equal "m.replace" a-rel-type)
             (equal a-replaces-event-id b-id))
        (equal a-id b-replaced-by-event-id))))
(defun ement--events-equal-p (a b)
  "Return non-nil if events A and B are essentially equal.
That is, A and B are either the same event (having the same event
ID), or one event replaces the other (in their m.relates_to and
m.replace metadata)."
  (or (equal (ement-event-id a) (ement-event-id b))
      (ement--event-replaces-p a b)
      (ement--event-replaces-p b a)))
(defun ement--format-room (room &optional topic)
  "Return ROOM formatted with name, alias, ID, and optionally TOPIC.
Suitable for use in completion, etc."
  (if topic
      (format "%s%s(<%s>)%s"
              (or (ement-room-display-name room)
                  (setf (ement-room-display-name room)
                        (ement--room-display-name room)))
              (if (ement-room-canonical-alias room)
                  (format " <%s> " (ement-room-canonical-alias room))
                " ")
              (ement-room-id room)
              (if (ement-room-topic room)
                  (format ": \"%s\"" (ement-room-topic room))
                ""))
    (format "%s%s(<%s>)"
            (or (ement-room-display-name room)
                (setf (ement-room-display-name room)
                      (ement--room-display-name room)))
            (if (ement-room-canonical-alias room)
                (format " <%s> " (ement-room-canonical-alias room))
              " ")
            (ement-room-id room))))
(defun ement--members-alist (room)
  "Return alist of member displaynames mapped to IDs seen in ROOM."
  ;; We map displaynames to IDs because `ement-room--format-body-mentions' needs to find
  ;; MXIDs from displaynames.
  (pcase-let* (((cl-struct ement-room timeline) room)
               (members-seen (mapcar #'ement-event-sender timeline))
               (members-alist))
    (dolist (member members-seen)
      ;; Testing with `benchmark-run-compiled', it appears that using `cl-pushnew' is
      ;; about 10x faster than using `delete-dups'.
      (cl-pushnew (cons (ement--user-displayname-in room member)
                        (ement-user-id member))
                  members-alist))
    members-alist))
(defun ement--mxc-to-url (uri session)
  "Return HTTPS URL for MXC URI accessed through SESSION."
  (pcase-let* (((cl-struct ement-session server) session)
               ((cl-struct ement-server uri-prefix) server)
               (server-name) (media-id))
    (string-match (rx "mxc://" (group (1+ (not (any "/"))))
                      "/" (group (1+ anything))) uri)
    (setf server-name (match-string 1 uri)
          media-id (match-string 2 uri))
    (format "%s/_matrix/media/r0/download/%s/%s"
            uri-prefix server-name media-id)))
(defun ement--remove-face-property (string value)
  "Remove VALUE from STRING's `face' properties.
Used to remove the `button' face from buttons, because that face
can cause undesirable underlining."
  (let ((pos 0))
    (cl-loop for next-face-change-pos = (next-single-property-change pos 'face string)
             for face-at = (get-text-property pos 'face string)
             when face-at
             do (put-text-property pos (or next-face-change-pos (length string))
                                   'face (cl-typecase face-at
                                           (atom (if (equal value face-at)
                                                     nil face-at))
                                           (list (remove value face-at)))
                                   string)
             while next-face-change-pos
             do (setf pos next-face-change-pos))))
(defun ement--resize-image (image max-width max-height)
  "Return a copy of IMAGE set to MAX-WIDTH and MAX-HEIGHT.
IMAGE should be one as created by, e.g. `create-image'."
  ;; It would be nice if the image library had some simple functions to do this sort of thing.
  (let ((new-image (cl-copy-list image)))
    (when (fboundp 'imagemagick-types)
      ;; Only do this when ImageMagick is supported.
      ;; FIXME: When requiring Emacs 27+, remove this (I guess?).
      (setf (image-property new-image :type) 'imagemagick))
    (setf (image-property new-image :max-width) max-width
          (image-property new-image :max-height) max-height)
    new-image))
(defun ement--room-alias (room)
  "Return latest m.room.canonical_alias event in ROOM."
  ;; FIXME: This function probably needs to compare timestamps to ensure that older events
  ;; that are inserted at the head of the events lists aren't used instead of newer ones.
  (or (cl-loop for event in (ement-room-timeline room)
               when (equal "m.room.canonical_alias" (ement-event-type event))
               return (alist-get 'alias (ement-event-content event)))
      (cl-loop for event in (ement-room-state room)
               when (equal "m.room.canonical_alias" (ement-event-type event))
               return (alist-get 'alias (ement-event-content event)))))
(declare-function magit-current-section "magit-section")
(declare-function eieio-oref "eieio-core")
(defun ement--room-at-point ()
  "Return room at point.
Works in major-modes `ement-room-mode',
`ement-tabulated-room-list-mode', and `ement-room-list-mode'."
  (pcase major-mode
    ('ement-room-mode ement-room)
    ('ement-tabulated-room-list-mode (tabulated-list-get-id))
    ('ement-room-list-mode
     (cl-typecase (oref (magit-current-section) value)
       (taxy-magit-section nil)
       (t (pcase (oref (magit-current-section) value)
            (`[,room ,_session] room)))))))
(defun ement--room-direct-p (room session)
  "Return non-nil if ROOM on SESSION is a direct chat."
  (cl-labels ((content-contains-room-id
               (content room-id) (cl-loop for (_user-id . room-ids) in content
                                          ;; NOTE: room-ids is a vector.
                                          thereis (seq-contains-p room-ids room-id))))
    (pcase-let* (((cl-struct ement-session account-data) session)
                 ((cl-struct ement-room id) room))
      (or (cl-loop for event in account-data
                   when (equal "m.direct" (alist-get 'type event))
                   thereis (content-contains-room-id (alist-get 'content event) id))
          (cl-loop
           ;; Invited rooms have no account-data yet, and their
           ;; directness flag is in invite-state events.
           for event in (ement-room-invite-state room)
           thereis (alist-get 'is_direct (ement-event-content event)))))))
(defun ement--room-display-name (room)
  "Return the displayname for ROOM."
  ;; SPEC: <https://matrix.org/docs/spec/client_server/r0.6.1#calculating-the-display-name-for-a-room>.
  ;; NOTE: The spec seems incomplete, because the algorithm it recommends does not say how
  ;; or when to use "m.room.member" events for rooms without heroes (e.g. invited rooms).
  ;; TODO: Add SESSION argument and use it to remove local user from names.
  (cl-labels ((latest-event (type content-field)
                            (or (cl-loop for event in (ement-room-timeline room)
                                         when (and (equal type (ement-event-type event))
                                                   (not (string-empty-p (alist-get content-field (ement-event-content event)))))
                                         return (alist-get content-field (ement-event-content event)))
                                (cl-loop for event in (ement-room-state room)
                                         when (and (equal type (ement-event-type event))
                                                   (not (string-empty-p (alist-get content-field (ement-event-content event)))))
                                         return (alist-get content-field (ement-event-content event)))))
              (member-events-name
               () (when-let ((member-events (cl-loop for accessor in '(ement-room-timeline ement-room-state ement-room-invite-state)
                                                     append (cl-remove-if-not (apply-partially #'equal "m.room.member")
                                                                              (funcall accessor room)
                                                                              :key #'ement-event-type))))
                    (string-join (delete-dups
                                  (mapcar (lambda (event)
                                            (ement--user-displayname-in room (ement-event-sender event)))
                                          member-events))
                                 ", ")))
              (heroes-name
               () (pcase-let* (((cl-struct ement-room summary) room)
                               ((map ('m.heroes hero-ids) ('m.joined_member_count joined-count)
                                     ('m.invited_member_count invited-count))
                                summary))
                    ;; TODO: Disambiguate hero display names.
                    (when hero-ids
                      (cond ((<= (+ joined-count invited-count) 1)
                             ;; Empty room.
                             (empty-room hero-ids joined-count))
                            ((>= (length hero-ids) (1- (+ joined-count invited-count)))
                             ;; Members == heroes.
                             (hero-names hero-ids))
                            ((and (< (length hero-ids) (1- (+ joined-count invited-count)))
                                  (> (+ joined-count invited-count) 1))
                             ;; More members than heroes.
                             (heroes-and-others hero-ids joined-count))))))
              (hero-names
               (heroes) (string-join (mapcar #'hero-name heroes) ", "))
              (hero-name
               (id) (if-let ((user (gethash id ement-users)))
                        (ement--user-displayname-in room user)
                      id))
              (heroes-and-others
               (heroes joined)
               (format "%s, and %s others" (hero-names heroes)
                       (- joined (length heroes))))
              (name-override
               () (when-let ((event (alist-get "org.matrix.msc3015.m.room.name.override"
                                               (ement-room-account-data room)
                                               nil nil #'equal)))
                    (map-nested-elt event '(content name))))
              (empty-room
               (heroes joined) (cl-etypecase (length heroes)
                                 ((satisfies zerop) "Empty room")
                                 ((number 1 5) (format "Empty room (was %s)"
                                                       (hero-names heroes)))
                                 (t (format "Empty room (was %s)"
                                            (heroes-and-others heroes joined))))))
    (or (name-override)
        (latest-event "m.room.name" 'name)
        (latest-event "m.room.canonical_alias" 'alias)
        (heroes-name)
        (member-events-name)
        (ement-room-id room))))
(defun ement--room-favourite-p (room)
  "Return non-nil if ROOM is tagged as favourite."
  (ement--room-tagged-p "m.favourite" room))
(defun ement--room-low-priority-p (room)
  "Return non-nil if ROOM is tagged as low-priority."
  (ement--room-tagged-p "m.lowpriority" room))
(defun ement--room-tagged-p (tag room)
  "Return non-nil if ROOM has TAG."
  ;; TODO: Use `make-ement-event' on account-data events.
  (pcase-let* (((cl-struct ement-room account-data) room)
               (tag-event (alist-get "m.tag" account-data nil nil #'equal)))
    (when tag-event
      (pcase-let (((map ('content (map tags))) tag-event))
        (cl-typecase tag
          ;; Tags are symbols internally, because `json-read' converts map keys to them.
          (string (setf tag (intern tag))))
        (assoc tag tags)))))
(defun ement--room-unread-p (room session)
  "Return non-nil if ROOM is considered unread for SESSION.
The room is unread if it has a modified, live buffer; if it has
non-zero unread notification counts; or if its fully-read marker
is not at the latest known message event."
  ;; Roughly equivalent to the "red/gray/bold/idle" states listed in
  ;; <https://github.com/matrix-org/matrix-react-sdk/blob/b0af163002e8252d99b6d7075c83aadd91866735/docs/room-list-store.md#list-ordering-algorithm-importance>.
  (pcase-let* (((cl-struct ement-room timeline account-data unread-notifications receipts
                           (local (map buffer)))
                room)
               ((cl-struct ement-session user) session)
               ((cl-struct ement-user (id our-id)) user)
               ((map notification_count highlight_count) unread-notifications)
               (fully-read-event-id (map-nested-elt (alist-get "m.fully_read" account-data nil nil #'equal)
                                                    '(content event_id))))
    ;; MAYBE: Ignore whether the buffer is modified.  Since we have a better handle on how
    ;; Matrix does notifications/unreads/highlights, maybe that's not needed, and it would
    ;; be more consistent to ignore it.
    (or (and buffer (buffer-modified-p buffer))
        (and unread-notifications
             (or (not (zerop notification_count))
                 (not (zerop highlight_count))))
        ;; NOTE: This is *WAY* too complicated, but it seems roughly equivalent to doesRoomHaveUnreadMessages() from
        ;; <https://github.com/matrix-org/matrix-react-sdk/blob/7fa01ffb068f014506041bce5f02df4f17305f02/src/Unread.ts#L52>.
        (when (and (not ement-room-unread-only-counts-notifications)
                   timeline)
          ;; A room should rarely, if ever, have a nil timeline, but in case it does
          ;; (which apparently can happen, given user reports), it should not be
          ;; considered unread.
          (cl-labels ((event-counts-toward-unread-p
                       ;; NOTE: We only consider message events, so membership, reaction,
                       ;; etc. events will not mark a room as unread.  Ideally, I think
                       ;; that join/leave events should, at least optionally, mark a room
                       ;; as unread (e.g. in a 1:1 room with a friend, if the other user
                       ;; left, one would probably want to know, and marking the room
                       ;; unread would help the user notice), but since membership events
                       ;; have to be processed to understand their meaning, it's not
                       ;; straightforward to know whether one should mark a room unread.
                       ;; FIXME: Use code from `ement-room--format-member-event' to
                       ;; distinguish ones that should count.
                       (event) (equal "m.room.message" (ement-event-type event))))
            (let ((our-read-receipt-event-id (car (gethash our-id receipts)))
                  (first-counting-event (cl-find-if #'event-counts-toward-unread-p timeline)))
              (cond ((equal fully-read-event-id (ement-event-id (car timeline)))
                     ;; The fully-read marker is at the last known event: the room is read.
                     nil)
                    ((and (not our-read-receipt-event-id)
                          (when first-counting-event
                            (and (not (equal fully-read-event-id (ement-event-id first-counting-event)))
                                 (not (equal our-id (ement-user-id (ement-event-sender first-counting-event)))))))
                     ;; The room has no read receipt, and the latest message event is not
                     ;; the event at which our fully-read marker is at, and it is not sent
                     ;; by us: the room is unread.  (This is a kind of failsafe to ensure
                     ;; the user doesn't miss any messages, but it's unclear whether this
                     ;; is really correct or best.)
                     t)
                    ((equal our-id (ement-user-id (ement-event-sender (car timeline))))
                     ;; We sent the last event: the room is read.
                     nil)
                    ((and first-counting-event
                          (equal our-id (ement-user-id (ement-event-sender first-counting-event))))
                     ;; We sent the last message event: the room is read.
                     nil)
                    ((cl-loop for event in timeline
                              when (event-counts-toward-unread-p event)
                              return (and (not (equal our-read-receipt-event-id (ement-event-id event)))
                                          (not (equal fully-read-event-id (ement-event-id event)))))
                     ;; The latest message event is not the event at which our
                     ;; read-receipt or fully-read marker are at: the room is unread.
                     t))))))))
(defun ement--update-transaction-id (session)
  "Return SESSION's incremented transaction ID formatted for sending.
Increments ID and appends current timestamp to avoid reuse
problems."
  ;; TODO: Naming things is hard.
  ;; In the event that Emacs isn't killed cleanly and the session isn't saved to disk, the
  ;; transaction ID would get reused the next time the user connects.  To avoid that, we
  ;; append the current time to the ID.  (IDs are just strings, and Element does something
  ;; similar, so this seems reasonable.)
  (format "%s-%s"
          (cl-incf (ement-session-transaction-id session))
          (format-time-string "%s")))
(defun ement--user-displayname-in (room user)
  "Return the displayname for USER in ROOM."
  ;; SPEC: <https://matrix.org/docs/spec/client_server/r0.6.1#calculating-the-display-name-for-a-user>.
  ;; FIXME: Add step 3 of the spec.  For now we skip to step 4.
  ;; NOTE: Both state and timeline events must be searched.  (A helpful user
  ;; in #matrix-dev:matrix.org, Michael (t3chguy), clarified this for me).
  (if-let ((cached-name (gethash user (ement-room-displaynames room))))
      cached-name
    ;; Put timeline events before state events, because IIUC they should be more recent.
    (cl-labels ((join-displayname-event-p
                 (event) (and (eq user (ement-event-sender event))
                              (equal "m.room.member" (ement-event-type event))
                              (equal "join" (alist-get 'membership (ement-event-content event)))
                              (alist-get 'displayname (ement-event-content event)))))
      ;; FIXME: Should probably sort the relevant events to get the latest one.
      (if-let* ((displayname (or (cl-loop for event in (ement-room-timeline room)
                                          when (join-displayname-event-p event)
                                          return (alist-get 'displayname (ement-event-content event)))
                                 (cl-loop for event in (ement-room-state room)
                                          when (join-displayname-event-p event)
                                          return (alist-get 'displayname (ement-event-content event)))))
                (calculated-name displayname))
          (puthash user calculated-name (ement-room-displaynames room))
        ;; No membership state event: use pre-calculated displayname or ID.
        (or (ement-user-displayname user)
            (ement-user-id user))))))
(defun ement--xml-escape-string (string)
  "Return STRING having been escaped with `xml-escape-string'.
Before Emacs 28, ignores `xml-invalid-character' errors (and any
invalid characters cause STRING to remain unescaped).  After
Emacs 28, uses the NOERROR argument to `xml-escape-string'."
  (condition-case _
      (xml-escape-string string 'noerror)
    (wrong-number-of-arguments
     (condition-case _
         (xml-escape-string string)
       (xml-invalid-character
        ;; We still don't want to error on this, so just return the string.
        string)))))
(defun ement--mark-room-direct (room session)
  "Mark ROOM on SESSION as a direct room.
This may be used to mark rooms as direct which, for whatever
reason (like a bug in your favorite client), were not marked as
such when they were created."
  (pcase-let* (((cl-struct ement-room timeline (id room-id)) room)
               ((cl-struct ement-session (user local-user)) session)
               ((cl-struct ement-user (id local-user-id)) local-user)
               (direct-rooms-account-data-event-content
                (alist-get 'content
                           (cl-find-if (lambda (event)
                                         (equal "m.direct" (alist-get 'type event)))
                                       (ement-session-account-data session))))
               (members (delete-dups (mapcar #'ement-event-sender timeline)))
               (other-users (cl-remove local-user-id members
                                       :key #'ement-user-id :test #'equal))
               ((cl-struct ement-user (id other-user-id)) (car other-users))
               ;; The alist keys are MXIDs as symbols.
               (other-user-id (intern other-user-id))
               (existing-direct-rooms-for-user (map-elt direct-rooms-account-data-event-content other-user-id)))
    (cl-assert (= 1 (length other-users)))
    (setf (map-elt direct-rooms-account-data-event-content other-user-id)
          (cl-coerce (append existing-direct-rooms-for-user (list room-id))
                     'vector))
    (ement-put-account-data session "m.direct" direct-rooms-account-data-event-content
      :then (lambda (_data)
              (message "Ement: Room <%s> marked as direct for <%s>." room-id other-user-id)))
    (message "Ement: Marking room as direct...")))
(cl-defun ement--get-joined-members (room session &key then else)
  "Get joined members in ROOM on SESSION and call THEN with response data.
Or call ELSE with error data if request fails.  Also puts members
on `ement-users', updating their displayname and avatar URL
slots, and puts them on ROOM's `members' table."
  (declare (indent defun))
  (pcase-let* (((cl-struct ement-room id members) room)
               (endpoint (format "rooms/%s/joined_members" (url-hexify-string id))))
    (ement-api session endpoint
      :else else
      :then (lambda (data)
              (clrhash members)
              (mapc (lambda (member)
                      (pcase-let* ((`(,id-symbol
                                      . ,(map ('avatar_url avatar-url)
                                              ('display_name display-name)))
                                    member)
                                   (member-id (symbol-name id-symbol))
                                   (user (or (gethash member-id ement-users)
                                             (puthash member-id (make-ement-user :id member-id)
                                                      ement-users))))
                        (setf (ement-user-displayname user) display-name
                              (ement-user-avatar-url user) avatar-url)
                        (puthash member-id user members)))
                    (alist-get 'joined data))
              (setf (alist-get 'fetched-members-p (ement-room-local room)) t)
              (when then
                ;; Finally, call the given callback.
                (funcall then data))))
    (message "Ement: Getting joined members in %s..." (ement--format-room room))))
(cl-defun ement--human-format-duration (seconds &optional abbreviate)
  "Return human-formatted string describing duration SECONDS.
If SECONDS is less than 1, returns \"0 seconds\".  If ABBREVIATE
is non-nil, return a shorter version, without spaces.  This is a
simple calculation that does not account for leap years, leap
seconds, etc."
  ;; Copied from `ts-human-format-duration' (same author).
  (if (< seconds 1)
      (if abbreviate "0s" "0 seconds")
    (cl-macrolet ((format> (place)
                           ;; When PLACE is greater than 0, return formatted string using its symbol name.
                           `(when (> ,place 0)
                              (format "%d%s%s" ,place
                                      (if abbreviate "" " ")
                                      (if abbreviate
                                          ,(substring (symbol-name place) 0 1)
                                        ,(symbol-name place)))))
                  (join-places (&rest places)
                               ;; Return string joining the names and values of PLACES.
                               `(string-join (delq nil
                                                   (list ,@(cl-loop for place in places
                                                                    collect `(format> ,place))))
                                             (if abbreviate "" ", "))))
      (pcase-let ((`(,years ,days ,hours ,minutes ,seconds) (ement--human-duration seconds)))
        (join-places years days hours minutes seconds)))))
(defun ement--human-duration (seconds)
  "Return list describing duration SECONDS.
List includes years, days, hours, minutes, and seconds.  This is
a simple calculation that does not account for leap years, leap
seconds, etc."
  ;; Copied from `ts-human-format-duration' (same author).
  (cl-macrolet ((dividef (place divisor)
                         ;; Divide PLACE by DIVISOR, set PLACE to the remainder, and return the quotient.
                         `(prog1 (/ ,place ,divisor)
                            (setf ,place (% ,place ,divisor)))))
    (let* ((seconds (floor seconds))
           (years (dividef seconds 31536000))
           (days (dividef seconds 86400))
           (hours (dividef seconds 3600))
           (minutes (dividef seconds 60)))
      (list years days hours minutes seconds))))
;;; Footer
(provide 'ement-lib)
;;; ement-lib.el ends here

;;; ement-macros.el --- Ement macros                 -*- lexical-binding: t; -*-
;; Copyright (C) 2022  Free Software Foundation, Inc.
;; Author: Adam Porter <adam@alphapapa.net>
;; Maintainer: Adam Porter <adam@alphapapa.net>
;; This program is free software; you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation, either version 3 of the License, or
;; (at your option) any later version.
;; This program is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;; GNU General Public License for more details.
;; You should have received a copy of the GNU General Public License
;; along with this program.  If not, see <https://www.gnu.org/licenses/>.
;;; Commentary:
;;
;;; Code:
;;;; Requirements
(require 'map)
;;;; Debugging
(require 'warnings)
;; NOTE: Uncomment this form and `emacs-lisp-byte-compile-and-load' the file to enable
;; `ement-debug' messages.  This is commented out by default because, even though the
;; messages are only displayed when `warning-minimum-log-level' is `:debug' at runtime, if
;; that is so at expansion time, the expanded macro calls format the message and check the
;; log level at runtime, which is not zero-cost.
;; (eval-and-compile
;;   (setq-local warning-minimum-log-level nil)
;;   (setq-local warning-minimum-log-level :debug))
(cl-defmacro ement-debug (&rest args)
  "Display a debug warning showing the runtime value of ARGS.
The warning automatically includes the name of the containing
function, and it is only displayed if `warning-minimum-log-level'
is `:debug' at expansion time (otherwise the macro expands to a
call to `ignore' with ARGS and is eliminated by the
byte-compiler).  When debugging, the form also returns nil so,
e.g. it may be used in a conditional in place of nil.
Each of ARGS may be a string, which is displayed as-is, or a
symbol, the value of which is displayed prefixed by its name, or
a Lisp form, which is displayed prefixed by its first symbol.
Before the actual ARGS arguments, you can write keyword
arguments, i.e. alternating keywords and values.  The following
keywords are supported:
  :buffer BUFFER   Name of buffer to pass to `display-warning'.
  :level  LEVEL    Level passed to `display-warning', which see.
                   Default is :debug."
  ;; TODO: Can we use a compiler macro to handle this more elegantly?
  (pcase-let* ((fn-name (when byte-compile-current-buffer
                          (with-current-buffer byte-compile-current-buffer
                            ;; This is a hack, but a nifty one.
                            (save-excursion
                              (beginning-of-defun)
                              (cl-second (read (current-buffer)))))))
               (plist-args (cl-loop while (keywordp (car args))
                                    collect (pop args)
                                    collect (pop args)))
               ((map (:buffer buffer) (:level level)) plist-args)
               (level (or level :debug))
               (string (cl-loop for arg in args
                                concat (pcase arg
                                         ((pred stringp) "%S ")
                                         ((pred symbolp)
                                          (concat (upcase (symbol-name arg)) ":%S "))
                                         ((pred listp)
                                          (concat "(" (upcase (symbol-name (car arg)))
                                                  (pcase (length arg)
                                                    (1 ")")
                                                    (_ "...)"))
                                                  ":%S "))))))
    (if (eq :debug warning-minimum-log-level)
        `(let ((fn-name ,(if fn-name
                             `',fn-name
                           ;; In an interpreted function: use `backtrace-frame' to get the
                           ;; function name (we have to use a little hackery to figure out
                           ;; how far up the frame to look, but this seems to work).
                           `(cl-loop for frame in (backtrace-frames)
                                     for fn = (cl-second frame)
                                     when (not (or (subrp fn)
                                                   (special-form-p fn)
                                                   (eq 'backtrace-frames fn)))
                                     return (make-symbol (format "%s [interpreted]" fn))))))
           (display-warning fn-name (format ,string ,@args) ,level ,buffer)
           nil)
      `(ignore ,@args))))
;;;; Macros
(defmacro ement-alist (&rest pairs)
  "Expand to an alist of the keys and values in PAIRS."
  `(list ,@(cl-loop for (key value) on pairs by #'cddr
                    collect `(cons ,key ,value))))
;;;;; Anaphoric
;; We could just depend on dash.el and use --first, and anaphora.el (only
;; on MELPA, not ELPA) has aprog1, but in order to reduce dependencies...
(defmacro ement-afirst (form list)
  ;; Sometimes checkdoc is really annoying.  If I use "FORM returns" or
  ;; "FORM evaluates", it complains, so I can't have a clean linting.
  "Return the first element of LIST for which FORM is non-nil.
In FORM, `it' is bound to the element being tested."
  (declare (indent 1))
  `(cl-loop for it in ,list
            ;; Avoid the `when' clause's implicit binding of `it'.
            do (when ,form
                 (cl-return it))))
(defmacro ement-aprog1 (first &rest body)
  "Like `prog1', but FIRST's value is bound to `it' around BODY."
  (declare (indent 1))
  `(let ((it ,first))
     ,@body
     it))
(defmacro ement-singly (place-form &rest body)
  "If PLACE-FORM is nil, set it non-nil and eval BODY.
BODY should set PLACE-FORM to nil when BODY is eligible to run
again."
  (declare (indent defun))
  `(unless ,place-form
     (setf ,place-form t)
     ,@body))
;;;;; Progress reporters
;; MAYBE: Submit a `with-progress-reporter' macro to Emacs.
(defalias 'ement-progress-update #'ignore
  "By default, this function does nothing.  But inside
`ement-with-progress-reporter', it's bound to a function that
updates the current progress reporter.")
(defmacro ement-with-progress-reporter (args &rest body)
  "Eval BODY with a progress reporter according to ARGS.
ARGS is a plist of these values:
  :when  If specified, a form evaluated at runtime to determine
         whether to make and update a progress reporter.  If not
         specified, the reporter is always made and updated.
  :reporter  A list of arguments passed to
             `make-progress-reporter', which see.
Around BODY, the function `ement-progress-update' is set to a
function that calls `progress-reporter-update' on the progress
reporter (or if the :when form evaluates to nil, the function is
set to `ignore').  It optionally takes a VALUE argument, and
without one, it automatically updates the value from the
reporter's min-value to its max-value."
  (declare (indent defun))
  (pcase-let* ((progress-reporter-sym (gensym))
               (progress-value-sym (gensym))
               (start-time-sym (gensym))
               ((map (:when when-form) (:reporter reporter-args)) args)
               (`(,_message ,min-value ,_max-value) reporter-args)
               (update-fn `(cl-function
                            (lambda (&optional (value (cl-incf ,progress-value-sym)))
                              (ement-debug "Updating progress reporter to" value)
                              (progress-reporter-update ,progress-reporter-sym value)))))
    `(let* ((,start-time-sym (current-time))
            (,progress-value-sym (or ,min-value 0))
            (,progress-reporter-sym ,(if when-form
                                         `(when ,when-form
                                            (make-progress-reporter ,@reporter-args))
                                       `(make-progress-reporter ,@reporter-args))))
       ;; We use `cl-letf' rather than `cl-labels', because labels expand to lambdas and funcalls,
       ;; so other functions that call `ement-progress-update' wouldn't call this definition.
       (cl-letf (((symbol-function 'ement-progress-update)
                  ,(if when-form
                       `(if ,when-form
                            ,update-fn
                          #'ignore)
                     update-fn)))
         ,@body
         (ement-debug (format "Ement: Progress reporter done (took %.2f seconds)"
                              (float-time (time-subtract (current-time) ,start-time-sym))))))))
;;;;; Room-related macros
;; Prevent compiler from complaining that `value' is an unknown slot.
(require 'magit-section)
(cl-defmacro ement-with-room-and-session (&rest body)
  "Eval BODY with `ement-room' and `ement-session' bound.
If in an `ement-room-list-mode' buffer and `current-prefix-arg'
is nil, use the room and session at point.  If in an `ement-room'
buffer and `current-prefix-arg' is nil, use buffer-local value of
`ement-room' and `ement-session'.  Otherwise, prompt for them
with `ement-complete-room' or that given with :prompt-form.
BODY may begin with property list arguments, including:
  :prompt-form  A Lisp form evaluated for the binding of
                `ement-room'."
  (declare (indent defun))
  (pcase-let* ((plist (cl-loop while (keywordp (car body))
                               append (list (car body) (cadr body))
                               and do (setf body (cddr body))))
               (prompt-form (or (plist-get plist :prompt-form)
                                '(ement-complete-room :suggest t))))
    `(pcase-let* ((`[,list-room ,list-session] (if (eq 'ement-room-list-mode major-mode)
                                                   (oref (magit-current-section) value)
                                                 [nil nil]))
                  (ement-room (or list-room ement-room))
                  (ement-session (or list-session ement-session)))
       (when (or current-prefix-arg (not ement-room))
         (pcase-let ((`(,room ,session) ,prompt-form))
           (setf ement-room room
                 ement-session session)))
       ,@body)))
;;;; Variables
;;;; Customization
;;;; Commands
;;;; Functions
;;;; Footer
(provide 'ement-macros)
;;; ement-macros.el ends here

;;; ement-notify.el --- Notifications for Ement events  -*- lexical-binding: t; -*-
;; Copyright (C) 2022  Free Software Foundation, Inc.
;; Author: Adam Porter <adam@alphapapa.net>
;; Maintainer: Adam Porter <adam@alphapapa.net>
;; This program is free software; you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation, either version 3 of the License, or
;; (at your option) any later version.
;; This program is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;; GNU General Public License for more details.
;; You should have received a copy of the GNU General Public License
;; along with this program.  If not, see <https://www.gnu.org/licenses/>.
;;; Commentary:
;; This library implements notifications for Ement events.
;;; Code:
;;;; Requirements
(require 'cl-lib)
(require 'map)
(require 'notifications)
(require 'ement-lib)
(require 'ement-room)
(eval-when-compile
  (require 'ement-structs))
;;;; Variables
(declare-function ement-room-list "ement-room-list")
(defvar ement-notify-mode-map
  (let ((map (make-sparse-keymap)))
    (define-key map (kbd "S-<return>") #'ement-notify-reply)
    (define-key map (kbd "M-g M-l") #'ement-room-list)
    (define-key map (kbd "M-g M-m") #'ement-notify-switch-to-mentions-buffer)
    (define-key map (kbd "M-g M-n") #'ement-notify-switch-to-notifications-buffer)
    (make-composed-keymap (list map button-buffer-map) 'view-mode-map))
  "Map for Ement notification buffers.")
(defvar ement-notify-dbus-p
  (and (featurep 'dbusbind)
       (require 'dbus nil :no-error)
       (dbus-ignore-errors (dbus-get-unique-name :session))
       ;; By default, emacs waits up to 25 seconds for a PONG.  Realistically, if there's
       ;; no pong after 2000ms, there's pretty sure no notification service connected or
       ;; the system's setup has issues.
       (dbus-ping :session "org.freedesktop.Notifications" 2000))
  "Whether D-Bus notifications are usable.")
;;;; Customization
(defgroup ement-notify nil
  "Notification options."
  :group 'ement)
(defcustom ement-notify-ignore-predicates
  '(ement-notify--event-not-message-p ement-notify--event-from-session-user-p)
  "Display notification if none of these return non-nil for an event.
Each predicate is called with three arguments: the event, the
room, and the session (each the respective struct)."
  :type '(repeat (choice (function-item ement-notify--event-not-message-p)
                         (function-item ement-notify--event-from-session-user-p)
                         (function :tag "Custom predicate"))))
(defcustom ement-notify-log-predicates
  '(ement-notify--event-mentions-session-user-p
    ement-notify--event-mentions-room-p
    ement-notify--room-buffer-live-p
    ement-notify--room-unread-p)
  "Predicates to determine whether to log an event to the notifications buffer.
If one of these returns non-nil for an event, the event is logged."
  :type 'hook
  :options '(ement-notify--event-mentions-session-user-p
             ement-notify--event-mentions-room-p
             ement-notify--room-buffer-live-p
             ement-notify--room-unread-p))
(defcustom ement-notify-mark-frame-urgent-predicates
  '(ement-notify--event-mentions-session-user-p
    ement-notify--event-mentions-room-p)
  "Predicates to determine whether to mark a frame as urgent.
If one of these returns non-nil for an event, the frame that most
recently showed the event's room's buffer is marked
urgent.  (Only works on X, not other GUI platforms.)"
  :type 'hook
  :options '(ement-notify--event-mentions-session-user-p
             ement-notify--event-mentions-room-p))
(defcustom ement-notify-mention-predicates
  '(ement-notify--event-mentions-session-user-p
    ement-notify--event-mentions-room-p)
  "Predicates to determine whether to log an event to the mentions buffer.
If one of these returns non-nil for an event, the event is logged."
  :type 'hook
  :options '(ement-notify--event-mentions-session-user-p
             ement-notify--event-mentions-room-p))
(defcustom ement-notify-notification-predicates
  '(ement-notify--event-mentions-session-user-p
    ement-notify--event-mentions-room-p
    ement-notify--room-buffer-live-p
    ement-notify--room-unread-p)
  "Predicates to determine whether to send a desktop notification.
If one of these returns non-nil for an event, the notification is sent."
  :type 'hook
  :options '(ement-notify--event-mentions-session-user-p
             ement-notify--event-mentions-room-p
             ement-notify--room-buffer-live-p
             ement-notify--room-unread-p))
(defcustom ement-notify-sound nil
  "Sound to play for notifications."
  :type '(choice (file :tag "Sound file")
                 (string :tag "XDG sound name")
                 (const :tag "Default XDG message sound" "message-new-instant")
                 (const :tag "Don't play a sound" nil)))
(defcustom ement-notify-limit-room-name-width nil
  "Limit the width of room display names in mentions and notifications buffers.
This prevents the margin from being made excessively wide."
  :type '(choice (integer :tag "Maximum width")
                 (const :tag "Unlimited width" nil)))
(defcustom ement-notify-prism-background nil
  "Add distinct background color by room to messages in notification buffers.
The color is specific to each room, generated automatically, and
can help distinguish messages by room."
  :type 'boolean)
(defcustom ement-notify-room-avatars t
  "Show room avatars in the notifications buffers.
This shows room avatars at the left of the window margin in
notification buffers.  It's not customizeable beyond that due to
limitations and complexities of displaying strings and images in
margins in Emacs.  But it's useful, anyway."
  :type 'boolean)
;;;; Commands
(declare-function ement-room-goto-event "ement-room")
(defun ement-notify-button-action (button)
  "Show BUTTON's event in its room buffer."
  ;; TODO: Is `interactive' necessary here?
  (interactive)
  (let* ((session (button-get button 'session))
         (room (button-get button 'room))
         (event (button-get button 'event)))
    (ement-view-room room session)
    (ement-room-goto-event event)))
(defun ement-notify-reply ()
  "Send a reply to event at point."
  (interactive)
  (save-window-excursion
    ;; Not sure why `call-interactively' doesn't work for `push-button' but oh well.
    (push-button)
    (call-interactively #'ement-room-write-reply)))
(defun ement-notify-switch-to-notifications-buffer ()
  "Switch to \"*Ement Notifications*\" buffer."
  (interactive)
  (switch-to-buffer (ement-notify--log-buffer "*Ement Notifications*")))
(defun ement-notify-switch-to-mentions-buffer ()
  "Switch to \"*Ement Mentions*\" buffer."
  (interactive)
  (switch-to-buffer (ement-notify--log-buffer "*Ement Mentions*")))
;;;; Functions
(defun ement-notify (event room session)
  "Send notifications for EVENT in ROOM on SESSION.
Sends if all of `ement-notify-ignore-predicates' return nil.
Does not do anything if session hasn't finished initial sync."
  (when (and (ement-session-has-synced-p session)
             (cl-loop for pred in ement-notify-ignore-predicates
                      never (funcall pred event room session)))
    (when (and ement-notify-dbus-p
               (run-hook-with-args-until-success 'ement-notify-notification-predicates event room session))
      (ement-notify--notifications-notify event room session))
    (when (run-hook-with-args-until-success 'ement-notify-log-predicates event room session)
      (ement-notify--log-to-buffer event room session))
    (when (run-hook-with-args-until-success 'ement-notify-mention-predicates event room session)
      (ement-notify--log-to-buffer event room session :buffer-name "*Ement Mentions*"))
    (when (run-hook-with-args-until-success 'ement-notify-mark-frame-urgent-predicates event room session)
      (ement-notify--mark-frame-urgent event room session))))
(defun ement-notify--mark-frame-urgent (_event room _session)
  "Mark frame showing ROOM's buffer as urgent.
If ROOM has no existing buffer, do nothing."
  (cl-labels ((mark-frame-urgent
               (frame) (let* ((prop "WM_HINTS")
                              (hints (cl-coerce
                                      (x-window-property prop frame prop nil nil t)
                                      'list)))
                         (setf (car hints) (logior (car hints) 256))
                         (x-change-window-property prop hints nil prop 32 t))))
    (when-let* ((buffer (alist-get 'buffer (ement-room-local room)))
                (frames (cl-loop for frame in (frame-list)
                                 when (eq 'x (framep frame))
                                 collect frame))
                (frame (pcase (length frames)
                         (1 (car frames))
                         (_
                          ;; Use the frame that most recently showed ROOM's buffer.
                          (car (sort frames
                                     (lambda (frame-a frame-b)
                                       (let ((a-pos (cl-position buffer (buffer-list frame-a)))
                                             (b-pos (cl-position buffer (buffer-list frame-b))))
                                         (cond ((and a-pos b-pos)
                                                (< a-pos b-pos))
                                               (a-pos)
                                               (b-pos))))))))))
      (mark-frame-urgent frame))))
(defun ement-notify--notifications-notify (event room _session)
  "Call `notifications-notify' for EVENT in ROOM on SESSION."
  (pcase-let* (((cl-struct ement-event sender content) event)
               ((cl-struct ement-room avatar (display-name room-displayname)) room)
               ((map body) content)
               (room-name (or room-displayname (ement--room-display-name room)))
               (sender-name (ement--user-displayname-in room sender))
               (title (format "%s in %s" sender-name room-name)))
    ;; TODO: Encode HTML entities.
    (when (stringp body)
      ;; If event has no body, it was probably redacted or something, so don't notify.
      (truncate-string-to-width body 60)
      (notifications-notify :title title :body body
                            :app-name "Ement.el"
                            :app-icon (when avatar
                                        (ement-notify--temp-file
                                         (plist-get (cdr (get-text-property 0 'display avatar)) :data)))
                            :category "im.received"
                            :timeout 5000
                            ;; FIXME: Using :sound-file seems to do nothing, ever.  Maybe a bug in notifications-notify?
                            :sound-file (when (and ement-notify-sound
                                                   (file-name-absolute-p ement-notify-sound))
                                          ement-notify-sound)
                            :sound-name (when (and ement-notify-sound
                                                   (not (file-name-absolute-p ement-notify-sound)))
                                          ement-notify-sound)
                            ;; TODO: Show when action used.
                            ;; :actions '("default" "Show")
                            ;; :on-action #'ement-notify-show
                            ))))
(cl-defun ement-notify--temp-file (content &key (timeout 5))
  "Return a filename holding CONTENT, and delete it after TIMEOUT seconds."
  (let ((filename (make-temp-file "ement-notify--temp-file-"))
        (coding-system-for-write 'no-conversion))
    (with-temp-file filename
      (insert content))
    (run-at-time timeout nil (lambda ()
                               (delete-file filename)))
    filename))
(define-derived-mode ement-notify-mode ement-room-mode "Ement Notify"
  (setf ement-room-sender-in-left-margin nil
        left-margin-width 0
        right-margin-width 8)
  (setq-local ement-room-message-format-spec "[%o%O] %S> %B%R%t"
              bookmark-make-record-function #'ement-notify-bookmark-make-record))
(cl-defun ement-notify--log-to-buffer (event room session &key (buffer-name "*Ement Notifications*"))
  "Log EVENT in ROOM on SESSION to \"*Ement Notifications*\" buffer."
  (with-demoted-errors "ement-notify--log-to-buffer: %S"
    ;; HACK: We only log "m.room.message" events for now.  This shouldn't be necessary
    ;; since we have `ement-notify--event-message-p' in `ement-notify-predicates', but
    ;; just to be safe...
    (when (equal "m.room.message" (ement-event-type event))
      (with-current-buffer (ement-notify--log-buffer buffer-name)
        (let* ((ement-session session)
               (ement-room room)
               (ement-room-sender-in-left-margin nil)
               (ement-room-message-format-spec "%o%O »%W %S> %B%R%t")
               (new-node (ement-room--insert-event event))
               (inhibit-read-only t)
               start end)
          (ewoc-goto-node ement-ewoc new-node)
          (setf start (point))
          (if-let (next-node (ewoc-next ement-ewoc new-node))
              (ewoc-goto-node ement-ewoc next-node)
            (goto-char (point-max)))
          (setf end (- (point) 2))
          (add-text-properties start end
                               (list 'button '(t)
                                     'category 'default-button
                                     'action #'ement-notify-button-action
                                     'session session
                                     'room room
                                     'event event))
          ;; Remove button face property.
          (alter-text-property start end 'face
                               (lambda (face)
                                 (pcase face
                                   ('button nil)
                                   ((pred listp) (remq 'button face))
                                   (_ face))))
          (when ement-notify-prism-background
            (add-face-text-property start end (list :background (ement-notify--room-background-color room)
                                                    :extend t))))))))
(defun ement-notify--log-buffer (name)
  "Return an Ement notifications buffer named NAME."
  (or (get-buffer name)
      (with-current-buffer (get-buffer-create name)
        (ement-notify-mode)
        (current-buffer))))
(defun ement-notify--room-background-color (room)
  "Return a background color on which to display ROOM's messages."
  (or (alist-get 'notify-background-color (ement-room-local room))
      (setf (alist-get 'notify-background-color (ement-room-local room))
            (let ((color (color-desaturate-name
                          (ement--prism-color (ement-room-id room) :contrast-with (face-foreground 'default))
                          50)))
              (if (ement--color-dark-p (color-name-to-rgb (face-background 'default)))
                  (color-darken-name color 25)
                (color-lighten-name color 25))))))
;;;;; Predicates
(defun ement-notify--event-mentions-session-user-p (event room session)
  "Return non-nil if EVENT in ROOM mentions SESSION's user.
If EVENT's sender is SESSION's user, returns nil."
  (pcase-let* (((cl-struct ement-session user) session)
               ((cl-struct ement-event sender) event))
    (unless (equal (ement-user-id user) (ement-user-id sender))
      (ement-room--event-mentions-user-p event user room))))
(defun ement-notify--room-buffer-live-p (_event room _session)
  "Return non-nil if ROOM has a live buffer."
  (buffer-live-p (alist-get 'buffer (ement-room-local room))))
(defun ement-notify--room-unread-p (_event room _session)
  "Return non-nil if ROOM has unread notifications.
According to the room's notification configuration on the server."
  (pcase-let* (((cl-struct ement-room unread-notifications) room)
               ((map notification_count highlight_count) unread-notifications))
    (not (and (equal 0 notification_count)
              (equal 0 highlight_count)))))
(defun ement-notify--event-message-p (event _room _session)
  "Return non-nil if EVENT is an \"m.room.message\" event."
  (equal "m.room.message" (ement-event-type event)))
(defun ement-notify--event-not-message-p (event _room _session)
  "Return non-nil if EVENT is not an \"m.room.message\" event."
  (not (equal "m.room.message" (ement-event-type event))))
(defun ement-notify--event-from-session-user-p (event _room session)
  "Return non-nil if EVENT is sent by SESSION's user."
  (equal (ement-user-id (ement-session-user session))
         (ement-user-id (ement-event-sender event))))
(defalias 'ement-notify--event-mentions-room-p #'ement--event-mentions-room-p)
;;;; Bookmark support
;; Especially useful with Burly: <https://github.com/alphapapa/burly.el>
(require 'bookmark)
(defun ement-notify-bookmark-make-record ()
  "Return a bookmark record for the current `ement-notify' buffer."
  (list (buffer-name)
        ;; It seems silly to have to record the buffer name twice, but the
        ;; `bookmark-make-record' function seems to override the bookmark name sometimes,
        ;; which makes the result useless unless we save the buffer name separately.
        (cons 'buffer-name (buffer-name))
        (cons 'handler #'ement-notify-bookmark-handler)))
(defun ement-notify-bookmark-handler (bookmark)
  "Show Ement notifications buffer for BOOKMARK."
  (pcase-let ((`(,_bookmark-name . ,(map buffer-name)) bookmark))
    (switch-to-buffer (ement-notify--log-buffer buffer-name))))
;;;; Footer
(provide 'ement-notify)
;;; ement-notify.el ends here