lisp/thingatpt.el

   1 ;;; thingatpt.el --- Get the `thing' at point
   2
   3 ;; Copyright (C) 1991,92,93,94,95,1996 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   (let ((orig (point)))
  76     (condition-case nil
  77         (save-excursion
  78           (let ((end (progn
  79                        (funcall
  80                         (or (get thing 'end-op)
  81                             (function (lambda () (forward-thing thing 1)))))
  82                        (point)))
  83                 (beg (progn
  84                        (funcall
  85                         (or (get thing 'beginning-op)
  86                             (function (lambda () (forward-thing thing -1)))))
  87                        (point))))
  88             (if (and beg end (<= beg orig) (<= orig end))
  89                 (cons beg end)
  90               ;; Try a second time, moving backward first and forward after,
  91               ;; so that we can find a thing that ends at ORIG.
  92               (let ((beg (progn
  93                            (funcall
  94                             (or (get thing 'beginning-op)
  95                                 (function (lambda () (forward-thing thing -1)))))
  96                            (point)))
  97                     (end (progn
  98                            (funcall
  99                             (or (get thing 'end-op)
 100                                 (function (lambda () (forward-thing thing 1)))))
 101                            (point))))
 102                 (if (and beg end (<= beg orig) (<= orig end))
 103                     (cons beg end))))))
 104       (error nil))))
 105
 106 ;;;###autoload
 107 (defun thing-at-point (thing)
 108   "Return the THING at point.
 109 THING is a symbol which specifies the kind of syntactic entity you want.
 110 Possibilities include `symbol', `list', `sexp', `defun', `filename', `url',
 111 `word', `sentence', `whitespace', `line', `page' and others.
 112
 113 See the file `thingatpt.el' for documentation on how to define
 114 a symbol as a valid THING."
 115   (let ((bounds (bounds-of-thing-at-point thing)))
 116     (if bounds
 117         (buffer-substring (car bounds) (cdr bounds)))))
 118
 119 ;; Go to beginning/end
 120
 121 (defun beginning-of-thing (thing)
 122   (let ((bounds (bounds-of-thing-at-point thing)))
 123     (or bounds (error "No %s here" thing))
 124     (goto-char (car bounds))))
 125
 126 (defun end-of-thing (thing)
 127   (let ((bounds (bounds-of-thing-at-point thing)))
 128     (or bounds (error "No %s here" thing))
 129     (goto-char (cdr bounds))))
 130
 131 ;;  Special cases
 132
 133 ;;  Lines
 134
 135 ;; bolp will be false when you click on the last line in the buffer
 136 ;; and it has no final newline.
 137
 138 (put 'line 'beginning-op
 139      (function (lambda () (if (bolp) (forward-line -1) (beginning-of-line)))))
 140
 141 ;;  Sexps
 142
 143 (defun in-string-p ()
 144   (let ((orig (point)))
 145     (save-excursion
 146       (beginning-of-defun)
 147       (nth 3 (parse-partial-sexp (point) orig)))))
 148
 149 (defun end-of-sexp ()
 150   (let ((char-syntax (char-syntax (char-after (point)))))
 151     (if (or (eq char-syntax ?\))
 152             (and (eq char-syntax ?\") (in-string-p)))
 153         (forward-char 1)
 154       (forward-sexp 1))))
 155
 156 (put 'sexp 'end-op 'end-of-sexp)
 157
 158 ;;  Lists
 159
 160 (put 'list 'end-op (function (lambda () (up-list 1))))
 161 (put 'list 'beginning-op 'backward-sexp)
 162
 163 ;;  Filenames and URLs
 164
 165 (defvar thing-at-point-file-name-chars "~/A-Za-z0-9---_.${}#%,:"
 166   "Characters allowable in filenames.")
 167
 168 (put 'filename 'end-op
 169      '(lambda () (skip-chars-forward thing-at-point-file-name-chars)))
 170 (put 'filename 'beginning-op
 171      '(lambda () (skip-chars-backward thing-at-point-file-name-chars)))
 172
 173 (defvar thing-at-point-url-chars "~/A-Za-z0-9---_@$%&=.,"
 174   "Characters allowable in a URL.")
 175
 176 (put 'url 'end-op
 177      '(lambda () (skip-chars-forward (concat ":" thing-at-point-url-chars))
 178         (skip-chars-backward ".,:")))
 179 (put 'url 'beginning-op
 180      '(lambda ()
 181         (skip-chars-backward thing-at-point-url-chars)
 182         (or (= (preceding-char) ?:)
 183             (error "No URL here"))
 184         (forward-char -1)
 185         (skip-chars-backward "a-zA-Z")))
 186
 187 ;;  Whitespace
 188
 189 (defun forward-whitespace (arg)
 190   (interactive "p")
 191   (if (natnump arg)
 192       (re-search-forward "[ \t]+\\|\n" nil nil arg)
 193     (while (< arg 0)
 194       (if (re-search-backward "[ \t]+\\|\n" nil nil)
 195           (or (eq (char-after (match-beginning 0)) 10)
 196               (skip-chars-backward " \t")))
 197       (setq arg (1+ arg)))))
 198
 199 ;;  Buffer
 200
 201 (put 'buffer 'end-op 'end-of-buffer)
 202 (put 'buffer 'beginning-op 'beginning-of-buffer)
 203
 204 ;;  Symbols
 205
 206 (defun forward-symbol (arg)
 207   (interactive "p")
 208   (if (natnump arg)
 209       (re-search-forward "\\(\\sw\\|\\s_\\)+" nil nil arg)
 210     (while (< arg 0)
 211       (if (re-search-backward "\\(\\sw\\|\\s_\\)+" nil nil)
 212           (skip-syntax-backward "w_"))
 213       (setq arg (1+ arg)))))
 214
 215 ;;  Syntax blocks
 216
 217 (defun forward-same-syntax (&optional arg)
 218   (interactive "p")
 219   (while (< arg 0)
 220     (skip-syntax-backward
 221      (char-to-string (char-syntax (char-after (1- (point))))))
 222     (setq arg (1+ arg)))
 223   (while (> arg 0)
 224     (skip-syntax-forward (char-to-string (char-syntax (char-after (point)))))
 225     (setq arg (1- arg))))
 226
 227 ;;  Aliases
 228
 229 (defun word-at-point () (thing-at-point 'word))
 230 (defun sentence-at-point () (thing-at-point 'sentence))
 231
 232 (defun read-from-whole-string (str)
 233   "Read a lisp expression from STR.
 234 Signal an error if the entire string was not used."
 235   (let* ((read-data (read-from-string str))
 236          (more-left
 237           (condition-case nil
 238               (progn (read-from-string (substring str (cdr read-data)))
 239                      t)
 240             (end-of-file nil))))
 241     (if more-left
 242         (error "Can't read whole string")
 243       (car read-data))))
 244
 245 (defun form-at-point (&optional thing pred)
 246   (let ((sexp (condition-case nil
 247                   (read-from-whole-string (thing-at-point (or thing 'sexp)))
 248                 (error nil))))
 249     (if (or (not pred) (funcall pred sexp)) sexp)))
 250
 251 (defun sexp-at-point ()   (form-at-point 'sexp))
 252 (defun symbol-at-point () (form-at-point 'sexp 'symbolp))
 253 (defun number-at-point () (form-at-point 'sexp 'numberp))
 254 (defun list-at-point ()   (form-at-point 'list 'listp))
 255
 256 ;; thingatpt.el ends here.