This page describes library ThingAtPoint+ (thingatpt+.el). This is an extension of standard library thingatpt.el (See ThingAtPoint). It provides various functions for determining (returning) different objects at or near point.

The objects are THINGs for which there is either a corresponding ‘forward-’THING operation, or corresponding ‘beginning-of-’THING and ‘end-of-’THING operations.

Examples of THING are ‘word’, ‘sentence’, and ‘defun’. For example, words have Emacs Lisp functions ‘forward-word’, ‘beginning-of-word’, and ‘end-of-word’ functions. Library thingatpt+.el uses such functions to return the word at or nearest the cursor.

Library thingatpt+.el also provides functions to pick up things that are near the cursor, not just things that are exactly under the cursor. For this feature, you can customize two user options that control what “near” means, that is, how far from the cursor to look.

In addition, the code in thingatpt+.el respects Emacs field boundaries. This means, for example, that if you pick up a thing near the minibuffer prompt you won’t get “Text is read-only” errors etc.

Things

‘thing-nearest-point’ – like ‘thing-at-point’, but returns the THINGnearest point. “Nearest” is determined as follows:

The nearest THING on the same line is returned, if there is any. Between two THINGs equidistant from point on the same line, the leftmost is considered nearer.

Otherwise, neighboring lines are tried in sequence: previous, next, 2nd previous, 2nd next, 3rd previous, 3rd next, etc. This means that between two THINGs equidistant from point in lines above and below it, the THING in the line above point (previous Nth) is considered nearer to it.

User options ‘near-point-x-distance’ and ‘near-point-y-distance’ control how far to search before considering that there is no thing near the cursor.

‘thing-at-point-with-bounds’, ‘thing-nearest-point-with-bounds’ – returns (THINGSTART.END) with START and END of THING, where THING is the ‘thing-at-point’ or ‘thing-nearest-point’.

‘bounds-of-thing-at-point’, ‘bounds-of-thing-nearest-point’ – determine the start and end buffer locations for the THING at or nearest point.

Forms

A form is a particular kind of Lisp thing that optionally satisfies a particular predicate. The default kind of form is a Lisp S-expression (sexp).

‘form-at-point’ – returns the form at point, if any, else returns nil. The form is any Lisp entity, not necessarily a string. Optional Arguments include:

Lists

The ThingAtPt+ list functions all accept an optional argument ‘UP’, which is the number of list levels to go up to start with. IOW, ‘UP’ lets you retrieve a wider list than the one immediately surrounding point.

In addition, the ThingAtPt+ redefinition of standard function ‘list-at-point’ provides better and more consistent behavior: it does what you would expect.

The ‘unquoted-’ functions remove any quote or backquote, so that, e.g., 'bar and `(foo a b) gives you bar and (foo a b) instead of (quote bar) and (backquote-backquote-symbol(foo a b)), which is `(foo a b).

See also: ThingAtPointCommands, for commands such as ‘mark-enclosing-sexp’, to select successively larger lists surroundig point.

This work is licensed to you under version 2 of the
GNUGeneral Public License.
Alternatively, you may choose to receive this work under any other
license that grants the right to use, copy, modify, and/or distribute
the work, as long as that license imposes the restriction that
derivative works have to grant the same rights and impose the same
restriction. For example, you may choose to receive this work under
the
GNUFree Documentation License, the
CreativeCommonsShareAlike
License, the XEmacs manual license, or
similar licenses.