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 (see Stickiness of Text 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
value of point is used by default. If narrowing is in effect, then
pos should fall within the accessible portion. See Narrowing.
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
If limit is non-
nil, it is a buffer position; if the
beginning of the field is before limit, then limit will be
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
nil, then the return value is always the end of the following
field that begins at pos, regardless of the stickiness of
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
field-string &optional pos ¶
This function returns the contents of the field specified by pos, as a string.
field-string-no-properties &optional pos ¶
This function returns the contents of the field specified by pos, as a string, discarding text properties.
delete-field &optional pos ¶
This function deletes the text of the field specified by pos.
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
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
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-
new-pos can be anywhere in the two adjacent fields.
Additionally, if two fields are separated by another field with the
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
nil for escape-from-edge. Other motion
commands that check fields should probably pass
If the optional argument only-in-line is non-
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
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
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-