43.18.6 Fields

FSF Emacs supplies a notion of a text field, which is a region of text where every character has the same value of the field property. It is used to identify regions of a buffer used for communicating with an external process, for example.

SXEmacs supplies a compatible interface. In SXEmacs, the field property can be set as either an extent property or a text property, mirroring the Emacs capability of using either overlays or text properties.

The field manipulating functions take a buffer position as the field-identifying argument, defaulting to point. This really means the field containing that buffer position. Consecutive buffer positions with no field property are considered an “empty” field. There is some ambiguity when a specified buffer position falls at the very beginning or the very end of a field: does it belong to the preceding or the following field? The answer depends on the openness or closedness of the corresponding extents (see Extent Endpoints). A buffer position corresponds to the field whose property would be inherited by a character inserted at that position. If the buffer position is between an end-open and a start-open extent, then it corresponds to an empty field at that position, since an inserted character will belong to neither extent.

Variable: inhibit-field-text-motion

This variable controls whether the text motion commands notice fields or not. When it is nil (the default), commands such as beginning-of-line will try to move only within fields.

Function: make-field value from to &optional buffer

There is no GNU Emacs counterpart to this function. The default open and closedness of extents in SXEmacs is opposite to the default for GNU Emacs overlays. Hence, fields based on extents in SXEmacs behave differently from the equivalent fields based on overlays in Emacs.

This function creates a field with value value over the region from to to in buffer, which defaults to the current buffer, with the default Emacs open and closedness.

Function: find-field &optional pos merge-at-boundary beg-limit end-limit

There is no (Lisp-visible) Emacs counterpart to this function. It is the workhorse for the other functions. It returns a dotted pair (start . stop) holding the endpoints of the field matching a specification. If pos is non-nil, it specifies a buffer position whose enclosing field should be found; otherwise, the value of point is used.

If merge-at-boundary is non-nil, then two changes are made to the search algorithm. First, if pos is at the very first position of a field, then the beginning of the previous field is returned instead of the beginning of pos’s field. Second, if the value of the field property at pos is the symbol boundary, then the beginning of the field before the boundary field and the end of the field after the boundary field are returned.

If beg-limit is a buffer position, and the start position that would be returned is less than beg-limit, then beg-limit is returned instead. Likewise, if end-limit is a buffer position, and the stop position that would be returned is greater than end-limit, then end-limit is returned instead.

Function: delete-field &optional pos

Delete the text of the field at pos.

Function: field-string &optional pos

Return the contents of the field at pos as a string.

Function: field-string-no-properties &optional pos

Return the contents of the field at pos as a string, without text properties.

Function: field-beginning &optional pos escape-from-edge limit

Return the beginning of the field at pos. If escape-from-edge is non-nil and pos is at the beginning of a field, then the beginning of the field that ends at pos is returned instead. If limit is a buffer position and the returned value would be less than limit, then limit is returned instead.

Function: field-end &optional pos escape-from-edge limit

Return the end of the field at pos. If escape-from-edge is non-nil and pos is at the end of a field, then the end of the field that begins at pos is returned instead. If limit is a buffer position and the returned value would be greater than limit, then limit is returned instead.

Function: constrain-to-field new-pos old-pos &optional escape-from-edge only-in-line inhibit-capture-property

Return the position closest to new-pos that is in the same field as old-pos. If new-pos is nil, then the value of point is used instead and point is set to the value that is returned.

If escape-from-edge is non-nil and old-pos is at the boundary of two fields, then the two adjacent fields are considered one field. Furthermore, if new-pos is in a field whose field property is the symbol boundary, then the preceding field, the boundary field, and the following field are considered one field.

If only-in-line is non-nil and the returned position would be on a different line than new-pos, return new-pos instead.

If inhibit-capture-property is non-nil and the character at old-pos has a property of the same name as the value of inhibit-capture-property, then all field boundaries are ignored; i.e., new-pos is returned.

If inhibit-field-text-motion is non-nil, then all field boundaries are ignored and this function always returns new-pos.