;;; x86-lookup.el --- jump to x86 instruction documentation -*- lexical-binding: t; -*-

;; This is free and unencumbered software released into the public domain.

;; Author: Christopher Wellons <wellons@nullprogram.com>
;; URL: https://github.com/skeeto/x86-lookup
;; Package-Version: 20180528.1635
;; Version: 1.2.0
;; Package-Requires: ((emacs "24.3") (cl-lib "0.3"))

;;; Commentary:

;; Requires the following:
;; * pdftotext command line program from Poppler
;; * Intel 64 and IA-32 Architecture Software Developer Manual PDF

;; http://www.intel.com/content/www/us/en/processors/architectures-software-developer-manuals.html

;; Building the index specifically requires Poppler's pdftotext, not
;; just any PDF to text converter. It has a critical feature over the
;; others: conventional line feed characters (U+000C) are output
;; between pages, allowing precise tracking of page numbers. These are
;; the markers Emacs uses for `forward-page' and `backward-page'.

;; Your copy of the manual must contain the full instruction set
;; reference in a single PDF. Set `x86-lookup-pdf' to this file name.
;; Intel optionally offers the instruction set reference in two
;; separate volumes, but don't use that.

;; Choose a PDF viewer by setting `x86-lookup-browse-pdf-function'. If
;; you provide a custom function, your PDF viewer should support
;; linking to a specific page (e.g. not supported by xdg-open,
;; unfortunately). Otherwise there's no reason to use this package.

;; Once configured, the main entrypoint is `x86-lookup'. You may want
;; to bind this to a key. The interactive prompt will default to the
;; mnemonic under the point. Here's a suggestion:

;;   (global-set-key (kbd "C-h x") #'x86-lookup)

;; This package pairs well with `nasm-mode'!

;;; Code

(require 'cl-lib)
(require 'doc-view)

(defgroup x86-lookup ()
  "Options for x86 instruction set lookup."
  :group 'extensions)

(defcustom x86-lookup-pdf nil
  "Path to Intel's manual containing the instruction set reference."
  :group 'x86-lookup
  :type '(choice (const nil)
                 (file :must-match t)))

(defcustom x86-lookup-pdftotext-program "pdftotext"
  "Path to pdftotext, part of Popper."
  :group 'x86-lookup
  :type 'string)

(defcustom x86-lookup-browse-pdf-function #'x86-lookup-browse-pdf-any
  "A function that launches a PDF viewer at a specific page.
This function accepts two arguments: filename and page number."
  :group 'x86-lookup
  :type '(choice (function-item :tag "First suitable PDF reader" :value
                                x86-lookup-browse-pdf-any)
                 (function-item :tag "Evince" :value
                                x86-lookup-browse-pdf-evince)
                 (function-item :tag "Xpdf" :value
                                x86-lookup-browse-pdf-xpdf)
                 (function-item :tag "Okular" :value
                                x86-lookup-browse-pdf-okular)
                 (function-item :tag "gv" :value
                                x86-lookup-browse-pdf-gv)
                 (function-item :tag "zathura" :value
                                x86-lookup-browse-pdf-zathura)
                 (function-item :tag "MuPDF" :value
                                x86-lookup-browse-pdf-mupdf)
                 (function-item :tag "Sumatra PDF" :value
                                x86-lookup-browse-pdf-sumatrapdf)
                 (function-item :tag "browse-url"
                                :value x86-lookup-browse-pdf-browser)
                 (function :tag "Your own function")))

(defcustom x86-lookup-cache-directory
  (let ((base (or (getenv "XDG_CACHE_HOME")
                  (getenv "LocalAppData")
                  "~/.cache")))
    (expand-file-name "x86-lookup" base))
  "Directory where the PDF mnemonic index with be cached."
  :type 'string)

(defvar x86-lookup-index nil
  "Alist mapping instructions to page numbers.")

(defvar x86-lookup--expansions
  '(("^PREFETCH\\(h\\)$"
     "" "nta" "t0" "t1" "t2")
    ("^J\\(cc\\)$"
     "a" "ae" "b" "be" "c" "cxz" "e" "ecxz" "g" "ge" "l" "le" "na" "nae" "nb"
     "nbe" "nc" "ne" "ng" "nge" "nl" "nle" "no" "np" "ns" "nz" "o" "p" "pe"
     "po" "rcxz" "s" "z")
    ("^SET\\(cc\\)$"
     "a" "ae" "b" "be" "c" "e" "g" "ge" "l" "le" "na" "nae" "nb" "nbe" "nc"
     "ne" "ng" "nge" "nl" "nle" "no" "np" "ns" "nz" "o" "p" "pe" "po" "s" "z")
    ("^CMOV\\(cc\\)$"
     "a" "ae" "b" "be" "c" "e" "g" "ge" "l" "le" "na" "nae" "nb" "nbe" "nc"
     "ne" "ng" "nge" "nl" "nle" "no" "np" "ns" "nz" "o" "p" "pe" "po" "s" "z")
    ("^FCMOV\\(cc\\)$"
     "b" "e" "be" "u" "nb" "ne" "nbe" "nu")
    ("^LOOP\\(cc\\)$"
     "e" "ne")
    ("^VBROADCAST\\(\\)$"
     "" "ss" "sd" "f128")
    ("^VMASKMOV\\(\\)$"
     "" "ps" "pd")
    ("^VPBROADCAST\\(\\)$"
     "" "b" "w" "d" "q" "I128")
    ("^VPMASKMOV\\(\\)$"
     "" "d" "q")
    ("\\(\\)" ; fallback "match"
     ""))
  "How to expand mnemonics into multiple mnemonics.")

(defun x86-lookup--expand (names page)
  "Expand string of PDF-sourced mnemonics into user-friendly mnemonics."
  (let ((case-fold-search nil)
        (rev-string-match-p (lambda (s re) (string-match re s))))
    (save-match-data
      (cl-loop for mnemonic-raw in (split-string names " */ *")
               ;; Collapse "int 3" and "int n" into "int"
               for mnemonic = (replace-regexp-in-string " .+$" "" mnemonic-raw)
               for (_ . tails) = (cl-assoc mnemonic x86-lookup--expansions
                                           :test rev-string-match-p)
               nconc (cl-loop for tail in tails
                              for rep = (replace-match tail nil nil mnemonic 1)
                              collect (cons (downcase rep) page))))))

(cl-defun x86-lookup-create-index (&optional (pdf x86-lookup-pdf))
  "Create an index alist from PDF mapping mnemonics to page numbers.
This function requires the pdftotext command line program."
  (let ((mnemonic (concat "\\(?:.*\n\n?\\)?"
                          "\\([[:alnum:]/[:blank:]]+\\)[[:blank:]]*"
                          "\\(?:--\\|—\\)\\(?:.*\n\n?\\)\\{1,3\\}"
                          "[[:blank:]]*Opcode"))
        (coding-system-for-read 'utf-8)
        (coding-system-for-write 'utf-8)
        (case-fold-search t))
    (with-temp-buffer
      (call-process x86-lookup-pdftotext-program nil t nil
                    (file-truename pdf) "-")
      (setf (point) (point-min))
      (cl-loop for page upfrom 1
               while (< (point) (point-max))
               when (looking-at mnemonic)
               nconc (x86-lookup--expand (match-string 1) page) into index
               do (forward-page)
               finally (cl-return
                        (cl-remove-duplicates
                         index :key #'car :test #'string= :from-end t))))))

(defun x86-lookup--index-file (pdf)
  "Return index filename from PDF filename."
  (concat (sha1 pdf) "_v3"))

(defun x86-lookup--save-index (pdf index)
  "Save INDEX for PDF in `x86-lookup-cache-directory'."
  (let* ((index-file (x86-lookup--index-file pdf))
         (cache-path (expand-file-name index-file x86-lookup-cache-directory)))
    (mkdir x86-lookup-cache-directory t)
    (with-temp-file cache-path
      (prin1 index (current-buffer)))
    index))

(defun x86-lookup--load-index (pdf)
  "Return index PDF from `x86-lookup-cache-directory'."
  (let* ((index-file (x86-lookup--index-file pdf))
         (cache-path (expand-file-name index-file x86-lookup-cache-directory)))
    (when (file-exists-p cache-path)
      (with-temp-buffer
        (insert-file-contents cache-path)
        (setf (point) (point-min))
        (ignore-errors (read (current-buffer)))))))

(defun x86-lookup-ensure-index ()
  "Ensure the PDF index has been created, returning the index."
  (when (null x86-lookup-index)
    (cond
     ((null x86-lookup-pdf)
      (error "No PDF available. Set `x86-lookup-pdf'."))
     ((not (file-exists-p x86-lookup-pdf))
      (error "PDF not found. Check `x86-lookup-pdf'."))
     ((setf x86-lookup-index (x86-lookup--load-index x86-lookup-pdf))
      x86-lookup-index)
     ((progn
        (message "Generating mnemonic index ...")
        (setf x86-lookup-index (x86-lookup-create-index))
        (x86-lookup--save-index x86-lookup-pdf x86-lookup-index)))))
  x86-lookup-index)

(defun x86-lookup-ensure-and-update-index ()
  "Ensure the PDF index has been created and (unconditionally) updated.
Useful for forcibly syncing the index with the current PDF without resorting
to manual deletion of index file on filesystem."
  (interactive)
  (cond
   ((null x86-lookup-pdf)
    (error "No PDF available. Set `x86-lookup-pdf'."))
   ((not (file-exists-p x86-lookup-pdf))
    (error "PDF not found. Check `x86-lookup-pdf'."))
   ((message "Generating mnemonic index ...")
    (setf x86-lookup-index (x86-lookup-create-index))
    (x86-lookup--save-index x86-lookup-pdf x86-lookup-index)
    (message "Finished generating mnemonic index."))))

(defun x86-lookup-browse-pdf (pdf page)
  "Launch a PDF viewer using `x86-lookup-browse-pdf-function'."
  (funcall x86-lookup-browse-pdf-function pdf page))

;;;###autoload
(defun x86-lookup (mnemonic)
  "Jump to the PDF documentation for MNEMONIC.
Defaults to the mnemonic under point."
  (interactive
   (progn
     (x86-lookup-ensure-index)
     (let* ((mnemonics (mapcar #'car x86-lookup-index))
            (thing (thing-at-point 'word))
            (mnemonic (if (member thing mnemonics) thing nil))
            (prompt (if mnemonic
                        (format "Mnemonic (default %s): " mnemonic)
                      "Mnemonic: ")))
       (list
        (completing-read prompt mnemonics nil t nil nil mnemonic)))))
  (let ((page (cdr (assoc mnemonic x86-lookup-index))))
    (x86-lookup-browse-pdf (file-truename x86-lookup-pdf) page)))

;; PDF viewers:

(defun x86-lookup-browse-pdf-pdf-tools (pdf page)
  "View PDF at PAGE using Emacs' `pdf-view-mode' and `display-buffer'."
  (require 'pdf-tools)
  (prog1 t
    (with-selected-window (display-buffer (find-file-noselect pdf :nowarn))
      (with-no-warnings
        (pdf-view-goto-page page)))))

(defun x86-lookup-browse-pdf-doc-view (pdf page)
  "View PDF at PAGE using Emacs' `doc-view-mode' and `display-buffer'."
  (prog1 t
    (unless (doc-view-mode-p 'pdf)
      (error "doc-view not available for PDF"))
    (with-selected-window (display-buffer (find-file-noselect pdf :nowarn))
      (doc-view-goto-page page))))

(defun x86-lookup-browse-pdf-xpdf (pdf page)
  "View PDF at PAGE using xpdf."
  (start-process "xpdf" nil "xpdf" "--" pdf (format "%d" page)))

(defun x86-lookup-browse-pdf-evince (pdf page)
  "View PDF at PAGE using Evince."
  (start-process "evince" nil "evince" "-p" (format "%d" page) "--" pdf))

(defun x86-lookup-browse-pdf-okular (pdf page)
  "View PDF at PAGE file using Okular."
  (start-process "okular" nil "okular" "-p" (format "%d" page) "--" pdf))

(defun x86-lookup-browse-pdf-gv (pdf page)
  "View PDF at PAGE using gv."
  (start-process "gv" nil "gv" "-nocenter" (format "-page=%d" page) "--" pdf))

(defun x86-lookup-browse-pdf-zathura (pdf page)
  "View PDF at PAGE using zathura."
  (start-process "zathura" nil "zathura" "-P" (format "%d" page) "--" pdf))

(defun x86-lookup-browse-pdf-sumatrapdf (pdf page)
  "View PDF at PAGE using Sumatra PDF."
  (start-process "sumatrapdf" nil "sumatrapdf" "-page" (format "%d" page) pdf))

(defun x86-lookup-browse-pdf-mupdf (pdf page)
  "View PDF at PAGE using MuPDF."
  ;; MuPDF doesn't have a consistent name across platforms.
  ;; Furthermore, Debian ships with a broken "mupdf" wrapper shell
  ;; script and must be avoided. Here we use `executable-find' to
  ;; avoid calling it as mupdf-x11 on non-X11 platforms.
  (let ((exe (or (executable-find "mupdf-x11") "mupdf")))
    (start-process "mupdf" nil exe "--" pdf (format "%d" page))))

(defun x86-lookup-browse-pdf-browser (pdf page)
  "Visit PDF using `browse-url' with a fragment for the PAGE."
  (browse-url (format "file://%s#%d" pdf page)))

(defun x86-lookup-browse-pdf-any (pdf page)
  "Try visiting PDF using the first viewer found."
  (or (ignore-errors (x86-lookup-browse-pdf-pdf-tools pdf page))
      (ignore-errors (x86-lookup-browse-pdf-doc-view pdf page))
      (ignore-errors (x86-lookup-browse-pdf-evince pdf page))
      (ignore-errors (x86-lookup-browse-pdf-xpdf pdf page))
      (ignore-errors (x86-lookup-browse-pdf-okular pdf page))
      (ignore-errors (x86-lookup-browse-pdf-gv pdf page))
      (ignore-errors (x86-lookup-browse-pdf-zathura pdf page))
      (ignore-errors (x86-lookup-browse-pdf-mupdf pdf page))
      (ignore-errors (x86-lookup-browse-pdf-sumatrapdf pdf page))
      (ignore-errors (x86-lookup-browse-pdf-browser pdf page))
      (error "Could not find a PDF viewer.")))

(provide 'x86-lookup)

;;; x86-lookup.el ends here