bug#31094: 25.2: Feature Reuqest: apropos-value: limit scope [CODE INCLUDED]

bug#31094: 25.2: Feature Reuqest: apropos-value: limit scope [CODE INCLUDED]

[Boruch Baum]

[-- Attachment #1: Type: text/plain, Size: 1126 bytes --]

I've begun using function apropos-value, and find that its ouput is
undesirably huge, because the feature prints out the entire value of
each variable that contains a match.

Some of this can be reduced when considegring that in most cases, I know
in advance that a value will be present in some very commonly used huge
variables, that won't be of use to me (eg. kill-ring,
minibuffer-history).f

A better solution would be an option to initially print only the names
of symbol that contain a match. The user can then easily view any value
of interest, because the output buffer already includes a feature that
pressing return on any symbol in the output list will display the
documentation for the symbol, which will include the variable's value.

Attached was my first thought at a solution, using an exclude list to
exclude certain variables from a search. As I said, upon further
consideration, I decided it would be better to abbreviate the output
buffer to just a list of symbol names, but I came to that conclusion
after writing the snippet.

-- 
hkp://keys.gnupg.net
CA45 09B5 5351 7C11 A9D1  7286 0036 9E45 1595 8BC0

[-- Attachment #2: apropos-value.el --]
[-- Type: text/plain, Size: 2547 bytes --]

(defcustom apropos-value-exclude-list
  '(kill-ring values minibuffer-history buffer-name-history
     command-history ivy--all-candidates)
"List of variable names to be excluded from `apropos-value' searches."
  :type '(repeat variable))


(defun my-apropos-value (pattern &optional do-all)
  "Allow `apropos-value' to limit scope of its searches.

With \\[universal-argument] prefix, or if `apropos-do-all' is
non-nil, also looks at function definitions (arguments,
documentation and body) and at the names and values of
properties.

With two \\[universal-argument] prefixes, excludes the variables
listed in `apropos-value-exclude-list' from its search.

With three \\[universal-argument] prefixes, performs a search
only on the variables listed in `apropos-value-exclude-list'.

See also variable `apropos-value-limited-print'."
  (interactive (list (apropos-read-pattern "value")
		     current-prefix-arg))
  (apropos-parse-pattern pattern)
  (or do-all (when apropos-do-all (setq do-all '(4))))
  (setq apropos-accumulator ())
  (let (f v p)
    (if (equal do-all '(64)) ; C-u C-u C-u
      (dolist (symbol apropos-value-exclude-list)
        (when (setq v (apropos-value-internal 'boundp symbol 'symbol-value))
          (setq apropos-accumulator
            (cons (list symbol (apropos-score-str v) nil v nil) apropos-accumulator))))
     (mapatoms (lambda (symbol)
       (setq f nil v nil p nil)
       (or (memq symbol '(apropos-regexp
       		   apropos-pattern apropos-all-words-regexp
       		   apropos-words apropos-all-words
       		   do-all apropos-accumulator apropos-value-exclude-list
       		   symbol f v p))
           (and (equal do-all '(16)) ; C-u C-u
                (memq symbol apropos-value-exclude-list))
           (setq v (apropos-value-internal 'boundp symbol 'symbol-value)))
       (when (equal do-all '(4)) ; C-u
         (setq f (apropos-value-internal 'fboundp symbol 'symbol-function)
               p (apropos-format-plist symbol "\n    " t)))
       (if (apropos-false-hit-str v)
           (setq v nil))
       (if (apropos-false-hit-str f)
           (setq f nil))
       (if (apropos-false-hit-str p)
           (setq p nil))
       (if (or f v p)
           (setq apropos-accumulator (cons (list symbol
       					  (+ (apropos-score-str f)
       					     (apropos-score-str v)
       					     (apropos-score-str p))
       					  f v p)
       				    apropos-accumulator)))))))
  (let ((apropos-multi-type (if (equal do-all '(4)) t nil)))
    (apropos-print nil "\n----------------\n")))

bug#31094: Code for second solution

[Boruch Baum]

[-- Attachment #1: Type: text/plain, Size: 441 bytes --]

Attached is code for the second solution idea that I mrentioned in my
first post. Note that these approaches are complementary and
independent; I would advocate for both being adopted.

Do note that this 'breaks' a feature formerly available. Prior, pressing
return on an entry would display documentation for that entry; Now one
must press `C-h v' / `C-h f' etc.

-- 
hkp://keys.gnupg.net
CA45 09B5 5351 7C11 A9D1  7286 0036 9E45 1595 8BC0

[-- Attachment #2: apropos-print.el --]
[-- Type: text/plain, Size: 5329 bytes --]

(defcustom apropos-value-limited-print nil
"Print only symbol names, not their contents.

When this option is active, one may always view a symbol's
contents by `C-h v' while point is on the symbol's name."
  :type 'boolean)


(defun apropos-print (do-keys spacing &optional text nosubst)
  "Output result of apropos searching into buffer `*Apropos*'.
The value of `apropos-accumulator' is the list of items to output.
Each element should have the format
 (SYMBOL SCORE FN-DOC VAR-DOC [PLIST-DOC WIDGET-DOC FACE-DOC GROUP-DOC]).
The return value is the list that was in `apropos-accumulator', sorted
alphabetically by symbol name; but this function also sets
`apropos-accumulator' to nil before returning.
If DO-KEYS is non-nil, output the key bindings.  If NOSUBST is
nil, substitute \"ASCII quotes\" (i.e., grace accent and
apostrophe) with curly quotes), and if non-nil, leave them alone.
If SPACING is non-nil, it should be a string; separate items with
that string.  If non-nil, TEXT is a string that will be printed
as a heading."
  (if (null apropos-accumulator)
      (message "No apropos matches for `%s'" apropos-pattern)
    (setq apropos-accumulator
	  (sort apropos-accumulator
		(lambda (a b)
		  (if apropos-sort-by-scores
		      (or (> (cadr a) (cadr b))
			  (and (= (cadr a) (cadr b))
			       (string-lessp (car a) (car b))))
		    (string-lessp (car a) (car b))))))
    (with-output-to-temp-buffer "*Apropos*"
      (let ((p apropos-accumulator)
	    (old-buffer (current-buffer))
	    (inhibit-read-only t)
	    (button-end 0)
	    symbol item)
	(set-buffer standard-output)
	(apropos-mode)
	(if text (insert text "\n\n"))
	(dolist (apropos-item p)
	  (when (and (not apropos-value-limited-print) spacing (not (bobp)))
	    (princ spacing))
	  (setq symbol (car apropos-item))
	  ;; Insert dummy score element for backwards compatibility with 21.x
	  ;; apropos-item format.
	  (if (not (numberp (cadr apropos-item)))
	      (setq apropos-item
		    (cons (car apropos-item)
			  (cons nil (cdr apropos-item)))))
	  (when (= (point) button-end) (terpri))
	  (insert-text-button (symbol-name symbol)
			      'type 'apropos-symbol
			      'skip apropos-multi-type
			      'face 'apropos-symbol)
	  (setq button-end (point))
	  (if (and (eq apropos-sort-by-scores 'verbose)
		   (cadr apropos-item))
	      (insert " (" (number-to-string (cadr apropos-item)) ") "))
	  ;; Calculate key-bindings if we want them.
          (unless apropos-compact-layout
            (and do-keys
                 (commandp symbol)
                 (not (eq symbol 'self-insert-command))
                 (indent-to 30 1)
                 (if (let ((keys
                            (with-current-buffer old-buffer
                              (where-is-internal symbol)))
                           filtered)
                       ;; Copy over the list of key sequences,
                       ;; omitting any that contain a buffer or a frame.
                       ;; FIXME: Why omit keys that contain buffers and
                       ;; frames?  This looks like a bad workaround rather
                       ;; than a proper fix.  Does anybody know what problem
                       ;; this is trying to address?  --Stef
                       (dolist (key keys)
                         (let ((i 0)
                               loser)
                           (while (< i (length key))
                             (if (or (framep (aref key i))
                                     (bufferp (aref key i)))
                                 (setq loser t))
                             (setq i (1+ i)))
                           (or loser
                               (push key filtered))))
                       (setq item filtered))
                     ;; Convert the remaining keys to a string and insert.
                     (insert
                      (mapconcat
                       (lambda (key)
                         (setq key (condition-case ()
                                       (key-description key)
                                     (error)))
			 (put-text-property 0 (length key)
					    'face 'apropos-keybinding
					    key)
                         key)
                       item ", "))
                   (insert "M-x ... RET")
		   (put-text-property (- (point) 11) (- (point) 8)
				      'face 'apropos-keybinding)
		   (put-text-property (- (point) 3) (point)
				      'face 'apropos-keybinding)))
            (terpri))
          (when (not apropos-value-limited-print)
	    (apropos-print-doc 2
	          	     (if (commandp symbol)
	          		 'apropos-command
	          	       (if (macrop symbol)
	          		   'apropos-macro
	          		 'apropos-function))
	          	     (not nosubst))
	    (apropos-print-doc 3
	          	     (if (custom-variable-p symbol)
	          		 'apropos-user-option
	          	       'apropos-variable)
	          	     (not nosubst))
	    (apropos-print-doc 7 'apropos-group t)
	    (apropos-print-doc 6 'apropos-face t)
	    (apropos-print-doc 5 'apropos-widget t)
	    (apropos-print-doc 4 'apropos-plist nil)))
        (set (make-local-variable 'truncate-partial-width-windows) t)
        (set (make-local-variable 'truncate-lines) t))))
  (prog1 apropos-accumulator
    (setq apropos-accumulator ())))	; permit gc

bug#31094: Code for second solution

[Eli Zaretskii]

> Date: Sun, 8 Apr 2018 07:09:01 -0400
> From: Boruch Baum <boruch_baum@gmx.com>
> 
> Attached is code for the second solution idea that I mrentioned in my
> first post. Note that these approaches are complementary and
> independent; I would advocate for both being adopted.
> 
> Do note that this 'breaks' a feature formerly available. Prior, pressing
> return on an entry would display documentation for that entry; Now one
> must press `C-h v' / `C-h f' etc.

Why not do this the other way around: make apropos-value present a
shorter list when invoked with some special value of the prefix
argument?  Or even make this a new command?  That way, people's muscle
memory doesn't need to change, which I think is a Good Thing, given
that I think we never had any complaints about the current behavior.

Thanks.

bug#31094: Code for second solution

[Boruch Baum]

On 2018-04-08 16:06, Eli Zaretskii wrote:
> Why not do this the other way around: make apropos-value present a
> shorter list when invoked with some special value of the prefix
> argument?  Or even make this a new command?  That way, people's muscle
> memory doesn't need to change, which I think is a Good Thing, given
> that I think we never had any complaints about the current behavior.

If either or both proposed changes are adopted, there will be no need to
change muscle memory for those who want the behavior to remain the same.

The first code snippet already only changes behavior when the function
is called with either two or three universal prefix args.

The second snippet is controlled by a boolean defcustom variable,
defaulting to the current long print-out behavior.

-- 
hkp://keys.gnupg.net
CA45 09B5 5351 7C11 A9D1  7286 0036 9E45 1595 8BC0

bug#31094: Code for second solution

[Eli Zaretskii]

> Date: Sun, 8 Apr 2018 09:17:01 -0400
> From: Boruch Baum <boruch_baum@gmx.com>
> Cc: 31094@debbugs.gnu.org
> 
> The first code snippet already only changes behavior when the function
> is called with either two or three universal prefix args.

I was under the impression that the first variant was not what you were
promoting.

> The second snippet is controlled by a boolean defcustom variable,
> defaulting to the current long print-out behavior.

That sounds sub-optimal to me: completely changing the behavior of a
command given an option is not the best UI, IMO.  Two different
commands are better.

bug#31094: Code for second solution

[Boruch Baum]

On 2018-04-08 16:54, Eli Zaretskii wrote:
> > Date: Sun, 8 Apr 2018 09:17:01 -0400
> > From: Boruch Baum <boruch_baum@gmx.com>
> > Cc: 31094@debbugs.gnu.org
> >
> > The first code snippet already only changes behavior when the function
> > is called with either two or three universal prefix args.
>
> I was under the impression that the first variant was not what you were
> promoting.

Different strokes for different folks. Personally, I would end up using
the second variant, but I wouldn't begrudge anyone the first option and
they can co-exist peacefully in the code. Both are minor tweaks.

> > The second snippet is controlled by a boolean defcustom variable,
> > defaulting to the current long print-out behavior.
>
> That sounds sub-optimal to me: completely changing the behavior of a
> command given an option is not the best UI, IMO.  Two different
> commands are better.

You're over stating the behavior change of the second snippet; it
changes the detail level of the output. True, as written, it 'breaks'
the response to <RET> keybinding, but I consider that trivial, because
the same functionality is available with `C-h v` or `C-h f', and to the
benefit that the snippet is much leaner on memory. If you insist that
you absolutely need that <RET> key to display the symbol's complete
documentation, that can be done without rejecting the idea of the
snippet, but it's a minor coding hassle for no real reason; Everyone
knows `C-h v' and `C-h f' describe the symbol at point.

-- 
hkp://keys.gnupg.net
CA45 09B5 5351 7C11 A9D1  7286 0036 9E45 1595 8BC0

bug#31094: Code for second solution

[Eli Zaretskii]

> Date: Sun, 8 Apr 2018 10:13:30 -0400
> From: Boruch Baum <boruch_baum@gmx.com>
> Cc: 31094@debbugs.gnu.org
> 
> > > The second snippet is controlled by a boolean defcustom variable,
> > > defaulting to the current long print-out behavior.
> >
> > That sounds sub-optimal to me: completely changing the behavior of a
> > command given an option is not the best UI, IMO.  Two different
> > commands are better.
> 
> You're over stating the behavior change of the second snippet; it
> changes the detail level of the output. True, as written, it 'breaks'
> the response to <RET> keybinding, but I consider that trivial, because
> the same functionality is available with `C-h v` or `C-h f', and to the
> benefit that the snippet is much leaner on memory. If you insist that
> you absolutely need that <RET> key to display the symbol's complete
> documentation, that can be done without rejecting the idea of the
> snippet, but it's a minor coding hassle for no real reason; Everyone
> knows `C-h v' and `C-h f' describe the symbol at point.

I hear you.  Let's see what others think about this.

Thanks.

bug#31094: 25.2: Feature Reuqest: apropos-value: limit scope [CODE INCLUDED]

[Lars Ingebrigtsen]

Boruch Baum <boruch_baum@gmx.com> writes:

> A better solution would be an option to initially print only the names
> of symbol that contain a match. The user can then easily view any value
> of interest, because the output buffer already includes a feature that
> pressing return on any symbol in the output list will display the
> documentation for the symbol, which will include the variable's value.

(I'm going through old bug reports that unfortunately weren't resolved
at the time.)

Instead of adding a special user option for this, I think it makes sense
to allow using outline-minor-mode in *Apropos* buffers.  So I've now
added support for that in Emacs 29.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#31094: 25.2: Feature Reuqest: apropos-value: limit scope [CODE INCLUDED]

[Juri Linkov]

> Instead of adding a special user option for this, I think it makes sense
> to allow using outline-minor-mode in *Apropos* buffers.  So I've now
> added support for that in Emacs 29.

I see you added support for that, but not activated outline-minor-mode.
Is this intentional?

bug#31094: 25.2: Feature Reuqest: apropos-value: limit scope [CODE INCLUDED]

[Lars Ingebrigtsen]

Juri Linkov <juri@linkov.net> writes:

>> Instead of adding a special user option for this, I think it makes sense
>> to allow using outline-minor-mode in *Apropos* buffers.  So I've now
>> added support for that in Emacs 29.
>
> I see you added support for that, but not activated outline-minor-mode.
> Is this intentional?

Yes, I think using outline mode by default here isn't what most people
would expect, but outline mode fans can switch it on from a hook if they
want.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#31094: 25.2: Feature Reuqest: apropos-value: limit scope [CODE INCLUDED]

[Juri Linkov]

>>> Instead of adding a special user option for this, I think it makes sense
>>> to allow using outline-minor-mode in *Apropos* buffers.  So I've now
>>> added support for that in Emacs 29.
>>
>> I see you added support for that, but not activated outline-minor-mode.
>> Is this intentional?
>
> Yes, I think using outline mode by default here isn't what most people
> would expect, but outline mode fans can switch it on from a hook if they
> want.

Maybe then the apropos docstrings could mention this feature?

bug#31094: 25.2: Feature Reuqest: apropos-value: limit scope [CODE INCLUDED]

[Lars Ingebrigtsen]

Juri Linkov <juri@linkov.net> writes:

> Maybe then the apropos docstrings could mention this feature?

Sure, but on the other hand -- we do want to allow using outline
everywhere it makes sense, so I'm not sure it makes sense to mention it
everywhere -- it should Just Work.

(Outline minor mode should grow support for non-regexp outlines,
though -- in these read-only buffers where we're generating the
contents, it would be way more convenient if the generator did the
markup.  I.e., put a `outline-header' text property on the header, or
something like that.)

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#31094: 25.2: Feature Reuqest: apropos-value: limit scope [CODE INCLUDED]

[Juri Linkov]

> (Outline minor mode should grow support for non-regexp outlines,
> though -- in these read-only buffers where we're generating the
> contents, it would be way more convenient if the generator did the
> markup.  I.e., put a `outline-header' text property on the header, or
> something like that.)

In read-only buffers outline-minor-mode-highlight-buffer currently does:

    (let ((regexp (concat "^\\(?:" outline-regexp "\\).*$")))
      (while (re-search-forward regexp nil t)
        (let ((overlay (make-overlay (match-beginning 0) (match-end 0))))

but can use anything including special properties instead of regexps.

bug#31094: 25.2: Feature Reuqest: apropos-value: limit scope [CODE INCLUDED]

[Lars Ingebrigtsen]

Juri Linkov <juri@linkov.net> writes:

> In read-only buffers outline-minor-mode-highlight-buffer currently does:
>
>     (let ((regexp (concat "^\\(?:" outline-regexp "\\).*$")))
>       (while (re-search-forward regexp nil t)
>         (let ((overlay (make-overlay (match-beginning 0) (match-end 0))))
>
> but can use anything including special properties instead of regexps.

Well, we'd add a separate loop with (text-property-search-forward
'outline-header) or something?

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

bug#31094: 25.2: Feature Reuqest: apropos-value: limit scope [CODE INCLUDED]

[Juri Linkov]

>> In read-only buffers outline-minor-mode-highlight-buffer currently does:
>>
>>     (let ((regexp (concat "^\\(?:" outline-regexp "\\).*$")))
>>       (while (re-search-forward regexp nil t)
>>         (let ((overlay (make-overlay (match-beginning 0) (match-end 0))))
>>
>> but can use anything including special properties instead of regexps.
>
> Well, we'd add a separate loop with (text-property-search-forward
> 'outline-header) or something?

Whether to use a re-search-forward loop or a text-property-search-forward
loop could depend on a new buffer-local variable, like
hi-lock-use-overlays added to hi-lock.el.

bug#31094: 25.2: Feature Reuqest: apropos-value: limit scope [CODE INCLUDED]

[Michael Heerdegen]

Boruch Baum <boruch_baum@gmx.com> writes:

> Some of this can be reduced when considegring that in most cases, I know
> in advance that a value will be present in some very commonly used huge
> variables, that won't be of use to me (eg. kill-ring,
> minibuffer-history).

If you are interested in alternative approaches:

In my config I have added a query for a maximal length of the (printed)
value.  0 means "use any", but a positive value filters all variables
with bindings wider than the given limit.

I chose this way because typically you get lots of results, too many to
view them one by one, so most of the time I use isearch to find the
stuff I'm interested in.  With a folding approach, the output looks
nicer, but it still contains a lot of stuff I'm surely not interested
in.  Most of the time these huge list values are irrelevant for what you
are searching for.

Michael.

bug#31094: 25.2: Feature Reuqest: apropos-value: limit scope [CODE INCLUDED]

[Lars Ingebrigtsen]

Juri Linkov <juri@linkov.net> writes:

> Whether to use a re-search-forward loop or a text-property-search-forward
> loop could depend on a new buffer-local variable, like
> hi-lock-use-overlays added to hi-lock.el.

Yes, that'd be OK.  But I'm not sure it's really necessary --
outline-minor-mode could just do that always?  Or perhaps modes that do
this could just set outline-regexp to nil (or some other special value)...

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no