1 ;;; thingatpt.el --- Get the `thing' at point
3 ;; Copyright (C) 1991,92,93,94,95,96,1997 Free Software Foundation, Inc.
5 ;; Author: Mike Williams <mikew@gopher.dosli.govt.nz>
6 ;; Keywords: extensions, matching, mouse
7 ;; Created: Thu Mar 28 13:48:23 1991
9 ;; This file is part of GNU Emacs.
11 ;; GNU Emacs is free software; you can redistribute it and/or modify
12 ;; it under the terms of the GNU General Public License as published by
13 ;; the Free Software Foundation; either version 2, or (at your option)
16 ;; GNU Emacs is distributed in the hope that it will be useful,
17 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
18 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
19 ;; GNU General Public License for more details.
23 ;; This file provides routines for getting the "thing" at the location of
24 ;; point, whatever that "thing" happens to be. The "thing" is defined by
25 ;; its beginning and end positions in the buffer.
27 ;; The function bounds-of-thing-at-point finds the beginning and end
28 ;; positions by moving first forward to the end of the "thing", and then
29 ;; backwards to the beginning. By default, it uses the corresponding
30 ;; forward-"thing" operator (eg. forward-word, forward-line).
32 ;; Special cases are allowed for using properties associated with the named
35 ;; forward-op Function to call to skip forward over a "thing" (or
36 ;; with a negative argument, backward).
38 ;; beginning-op Function to call to skip to the beginning of a "thing".
39 ;; end-op Function to call to skip to the end of a "thing".
41 ;; Reliance on existing operators means that many `things' can be accessed
42 ;; without further code: eg.
43 ;; (thing-at-point 'line)
44 ;; (thing-at-point 'page)
53 (defun forward-thing (thing &optional n)
54 "Move forward to the end of the next THING."
55 (let ((forward-op (or (get thing 'forward-op)
56 (intern-soft (format "forward-%s" thing)))))
57 (if (fboundp forward-op)
58 (funcall forward-op (or n 1))
59 (error "Can't determine how to move over a %s" thing))))
64 (defun bounds-of-thing-at-point (thing)
65 "Determine the start and end buffer locations for the THING at point.
66 THING is a symbol which specifies the kind of syntactic entity you want.
67 Possibilities include `symbol', `list', `sexp', `defun', `filename', `url',
68 `word', `sentence', `whitespace', `line', `page' and others.
70 See the file `thingatpt.el' for documentation on how to define
71 a symbol as a valid THING.
73 The value is a cons cell (START . END) giving the start and end positions
74 of the textual entity that was found."
75 (if (get thing 'bounds-of-thing-at-point)
76 (funcall (get thing 'bounds-of-thing-at-point))
80 ;; Try moving forward, then back.
83 (or (get thing 'end-op)
84 (function (lambda () (forward-thing thing 1)))))
88 (or (get thing 'beginning-op)
89 (function (lambda () (forward-thing thing -1)))))
91 (if (not (and beg (> beg orig)))
92 ;; If that brings us all the way back to ORIG,
93 ;; it worked. But END may not be the real end.
94 ;; So find the real end that corresponds to BEG.
98 (or (get thing 'end-op)
99 (function (lambda () (forward-thing thing 1)))))
101 (if (and beg real-end (<= beg orig) (<= orig real-end))
102 (cons beg real-end)))
104 ;; Try a second time, moving backward first and then forward,
105 ;; so that we can find a thing that ends at ORIG.
108 (or (get thing 'beginning-op)
109 (function (lambda () (forward-thing thing -1)))))
113 (or (get thing 'end-op)
114 (function (lambda () (forward-thing thing 1)))))
119 (or (get thing 'beginning-op)
120 (function (lambda () (forward-thing thing -1)))))
122 (if (and real-beg end (<= real-beg orig) (<= orig end))
123 (cons real-beg end))))))
127 (defun thing-at-point (thing)
128 "Return the THING at point.
129 THING is a symbol which specifies the kind of syntactic entity you want.
130 Possibilities include `symbol', `list', `sexp', `defun', `filename', `url',
131 `word', `sentence', `whitespace', `line', `page' and others.
133 See the file `thingatpt.el' for documentation on how to define
134 a symbol as a valid THING."
135 (if (get thing 'thing-at-point)
136 (funcall (get thing 'thing-at-point))
137 (let ((bounds (bounds-of-thing-at-point thing)))
139 (buffer-substring (car bounds) (cdr bounds))))))
141 ;; Go to beginning/end
143 (defun beginning-of-thing (thing)
144 (let ((bounds (bounds-of-thing-at-point thing)))
145 (or bounds (error "No %s here" thing))
146 (goto-char (car bounds))))
148 (defun end-of-thing (thing)
149 (let ((bounds (bounds-of-thing-at-point thing)))
150 (or bounds (error "No %s here" thing))
151 (goto-char (cdr bounds))))
157 ;; bolp will be false when you click on the last line in the buffer
158 ;; and it has no final newline.
160 (put 'line 'beginning-op
161 (function (lambda () (if (bolp) (forward-line -1) (beginning-of-line)))))
165 (defun in-string-p ()
166 (let ((orig (point)))
169 (nth 3 (parse-partial-sexp (point) orig)))))
171 (defun end-of-sexp ()
172 (let ((char-syntax (char-syntax (char-after (point)))))
173 (if (or (eq char-syntax ?\))
174 (and (eq char-syntax ?\") (in-string-p)))
178 (put 'sexp 'end-op 'end-of-sexp)
180 (defun beginning-of-sexp ()
181 (let ((char-syntax (char-syntax (char-before (point)))))
182 (if (or (eq char-syntax ?\()
183 (and (eq char-syntax ?\") (in-string-p)))
187 (put 'sexp 'beginning-op 'beginning-of-sexp)
191 (put 'list 'end-op (function (lambda () (up-list 1))))
192 (put 'list 'beginning-op 'backward-sexp)
194 ;; Filenames and URLs
196 (defvar thing-at-point-file-name-chars "~/A-Za-z0-9---_.${}#%,:"
197 "Characters allowable in filenames.")
199 (put 'filename 'end-op
200 '(lambda () (skip-chars-forward thing-at-point-file-name-chars)))
201 (put 'filename 'beginning-op
202 '(lambda () (skip-chars-backward thing-at-point-file-name-chars)))
204 (defvar thing-at-point-url-path-regexp
205 "[^]\t\n \"'()<>[^`{}]*[^]\t\n \"'()<>[^`{}.,;]+"
206 "A regular expression probably matching the host, path or e-mail part of a URL.")
208 (defvar thing-at-point-short-url-regexp
209 (concat "[-A-Za-z0-9.]+" thing-at-point-url-path-regexp)
210 "A regular expression probably matching a URL without an access scheme.
211 Hostname matching is stricter in this case than for
212 ``thing-at-point-url-regexp''.")
214 (defvar thing-at-point-url-regexp
216 "\\(https?://\\|ftp://\\|gopher://\\|telnet://\\|wais://\\|file:/\\|s?news:\\|mailto:\\)"
217 thing-at-point-url-path-regexp)
218 "A regular expression probably matching a complete URL.")
220 (defvar thing-at-point-markedup-url-regexp
222 "A regular expression matching a URL marked up per RFC1738.
223 This may contain whitespace (including newlines) .")
225 (put 'url 'bounds-of-thing-at-point 'thing-at-point-bounds-of-url-at-point)
226 (defun thing-at-point-bounds-of-url-at-point ()
227 (let ((url "") short strip)
228 (if (or (setq strip (thing-at-point-looking-at
229 thing-at-point-markedup-url-regexp))
230 (thing-at-point-looking-at thing-at-point-url-regexp)
231 ;; Access scheme omitted?
232 (setq short (thing-at-point-looking-at
233 thing-at-point-short-url-regexp)))
234 (let ((beginning (match-beginning 0))
237 (setq beginning (+ beginning 5))
238 (setq end (- end 1))))
239 (cons beginning end)))))
241 (put 'url 'thing-at-point 'thing-at-point-url-at-point)
242 (defun thing-at-point-url-at-point ()
243 "Return the URL around or before point.
244 Search backwards for the start of a URL ending at or after
245 point. If no URL found, return nil. The access scheme, `http://'
246 will be prepended if absent."
247 (let ((url "") short strip)
248 (if (or (setq strip (thing-at-point-looking-at
249 thing-at-point-markedup-url-regexp))
250 (thing-at-point-looking-at thing-at-point-url-regexp)
251 ;; Access scheme omitted?
252 (setq short (thing-at-point-looking-at
253 thing-at-point-short-url-regexp)))
255 (setq url (buffer-substring-no-properties (match-beginning 0)
257 (and strip (setq url (substring url 5 -1))) ; Drop "<URL:" & ">"
259 (while (string-match "\\s +\\|\n+" url)
260 (setq url (replace-match "" t t url)))
261 (and short (setq url (concat (if (string-match "@" url)
262 "mailto:" "http://") url)))
263 (if (string-equal "" url)
267 ;; The normal thingatpt mechanism doesn't work for complex regexps.
268 ;; This should work for almost any regexp wherever we are in the
269 ;; match. To do a perfect job for any arbitrary regexp would mean
270 ;; testing every position before point. Regexp searches won't find
271 ;; matches that straddle the start position so we search forwards once
272 ;; and then back repeatedly and then back up a char at a time.
274 (defun thing-at-point-looking-at (regexp)
275 "Return non-nil if point is in or just after a match for REGEXP.
276 Set the match data from the earliest such match ending at or after
279 (let ((old-point (point)) match)
280 (and (looking-at regexp)
281 (>= (match-end 0) old-point)
282 (setq match (point)))
283 ;; Search back repeatedly from end of next match.
284 ;; This may fail if next match ends before this match does.
285 (re-search-forward regexp nil 'limit)
286 (while (and (re-search-backward regexp nil t)
287 (or (> (match-beginning 0) old-point)
288 (and (looking-at regexp) ; Extend match-end past search start
289 (>= (match-end 0) old-point)
290 (setq match (point))))))
293 ;; Back up a char at a time in case search skipped
294 ;; intermediate match straddling search start pos.
295 (while (and (not (bobp))
296 (progn (backward-char 1) (looking-at regexp))
297 (>= (match-end 0) old-point)
298 (setq match (point))))
300 (looking-at regexp)))))
304 (let ((bounds (thing-at-point-bounds-of-url-at-point)))
306 (goto-char (cdr bounds))
307 (error "No URL here"))))))
308 (put 'url 'beginning-op
310 (let ((bounds (thing-at-point-bounds-of-url-at-point)))
312 (goto-char (car bounds))
313 (error "No URL here"))))))
317 (defun forward-whitespace (arg)
320 (re-search-forward "[ \t]+\\|\n" nil 'move arg)
322 (if (re-search-backward "[ \t]+\\|\n" nil 'move)
323 (or (eq (char-after (match-beginning 0)) 10)
324 (skip-chars-backward " \t")))
325 (setq arg (1+ arg)))))
329 (put 'buffer 'end-op '(lambda () (goto-char (point-max))))
330 (put 'buffer 'beginning-op '(lambda () (goto-char (point-min))))
334 (defun forward-symbol (arg)
337 (re-search-forward "\\(\\sw\\|\\s_\\)+" nil 'move arg)
339 (if (re-search-backward "\\(\\sw\\|\\s_\\)+" nil 'move)
340 (skip-syntax-backward "w_"))
341 (setq arg (1+ arg)))))
345 (defun forward-same-syntax (&optional arg)
348 (skip-syntax-backward
349 (char-to-string (char-syntax (char-after (1- (point))))))
352 (skip-syntax-forward (char-to-string (char-syntax (char-after (point)))))
353 (setq arg (1- arg))))
357 (defun word-at-point () (thing-at-point 'word))
358 (defun sentence-at-point () (thing-at-point 'sentence))
360 (defun read-from-whole-string (str)
361 "Read a lisp expression from STR.
362 Signal an error if the entire string was not used."
363 (let* ((read-data (read-from-string str))
366 (progn (read-from-string (substring str (cdr read-data)))
370 (error "Can't read whole string")
373 (defun form-at-point (&optional thing pred)
374 (let ((sexp (condition-case nil
375 (read-from-whole-string (thing-at-point (or thing 'sexp)))
377 (if (or (not pred) (funcall pred sexp)) sexp)))
379 (defun sexp-at-point () (form-at-point 'sexp))
380 (defun symbol-at-point () (form-at-point 'sexp 'symbolp))
381 (defun number-at-point () (form-at-point 'sexp 'numberp))
382 (defun list-at-point () (form-at-point 'list 'listp))
384 ;; thingatpt.el ends here.