1;;; refer.el --- look up references in bibliography files
2
3;; Copyright (C) 1992, 1996, 2001-2021 Free Software Foundation, Inc.
4
5;; Author: Ashwin Ram <ashwin@cc.gatech.edu>
6;; Maintainer: emacs-devel@gnu.org
7;; Adapted-By: ESR
8;; Keywords: bib
9
10;; This file is part of GNU Emacs.
11
12;; GNU Emacs is free software: you can redistribute it and/or modify
13;; it under the terms of the GNU General Public License as published by
14;; the Free Software Foundation, either version 3 of the License, or
15;; (at your option) any later version.
16
17;; GNU Emacs is distributed in the hope that it will be useful,
18;; but WITHOUT ANY WARRANTY; without even the implied warranty of
19;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
20;; GNU General Public License for more details.
21
22;; You should have received a copy of the GNU General Public License
23;; along with GNU Emacs.  If not, see <https://www.gnu.org/licenses/>.
24
25;;; Commentary:
26
27;; Functions to look up references in bibliography files given lists of
28;; keywords, similar to refer(1).  I don't use tags since tags on .bib files
29;; only picks up the cite key, where as refer-find-entry looks for occurrences
30;; of keywords anywhere in the bibliography entry.
31;;
32;; To use:
33;;      (autoload 'refer-find-entry "refer" nil t)
34;; or   (require 'refer)
35;;
36;;      To look for an article by Knuth about semaphores:
37;;          Invoke refer-find-entry, then in response to the Keywords: prompt,
38;;          say: Knuth semaphores (a blank-separated list of keywords to be used
39;;          as search strings).
40;;
41;;      To continue the previous search, i.e., to search for the next occurrence
42;;      of the keywords, use refer-find-next-entry, or invoke refer-find-entry
43;;      with a prefix argument.
44;;
45;;	Once you've found the entry you want to reference, invoke
46;;	refer-yank-key to insert it at point in the current buffer
47;;	(typically as the argument of a \cite{} command).
48;;
49;;	I use (define-key tex-mode-map    "\C-c\C-y"  'refer-yank-key)
50;;	to bind this often-used function to a key in (la)tex-mode.
51;;
52;;      If the list of bibliography files changes, reinitialize the variable
53;;      refer-bib-files.
54;;
55;; To customize:
56;;      See variables refer-bib-files, refer-cache-bib-files and
57;;      refer-bib-files-regexp.  By default, these are set up so that refer
58;;      looks for the keywords you specify in all the .bib files in the current
59;;      directory.
60;;
61;;      The only assumption I make about bib files is that they contain a bunch
62;;      of entries, one to a paragraph.  refer-find-entry searches paragraph by
63;;      paragraph, looking for a paragraph containing all the keywords
64;;      specified.  So you should be able to use pretty much any bib file with
65;;      this code.  If your bib file does not use paragraphs to separate
66;;      entries, try setting the paragraph-start/separate variables, or changing
67;;      the (forward-paragraph 1) call in refer-find-entry-in-file.
68
69;;; Code:
70
71(provide 'refer)
72
73(defgroup refer nil
74  "Look up references in bibliography files."
75  :prefix "refer-"
76  :group 'text)
77
78(defcustom refer-bib-directory nil
79  "Directory, or list of directories, to search for \\.bib files.
80Can be set to `bibinputs' or `texinputs', in which case the environment
81variable BIBINPUTS or TEXINPUTS, respectively, is used to obtain a
82list of directories.  Useful only if `refer-bib-files' is set to `dir' or
83a list of file names (without directory).  A value of nil indicates the
84current working directory.
85
86If `refer-bib-directory' is `bibinputs' or `texinputs', it is setq'd to
87the appropriate list of directories when it is first used.
88
89Note that an empty directory is interpreted by BibTeX as indicating
90the default search path.  Since Refer does not know that default path,
91it cannot search it.  Include that path explicitly in your BIBINPUTS
92environment if you really want it searched (which is not likely to
93happen anyway)."
94  :type '(choice (repeat directory) (const bibinputs) (const texinputs))
95  :group 'refer)
96
97(defcustom refer-bib-files 'dir
98  "List of \\.bib files to search for references,
99or one of the following special values:
100nil  = prompt for \\.bib file (if visiting a \\.bib file, use it as default)
101auto = read \\.bib file names from appropriate command in buffer (see
102       `refer-bib-files-regexp') unless the buffer's mode is `bibtex-mode',
103       in which case only the buffer is searched
104dir  = use all \\.bib files in directories referenced by `refer-bib-directory'.
105
106If a specified file doesn't exist and has no extension, a \\.bib extension
107is automatically tried.
108
109If `refer-bib-files' is nil, auto or dir, it is setq'd to the appropriate
110list of files when it is first used if `refer-cache-bib-files' is t.  If
111`refer-cache-bib-files' is nil, the list of \\.bib files to use is re-read
112each time it is needed."
113  :type '(choice (repeat file) (const nil) (const auto) (const dir))
114  :group 'refer)
115
116(defcustom refer-cache-bib-files t
117  "Variable determining whether the value of `refer-bib-files' should be cached.
118If t, initialize the value of refer-bib-files the first time it is used.  If
119nil, re-read the list of \\.bib files depending on the value of `refer-bib-files'
120each time it is needed."
121  :type 'boolean
122  :group 'refer)
123
124(defcustom refer-bib-files-regexp "\\\\bibliography"
125  "Regexp matching a bibliography file declaration.
126The current buffer is expected to contain a line such as
127\\bibliography{file1,file2,file3}
128which is read to set up `refer-bib-files'.  The regexp must specify the command
129\(such as \\bibliography) that is used to specify the list of bib files.  The
130command is expected to specify a file name, or a list of comma-separated file
131names, within curly braces.
132If a specified file doesn't exist and has no extension, a \\.bib extension
133is automatically tried."
134  :type 'regexp
135  :group 'refer)
136
137(make-variable-buffer-local 'refer-bib-files)
138(make-variable-buffer-local 'refer-cache-bib-files)
139(make-variable-buffer-local 'refer-bib-directory)
140
141;;; Internal variables
142(defvar refer-saved-state nil)
143(defvar refer-previous-keywords nil)
144(defvar refer-saved-pos nil)
145(defvar refer-same-file nil)
146
147(defun refer-find-entry (keywords &optional continue)
148   "Find entry in refer-bib-files containing KEYWORDS.
149If KEYWORDS is nil, prompt user for blank-separated list of keywords.
150If CONTINUE is non-nil, or if called interactively with a prefix arg,
151look for next entry by continuing search from previous point."
152   (interactive (list nil current-prefix-arg))
153   (or keywords (setq keywords (if continue
154                                   refer-previous-keywords
155                                 (read-string "Keywords: "))))
156   (setq refer-previous-keywords keywords)
157   (refer-find-entry-internal keywords continue))
158
159(defun refer-find-next-entry ()
160   "Find next occurrence of entry in `refer-bib-files'.  See `refer-find-entry'."
161   (interactive)
162   (refer-find-entry-internal refer-previous-keywords t))
163
164(defun refer-yank-key ()
165  "Inserts at point in current buffer the \"key\" field of the entry
166found on the last `refer-find-entry' or `refer-find-next-entry'."
167  (interactive)
168  (let ((old-point (point)))
169    (insert
170     (save-window-excursion
171       (save-excursion
172         (find-file (car refer-saved-state))
173         (if (looking-at
174              "[ \t\n]*@\\s-*[a-zA-Z][a-zA-Z0-9]*\\s-*{\\s-*\\([^ \t\n,]+\\)\\s-*,")
175             (buffer-substring (match-beginning 1) (match-end 1))
176           (error "Cannot find key for entry in file %s"
177                  (car refer-saved-state))))))
178    (if (not (= (point) old-point))
179      (set-mark old-point))))
180
181(defun refer-find-entry-internal (keywords continue)
182   (let ((keywords-list (refer-convert-string-to-list-of-strings keywords))
183         (old-buffer (current-buffer))
184         (old-window (selected-window))
185         (new-window (selected-window))
186         (files (if continue
187                    refer-saved-state
188                  (setq refer-saved-pos nil)
189                  (refer-get-bib-files)))
190         (n 0)
191         (found nil)
192         (file nil))
193     ;; find window in which to display bibliography file.
194     ;; if a bibliography file is already displayed in a window, use
195     ;; that one, otherwise use any window other than the current one
196     (setq new-window
197	   (get-window-with-predicate
198	    (lambda (w)
199	      (while (and (not (null (setq file (nth n files))))
200			  (setq n (1+ n))
201			  (not (string-equal file
202					     (buffer-file-name
203					      (window-buffer w))))))
204	      file)))
205     (unless new-window
206       ;; didn't find bib file in any window:
207       (when (one-window-p 'nomini)
208	 (setq old-window (split-window)))
209       (setq new-window (next-window old-window 'nomini)))
210     (select-window (if refer-same-file
211                        old-window
212                      new-window))  ; the window in which to show the bib file
213     (catch 'found
214       (while files
215         (let ((file (cond ((file-exists-p (car files)) (car files))
216                           ((file-exists-p (concat (car files) ".bib"))
217                            (concat (car files) ".bib")))))
218           (setq refer-saved-state files)
219           (if file
220               (if (refer-find-entry-in-file keywords-list file refer-saved-pos)
221                   (progn
222                     (setq refer-saved-pos (point))
223                     (recenter 0)
224                     (throw 'found (find-file file)))
225                 (setq refer-saved-pos nil
226                       files (cdr files)))
227             (progn (ding)
228		    (message "Scanning %s... No such file" (car files))
229                    (sit-for 1)
230                    (setq files (cdr files))))))
231       (ding)
232       (message "Keywords \"%s\" not found in any .bib file" keywords))
233     (select-window old-window)))
234
235(defun refer-find-entry-in-file (keywords-list file &optional old-pos)
236   (message "Scanning %s..." file)
237   (expand-file-name file)
238   (set-buffer (find-file-noselect file))
239   (find-file file)
240   (if (not old-pos)
241       (goto-char (point-min))
242     (goto-char old-pos)
243     (forward-paragraph 1))
244   (let ((begin (point))
245         (end 0)
246         (found nil))
247     (while (and (not found)
248                 (not (eobp)))
249       (forward-paragraph 1)
250       (setq end (point))
251       (setq found
252             (refer-every (function (lambda (keyword)
253                                (goto-char begin)
254                                (re-search-forward keyword end t)))
255                    keywords-list))
256       (if (not found)
257           (progn
258             (setq begin end)
259             (goto-char begin))))
260     (if found
261         (progn (goto-char begin)
262                (re-search-forward "\\W" nil t)
263                (message "Scanning %s... found" file))
264       (progn (message "Scanning %s... not found" file)
265              nil))))
266
267(defun refer-every (pred l)
268  (cond ((null l) nil)
269	((funcall pred (car l))
270	 (or (null (cdr l))
271	     (refer-every pred (cdr l))))))
272
273(defun refer-convert-string-to-list-of-strings (s)
274   (let ((current (current-buffer))
275         (temp-buffer (get-buffer-create "*refer-temp*")))
276      (set-buffer temp-buffer)
277      (erase-buffer)
278      (insert (regexp-quote s))
279      (goto-char (point-min))
280      (insert "(\"")
281      (while (re-search-forward "[ \t]+" nil t)
282         (replace-match "\" \"" t t))
283      (goto-char (point-max))
284      (insert "\")")
285      (goto-char (point-min))
286      (prog1 (read temp-buffer)
287         (set-buffer current))))
288
289(defun refer-expand-files (file-list dir-list)
290  (let (file files dir dirs)
291    (while (setq file (car file-list))
292      (setq dirs (copy-alist dir-list))
293      (while (setq dir (car dirs))
294        (if (file-exists-p (expand-file-name file dir))
295            (setq files (append files (list (expand-file-name file dir)))
296                  dirs  nil)
297          (if (file-exists-p (expand-file-name (concat file ".bib") dir))
298              (setq files (append files (list (expand-file-name (concat file ".bib")
299                                                                dir)))
300                    dirs  nil)
301            (setq dirs (cdr dirs)))))
302      (setq file-list (cdr file-list)))
303    files))
304
305(defun refer-get-bib-files ()
306  (let* ((dir-list
307          (cond
308           ((null refer-bib-directory)
309            '("."))
310           ((or (eq refer-bib-directory 'texinputs)
311                (eq refer-bib-directory 'bibinputs))
312            (let ((envvar (getenv (if (eq refer-bib-directory 'texinputs)
313                                      "TEXINPUTS"
314                                    "BIBINPUTS")))
315                  (dirs nil))
316              (if (null envvar)
317                  (setq envvar "."))
318              (while (string-match ":" envvar)
319		(let ((dir (substring envvar 0 (match-beginning 0))))
320		  (if (and (not (string-equal "" dir))
321                           (file-directory-p dir))
322		      (setq dirs (append (list (expand-file-name dir nil))
323                                         dirs))))
324                (setq envvar (substring envvar (match-end 0))))
325	      (if (and (not (string-equal "" envvar))
326                       (file-directory-p envvar))
327		  (setq dirs (append (list envvar) dirs)))
328              (setq dirs (nreverse dirs))))
329	   ((listp refer-bib-directory)
330	    refer-bib-directory)
331           (t
332            (list refer-bib-directory))))
333         (files
334           (cond
335            ((null refer-bib-files)
336             (list (expand-file-name
337                    (if (eq major-mode 'bibtex-mode)
338                        (read-file-name
339                         (format ".bib file (default %s): "
340                                 (file-name-nondirectory
341                                  (buffer-file-name)))
342                         (file-name-directory (buffer-file-name))
343                         (file-name-nondirectory (buffer-file-name))
344                         t)
345                      (read-file-name ".bib file: " nil nil t)))))
346            ((eq refer-bib-files 'auto)
347             (let ((files
348                    (save-excursion
349                      (if (setq refer-same-file (eq major-mode 'bibtex-mode))
350                          (list buffer-file-name)
351                        (if (progn
352                              (goto-char (point-min))
353                              (re-search-forward (concat refer-bib-files-regexp
354                                                         "\\s-*{") nil t))
355                            (let ((files (list (buffer-substring
356                                                (point)
357                                                (progn
358                                                  (re-search-forward "[,}]"
359                                                                     nil t)
360                                                  (backward-char 1)
361                                                  (point))))))
362                              (while (not (looking-at "}"))
363                                (setq files (append files
364                                                    (list (buffer-substring
365                                                           (progn (forward-char 1)
366                                                                  (point))
367                                                           (progn (re-search-forward
368                                                                   "[,}]" nil t)
369                                                                  (backward-char 1)
370                                                                  (point)))))))
371                              files)
372                          (error (concat "No \\\\bibliography command in this "
373                                         "buffer, can't read refer-bib-files")))))))
374               (refer-expand-files files dir-list)))
375            ((eq refer-bib-files 'dir)
376             (let ((dirs (nreverse dir-list))
377                   dir files)
378               (while (setq dir (car dirs))
379                 (setq files
380                       (append (directory-files dir t "\\.bib\\'")
381                               files))
382                 (setq dirs (cdr dirs)))
383               files))
384            ((and (listp refer-bib-files)
385                  (or (eq refer-bib-directory 'texinputs)
386                      (eq refer-bib-directory 'bibinputs)))
387             (refer-expand-files refer-bib-files dir-list))
388            ((listp refer-bib-files) refer-bib-files)
389            (t (error "Invalid value for refer-bib-files: %s"
390                      refer-bib-files)))))
391    (if (or (eq refer-bib-directory 'texinputs)
392            (eq refer-bib-directory 'bibinputs))
393        (setq refer-bib-directory dir-list))
394    (if refer-cache-bib-files
395        (setq refer-bib-files files))
396    files))
397
398;;; refer.el ends here
399