ThingAtPoint

This page describes the standard GNU Emacs library thingatpt.el and extensions thereof. The library can determine and retrieve different kinds of thing at point. The function ‘thing-at-point’ retrieves the thing at point.

Using the library

To use this library in your own EmacsLisp code, do this:

  (require 'thingatpt)

The possibilities of a “thing” include symbol, list, S-expression (sexp), function definition (defun), filename, URL, word, sentence, whitespace, line, page and others. For any standard thing that has a ‘forward-thing’ function, just pass the symbol of thing to ‘thing-at-point’. If found, the thing at point is returned as a string. Here is an example for getting the sentence at the current location:

  (thing-at-point 'sentence)

There are other useful functions provided by the library, including:

The thingatpt library is quintessential Emacs, powerful but minimal. View the source code with ‘M-x find-library RET thingatpt RET’ to learn more its features and how to extend it to things of your own.

Specific "-at-point" functions

Rather than passing a symbol for a type of thing, several ‘-at-point’ functions are defined for specific types of things. For example,

  (sentence-at-point)

These functions will usually return the appropriate object type for the particular type of thing. For example, an object of type symbol is returned for symbols and of type integer for numbers.

  (sentence-at-point)      ;; returns string
  (thing-at-point 'symbol) ;; returns string
  (symbol-at-point)        ;; returns symbol 

Specific thing-at-point functions are available for most major types of things and are defined in thingatpt.el. Any other things you want the library to recognize you have to extend the library by defining functions that can recognize your thing.

How it works

The library behind ‘thing-at-point’ is generic and extensible to additional types of things. It relies on function ‘bounds-of-thing-at-point’, which starts from point and uses function ‘forward-thing’ to move forward, then backward to retrieve the bounds of the thing. If ‘forward-thing’ works for a particular type of thing, then so will ‘bounds-of-thing-at-point’.

Function ‘forward-thing’ takes as argument a symbol naming a type of thing. For example, argument ‘sentence’ tells ‘forward-thing’ to move forward one sentence. That is, it does so if a function named ‘forward-sentence’ is defined, or if the symbol ‘sentence’ has a ‘forward-op’ property on its property list. Because function ‘forward-sentence’ is defined in Emacs, ‘forward-thing’ can operate with sentences.

To make ‘forward-thing’ work with a particular kind of thing, say, a new type ‘foobar’ that you define, you can define a function ‘forward-foobar’ that moves forward one or more ‘foobar’s. (With a negative argument, ‘forward-foobar’ should move backward.)

Examples:

Extensions to library `thingatpt.el'

Libraries are available that extend library thingatpt.el in various ways.

The following add new kinds of things at point. They provide examples of how to use thingatpt.el.

See Also


CategoryCode CategoryExtensions