git.notmuchmail.org Git - notmuch/blob - emacs/notmuch-lib.el

   1 ;; notmuch-lib.el --- common variables, functions and function declarations
   2 ;;
   3 ;; Copyright © Carl Worth
   4 ;;
   5 ;; This file is part of Notmuch.
   6 ;;
   7 ;; Notmuch is free software: you can redistribute it and/or modify it
   8 ;; under the terms of the GNU General Public License as published by
   9 ;; the Free Software Foundation, either version 3 of the License, or
  10 ;; (at your option) any later version.
  11 ;;
  12 ;; Notmuch is distributed in the hope that it will be useful, but
  13 ;; WITHOUT ANY WARRANTY; without even the implied warranty of
  14 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15 ;; General Public License for more details.
  16 ;;
  17 ;; You should have received a copy of the GNU General Public License
  18 ;; along with Notmuch.  If not, see <http://www.gnu.org/licenses/>.
  19 ;;
  20 ;; Authors: Carl Worth <cworth@cworth.org>
  21
  22 ;; This is an part of an emacs-based interface to the notmuch mail system.
  23
  24 (require 'mm-view)
  25 (require 'mm-decode)
  26 (require 'json)
  27 (require 'cl)
  28
  29 (defvar notmuch-command "notmuch"
  30   "Command to run the notmuch binary.")
  31
  32 (defgroup notmuch nil
  33   "Notmuch mail reader for Emacs."
  34   :group 'mail)
  35
  36 (defgroup notmuch-hello nil
  37   "Overview of saved searches, tags, etc."
  38   :group 'notmuch)
  39
  40 (defgroup notmuch-search nil
  41   "Searching and sorting mail."
  42   :group 'notmuch)
  43
  44 (defgroup notmuch-show nil
  45   "Showing messages and threads."
  46   :group 'notmuch)
  47
  48 (defgroup notmuch-send nil
  49   "Sending messages from Notmuch."
  50   :group 'notmuch)
  51
  52 (custom-add-to-group 'notmuch-send 'message 'custom-group)
  53
  54 (defgroup notmuch-crypto nil
  55   "Processing and display of cryptographic MIME parts."
  56   :group 'notmuch)
  57
  58 (defgroup notmuch-hooks nil
  59   "Running custom code on well-defined occasions."
  60   :group 'notmuch)
  61
  62 (defgroup notmuch-external nil
  63   "Running external commands from within Notmuch."
  64   :group 'notmuch)
  65
  66 (defgroup notmuch-faces nil
  67   "Graphical attributes for displaying text"
  68   :group 'notmuch)
  69
  70 (defcustom notmuch-search-oldest-first t
  71   "Show the oldest mail first when searching."
  72   :type 'boolean
  73   :group 'notmuch-search)
  74
  75 ;;
  76
  77 (defvar notmuch-search-history nil
  78   "Variable to store notmuch searches history.")
  79
  80 (defcustom notmuch-saved-searches '(("inbox" . "tag:inbox")
  81                                     ("unread" . "tag:unread"))
  82   "A list of saved searches to display."
  83   :type '(alist :key-type string :value-type string)
  84   :group 'notmuch-hello)
  85
  86 (defcustom notmuch-archive-tags '("-inbox")
  87   "List of tag changes to apply to a message or a thread when it is archived.
  88
  89 Tags starting with \"+\" (or not starting with either \"+\" or
  90 \"-\") in the list will be added, and tags starting with \"-\"
  91 will be removed from the message or thread being archived.
  92
  93 For example, if you wanted to remove an \"inbox\" tag and add an
  94 \"archived\" tag, you would set:
  95     (\"-inbox\" \"+archived\")"
  96   :type '(repeat string)
  97   :group 'notmuch-search
  98   :group 'notmuch-show)
  99
 100 ;; By default clicking on a button does not select the window
 101 ;; containing the button (as opposed to clicking on a widget which
 102 ;; does). This means that the button action is then executed in the
 103 ;; current selected window which can cause problems if the button
 104 ;; changes the buffer (e.g., id: links) or moves point.
 105 ;;
 106 ;; This provides a button type which overrides mouse-action so that
 107 ;; the button's window is selected before the action is run. Other
 108 ;; notmuch buttons can get the same behaviour by inheriting from this
 109 ;; button type.
 110 (define-button-type 'notmuch-button-type
 111   'mouse-action (lambda (button)
 112                   (select-window (posn-window (event-start last-input-event)))
 113                   (button-activate button)))
 114
 115 (defun notmuch-command-to-string (&rest args)
 116   "Synchronously invoke \"notmuch\" with the given list of arguments.
 117
 118 If notmuch exits with a non-zero status, output from the process
 119 will appear in a buffer named \"*Notmuch errors*\" and an error
 120 will be signaled.
 121
 122 Otherwise the output will be returned"
 123   (with-temp-buffer
 124     (let* ((status (apply #'call-process notmuch-command nil t nil args))
 125            (output (buffer-string)))
 126       (notmuch-check-exit-status status (cons notmuch-command args) output)
 127       output)))
 128
 129 (defun notmuch-version ()
 130   "Return a string with the notmuch version number."
 131   (let ((long-string
 132          ;; Trim off the trailing newline.
 133          (substring (notmuch-command-to-string "--version") 0 -1)))
 134     (if (string-match "^notmuch\\( version\\)? \\(.*\\)$"
 135                       long-string)
 136         (match-string 2 long-string)
 137       "unknown")))
 138
 139 (defun notmuch-config-get (item)
 140   "Return a value from the notmuch configuration."
 141   ;; Trim off the trailing newline
 142   (substring (notmuch-command-to-string "config" "get" item) 0 -1))
 143
 144 (defun notmuch-database-path ()
 145   "Return the database.path value from the notmuch configuration."
 146   (notmuch-config-get "database.path"))
 147
 148 (defun notmuch-user-name ()
 149   "Return the user.name value from the notmuch configuration."
 150   (notmuch-config-get "user.name"))
 151
 152 (defun notmuch-user-primary-email ()
 153   "Return the user.primary_email value from the notmuch configuration."
 154   (notmuch-config-get "user.primary_email"))
 155
 156 (defun notmuch-user-other-email ()
 157   "Return the user.other_email value (as a list) from the notmuch configuration."
 158   (split-string (notmuch-config-get "user.other_email") "\n"))
 159
 160 (defun notmuch-kill-this-buffer ()
 161   "Kill the current buffer."
 162   (interactive)
 163   (kill-buffer (current-buffer)))
 164
 165 (defun notmuch-prettify-subject (subject)
 166   ;; This function is used by `notmuch-search-process-filter' which
 167   ;; requires that we not disrupt its' matching state.
 168   (save-match-data
 169     (if (and subject
 170              (string-match "^[ \t]*$" subject))
 171         "[No Subject]"
 172       subject)))
 173
 174 (defun notmuch-escape-boolean-term (term)
 175   "Escape a boolean term for use in a query.
 176
 177 The caller is responsible for prepending the term prefix and a
 178 colon.  This performs minimal escaping in order to produce
 179 user-friendly queries."
 180
 181   (save-match-data
 182     (if (or (equal term "")
 183             (string-match "[ ()]\\|^\"" term))
 184         ;; Requires escaping
 185         (concat "\"" (replace-regexp-in-string "\"" "\"\"" term t t) "\"")
 186       term)))
 187
 188 (defun notmuch-id-to-query (id)
 189   "Return a query that matches the message with id ID."
 190   (concat "id:" (notmuch-escape-boolean-term id)))
 191
 192 ;;
 193
 194 (defun notmuch-common-do-stash (text)
 195   "Common function to stash text in kill ring, and display in minibuffer."
 196   (if text
 197       (progn
 198         (kill-new text)
 199         (message "Stashed: %s" text))
 200     ;; There is nothing to stash so stash an empty string so the user
 201     ;; doesn't accidentally paste something else somewhere.
 202     (kill-new "")
 203     (message "Nothing to stash!")))
 204
 205 ;;
 206
 207 (defun notmuch-remove-if-not (predicate list)
 208   "Return a copy of LIST with all items not satisfying PREDICATE removed."
 209   (let (out)
 210     (while list
 211       (when (funcall predicate (car list))
 212         (push (car list) out))
 213       (setq list (cdr list)))
 214     (nreverse out)))
 215
 216 (defun notmuch-split-content-type (content-type)
 217   "Split content/type into 'content' and 'type'"
 218   (split-string content-type "/"))
 219
 220 (defun notmuch-match-content-type (t1 t2)
 221   "Return t if t1 and t2 are matching content types, taking wildcards into account"
 222   (let ((st1 (notmuch-split-content-type t1))
 223         (st2 (notmuch-split-content-type t2)))
 224     (if (or (string= (cadr st1) "*")
 225             (string= (cadr st2) "*"))
 226         ;; Comparison of content types should be case insensitive.
 227         (string= (downcase (car st1)) (downcase (car st2)))
 228       (string= (downcase t1) (downcase t2)))))
 229
 230 (defvar notmuch-multipart/alternative-discouraged
 231   '(
 232     ;; Avoid HTML parts.
 233     "text/html"
 234     ;; multipart/related usually contain a text/html part and some associated graphics.
 235     "multipart/related"
 236     ))
 237
 238 (defun notmuch-multipart/alternative-choose (types)
 239   "Return a list of preferred types from the given list of types"
 240   ;; Based on `mm-preferred-alternative-precedence'.
 241   (let ((seq types))
 242     (dolist (pref (reverse notmuch-multipart/alternative-discouraged))
 243       (dolist (elem (copy-sequence seq))
 244         (when (string-match pref elem)
 245           (setq seq (nconc (delete elem seq) (list elem))))))
 246     seq))
 247
 248 (defun notmuch-parts-filter-by-type (parts type)
 249   "Given a list of message parts, return a list containing the ones matching
 250 the given type."
 251   (remove-if-not
 252    (lambda (part) (notmuch-match-content-type (plist-get part :content-type) type))
 253    parts))
 254
 255 ;; Helper for parts which are generally not included in the default
 256 ;; JSON output.
 257 (defun notmuch-get-bodypart-internal (query part-number process-crypto)
 258   (let ((args '("show" "--format=raw"))
 259         (part-arg (format "--part=%s" part-number)))
 260     (setq args (append args (list part-arg)))
 261     (if process-crypto
 262         (setq args (append args '("--decrypt"))))
 263     (setq args (append args (list query)))
 264     (with-temp-buffer
 265       (let ((coding-system-for-read 'no-conversion))
 266         (progn
 267           (apply 'call-process (append (list notmuch-command nil (list t nil) nil) args))
 268           (buffer-string))))))
 269
 270 (defun notmuch-get-bodypart-content (msg part nth process-crypto)
 271   (or (plist-get part :content)
 272       (notmuch-get-bodypart-internal (notmuch-id-to-query (plist-get msg :id)) nth process-crypto)))
 273
 274 ;; Workaround: The call to `mm-display-part' below triggers a bug in
 275 ;; Emacs 24 if it attempts to use the shr renderer to display an HTML
 276 ;; part with images in it (demonstrated in 24.1 and 24.2 on Debian and
 277 ;; Fedora 17, though unreproducable in other configurations).
 278 ;; `mm-shr' references the variable `gnus-inhibit-images' without
 279 ;; first loading gnus-art, which defines it, resulting in a
 280 ;; void-variable error.  Hence, we advise `mm-shr' to ensure gnus-art
 281 ;; is loaded.
 282 (if (>= emacs-major-version 24)
 283     (defadvice mm-shr (before load-gnus-arts activate)
 284       (require 'gnus-art nil t)
 285       (ad-disable-advice 'mm-shr 'before 'load-gnus-arts)))
 286
 287 (defun notmuch-mm-display-part-inline (msg part nth content-type process-crypto)
 288   "Use the mm-decode/mm-view functions to display a part in the
 289 current buffer, if possible."
 290   (let ((display-buffer (current-buffer)))
 291     (with-temp-buffer
 292       ;; In case there is :content, the content string is already converted
 293       ;; into emacs internal format. `gnus-decoded' is a fake charset,
 294       ;; which means no further decoding (to be done by mm- functions).
 295       (let* ((charset (if (plist-member part :content)
 296                           'gnus-decoded
 297                         (plist-get part :content-charset)))
 298              (handle (mm-make-handle (current-buffer) `(,content-type (charset . ,charset)))))
 299         ;; If the user wants the part inlined, insert the content and
 300         ;; test whether we are able to inline it (which includes both
 301         ;; capability and suitability tests).
 302         (when (mm-inlined-p handle)
 303           (insert (notmuch-get-bodypart-content msg part nth process-crypto))
 304           (when (mm-inlinable-p handle)
 305             (set-buffer display-buffer)
 306             (mm-display-part handle)
 307             t))))))
 308
 309 ;; Converts a plist of headers to an alist of headers. The input plist should
 310 ;; have symbols of the form :Header as keys, and the resulting alist will have
 311 ;; symbols of the form 'Header as keys.
 312 (defun notmuch-headers-plist-to-alist (plist)
 313   (loop for (key value . rest) on plist by #'cddr
 314         collect (cons (intern (substring (symbol-name key) 1)) value)))
 315
 316 (defun notmuch-face-ensure-list-form (face)
 317   "Return FACE in face list form.
 318
 319 If FACE is already a face list, it will be returned as-is.  If
 320 FACE is a face name or face plist, it will be returned as a
 321 single element face list."
 322   (if (and (listp face) (not (keywordp (car face))))
 323       face
 324     (list face)))
 325
 326 (defun notmuch-combine-face-text-property (start end face &optional below object)
 327   "Combine FACE into the 'face text property between START and END.
 328
 329 This function combines FACE with any existing faces between START
 330 and END in OBJECT (which defaults to the current buffer).
 331 Attributes specified by FACE take precedence over existing
 332 attributes unless BELOW is non-nil.  FACE must be a face name (a
 333 symbol or string), a property list of face attributes, or a list
 334 of these.  For convenience when applied to strings, this returns
 335 OBJECT."
 336
 337   ;; A face property can have three forms: a face name (a string or
 338   ;; symbol), a property list, or a list of these two forms.  In the
 339   ;; list case, the faces will be combined, with the earlier faces
 340   ;; taking precedent.  Here we canonicalize everything to list form
 341   ;; to make it easy to combine.
 342   (let ((pos start)
 343         (face-list (notmuch-face-ensure-list-form face)))
 344     (while (< pos end)
 345       (let* ((cur (get-text-property pos 'face object))
 346              (cur-list (notmuch-face-ensure-list-form cur))
 347              (new (cond ((null cur-list) face)
 348                         (below (append cur-list face-list))
 349                         (t (append face-list cur-list))))
 350              (next (next-single-property-change pos 'face object end)))
 351         (put-text-property pos next 'face new object)
 352         (setq pos next))))
 353   object)
 354
 355 (defun notmuch-combine-face-text-property-string (string face &optional below)
 356   (notmuch-combine-face-text-property
 357    0
 358    (length string)
 359    face
 360    below
 361    string))
 362
 363 (defun notmuch-logged-error (msg &optional extra)
 364   "Log MSG and EXTRA to *Notmuch errors* and signal MSG.
 365
 366 This logs MSG and EXTRA to the *Notmuch errors* buffer and
 367 signals MSG as an error.  If EXTRA is non-nil, text referring the
 368 user to the *Notmuch errors* buffer will be appended to the
 369 signaled error.  This function does not return."
 370
 371   (with-current-buffer (get-buffer-create "*Notmuch errors*")
 372     (goto-char (point-max))
 373     (unless (bobp)
 374       (newline))
 375     (save-excursion
 376       (insert "[" (current-time-string) "]\n" msg)
 377       (unless (bolp)
 378         (newline))
 379       (when extra
 380         (insert extra)
 381         (unless (bolp)
 382           (newline)))))
 383   (error "%s" (concat msg (when extra
 384                             " (see *Notmuch errors* for more details)"))))
 385
 386 (defun notmuch-check-async-exit-status (proc msg)
 387   "If PROC exited abnormally, pop up an error buffer and signal an error.
 388
 389 This is a wrapper around `notmuch-check-exit-status' for
 390 asynchronous process sentinels.  PROC and MSG must be the
 391 arguments passed to the sentinel."
 392   (let ((exit-status
 393          (case (process-status proc)
 394            ((exit) (process-exit-status proc))
 395            ((signal) msg))))
 396     (when exit-status
 397       (notmuch-check-exit-status exit-status (process-command proc)))))
 398
 399 (defun notmuch-check-exit-status (exit-status command &optional output err-file)
 400   "If EXIT-STATUS is non-zero, pop up an error buffer and signal an error.
 401
 402 If EXIT-STATUS is non-zero, pop up a notmuch error buffer
 403 describing the error and signal an Elisp error.  EXIT-STATUS must
 404 be a number indicating the exit status code of a process or a
 405 string describing the signal that terminated the process (such as
 406 returned by `call-process').  COMMAND must be a list giving the
 407 command and its arguments.  OUTPUT, if provided, is a string
 408 giving the output of command.  ERR-FILE, if provided, is the name
 409 of a file containing the error output of command.  OUTPUT and the
 410 contents of ERR-FILE will be included in the error message."
 411
 412   (cond
 413    ((eq exit-status 0) t)
 414    ((eq exit-status 20)
 415     (notmuch-logged-error "notmuch CLI version mismatch
 416 Emacs requested an older output format than supported by the notmuch CLI.
 417 You may need to restart Emacs or upgrade your notmuch Emacs package."))
 418    ((eq exit-status 21)
 419     (notmuch-logged-error "notmuch CLI version mismatch
 420 Emacs requested a newer output format than supported by the notmuch CLI.
 421 You may need to restart Emacs or upgrade your notmuch package."))
 422    (t
 423     (let* ((err (when err-file
 424                   (with-temp-buffer
 425                     (insert-file-contents err-file)
 426                     (unless (eobp)
 427                       (buffer-string)))))
 428            (extra
 429             (concat
 430              "command: " (mapconcat #'shell-quote-argument command " ") "\n"
 431              (if (integerp exit-status)
 432                  (format "exit status: %s\n" exit-status)
 433                (format "exit signal: %s\n" exit-status))
 434              (when err
 435                (concat "stderr:\n" err))
 436              (when output
 437                (concat "stdout:\n" output)))))
 438         (if err
 439             ;; We have an error message straight from the CLI.
 440             (notmuch-logged-error
 441              (replace-regexp-in-string "\\s $" "" err) extra)
 442           ;; We only have combined output from the CLI; don't inundate
 443           ;; the user with it.  Mimic `process-lines'.
 444           (notmuch-logged-error (format "%s exited with status %s"
 445                                         (car command) exit-status)
 446                                 extra))
 447         ;; `notmuch-logged-error' does not return.
 448         ))))
 449
 450 (defun notmuch-call-notmuch-json (&rest args)
 451   "Invoke `notmuch-command' with `args' and return the parsed JSON output.
 452
 453 The returned output will represent objects using property lists
 454 and arrays as lists.  If notmuch exits with a non-zero status,
 455 this will pop up a buffer containing notmuch's output and signal
 456 an error."
 457
 458   (with-temp-buffer
 459     (let ((err-file (make-temp-file "nmerr")))
 460       (unwind-protect
 461           (let ((status (apply #'call-process
 462                                notmuch-command nil (list t err-file) nil args)))
 463             (notmuch-check-exit-status status (cons notmuch-command args)
 464                                        (buffer-string) err-file)
 465             (goto-char (point-min))
 466             (let ((json-object-type 'plist)
 467                   (json-array-type 'list)
 468                   (json-false 'nil))
 469               (json-read)))
 470         (delete-file err-file)))))
 471
 472 ;; This variable is used only buffer local, but it needs to be
 473 ;; declared globally first to avoid compiler warnings.
 474 (defvar notmuch-show-process-crypto nil)
 475 (make-variable-buffer-local 'notmuch-show-process-crypto)
 476
 477 ;; Incremental JSON parsing
 478
 479 ;; These two variables are internal variables to the parsing
 480 ;; routines. They are always used buffer local but need to be declared
 481 ;; globally to avoid compiler warnings.
 482
 483 (defvar notmuch-json-parser nil
 484   "Internal incremental JSON parser object: local to the buffer being parsed.")
 485
 486 (defvar notmuch-json-state nil
 487   "State of the internal JSON parser: local to the buffer being parsed.")
 488
 489 (defun notmuch-json-create-parser (buffer)
 490   "Return a streaming JSON parser that consumes input from BUFFER.
 491
 492 This parser is designed to read streaming JSON whose structure is
 493 known to the caller.  Like a typical JSON parsing interface, it
 494 provides a function to read a complete JSON value from the input.
 495 However, it extends this with an additional function that
 496 requires the next value in the input to be a compound value and
 497 descends into it, allowing its elements to be read one at a time
 498 or further descended into.  Both functions can return 'retry to
 499 indicate that not enough input is available.
 500
 501 The parser always consumes input from BUFFER's point.  Hence, the
 502 caller is allowed to delete and data before point and may
 503 resynchronize after an error by moving point."
 504
 505   (list buffer
 506         ;; Terminator stack: a stack of characters that indicate the
 507         ;; end of the compound values enclosing point
 508         '()
 509         ;; Next: One of
 510         ;; * 'expect-value if the next token must be a value, but a
 511         ;;   value has not yet been reached
 512         ;; * 'value if point is at the beginning of a value
 513         ;; * 'expect-comma if the next token must be a comma
 514         'expect-value
 515         ;; Allow terminator: non-nil if the next token may be a
 516         ;; terminator
 517         nil
 518         ;; Partial parse position: If state is 'value, a marker for
 519         ;; the position of the partial parser or nil if no partial
 520         ;; parsing has happened yet
 521         nil
 522         ;; Partial parse state: If state is 'value, the current
 523         ;; `parse-partial-sexp' state
 524         nil))
 525
 526 (defmacro notmuch-json-buffer (jp) `(first ,jp))
 527 (defmacro notmuch-json-term-stack (jp) `(second ,jp))
 528 (defmacro notmuch-json-next (jp) `(third ,jp))
 529 (defmacro notmuch-json-allow-term (jp) `(fourth ,jp))
 530 (defmacro notmuch-json-partial-pos (jp) `(fifth ,jp))
 531 (defmacro notmuch-json-partial-state (jp) `(sixth ,jp))
 532
 533 (defvar notmuch-json-syntax-table
 534   (let ((table (make-syntax-table)))
 535     ;; The standard syntax table is what we need except that "." needs
 536     ;; to have word syntax instead of punctuation syntax.
 537     (modify-syntax-entry ?. "w" table)
 538     table)
 539   "Syntax table used for incremental JSON parsing.")
 540
 541 (defun notmuch-json-scan-to-value (jp)
 542   ;; Helper function that consumes separators, terminators, and
 543   ;; whitespace from point.  Returns nil if it successfully reached
 544   ;; the beginning of a value, 'end if it consumed a terminator, or
 545   ;; 'retry if not enough input was available to reach a value.  Upon
 546   ;; nil return, (notmuch-json-next jp) is always 'value.
 547
 548   (if (eq (notmuch-json-next jp) 'value)
 549       ;; We're already at a value
 550       nil
 551     ;; Drive the state toward 'expect-value
 552     (skip-chars-forward " \t\r\n")
 553     (or (when (eobp) 'retry)
 554         ;; Test for the terminator for the current compound
 555         (when (and (notmuch-json-allow-term jp)
 556                    (eq (char-after) (car (notmuch-json-term-stack jp))))
 557           ;; Consume it and expect a comma or terminator next
 558           (forward-char)
 559           (setf (notmuch-json-term-stack jp) (cdr (notmuch-json-term-stack jp))
 560                 (notmuch-json-next jp) 'expect-comma
 561                 (notmuch-json-allow-term jp) t)
 562           'end)
 563         ;; Test for a separator
 564         (when (eq (notmuch-json-next jp) 'expect-comma)
 565           (when (/= (char-after) ?,)
 566             (signal 'json-readtable-error (list "expected ','")))
 567           ;; Consume it, switch to 'expect-value, and disallow a
 568           ;; terminator
 569           (forward-char)
 570           (skip-chars-forward " \t\r\n")
 571           (setf (notmuch-json-next jp) 'expect-value
 572                 (notmuch-json-allow-term jp) nil)
 573           ;; We moved point, so test for eobp again and fall through
 574           ;; to the next test if there's more input
 575           (when (eobp) 'retry))
 576         ;; Next must be 'expect-value and we know this isn't
 577         ;; whitespace, EOB, or a terminator, so point must be on a
 578         ;; value
 579         (progn
 580           (assert (eq (notmuch-json-next jp) 'expect-value))
 581           (setf (notmuch-json-next jp) 'value)
 582           nil))))
 583
 584 (defun notmuch-json-begin-compound (jp)
 585   "Parse the beginning of a compound value and traverse inside it.
 586
 587 Returns 'retry if there is insufficient input to parse the
 588 beginning of the compound.  If this is able to parse the
 589 beginning of a compound, it moves point past the token that opens
 590 the compound and returns t.  Later calls to `notmuch-json-read'
 591 will return the compound's elements.
 592
 593 Entering JSON objects is currently unimplemented."
 594
 595   (with-current-buffer (notmuch-json-buffer jp)
 596     ;; Disallow terminators
 597     (setf (notmuch-json-allow-term jp) nil)
 598     ;; Save "next" so we can restore it if there's a syntax error
 599     (let ((saved-next (notmuch-json-next jp)))
 600       (or (notmuch-json-scan-to-value jp)
 601           (if (/= (char-after) ?\[)
 602               (progn
 603                 (setf (notmuch-json-next jp) saved-next)
 604                 (signal 'json-readtable-error (list "expected '['")))
 605             (forward-char)
 606             (push ?\] (notmuch-json-term-stack jp))
 607             ;; Expect a value or terminator next
 608             (setf (notmuch-json-next jp) 'expect-value
 609                   (notmuch-json-allow-term jp) t)
 610             t)))))
 611
 612 (defun notmuch-json-read (jp)
 613   "Parse the value at point in JP's buffer.
 614
 615 Returns 'retry if there is insufficient input to parse a complete
 616 JSON value (though it may still move point over separators or
 617 whitespace).  If the parser is currently inside a compound value
 618 and the next token ends the list or object, this moves point just
 619 past the terminator and returns 'end.  Otherwise, this moves
 620 point to just past the end of the value and returns the value."
 621
 622   (with-current-buffer (notmuch-json-buffer jp)
 623     (or
 624      ;; Get to a value state
 625      (notmuch-json-scan-to-value jp)
 626
 627      ;; Can we parse a complete value?
 628      (let ((complete
 629             (if (looking-at "[-+0-9tfn]")
 630                 ;; This is a number or a keyword, so the partial
 631                 ;; parser isn't going to help us because a truncated
 632                 ;; number or keyword looks like a complete symbol to
 633                 ;; it.  Look for something that clearly ends it.
 634                 (save-excursion
 635                   (skip-chars-forward "^]},: \t\r\n")
 636                   (not (eobp)))
 637
 638               ;; We're looking at a string, object, or array, which we
 639               ;; can partial parse.  If we just reached the value, set
 640               ;; up the partial parser.
 641               (when (null (notmuch-json-partial-state jp))
 642                 (setf (notmuch-json-partial-pos jp) (point-marker)))
 643
 644               ;; Extend the partial parse until we either reach EOB or
 645               ;; get the whole value
 646               (save-excursion
 647                 (let ((pstate
 648                        (with-syntax-table notmuch-json-syntax-table
 649                          (parse-partial-sexp
 650                           (notmuch-json-partial-pos jp) (point-max) 0 nil
 651                           (notmuch-json-partial-state jp)))))
 652                   ;; A complete value is available if we've reached
 653                   ;; depth 0 or less and encountered a complete
 654                   ;; subexpression.
 655                   (if (and (<= (first pstate) 0) (third pstate))
 656                       t
 657                     ;; Not complete.  Update the partial parser state
 658                     (setf (notmuch-json-partial-pos jp) (point-marker)
 659                           (notmuch-json-partial-state jp) pstate)
 660                     nil))))))
 661
 662        (if (not complete)
 663            'retry
 664          ;; We have a value.  Reset the partial parse state and expect
 665          ;; a comma or terminator after the value.
 666          (setf (notmuch-json-next jp) 'expect-comma
 667                (notmuch-json-allow-term jp) t
 668                (notmuch-json-partial-pos jp) nil
 669                (notmuch-json-partial-state jp) nil)
 670          ;; Parse the value
 671          (let ((json-object-type 'plist)
 672                (json-array-type 'list)
 673                (json-false nil))
 674            (json-read)))))))
 675
 676 (defun notmuch-json-eof (jp)
 677   "Signal a json-error if there is more data in JP's buffer.
 678
 679 Moves point to the beginning of any trailing data or to the end
 680 of the buffer if there is only trailing whitespace."
 681
 682   (with-current-buffer (notmuch-json-buffer jp)
 683     (skip-chars-forward " \t\r\n")
 684     (unless (eobp)
 685       (signal 'json-error (list "Trailing garbage following JSON data")))))
 686
 687 (defun notmuch-json-parse-partial-list (result-function error-function results-buf)
 688   "Parse a partial JSON list from current buffer.
 689
 690 This function consumes a JSON list from the current buffer,
 691 applying RESULT-FUNCTION in buffer RESULT-BUFFER to each complete
 692 value in the list.  It operates incrementally and should be
 693 called whenever the buffer has been extended with additional
 694 data.
 695
 696 If there is a syntax error, this will attempt to resynchronize
 697 with the input and will apply ERROR-FUNCTION in buffer
 698 RESULT-BUFFER to any input that was skipped.
 699
 700 It sets up all the needed internal variables: the caller just
 701 needs to call it with point in the same place that the parser
 702 left it."
 703   (let (done)
 704     (unless (local-variable-p 'notmuch-json-parser)
 705       (set (make-local-variable 'notmuch-json-parser)
 706            (notmuch-json-create-parser (current-buffer)))
 707       (set (make-local-variable 'notmuch-json-state) 'begin))
 708     (while (not done)
 709       (condition-case nil
 710           (case notmuch-json-state
 711                 ((begin)
 712                  ;; Enter the results list
 713                  (if (eq (notmuch-json-begin-compound
 714                           notmuch-json-parser) 'retry)
 715                      (setq done t)
 716                    (setq notmuch-json-state 'result)))
 717                 ((result)
 718                  ;; Parse a result
 719                  (let ((result (notmuch-json-read notmuch-json-parser)))
 720                    (case result
 721                          ((retry) (setq done t))
 722                          ((end) (setq notmuch-json-state 'end))
 723                          (otherwise (with-current-buffer results-buf
 724                                       (funcall result-function result))))))
 725                 ((end)
 726                  ;; Any trailing data is unexpected
 727                  (notmuch-json-eof notmuch-json-parser)
 728                  (setq done t)))
 729         (json-error
 730          ;; Do our best to resynchronize and ensure forward
 731          ;; progress
 732          (let ((bad (buffer-substring (line-beginning-position)
 733                                       (line-end-position))))
 734            (forward-line)
 735            (with-current-buffer results-buf
 736              (funcall error-function "%s" bad))))))
 737     ;; Clear out what we've parsed
 738     (delete-region (point-min) (point))))
 739
 740
 741
 742
 743 (provide 'notmuch-lib)
 744
 745 ;; Local Variables:
 746 ;; byte-compile-warnings: (not cl-functions)
 747 ;; End: