diff options
| author | Eli Zaretskii <eliz@gnu.org> | 2023-07-01 12:28:33 +0300 |
|---|---|---|
| committer | Eli Zaretskii <eliz@gnu.org> | 2023-07-01 12:28:33 +0300 |
| commit | fc6099bf04696b01eaa21c9948a8d8d91345a66c (patch) | |
| tree | 1a4e88dd7dbeca53a52fa14ceb99c56b1296f8dd /lisp/emacs-lisp/text-property-search.el | |
| parent | cc660bd265172ffd75851d418db9af66704d0e54 (diff) | |
| download | emacs-fc6099bf04696b01eaa21c9948a8d8d91345a66c.tar.gz emacs-fc6099bf04696b01eaa21c9948a8d8d91345a66c.tar.bz2 emacs-fc6099bf04696b01eaa21c9948a8d8d91345a66c.zip | |
; Improve documentation of text-property-search-* functions
* doc/lispref/text.texi (Property Search): Improve wording and markup.
* lisp/emacs-lisp/text-property-search.el (text-property-search-forward)
(text-property-search-backward): Doc fixes. (Bug#64367)
Diffstat (limited to 'lisp/emacs-lisp/text-property-search.el')
| -rw-r--r-- | lisp/emacs-lisp/text-property-search.el | 35 |
1 files changed, 18 insertions, 17 deletions
diff --git a/lisp/emacs-lisp/text-property-search.el b/lisp/emacs-lisp/text-property-search.el index 920278b903a..669cdd97319 100644 --- a/lisp/emacs-lisp/text-property-search.el +++ b/lisp/emacs-lisp/text-property-search.el @@ -31,40 +31,41 @@ (defun text-property-search-forward (property &optional value predicate not-current) - "Search for the next region of text where PREDICATE is true. -PREDICATE is used to decide whether a value of PROPERTY should be -considered as matching VALUE. + "Search for next region of text where PREDICATE returns non-nil for PROPERTY. +PREDICATE is used to decide whether the value of PROPERTY at a given +buffer position should be considered as a match for VALUE. +VALUE defaults to nil if omitted. If PREDICATE is a function, it will be called with two arguments: -VALUE and the value of PROPERTY. The function should return -non-nil if these two values are to be considered a match. +VALUE and the value of PROPERTY at some buffer position. The function +should return non-nil if these two values are to be considered a match. Two special values of PREDICATE can also be used: -If PREDICATE is t, that means a value must `equal' VALUE to be -considered a match. -If PREDICATE is nil (which is the default value), a value will -match if is not `equal' to VALUE. Furthermore, a nil PREDICATE -means that the match region is ended if the value changes. For +If PREDICATE is t, that means the value of PROPERTY must `equal' VALUE +to be considered a match. +If PREDICATE is nil (which is the default), the value of PROPERTY will +match if it is not `equal' to VALUE. Furthermore, a nil PREDICATE +means that the match region ends where the value changes. For instance, this means that if you loop with (while (setq prop (text-property-search-forward \\='face)) ...) -you will get all distinct regions with non-nil `face' values in +you will get all the distinct regions with non-nil `face' values in the buffer, and the `prop' object will have the details about the match. See the manual for more details and examples about how VALUE and PREDICATE interact. -If NOT-CURRENT is non-nil, the function will search for the first -region that doesn't include point and has a value of PROPERTY -that matches VALUE. +If NOT-CURRENT is non-nil, current buffer position is not examined for +matches: the function will search for the first region that doesn't +include point and has a value of PROPERTY that matches VALUE. If no matches can be found, return nil and don't move point. If found, move point to the end of the region and return a `prop-match' object describing the match. To access the details of the match, use `prop-match-beginning' and `prop-match-end' for -the buffer positions that limit the region, and -`prop-match-value' for the value of PROPERTY in the region." +the buffer positions that limit the region, and `prop-match-value' +for the value of PROPERTY in the region." (interactive (list (let ((string (completing-read "Search for property: " obarray))) @@ -134,7 +135,7 @@ the buffer positions that limit the region, and (defun text-property-search-backward (property &optional value predicate not-current) - "Search for the previous region of text whose PROPERTY matches VALUE. + "Search for previous region of text where PREDICATE returns non-nil for PROPERTY. Like `text-property-search-forward', which see, but searches backward, and if a matching region is found, place point at the start of the region." |