1;;; thingatpt.el --- get the `thing' at point
2
3;; Copyright (C) 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 2000,
4;;   2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
5
6;; Author: Mike Williams <mikew@gopher.dosli.govt.nz>
7;; Maintainer: FSF
8;; Keywords: extensions, matching, mouse
9;; Created: Thu Mar 28 13:48:23 1991
10
11;; This file is part of GNU Emacs.
12
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 2, or (at your option)
16;; any later version.
17
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.
22
23;;; Commentary:
24
25;; This file provides routines for getting the "thing" at the location of
26;; point, whatever that "thing" happens to be.  The "thing" is defined by
27;; its beginning and end positions in the buffer.
28;;
29;; The function bounds-of-thing-at-point finds the beginning and end
30;; positions by moving first forward to the end of the "thing", and then
31;; backwards to the beginning.  By default, it uses the corresponding
32;; forward-"thing" operator (eg. forward-word, forward-line).
33;;
34;; Special cases are allowed for using properties associated with the named
35;; "thing":
36;;
37;;   forward-op		Function to call to skip forward over a "thing" (or
38;;                      with a negative argument, backward).
39;;
40;;   beginning-op	Function to call to skip to the beginning of a "thing".
41;;   end-op		Function to call to skip to the end of a "thing".
42;;
43;; Reliance on existing operators means that many `things' can be accessed
44;; without further code:  eg.
45;;     (thing-at-point 'line)
46;;     (thing-at-point 'page)
47
48;;; Code:
49
50(provide 'thingatpt)
51
52;; Basic movement
53
54;;;###autoload
55(defun forward-thing (thing &optional n)
56  "Move forward to the end of the Nth next THING."
57  (let ((forward-op (or (get thing 'forward-op)
58			(intern-soft (format "forward-%s" thing)))))
59    (if (functionp forward-op)
60	(funcall forward-op (or n 1))
61      (error "Can't determine how to move over a %s" thing))))
62
63;; General routines
64
65;;;###autoload
66(defun bounds-of-thing-at-point (thing)
67  "Determine the start and end buffer locations for the THING at point.
68THING is a symbol which specifies the kind of syntactic entity you want.
69Possibilities include `symbol', `list', `sexp', `defun', `filename', `url',
70`word', `sentence', `whitespace', `line', `page' and others.
71
72See the file `thingatpt.el' for documentation on how to define
73a symbol as a valid THING.
74
75The value is a cons cell (START . END) giving the start and end positions
76of the textual entity that was found."
77  (if (get thing 'bounds-of-thing-at-point)
78      (funcall (get thing 'bounds-of-thing-at-point))
79    (let ((orig (point)))
80      (condition-case nil
81	  (save-excursion
82	    ;; Try moving forward, then back.
83            (funcall ;; First move to end.
84             (or (get thing 'end-op)
85                 (lambda () (forward-thing thing 1))))
86            (funcall ;; Then move to beg.
87             (or (get thing 'beginning-op)
88                 (lambda () (forward-thing thing -1))))
89	    (let ((beg (point)))
90	      (if (not (and beg (> beg orig)))
91		  ;; If that brings us all the way back to ORIG,
92		  ;; it worked.  But END may not be the real end.
93		  ;; So find the real end that corresponds to BEG.
94		  (let ((real-end
95			 (progn
96			   (funcall
97			    (or (get thing 'end-op)
98                                (lambda () (forward-thing thing 1))))
99			   (point))))
100		    (if (and beg real-end (<= beg orig) (<= orig real-end))
101			(cons beg real-end)))
102		(goto-char orig)
103		;; Try a second time, moving backward first and then forward,
104		;; so that we can find a thing that ends at ORIG.
105                (funcall ;; First, move to beg.
106                 (or (get thing 'beginning-op)
107                     (lambda () (forward-thing thing -1))))
108                (funcall ;; Then move to end.
109                 (or (get thing 'end-op)
110                     (lambda () (forward-thing thing 1))))
111		(let ((end (point))
112                      (real-beg
113		       (progn
114			 (funcall
115			  (or (get thing 'beginning-op)
116                              (lambda () (forward-thing thing -1))))
117			 (point))))
118		  (if (and real-beg end (<= real-beg orig) (<= orig end))
119		      (cons real-beg end))))))
120	(error nil)))))
121
122;;;###autoload
123(defun thing-at-point (thing)
124  "Return the THING at point.
125THING is a symbol which specifies the kind of syntactic entity you want.
126Possibilities include `symbol', `list', `sexp', `defun', `filename', `url',
127`word', `sentence', `whitespace', `line', `page' and others.
128
129See the file `thingatpt.el' for documentation on how to define
130a symbol as a valid THING."
131  (if (get thing 'thing-at-point)
132      (funcall (get thing 'thing-at-point))
133    (let ((bounds (bounds-of-thing-at-point thing)))
134      (if bounds
135	  (buffer-substring (car bounds) (cdr bounds))))))
136
137;; Go to beginning/end
138
139(defun beginning-of-thing (thing)
140  (let ((bounds (bounds-of-thing-at-point thing)))
141    (or bounds (error "No %s here" thing))
142    (goto-char (car bounds))))
143
144(defun end-of-thing (thing)
145  (let ((bounds (bounds-of-thing-at-point thing)))
146    (or bounds (error "No %s here" thing))
147    (goto-char (cdr bounds))))
148
149;;  Special cases
150
151;;  Lines
152
153;; bolp will be false when you click on the last line in the buffer
154;; and it has no final newline.
155
156(put 'line 'beginning-op
157     (lambda () (if (bolp) (forward-line -1) (beginning-of-line))))
158
159;;  Sexps
160
161(defun in-string-p ()
162  (let ((orig (point)))
163    (save-excursion
164      (beginning-of-defun)
165      (nth 3 (parse-partial-sexp (point) orig)))))
166
167(defun end-of-sexp ()
168  (let ((char-syntax (char-syntax (char-after (point)))))
169    (if (or (eq char-syntax ?\))
170	    (and (eq char-syntax ?\") (in-string-p)))
171	(forward-char 1)
172      (forward-sexp 1))))
173
174(put 'sexp 'end-op 'end-of-sexp)
175
176(defun beginning-of-sexp ()
177  (let ((char-syntax (char-syntax (char-before (point)))))
178    (if (or (eq char-syntax ?\()
179	    (and (eq char-syntax ?\") (in-string-p)))
180	(forward-char -1)
181      (forward-sexp -1))))
182
183(put 'sexp 'beginning-op 'beginning-of-sexp)
184
185;;  Lists
186
187(put 'list 'end-op (lambda () (up-list 1)))
188(put 'list 'beginning-op 'backward-sexp)
189
190;;  Filenames and URLs  www.com/foo%32bar
191
192(defvar thing-at-point-file-name-chars "-~/[:alnum:]_.${}#%,:"
193  "Characters allowable in filenames.")
194
195(put 'filename 'end-op
196     (lambda ()
197       (re-search-forward (concat "\\=[" thing-at-point-file-name-chars "]*")
198			  nil t)))
199(put 'filename 'beginning-op
200     (lambda ()
201       (if (re-search-backward (concat "[^" thing-at-point-file-name-chars "]")
202			       nil t)
203	   (forward-char)
204	 (goto-char (point-min)))))
205
206(defvar thing-at-point-url-path-regexp
207  "[^]\t\n \"'()<>[^`{}]*[^]\t\n \"'()<>[^`{}.,;]+"
208  "A regular expression probably matching the host and filename or e-mail part of a URL.")
209
210(defvar thing-at-point-short-url-regexp
211  (concat "[-A-Za-z0-9.]+" thing-at-point-url-path-regexp)
212  "A regular expression probably matching a URL without an access scheme.
213Hostname matching is stricter in this case than for
214``thing-at-point-url-regexp''.")
215
216(defvar thing-at-point-uri-schemes
217  ;; Officials from http://www.iana.org/assignments/uri-schemes.html
218  '("ftp://" "http://" "gopher://" "mailto:" "news:" "nntp:"
219    "telnet://" "wais://" "file:/" "prospero:" "z39.50s:" "z39.50r:"
220    "cid:" "mid:" "vemmi:" "service:" "imap:" "nfs:" "acap:" "rtsp:"
221    "tip:" "pop:" "data:" "dav:" "opaquelocktoken:" "sip:" "tel:" "fax:"
222    "modem:" "ldap:" "https://" "soap.beep:" "soap.beeps:" "urn:" "go:"
223    "afs:" "tn3270:" "mailserver:"
224    "crid:" "dict:" "dns:" "dtn:" "h323:" "im:" "info:" "ipp:"
225    "iris.beep:" "mtqp:" "mupdate:" "pres:" "sips:" "snmp:" "tag:"
226    "tftp:" "xmlrpc.beep:" "xmlrpc.beeps:" "xmpp:"
227  ;; Compatibility
228    "snews:" "irc:" "mms://" "mmsh://")
229  "Uniform Resource Identifier (URI) Schemes.")
230
231(defvar thing-at-point-url-regexp
232  (concat "\\<\\(" (mapconcat 'identity thing-at-point-uri-schemes "\\|") "\\)"
233          thing-at-point-url-path-regexp)
234  "A regular expression probably matching a complete URL.")
235
236(defvar thing-at-point-markedup-url-regexp
237  "<URL:[^>]+>"
238  "A regular expression matching a URL marked up per RFC1738.
239This may contain whitespace (including newlines) .")
240
241(put 'url 'bounds-of-thing-at-point 'thing-at-point-bounds-of-url-at-point)
242(defun thing-at-point-bounds-of-url-at-point ()
243  (let ((strip (thing-at-point-looking-at
244			 thing-at-point-markedup-url-regexp))) ;; (url "") short
245    (if (or strip
246	    (thing-at-point-looking-at thing-at-point-url-regexp)
247	    ;; Access scheme omitted?
248	    ;; (setq short (thing-at-point-looking-at
249	    ;;     	 thing-at-point-short-url-regexp))
250            )
251	(let ((beginning (match-beginning 0))
252	      (end (match-end 0)))
253	  (when strip
254            (setq beginning (+ beginning 5))
255            (setq end (- end 1)))
256	  (cons beginning end)))))
257
258(put 'url 'thing-at-point 'thing-at-point-url-at-point)
259(defun thing-at-point-url-at-point ()
260  "Return the URL around or before point.
261
262Search backwards for the start of a URL ending at or after point.  If
263no URL found, return nil.  The access scheme will be prepended if
264absent: \"mailto:\" if the string contains \"@\", \"ftp://\" if it
265starts with \"ftp\" and not \"ftp:/\", or \"http://\" by default."
266
267  (let ((url "") short strip)
268    (if (or (setq strip (thing-at-point-looking-at
269			 thing-at-point-markedup-url-regexp))
270	    (thing-at-point-looking-at thing-at-point-url-regexp)
271	    ;; Access scheme omitted?
272	    (setq short (thing-at-point-looking-at
273			 thing-at-point-short-url-regexp)))
274	(progn
275	  (setq url (buffer-substring-no-properties (match-beginning 0)
276						    (match-end 0)))
277	  (and strip (setq url (substring url 5 -1))) ; Drop "<URL:" & ">"
278	  ;; strip whitespace
279	  (while (string-match "[ \t\n\r]+" url)
280	    (setq url (replace-match "" t t url)))
281	  (and short (setq url (concat (cond ((string-match "^[a-zA-Z]+:" url)
282					       ;; already has a URL scheme.
283					       "")
284					     ((string-match "@" url)
285                                              "mailto:")
286					     ;; e.g. ftp.swiss... or ftp-swiss...
287                                             ((string-match "^ftp" url)
288                                              "ftp://")
289                                             (t "http://"))
290                                       url)))
291	  (if (string-equal "" url)
292	      nil
293	    url)))))
294
295;; The normal thingatpt mechanism doesn't work for complex regexps.
296;; This should work for almost any regexp wherever we are in the
297;; match.  To do a perfect job for any arbitrary regexp would mean
298;; testing every position before point.  Regexp searches won't find
299;; matches that straddle the start position so we search forwards once
300;; and then back repeatedly and then back up a char at a time.
301
302(defun thing-at-point-looking-at (regexp)
303  "Return non-nil if point is in or just after a match for REGEXP.
304Set the match data from the earliest such match ending at or after
305point."
306  (save-excursion
307    (let ((old-point (point)) match)
308      (and (looking-at regexp)
309	   (>= (match-end 0) old-point)
310	   (setq match (point)))
311      ;; Search back repeatedly from end of next match.
312      ;; This may fail if next match ends before this match does.
313      (re-search-forward regexp nil 'limit)
314      (while (and (re-search-backward regexp nil t)
315		  (or (> (match-beginning 0) old-point)
316		      (and (looking-at regexp)	; Extend match-end past search start
317			   (>= (match-end 0) old-point)
318			   (setq match (point))))))
319      (if (not match) nil
320	(goto-char match)
321	;; Back up a char at a time in case search skipped
322	;; intermediate match straddling search start pos.
323	(while (and (not (bobp))
324		    (progn (backward-char 1) (looking-at regexp))
325		    (>= (match-end 0) old-point)
326		    (setq match (point))))
327	(goto-char match)
328	(looking-at regexp)))))
329
330(put 'url 'end-op
331     (lambda ()
332       (let ((bounds (thing-at-point-bounds-of-url-at-point)))
333         (if bounds
334             (goto-char (cdr bounds))
335           (error "No URL here")))))
336(put 'url 'beginning-op
337     (lambda ()
338       (let ((bounds (thing-at-point-bounds-of-url-at-point)))
339         (if bounds
340             (goto-char (car bounds))
341           (error "No URL here")))))
342
343;;  Whitespace
344
345(defun forward-whitespace (arg)
346  (interactive "p")
347  (if (natnump arg)
348      (re-search-forward "[ \t]+\\|\n" nil 'move arg)
349    (while (< arg 0)
350      (if (re-search-backward "[ \t]+\\|\n" nil 'move)
351	  (or (eq (char-after (match-beginning 0)) 10)
352	      (skip-chars-backward " \t")))
353      (setq arg (1+ arg)))))
354
355;;  Buffer
356
357(put 'buffer 'end-op (lambda () (goto-char (point-max))))
358(put 'buffer 'beginning-op (lambda () (goto-char (point-min))))
359
360;;  Symbols
361
362(defun forward-symbol (arg)
363  (interactive "p")
364  (if (natnump arg)
365      (re-search-forward "\\(\\sw\\|\\s_\\)+" nil 'move arg)
366    (while (< arg 0)
367      (if (re-search-backward "\\(\\sw\\|\\s_\\)+" nil 'move)
368	  (skip-syntax-backward "w_"))
369      (setq arg (1+ arg)))))
370
371;;  Syntax blocks
372
373(defun forward-same-syntax (&optional arg)
374  (interactive "p")
375  (while (< arg 0)
376    (skip-syntax-backward
377     (char-to-string (char-syntax (char-after (1- (point))))))
378    (setq arg (1+ arg)))
379  (while (> arg 0)
380    (skip-syntax-forward (char-to-string (char-syntax (char-after (point)))))
381    (setq arg (1- arg))))
382
383;;  Aliases
384
385(defun word-at-point () (thing-at-point 'word))
386(defun sentence-at-point () (thing-at-point 'sentence))
387
388(defun read-from-whole-string (str)
389  "Read a Lisp expression from STR.
390Signal an error if the entire string was not used."
391  (let* ((read-data (read-from-string str))
392	 (more-left
393	  (condition-case nil
394	      ;; The call to `ignore' suppresses a compiler warning.
395	      (progn (ignore (read-from-string (substring str (cdr read-data))))
396		     t)
397	    (end-of-file nil))))
398    (if more-left
399	(error "Can't read whole string")
400      (car read-data))))
401
402(defun form-at-point (&optional thing pred)
403  (let ((sexp (condition-case nil
404		  (read-from-whole-string (thing-at-point (or thing 'sexp)))
405		(error nil))))
406    (if (or (not pred) (funcall pred sexp)) sexp)))
407
408;;;###autoload
409(defun sexp-at-point ()   (form-at-point 'sexp))
410;;;###autoload
411(defun symbol-at-point ()
412  (let ((thing (thing-at-point 'symbol)))
413    (if thing (intern thing))))
414;;;###autoload
415(defun number-at-point () (form-at-point 'sexp 'numberp))
416;;;###autoload
417(defun list-at-point ()   (form-at-point 'list 'listp))
418
419;; arch-tag: bb65a163-dae2-4055-aedc-fe11f497f698
420;;; thingatpt.el ends here
421