Example functions

pdf-tools integration

Search contents of PDFs

If you run this and select candidates, this will pass the list of any associated PDF files to pdf-tools to search across all of them. If you run embark-act-all on a filtered candidate list, it will pass the files associated with all of them.

(defun ex/search-pdf-contents (keys-entries &optional str)
  "Search pdfs."
  (interactive (list (citar-select-refs)))
  (let ((files (citar-file--files-for-multiple-entries
                (citar--ensure-entries keys-entries)
                citar-library-paths
                '("pdf")))
        (search-str (or str (read-string "Search string: "))))
    (pdf-occur-search files search-str t)))

;; with this, you can exploit embark's multitarget actions, so that you can run `embark-act-all`
(add-to-list 'embark-multitarget-actions #'ex/search-pdf-contents)

Add metadata to PDF files

This function will use the metadata from the entry and update the PDF file metadata.

(defun ex/update-pdf-metadata (key-entry)
  "Add/update metadata of PDF for KEY-ENTRY."
  (interactive (list (citar-select-ref)))
  (let* ((entry (cdr key-entry))
         (key (car key-entry))
         (file (car (citar-file--files-for-entry
                     key
                     entry
                     citar-library-paths
                     '("pdf"))))
         (title (citar-clean-string (citar-get-value 'title entry)))
         (author (citar-get-value 'author entry)))
    (call-process-shell-command
     (concat "exiftool -Title='" title "' -Author='" author "' " file))))

Alternatively, in order to make use of the 'editor' field when the 'author' field is empty while also keeping your library free of the backup files that exiftool creates by default, the following may be of use:

(defvar ex/citar-library-backup-path "/path/to/library/backup")

(defun ex/update-pdf-metadata-alt (key-entry)
  "Add/update metadata of PDF for KEY-ENTRY.\n Adapted from citar's wiki"
  (interactive (list (citar-select-ref)))
  (let* ((entry (cdr key-entry))
         (key (car key-entry))
         (file (car (citar-file--files-for-entry
                     key
                     entry
                     citar-library-paths
                     '("pdf"))))
         (title (citar-clean-string (citar-get-value 'title entry)))
         (author (cond ((citar-has-a-value '(author) entry)
                        (citar-get-value 'author entry))
                        ((citar-has-a-value '(editor) entry)
                         (concat (citar-get-value 'editor entry) " (ed.)")))))
    (if (bound-and-true-p file)
        (progn
          (copy-file file my/citar-library-backup-path 1)
          (call-process-shell-command
           (concat "exiftool -overwrite_original_in_place -Title='" title "' -Author='" author "' " file)))
      (print (format "I could not find a file associated with %s" key)))))

Add file to library

(defun citar--add-file-to-library (key)
  "Add a file to the library for KEY.
The FILE can be added either from an open buffer, a file, or a
URL."
  (let* ((source
          (char-to-string
           (read-char-choice
            "Add file from [b]uffer, [f]ile, or [u]rl? " '(?b ?f ?u))))
         (directory (if (cdr citar-library-paths)
                        (completing-read "Directory: " citar-library-paths)
                      (car citar-library-paths)))
         (file-path
          (file-name-concat directory (concat key ".pdf")))) ; FIX so don't hardcode extension
    (pcase source
      ("b"
       (with-current-buffer (read-buffer-to-switch "Add file buffer: ")
         (write-file file-path)))
      ("f"
       (copy-file
        (expand-file-name
         (read-file-name "Add file: " nil nil t)) file-path))
      ("u"
       (url-copy-file (read-string "Add file URL: ") file-path)))))

(defun citar-add-file-to-library (key-entry)
  "Add a file to the library for KEY-ENTRY.
The FILE can be added either from an open buffer, a file, or a
URL."
  (interactive (list (citar-select-ref
                      :rebuild-cache current-prefix-arg)))
   (citar--add-file-to-library (car key-entry)))