From fc6099bf04696b01eaa21c9948a8d8d91345a66c Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Sat, 1 Jul 2023 12:28:33 +0300 Subject: [PATCH] ; 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) --- doc/lispref/text.texi | 51 ++++++++++++++----------- lisp/emacs-lisp/text-property-search.el | 35 ++++++++--------- 2 files changed, 47 insertions(+), 39 deletions(-) diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi index af6d6638b36..342e23beadb 100644 --- a/doc/lispref/text.texi +++ b/doc/lispref/text.texi @@ -3398,37 +3398,43 @@ for @var{object} is the current buffer. @end defun @defun text-property-search-forward prop &optional value predicate not-current -Search for the next region that has text property @var{prop} set to -@var{value} according to @var{predicate}. +Search for the next region of text whose property @var{prop} is a +match for @var{value} (which defaults to @code{nil}), according to +@var{predicate}. -This function is modeled after @code{search-forward} and friends in -that it moves point, but it returns a structure that describes the -match instead of returning it in @code{match-beginning} and friends. +This function is modeled after @code{search-forward} (@pxref{String +Search}) and friends, in that it moves point, but it also returns a +structure that describes the match instead of returning it in +@code{match-beginning} and friends. -If the text property can't be found, the function returns @code{nil}. -If it's found, point is placed at the end of the region that has this -text property match, and a @code{prop-match} structure is returned. +If the text property whose value is a match can't be found, the +function returns @code{nil}. If it's found, point is placed at the +end of the region that has this matching text property, and the +function returns a @code{prop-match} structure with information about +the match. @var{predicate} can either be @code{t} (which is a synonym for @code{equal}), @code{nil} (which means ``not equal''), or a predicate -that will be called with two parameters: The first is @var{value}, and -the second is the value of the text property we're inspecting. +that will be called with two arguments: @var{value} and the value of +the text property @var{prop} at the buffer position that is a +candidate for a match. The function should return non-@code{nil} if +there's a match, @code{nil} otherwise. -If @var{not-current}, if point is in a region where we have a match, -then skip past that and find the next instance instead. +If @var{not-current} is non-@code{nil}, then if point is already in a +region where we have a property match, skip past that region and find +the next region instead. -The @code{prop-match} structure has the following accessors: +The @code{prop-match} structure has the following accessor functionss: @code{prop-match-beginning} (the start of the match), @code{prop-match-end} (the end of the match), and @code{prop-match-value} (the value of @var{property} at the start of the match). -In the examples below, imagine that you're in a buffer that looks like -this: +In the examples below, we use a buffer whose contents is: -@example -This is a bold and here's bolditalic and this is the end. -@end example +@display +This is a @b{bold} and here's @b{@i{bolditalic}} and this is the end. +@end display That is, the ``bold'' words are the @code{bold} face, and the ``italic'' word is in the @code{italic} face. @@ -3452,8 +3458,9 @@ This will pick out all the words that use the @code{bold} face. @end lisp This will pick out all the bits that have no face properties, which -will result in the list @samp{("This is a " "and here's " "and this is -the end")} (only reversed, since we used @code{push}). +will result in the list @samp{(@w{"This is a "} @w{"and here's "} +@w{"and this is the end"})} (only in reverse order, since we used +@code{push}, @pxref{List Variables}). @lisp (while (setq match (text-property-search-forward 'face nil nil)) @@ -3481,8 +3488,8 @@ This will give you a list of all those URLs. @defun text-property-search-backward prop &optional value predicate not-current This is just like @code{text-property-search-forward}, but searches -backward instead. Point is placed at the beginning of the matched -region instead of the end, though. +backward instead, and if a match is found, point is placed at the +beginning of the matched region instead of the end. @end defun 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." -- 2.39.2