elisp: Fields
31.19.9 Defining and Using Fields
---------------------------------
A field is a range of consecutive characters in the buffer that are
identified by having the same value (comparing with ‘eq’) of the ‘field’
property (either a text-property or an overlay property). This section
describes special functions that are available for operating on fields.
You specify a field with a buffer position, POS. We think of each
field as containing a range of buffer positions, so the position you
specify stands for the field containing that position.
When the characters before and after POS are part of the same field,
there is no doubt which field contains POS: the one those characters
both belong to. When POS is at a boundary between fields, which field
it belongs to depends on the stickiness of the ‘field’ properties of the
two surrounding characters (
Sticky Properties). The field whose
property would be inherited by text inserted at POS is the field that
contains POS.
There is an anomalous case where newly inserted text at POS would not
inherit the ‘field’ property from either side. This happens if the
previous character’s ‘field’ property is not rear-sticky, and the
following character’s ‘field’ property is not front-sticky. In this
case, POS belongs to neither the preceding field nor the following
field; the field functions treat it as belonging to an empty field whose
beginning and end are both at POS.
In all of these functions, if POS is omitted or ‘nil’, the value of
point is used by default. If narrowing is in effect, then POS should
fall within the accessible portion. Narrowing.
-- Function: field-beginning &optional pos escape-from-edge limit
This function returns the beginning of the field specified by POS.
If POS is at the beginning of its field, and ESCAPE-FROM-EDGE is
non-‘nil’, then the return value is always the beginning of the
preceding field that _ends_ at POS, regardless of the stickiness of
the ‘field’ properties around POS.
If LIMIT is non-‘nil’, it is a buffer position; if the beginning of
the field is before LIMIT, then LIMIT will be returned instead.
-- Function: field-end &optional pos escape-from-edge limit
This function returns the end of the field specified by POS.
If POS is at the end of its field, and ESCAPE-FROM-EDGE is
non-‘nil’, then the return value is always the end of the following
field that _begins_ at POS, regardless of the stickiness of the
‘field’ properties around POS.
If LIMIT is non-‘nil’, it is a buffer position; if the end of the
field is after LIMIT, then LIMIT will be returned instead.
-- Function: field-string &optional pos
This function returns the contents of the field specified by POS,
as a string.
-- Function: field-string-no-properties &optional pos
This function returns the contents of the field specified by POS,
as a string, discarding text properties.
-- Function: delete-field &optional pos
This function deletes the text of the field specified by POS.
-- Function: constrain-to-field new-pos old-pos &optional
escape-from-edge only-in-line inhibit-capture-property
This function constrains NEW-POS to the field that OLD-POS belongs
to—in other words, it returns the position closest to NEW-POS that
is in the same field as OLD-POS.
If NEW-POS is ‘nil’, then ‘constrain-to-field’ uses the value of
point instead, and moves point to the resulting position in
addition to returning that position.
If OLD-POS is at the boundary of two fields, then the acceptable
final positions depend on the argument ESCAPE-FROM-EDGE. If
ESCAPE-FROM-EDGE is ‘nil’, then NEW-POS must be in the field whose
‘field’ property equals what new characters inserted at OLD-POS
would inherit. (This depends on the stickiness of the ‘field’
property for the characters before and after OLD-POS.) If
ESCAPE-FROM-EDGE is non-‘nil’, NEW-POS can be anywhere in the two
adjacent fields. Additionally, if two fields are separated by
another field with the special value ‘boundary’, then any point
within this special field is also considered to be on the boundary.
Commands like ‘C-a’ with no argument, that normally move backward
to a specific kind of location and stay there once there, probably
should specify ‘nil’ for ESCAPE-FROM-EDGE. Other motion commands
that check fields should probably pass ‘t’.
If the optional argument ONLY-IN-LINE is non-‘nil’, and
constraining NEW-POS in the usual way would move it to a different
line, NEW-POS is returned unconstrained. This used in commands
that move by line, such as ‘next-line’ and ‘beginning-of-line’, so
that they respect field boundaries only in the case where they can
still move to the right line.
If the optional argument INHIBIT-CAPTURE-PROPERTY is non-‘nil’, and
OLD-POS has a non-‘nil’ property of that name, then any field
boundaries are ignored.
You can cause ‘constrain-to-field’ to ignore all field boundaries
(and so never constrain anything) by binding the variable
‘inhibit-field-text-motion’ to a non-‘nil’ value.
Info Catalog
elisp: Clickable Text
elisp: Text Properties
elisp: Not Intervals