lisp/thingatpt.el

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