262 lines
9.3 KiB
EmacsLisp
262 lines
9.3 KiB
EmacsLisp
;;; etherpad.el --- etherpad API -*- coding: utf-8; lexical-binding: t -*-
|
|
|
|
;; Copyright 2020 FoAM
|
|
;;
|
|
;; Author: nik gaffney <nik@fo.am>
|
|
;; Created: 2020-08-08
|
|
;; Version: 0.1
|
|
;; Package-Requires: ((emacs "26.1") (request "0.3") (let-alist "0.0"))
|
|
;; Keywords: etherpad, collaborative editing,
|
|
;; URL: https://github.com/zzkt/etherpad-emacs
|
|
|
|
;; This file is not part of GNU Emacs.
|
|
|
|
;; 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:
|
|
|
|
;; Etherpad is a highly customizable Open Source online editor providing
|
|
;; collaborative editing in really real-time.
|
|
;;
|
|
;; This package enables read-write access to pads on an Etherpad server
|
|
;; as if they were filelike but is not (yet) suitable for use as a
|
|
;; collaborative Etherpad client.
|
|
;;
|
|
;; details -> https://etherpad.org/doc/v1.8.5/#index_http_api
|
|
|
|
|
|
;; known bugs, limitations, shortcomings, etc
|
|
;; - doesn't do realtime editing
|
|
;; - the server and api key could be buffer local to enable editing on more than one server
|
|
;; - doesn't automate API interface generation from openapi.json
|
|
;; - not much in the way of error checking or recovery
|
|
;; - etc
|
|
|
|
|
|
;;; Code:
|
|
|
|
(require 'request)
|
|
(require 'let-alist)
|
|
(require 'cl-lib)
|
|
|
|
(defgroup etherpad nil
|
|
"Etherpad edits."
|
|
:prefix "etherpad-"
|
|
:group 'external)
|
|
|
|
(defcustom etherpad-apikey "request an API key"
|
|
"API key for the etherpad server."
|
|
:type 'string)
|
|
|
|
(defcustom etherpad-server "https://example.org"
|
|
"URL of the etherpad server."
|
|
:type 'string)
|
|
|
|
(defcustom etherpad-autosync nil
|
|
"Sync with etherpad server whenever the local buffer changes."
|
|
:type 'boolean)
|
|
|
|
(defcustom etherpad-idlesync nil
|
|
"Sync with etherpad server whenever auto-save is triggered."
|
|
:type 'boolean)
|
|
|
|
(defun etherpad-openapi ()
|
|
"Find API details using openAPI endpoint.
|
|
Should be available at http://<host>/api/1/openapi.json"
|
|
(interactive)
|
|
(request
|
|
(format "%s/api/1/openapi.json" etherpad-server)
|
|
:sync t
|
|
:parser 'json-read
|
|
:success (cl-function
|
|
(lambda (&key data &allow-other-keys)
|
|
(message "200: %s" data)))
|
|
:error (cl-function
|
|
(lambda (&rest args &key error-thrown &allow-other-keys)
|
|
(message "etherpad API error: %s" error-thrown)))))
|
|
|
|
|
|
(defun etherpad--api-pad-revision (pad-id)
|
|
"Current revision number for the pad with PAD-ID."
|
|
(catch 'rev
|
|
(request
|
|
(format "%s/api/1/getRevisionsCount?padID=%s&apikey=%s" etherpad-server pad-id etherpad-apikey)
|
|
:sync t
|
|
:parser 'json-read
|
|
:success (cl-function
|
|
(lambda (&key data &allow-other-keys)
|
|
(let-alist data (throw 'rev .data.revisions))))
|
|
:error (cl-function
|
|
(lambda (&rest args &key error-thrown &allow-other-keys)
|
|
(error "Etherpad API error: %s" error-thrown))))))
|
|
|
|
|
|
(defun etherpad--api-get-text (pad-id)
|
|
"Get the text of a pad with PAD-ID."
|
|
(catch 'text
|
|
(request
|
|
(format "%s/api/1/getText?padID=%s&apikey=%s" etherpad-server pad-id etherpad-apikey)
|
|
:sync t
|
|
:parser 'json-read
|
|
:success (cl-function
|
|
(lambda (&key data &allow-other-keys)
|
|
(let-alist data (throw 'text .data.text))))
|
|
:error (cl-function
|
|
(lambda (&rest args &key error-thrown &allow-other-keys)
|
|
(error "Etherpad API error: %s" error-thrown))))))
|
|
|
|
|
|
(defun etherpad--api-set-text (pad-id text)
|
|
"Overwrite the contents of the pad PAD-ID with some TEXT."
|
|
(request
|
|
(format "%s/api/1/setText" etherpad-server)
|
|
:type: "POST"
|
|
:data `(("apikey" . ,etherpad-apikey) ("padID" . ,pad-id) ("text" . ,text))
|
|
:parser 'json-read
|
|
:success (cl-function
|
|
(lambda (&key data &allow-other-keys)
|
|
(message "written to %s: %s" pad-id text)))
|
|
:error (cl-function
|
|
(lambda (&rest args &key error-thrown &allow-other-keys)
|
|
(error "Etherpad API error: %s" error-thrown)))))
|
|
|
|
|
|
|
|
;;;###autoload
|
|
(defun etherpad-edit (&optional pad-id)
|
|
"Edit a pad with the given PAD-ID."
|
|
(interactive "sName of the pad to edit: ")
|
|
;; note: check if pad-id exists and/or create new pad as required
|
|
(let* ((pad-remote-revision (etherpad--api-pad-revision pad-id))
|
|
(pad-buffer (get-buffer-create (format "%s:%s at %s" pad-id pad-remote-revision etherpad-server)))
|
|
(pad-text (etherpad--api-get-text pad-id)))
|
|
(with-current-buffer pad-buffer
|
|
(setq-local pad-name pad-id
|
|
pad-revision (etherpad--api-pad-revision pad-id))
|
|
(goto-char (point-min))
|
|
(erase-buffer)
|
|
(insert pad-text)
|
|
(message (format "opening pad: %s rev: %s" pad-name pad-revision))
|
|
(goto-char (point-max))
|
|
(display-buffer pad-buffer)
|
|
(make-local-variable 'etherpad-autosync)
|
|
(when etherpad-autosync (etherpad-autosync-enable))
|
|
(when etherpad-idlesync (etherpad-idlesync-enable)))
|
|
(set-buffer pad-buffer)))
|
|
|
|
|
|
(defun etherpad-update (&optional pad-id)
|
|
"Update current buffer with text from a remote pad (PAD-ID)."
|
|
(interactive "sName of the pad to sync from: ")
|
|
(when (not pad-id) (setq pad-id pad-name))
|
|
(message (format "pad-id: %s pad-name: %s (buffer local)" pad-id pad-name))
|
|
;; note: check if pad-id exists and/or create new pad as required
|
|
(let* ((pad-remote-revision (etherpad--api-pad-revision pad-id))
|
|
(pad-buffer (current-buffer))
|
|
(pad-text (etherpad--api-get-text pad-id)))
|
|
(with-current-buffer pad-buffer
|
|
(setq-local pad-name pad-id
|
|
pad-revision pad-remote-revision)
|
|
(rename-buffer (format "%s:%s at %s" pad-name pad-revision etherpad-server))
|
|
(goto-char (point-min))
|
|
(erase-buffer)
|
|
(insert pad-text)
|
|
(message (format "synced from pad: %s rev: %s" pad-name pad-revision))
|
|
(goto-char (point-max))
|
|
(display-buffer pad-buffer)
|
|
pad-buffer)))
|
|
|
|
|
|
;;;###autoload
|
|
(defun etherpad-save ()
|
|
"Write a buffer to an etherpad.
|
|
'pad-name' and 'pad-revision' are buffer local"
|
|
(interactive)
|
|
;; show diffs, merge, update, etc+
|
|
;; and save...
|
|
(message (format "preparing to write %s revision %s (from '%s')" pad-name (1+ pad-revision) (current-buffer)))
|
|
;; check for version drift & update revision
|
|
(let* ((remote-revision (etherpad--api-pad-revision pad-name))
|
|
(local-revision pad-revision))
|
|
(if (> remote-revision local-revision)
|
|
(when (y-or-n-p
|
|
(format "Text is out of sync with pad on the server (revision %s > %s) resync? "
|
|
remote-revision local-revision))
|
|
(etherpad-update pad-name))
|
|
(progn
|
|
(etherpad--api-set-text pad-name (buffer-string))
|
|
(message (format "wrote to pad: %s revision %s" pad-name (etherpad--api-pad-revision pad-name)))
|
|
(setq pad-revision (etherpad--api-pad-revision pad-name))
|
|
(message (format "new revision? %s" pad-revision))
|
|
(rename-buffer (format "%s:%s at %s" pad-name pad-revision etherpad-server))
|
|
(message (format "pad has been synced (at revision %s)" pad-revision))))))
|
|
|
|
|
|
(defun etherpad-before-change-function (begin end)
|
|
"Function to run before etherpad update (buffer BEGIN and END).
|
|
should be specific to minor mode and buffer local."
|
|
(let* ((remote-revision (etherpad--api-pad-revision pad-name))
|
|
(local-revision pad-revision))
|
|
(when (> remote-revision local-revision)
|
|
(etherpad-update))))
|
|
|
|
(defun etherpad-after-change-function (begin end length)
|
|
"Function to run after buuffer has changed (buffer BEGIN, END & LENGTH).
|
|
should be specific to minor mode and buffer local."
|
|
(etherpad-save))
|
|
|
|
(defun etherpad-autosync-toggle ()
|
|
"Toggle autosync."
|
|
(interactive)
|
|
(if etherpad-autosync
|
|
(progn (setq etherpad-autosync nil)
|
|
(etherpad-autosync-disable))
|
|
(progn (setq etherpad-autosync t)
|
|
(etherpad-autosync-enable))))
|
|
|
|
(defun etherpad-autosync-enable ()
|
|
"Enable autosync."
|
|
(interactive)
|
|
(message "enabled autosync with etherpad server.")
|
|
(make-local-variable 'after-change-functions)
|
|
(make-local-variable 'before-change-functions)
|
|
(add-hook 'after-change-functions 'etherpad-after-change-function)
|
|
(add-hook 'before-change-functions 'etherpad-before-change-function))
|
|
|
|
(defun etherpad-autosync-disable ()
|
|
"Disable autosync."
|
|
(interactive)
|
|
(message "disabled autosync with etherpad server.")
|
|
(remove-hook 'after-change-functions 'etherpad-after-change-function)
|
|
(remove-hook 'before-change-functions 'etherpad-before-change-function))
|
|
|
|
(defun etherpad-idlesync-enable ()
|
|
"Sync pad whenever auto-save would."
|
|
(interactive)
|
|
(make-local-variable 'auto-save-hook)
|
|
(make-local-variable 'auto-save-mode)
|
|
(auto-save-mode t)
|
|
(add-hook 'auto-save-hook 'etherpad-save))
|
|
|
|
|
|
(defun etherpad-idlesync-disable ()
|
|
"Disable idle syncing."
|
|
(interactive)
|
|
(remove-hook 'auto-save-hook 'etherpad-save))
|
|
|
|
(provide 'etherpad)
|
|
|
|
;;; etherpad.el ends here
|