1 ;;; thingatpt.el --- get the `thing' at point
3 ;; Copyright (C) 1991-1998, 2000-2011
4 ;; Free Software Foundation, Inc.
6 ;; Author: Mike Williams <mikew@gopher.dosli.govt.nz>
8 ;; Keywords: extensions, matching, mouse
9 ;; Created: Thu Mar 28 13:48:23 1991
11 ;; This file is part of GNU Emacs.
13 ;; GNU Emacs is free software: you can redistribute it and/or modify
14 ;; it under the terms of the GNU General Public License as published by
15 ;; the Free Software Foundation, either version 3 of the License, or
16 ;; (at your option) any later version.
18 ;; GNU Emacs is distributed in the hope that it will be useful,
19 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
20 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
21 ;; GNU General Public License for more details.
23 ;; You should have received a copy of the GNU General Public License
24 ;; along with GNU Emacs. If not, see <http://www.gnu.org/licenses/>.
28 ;; This file provides routines for getting the "thing" at the location of
29 ;; point, whatever that "thing" happens to be. The "thing" is defined by
30 ;; its beginning and end positions in the buffer.
32 ;; The function bounds-of-thing-at-point finds the beginning and end
33 ;; positions by moving first forward to the end of the "thing", and then
34 ;; backwards to the beginning. By default, it uses the corresponding
35 ;; forward-"thing" operator (eg. forward-word, forward-line).
37 ;; Special cases are allowed for using properties associated with the named
40 ;; forward-op Function to call to skip forward over a "thing" (or
41 ;; with a negative argument, backward).
43 ;; beginning-op Function to call to skip to the beginning of a "thing".
44 ;; end-op Function to call to skip to the end of a "thing".
46 ;; Reliance on existing operators means that many `things' can be accessed
47 ;; without further code: eg.
48 ;; (thing-at-point 'line)
49 ;; (thing-at-point 'page)
58 (defun forward-thing (thing &optional n)
59 "Move forward to the end of the Nth next THING."
60 (let ((forward-op (or (get thing 'forward-op)
61 (intern-soft (format "forward-%s" thing)))))
62 (if (functionp forward-op)
63 (funcall forward-op (or n 1))
64 (error "Can't determine how to move over a %s" thing))))
69 (defun bounds-of-thing-at-point (thing)
70 "Determine the start and end buffer locations for the THING at point.
71 THING is a symbol which specifies the kind of syntactic entity you want.
72 Possibilities include `symbol', `list', `sexp', `defun', `filename', `url',
73 `email', `word', `sentence', `whitespace', `line', `page' and others.
75 See the file `thingatpt.el' for documentation on how to define
76 a symbol as a valid THING.
78 The value is a cons cell (START . END) giving the start and end positions
79 of the textual entity that was found."
80 (if (get thing 'bounds-of-thing-at-point)
81 (funcall (get thing 'bounds-of-thing-at-point))
85 ;; Try moving forward, then back.
86 (funcall ;; First move to end.
87 (or (get thing 'end-op)
88 (lambda () (forward-thing thing 1))))
89 (funcall ;; Then move to beg.
90 (or (get thing 'beginning-op)
91 (lambda () (forward-thing thing -1))))
93 (if (not (and beg (> beg orig)))
94 ;; If that brings us all the way back to ORIG,
95 ;; it worked. But END may not be the real end.
96 ;; So find the real end that corresponds to BEG.
100 (or (get thing 'end-op)
101 (lambda () (forward-thing thing 1))))
103 (if (and beg real-end (<= beg orig) (<= orig real-end))
104 (cons beg real-end)))
106 ;; Try a second time, moving backward first and then forward,
107 ;; so that we can find a thing that ends at ORIG.
108 (funcall ;; First, move to beg.
109 (or (get thing 'beginning-op)
110 (lambda () (forward-thing thing -1))))
111 (funcall ;; Then move to end.
112 (or (get thing 'end-op)
113 (lambda () (forward-thing thing 1))))
118 (or (get thing 'beginning-op)
119 (lambda () (forward-thing thing -1))))
121 (if (and real-beg end (<= real-beg orig) (<= orig end))
122 (cons real-beg end))))))
126 (defun thing-at-point (thing)
127 "Return the THING at point.
128 THING is a symbol which specifies the kind of syntactic entity you want.
129 Possibilities include `symbol', `list', `sexp', `defun', `filename', `url',
130 `email', `word', `sentence', `whitespace', `line', `page' and others.
132 See the file `thingatpt.el' for documentation on how to define
133 a symbol as a valid THING."
134 (if (get thing 'thing-at-point)
135 (funcall (get thing 'thing-at-point))
136 (let ((bounds (bounds-of-thing-at-point thing)))
138 (buffer-substring (car bounds) (cdr bounds))))))
140 ;; Go to beginning/end
142 (defun beginning-of-thing (thing)
143 (let ((bounds (bounds-of-thing-at-point thing)))
144 (or bounds (error "No %s here" thing))
145 (goto-char (car bounds))))
147 (defun end-of-thing (thing)
148 (let ((bounds (bounds-of-thing-at-point thing)))
149 (or bounds (error "No %s here" thing))
150 (goto-char (cdr bounds))))
156 ;; bolp will be false when you click on the last line in the buffer
157 ;; and it has no final newline.
159 (put 'line 'beginning-op
160 (lambda () (if (bolp) (forward-line -1) (beginning-of-line))))
164 (defun in-string-p ()
165 (let ((orig (point)))
168 (nth 3 (parse-partial-sexp (point) orig)))))
170 (defun end-of-sexp ()
171 (let ((char-syntax (char-syntax (char-after))))
172 (if (or (eq char-syntax ?\))
173 (and (eq char-syntax ?\") (in-string-p)))
177 (put 'sexp 'end-op 'end-of-sexp)
179 (defun beginning-of-sexp ()
180 (let ((char-syntax (char-syntax (char-before))))
181 (if (or (eq char-syntax ?\()
182 (and (eq char-syntax ?\") (in-string-p)))
186 (put 'sexp 'beginning-op 'beginning-of-sexp)
190 (put 'list 'bounds-of-thing-at-point 'thing-at-point-bounds-of-list-at-point)
192 (defun thing-at-point-bounds-of-list-at-point ()
194 (let ((opoint (point))
195 (beg (condition-case nil
201 (progn (forward-sexp)
203 ;; Are we are at the beginning of a top-level sexp?
207 (if (>= opoint (point))
211 ;; Filenames and URLs www.com/foo%32bar
213 (defvar thing-at-point-file-name-chars "-~/[:alnum:]_.${}#%,:"
214 "Characters allowable in filenames.")
216 (put 'filename 'end-op
218 (re-search-forward (concat "\\=[" thing-at-point-file-name-chars "]*")
220 (put 'filename 'beginning-op
222 (if (re-search-backward (concat "[^" thing-at-point-file-name-chars "]")
225 (goto-char (point-min)))))
227 (defvar thing-at-point-url-path-regexp
228 "[^]\t\n \"'<>[^`{}]*[^]\t\n \"'<>[^`{}.,;]+"
229 "A regular expression probably matching the host and filename or e-mail part of a URL.")
231 (defvar thing-at-point-short-url-regexp
232 (concat "[-A-Za-z0-9.]+" thing-at-point-url-path-regexp)
233 "A regular expression probably matching a URL without an access scheme.
234 Hostname matching is stricter in this case than for
235 ``thing-at-point-url-regexp''.")
237 (defvar thing-at-point-uri-schemes
238 ;; Officials from http://www.iana.org/assignments/uri-schemes.html
239 '("ftp://" "http://" "gopher://" "mailto:" "news:" "nntp:"
240 "telnet://" "wais://" "file:/" "prospero:" "z39.50s:" "z39.50r:"
241 "cid:" "mid:" "vemmi:" "service:" "imap:" "nfs:" "acap:" "rtsp:"
242 "tip:" "pop:" "data:" "dav:" "opaquelocktoken:" "sip:" "tel:" "fax:"
243 "modem:" "ldap:" "https://" "soap.beep:" "soap.beeps:" "urn:" "go:"
244 "afs:" "tn3270:" "mailserver:"
245 "crid:" "dict:" "dns:" "dtn:" "h323:" "im:" "info:" "ipp:"
246 "iris.beep:" "mtqp:" "mupdate:" "pres:" "sips:" "snmp:" "tag:"
247 "tftp:" "xmlrpc.beep:" "xmlrpc.beeps:" "xmpp:"
249 "snews:" "irc:" "mms://" "mmsh://")
250 "Uniform Resource Identifier (URI) Schemes.")
252 (defvar thing-at-point-url-regexp
253 (concat "\\<\\(" (mapconcat 'identity thing-at-point-uri-schemes "\\|") "\\)"
254 thing-at-point-url-path-regexp)
255 "A regular expression probably matching a complete URL.")
257 (defvar thing-at-point-markedup-url-regexp
259 "A regular expression matching a URL marked up per RFC1738.
260 This may contain whitespace (including newlines) .")
262 (put 'url 'bounds-of-thing-at-point 'thing-at-point-bounds-of-url-at-point)
263 (defun thing-at-point-bounds-of-url-at-point ()
264 (let ((strip (thing-at-point-looking-at
265 thing-at-point-markedup-url-regexp))) ;; (url "") short
267 (thing-at-point-looking-at thing-at-point-url-regexp)
268 ;; Access scheme omitted?
269 ;; (setq short (thing-at-point-looking-at
270 ;; thing-at-point-short-url-regexp))
272 (let ((beginning (match-beginning 0))
275 (setq beginning (+ beginning 5))
276 (setq end (- end 1)))
277 (cons beginning end)))))
279 (put 'url 'thing-at-point 'thing-at-point-url-at-point)
280 (defun thing-at-point-url-at-point ()
281 "Return the URL around or before point.
283 Search backwards for the start of a URL ending at or after point. If
284 no URL found, return nil. The access scheme will be prepended if
285 absent: \"mailto:\" if the string contains \"@\", \"ftp://\" if it
286 starts with \"ftp\" and not \"ftp:/\", or \"http://\" by default."
288 (let ((url "") short strip)
289 (if (or (setq strip (thing-at-point-looking-at
290 thing-at-point-markedup-url-regexp))
291 (thing-at-point-looking-at thing-at-point-url-regexp)
292 ;; Access scheme omitted?
293 (setq short (thing-at-point-looking-at
294 thing-at-point-short-url-regexp)))
296 (setq url (buffer-substring-no-properties (match-beginning 0)
298 (and strip (setq url (substring url 5 -1))) ; Drop "<URL:" & ">"
300 (while (string-match "[ \t\n\r]+" url)
301 (setq url (replace-match "" t t url)))
302 (and short (setq url (concat (cond ((string-match "^[a-zA-Z]+:" url)
303 ;; already has a URL scheme.
305 ((string-match "@" url)
307 ;; e.g. ftp.swiss... or ftp-swiss...
308 ((string-match "^ftp" url)
312 (if (string-equal "" url)
316 ;; The normal thingatpt mechanism doesn't work for complex regexps.
317 ;; This should work for almost any regexp wherever we are in the
318 ;; match. To do a perfect job for any arbitrary regexp would mean
319 ;; testing every position before point. Regexp searches won't find
320 ;; matches that straddle the start position so we search forwards once
321 ;; and then back repeatedly and then back up a char at a time.
323 (defun thing-at-point-looking-at (regexp)
324 "Return non-nil if point is in or just after a match for REGEXP.
325 Set the match data from the earliest such match ending at or after
328 (let ((old-point (point)) match)
329 (and (looking-at regexp)
330 (>= (match-end 0) old-point)
331 (setq match (point)))
332 ;; Search back repeatedly from end of next match.
333 ;; This may fail if next match ends before this match does.
334 (re-search-forward regexp nil 'limit)
335 (while (and (re-search-backward regexp nil t)
336 (or (> (match-beginning 0) old-point)
337 (and (looking-at regexp) ; Extend match-end past search start
338 (>= (match-end 0) old-point)
339 (setq match (point))))))
342 ;; Back up a char at a time in case search skipped
343 ;; intermediate match straddling search start pos.
344 (while (and (not (bobp))
345 (progn (backward-char 1) (looking-at regexp))
346 (>= (match-end 0) old-point)
347 (setq match (point))))
349 (looking-at regexp)))))
353 (let ((bounds (thing-at-point-bounds-of-url-at-point)))
355 (goto-char (cdr bounds))
356 (error "No URL here")))))
357 (put 'url 'beginning-op
359 (let ((bounds (thing-at-point-bounds-of-url-at-point)))
361 (goto-char (car bounds))
362 (error "No URL here")))))
365 (defvar thing-at-point-email-regexp
366 "<?[-+_.~a-zA-Z][-+_.~:a-zA-Z0-9]*@[-.a-zA-Z0-9]+>?"
367 "A regular expression probably matching an email address.
368 This does not match the real name portion, only the address, optionally
369 with angle brackets.")
371 ;; Haven't set 'forward-op on 'email nor defined 'forward-email' because
372 ;; not sure they're actually needed, and URL seems to skip them too.
373 ;; Note that (end-of-thing 'email) and (beginning-of-thing 'email)
374 ;; work automagically, though.
376 (put 'email 'bounds-of-thing-at-point
378 (let ((thing (thing-at-point-looking-at thing-at-point-email-regexp)))
380 (let ((beginning (match-beginning 0))
382 (cons beginning end))))))
384 (put 'email 'thing-at-point
386 (let ((boundary-pair (bounds-of-thing-at-point 'email)))
388 (buffer-substring-no-properties
389 (car boundary-pair) (cdr boundary-pair))))))
393 (defun forward-whitespace (arg)
396 (re-search-forward "[ \t]+\\|\n" nil 'move arg)
398 (if (re-search-backward "[ \t]+\\|\n" nil 'move)
399 (or (eq (char-after (match-beginning 0)) 10)
400 (skip-chars-backward " \t")))
401 (setq arg (1+ arg)))))
405 (put 'buffer 'end-op (lambda () (goto-char (point-max))))
406 (put 'buffer 'beginning-op (lambda () (goto-char (point-min))))
410 (defun forward-symbol (arg)
413 (re-search-forward "\\(\\sw\\|\\s_\\)+" nil 'move arg)
415 (if (re-search-backward "\\(\\sw\\|\\s_\\)+" nil 'move)
416 (skip-syntax-backward "w_"))
417 (setq arg (1+ arg)))))
421 (defun forward-same-syntax (&optional arg)
424 (skip-syntax-backward
425 (char-to-string (char-syntax (char-before))))
428 (skip-syntax-forward (char-to-string (char-syntax (char-after))))
429 (setq arg (1- arg))))
433 (defun word-at-point () (thing-at-point 'word))
434 (defun sentence-at-point () (thing-at-point 'sentence))
436 (defun read-from-whole-string (str)
437 "Read a Lisp expression from STR.
438 Signal an error if the entire string was not used."
439 (let* ((read-data (read-from-string str))
442 ;; The call to `ignore' suppresses a compiler warning.
443 (progn (ignore (read-from-string (substring str (cdr read-data))))
447 (error "Can't read whole string")
450 (defun form-at-point (&optional thing pred)
451 (let ((sexp (condition-case nil
452 (read-from-whole-string (thing-at-point (or thing 'sexp)))
454 (if (or (not pred) (funcall pred sexp)) sexp)))
457 (defun sexp-at-point ()
458 "Return the sexp at point, or nil if none is found."
459 (form-at-point 'sexp))
461 (defun symbol-at-point ()
462 "Return the symbol at point, or nil if none is found."
463 (let ((thing (thing-at-point 'symbol)))
464 (if thing (intern thing))))
466 (defun number-at-point ()
467 "Return the number at point, or nil if none is found."
468 (form-at-point 'sexp 'numberp))
470 (defun list-at-point ()
471 "Return the Lisp list at point, or nil if none is found."
472 (form-at-point 'list 'listp))
474 ;;; thingatpt.el ends here