lisp/thingatpt.el

   1 ;;; thingatpt.el --- Get the `thing' at point
   2
   3 ;; Copyright (C) 1991,92,93,94,95,96,1997 Free Software Foundation, Inc.
   4
   5 ;; Author: Mike Williams <mikew@gopher.dosli.govt.nz>
   6 ;; Keywords: extensions, matching, mouse
   7 ;; Created: Thu Mar 28 13:48:23 1991
   8
   9 ;; This file is part of GNU Emacs.
  10
  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)
  14 ;; any later version.
  15
  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.
  20
  21 ;;; Commentary:
  22
  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.
  26 ;;
  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).
  31 ;;
  32 ;; Special cases are allowed for using properties associated with the named
  33 ;; "thing":
  34 ;;
  35 ;;   forward-op         Function to call to skip forward over a "thing" (or
  36 ;;                      with a negative argument, backward).
  37 ;;
  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".
  40 ;;
  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)
  45
  46 ;;; Code:
  47
  48 (provide 'thingatpt)
  49
  50 ;; Basic movement
  51
  52 ;;;###autoload
  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))))
  60
  61 ;; General routines
  62
  63 ;;;###autoload
  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.
  69
  70 See the file `thingatpt.el' for documentation on how to define
  71 a symbol as a valid THING.
  72
  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))
  77     (let ((orig (point)))
  78       (condition-case nil
  79           (save-excursion
  80             ;; Try moving forward, then back.
  81             (let ((end (progn
  82                          (funcall
  83                           (or (get thing 'end-op)
  84                               (function (lambda () (forward-thing thing 1)))))
  85                          (point)))
  86                   (beg (progn
  87                          (funcall
  88                           (or (get thing 'beginning-op)
  89                               (function (lambda () (forward-thing thing -1)))))
  90                          (point))))
  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.
  95                   (let ((real-end
  96                          (progn
  97                            (funcall
  98                             (or (get thing 'end-op)
  99                                 (function (lambda () (forward-thing thing 1)))))
 100                            (point))))
 101                     (if (and beg real-end (<= beg orig) (<= orig real-end))
 102                         (cons beg real-end)))
 103                 (goto-char orig)
 104                 ;; Try a second time, moving backward first and then forward,
 105                 ;; so that we can find a thing that ends at ORIG.
 106                 (let ((beg (progn
 107                              (funcall
 108                               (or (get thing 'beginning-op)
 109                                   (function (lambda () (forward-thing thing -1)))))
 110                              (point)))
 111                       (end (progn
 112                              (funcall
 113                               (or (get thing 'end-op)
 114                                   (function (lambda () (forward-thing thing 1)))))
 115                              (point)))
 116                       (real-beg
 117                        (progn
 118                          (funcall
 119                           (or (get thing 'beginning-op)
 120                               (function (lambda () (forward-thing thing -1)))))
 121                          (point))))
 122                   (if (and real-beg end (<= real-beg orig) (<= orig end))
 123                       (cons real-beg end))))))
 124         (error nil)))))
 125
 126 ;;;###autoload
 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.
 132
 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)))
 138       (if bounds
 139           (buffer-substring (car bounds) (cdr bounds))))))
 140
 141 ;; Go to beginning/end
 142
 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))))
 147
 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))))
 152
 153 ;;  Special cases
 154
 155 ;;  Lines
 156
 157 ;; bolp will be false when you click on the last line in the buffer
 158 ;; and it has no final newline.
 159
 160 (put 'line 'beginning-op
 161      (function (lambda () (if (bolp) (forward-line -1) (beginning-of-line)))))
 162
 163 ;;  Sexps
 164
 165 (defun in-string-p ()
 166   (let ((orig (point)))
 167     (save-excursion
 168       (beginning-of-defun)
 169       (nth 3 (parse-partial-sexp (point) orig)))))
 170
 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)))
 175         (forward-char 1)
 176       (forward-sexp 1))))
 177
 178 (put 'sexp 'end-op 'end-of-sexp)
 179
 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)))
 184         (forward-char -1)
 185       (forward-sexp -1))))
 186
 187 (put 'sexp 'beginning-op 'beginning-of-sexp)
 188
 189 ;;  Lists
 190
 191 (put 'list 'end-op (function (lambda () (up-list 1))))
 192 (put 'list 'beginning-op 'backward-sexp)
 193
 194 ;;  Filenames and URLs
 195
 196 (defvar thing-at-point-file-name-chars "~/A-Za-z0-9---_.${}#%,:"
 197   "Characters allowable in filenames.")
 198
 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)))
 203
 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.")
 207
 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''.")
 213
 214 (defvar thing-at-point-url-regexp
 215   (concat
 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.")
 219
 220 (defvar thing-at-point-markedup-url-regexp
 221   "<URL:[^>]+>"
 222   "A regular expression matching a URL marked up per RFC1738.
 223 This may contain whitespace (including newlines) .")
 224
 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))
 235               (end (match-end 0)))
 236           (cond (strip
 237                  (setq beginning (+ beginning 5))
 238                  (setq end (- end 1))))
 239           (cons beginning end)))))
 240
 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)))
 254         (progn
 255           (setq url (buffer-substring-no-properties (match-beginning 0)
 256                                                     (match-end 0)))
 257           (and strip (setq url (substring url 5 -1))) ; Drop "<URL:" & ">"
 258           ;; strip whitespace
 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)
 264               nil
 265             url)))))
 266
 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.
 273
 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
 277 point."
 278   (save-excursion
 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))))))
 291       (if (not match) nil
 292         (goto-char match)
 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))))
 299         (goto-char match)
 300         (looking-at regexp)))))
 301
 302 (put 'url 'end-op
 303      (function (lambda ()
 304                  (let ((bounds (thing-at-point-bounds-of-url-at-point)))
 305                    (if bounds
 306                        (goto-char (cdr bounds))
 307                      (error "No URL here"))))))
 308 (put 'url 'beginning-op
 309      (function (lambda ()
 310                  (let ((bounds (thing-at-point-bounds-of-url-at-point)))
 311                    (if bounds
 312                        (goto-char (car bounds))
 313                      (error "No URL here"))))))
 314
 315 ;;  Whitespace
 316
 317 (defun forward-whitespace (arg)
 318   (interactive "p")
 319   (if (natnump arg)
 320       (re-search-forward "[ \t]+\\|\n" nil 'move arg)
 321     (while (< arg 0)
 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)))))
 326
 327 ;;  Buffer
 328
 329 (put 'buffer 'end-op '(lambda () (goto-char (point-max))))
 330 (put 'buffer 'beginning-op '(lambda () (goto-char (point-min))))
 331
 332 ;;  Symbols
 333
 334 (defun forward-symbol (arg)
 335   (interactive "p")
 336   (if (natnump arg)
 337       (re-search-forward "\\(\\sw\\|\\s_\\)+" nil 'move arg)
 338     (while (< arg 0)
 339       (if (re-search-backward "\\(\\sw\\|\\s_\\)+" nil 'move)
 340           (skip-syntax-backward "w_"))
 341       (setq arg (1+ arg)))))
 342
 343 ;;  Syntax blocks
 344
 345 (defun forward-same-syntax (&optional arg)
 346   (interactive "p")
 347   (while (< arg 0)
 348     (skip-syntax-backward
 349      (char-to-string (char-syntax (char-after (1- (point))))))
 350     (setq arg (1+ arg)))
 351   (while (> arg 0)
 352     (skip-syntax-forward (char-to-string (char-syntax (char-after (point)))))
 353     (setq arg (1- arg))))
 354
 355 ;;  Aliases
 356
 357 (defun word-at-point () (thing-at-point 'word))
 358 (defun sentence-at-point () (thing-at-point 'sentence))
 359
 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))
 364          (more-left
 365           (condition-case nil
 366               (progn (read-from-string (substring str (cdr read-data)))
 367                      t)
 368             (end-of-file nil))))
 369     (if more-left
 370         (error "Can't read whole string")
 371       (car read-data))))
 372
 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)))
 376                 (error nil))))
 377     (if (or (not pred) (funcall pred sexp)) sexp)))
 378
 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))
 383
 384 ;; thingatpt.el ends here.