buffer variable values

buffer variable values

[drain]

Original insert-buffer function:

(defun insert-buffer (buffer)
  "Insert after point the contents of BUFFER.
  Puts mark after the inserted text.
  BUFFER may be a buffer or a buffer name."
  (interactive "*bInsert buffer: ")
  (or (bufferp buffer)
      (setq buffer (get-buffer buffer)))
  (let (start end newmark)
    (save-excursion
      (save-excursion
	(set-buffer buffer)
	(setq start (point-min) end (point-max)))
      (insert-buffer-substring buffer start end)
      (setq newmark (point)))
    (push-mark newmark)))

Under what conditions would (or (bufferp buffer) not be nil?

In the Emacs Lisp Intro, in the discussion of this function, there seem to
be three different "buffer" variable values referred to:

(assuming "web.org" is an existing buffer):

(1) #<buffer web.org> 
(2) web.org
(3) web

(1) is what setq assigns "buffer" in the expression (setq buffer (get-buffer
buffer)).
(2) is the name of an existing buffer that the interactive expression will
permit the user to enter.
(3) is a string that refers to no buffers.

I don't understand the point in the OR expression. How would the user pass
as argument to the function a buffer, rather than just the name of a buffer?
Entering #<buffer web.org> is invalid. 

If this function did not read input from the user, the OR expression would
serve a purpose; since "buffer" could have been assigned an actual buffer
elsewhere in the body of a larger function (that insert-buffer had been
embedded into).




--
View this message in context: http://emacs.1067599.n5.nabble.com/buffer-variable-values-tp262330.html
Sent from the Emacs - Help mailing list archive at Nabble.com.

Re: buffer variable values

[PJ Weisberg]

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

On Saturday, August 25, 2012, drain <aeuster@gmail.com> wrote:
> If this function did not read input from the user, the OR expression would
> serve a purpose; since "buffer" could have been assigned an actual buffer
> elsewhere in the body of a larger function (that insert-buffer had been
> embedded into).

Replace "embedded into" with "called by," and you've answered your own
question.

-- 
-PJ

Gehm's Corollary to Clark's Law: Any technology distinguishable from
magic is insufficiently advanced.

[-- Attachment #2: Type: text/html, Size: 647 bytes --]

Re: buffer variable values

[drain]

Was insert-buffer ever meant to be called non-interactively, though? The
newer insert-buffer has this in its documentation:

"This function is meant for the user to run interactively.
Don't call it from programs: use `insert-buffer-substring' instead!"



--
View this message in context: http://emacs.1067599.n5.nabble.com/buffer-variable-values-tp262330p262332.html
Sent from the Emacs - Help mailing list archive at Nabble.com.

RE: buffer variable values

[Drew Adams]

> Was insert-buffer ever meant to be called non-interactively, 
> though? The newer insert-buffer has this in its documentation:
> 
> "This function is meant for the user to run interactively.
> Don't call it from programs: use `insert-buffer-substring' instead!"

Barry M. gave the short answer:

 "Just because it's not *meant* to be used from programs
  doesn't mean it shouldn't work reasonably when it is."

"Shouldn't" could be "couldn't" here.  It was a design choice to make it "work
reasonably" for a buffer-name argument, for convenience.

That short answer is repeated as #2 here:

1. "Meant to be" is pretty loose in Lisp.  What you see in a doc string does not
necessarily convey all possibilities and situations.  It is intended as general
guidance, to help you.  This is not the Napoleon code.

You will sometimes see imperative directives such as "Don't...", like here.
Take them as if they were polite guidance/advice, in the spirit of "You probably
don't want to..."  They are generally just trying to remind you that this is
something that you probably do not want to do here.

2. All that first `setq' sexp does is make sure that the rest of the function
body really does have a buffer object to work with, in case the function was
passed a buffer name (string) - for whatever reason.  That is an alternative
design to raising an error.

It was deemed useful to mention in the doc string that the command is generally
meant to be invoked interactively.  That's a sign that at least some people have
confusedly invoked it non-interactively.  That `setq' sexp takes care of this.

3. Lisp is multi-leveled and dynamic.  And every command is also a function,
which _could_ be invoked non-interactively.  Sometimes code invokes other code
indirectly, including sometimes interactively (e.g. so that a user can pass it a
prefix arg).  And a function to be called indirectly could be passed as a
variable (so that the caller does not know what function it will call).

Re: buffer variable values

[Barry Margolin]

In article <mailman.7557.1345882485.855.help-gnu-emacs@gnu.org>,
 drain <aeuster@gmail.com> wrote:

> Was insert-buffer ever meant to be called non-interactively, though? The
> newer insert-buffer has this in its documentation:
> 
> "This function is meant for the user to run interactively.
> Don't call it from programs: use `insert-buffer-substring' instead!"

Just because it's not *meant* to be used from programs doesn't mean it 
shouldn't work reasonably when it is.

-- 
Barry Margolin, barmar@alum.mit.edu
Arlington, MA
*** PLEASE post questions in newsgroups, not directly to me ***

Re: buffer variable values

[Barry Margolin]

In article <mailman.7566.1345906894.855.help-gnu-emacs@gnu.org>,
 "Drew Adams" <drew.adams@oracle.com> wrote:

> > Was insert-buffer ever meant to be called non-interactively, 
> > though? The newer insert-buffer has this in its documentation:
> > 
> > "This function is meant for the user to run interactively.
> > Don't call it from programs: use `insert-buffer-substring' instead!"
> 
> Barry M. gave the short answer:
> 
>  "Just because it's not *meant* to be used from programs
>   doesn't mean it shouldn't work reasonably when it is."
> 
> "Shouldn't" could be "couldn't" here.  It was a design choice to make it 
> "work
> reasonably" for a buffer-name argument, for convenience.
> 
> That short answer is repeated as #2 here:
> 
> 1. "Meant to be" is pretty loose in Lisp.  What you see in a doc string does 
> not
> necessarily convey all possibilities and situations.  It is intended as 
> general
> guidance, to help you.  This is not the Napoleon code.
> 
> You will sometimes see imperative directives such as "Don't...", like here.
> Take them as if they were polite guidance/advice, in the spirit of "You 
> probably
> don't want to..."  They are generally just trying to remind you that this is
> something that you probably do not want to do here.

Another issue is backward compatibility.  Perhaps at one time the 
function was commonly used from programs, but when the preferred 
alternative was added they put that warning into the documentation.  But 
the function still has to work properly for all the old code that was 
calling it before this.

-- 
Barry Margolin, barmar@alum.mit.edu
Arlington, MA
*** PLEASE post questions in newsgroups, not directly to me ***

RE: buffer variable values

[Drew Adams]

> Another issue is backward compatibility.  Perhaps at one time the 
> function was commonly used from programs, but when the preferred 
> alternative was added they put that warning into the 
> documentation.  But the function still has to work properly for
> all the old code that was calling it before this.

Actually, I took a look at the Emacs 20 (distributed) source code before writing
that (non-exhaustive) list.  I didn't mention that point (a valid one), since
even back in Emacs 20 there were only a dozen or so non-interactive uses of it
remaining in the (distributed) source code, and even back then
`insert-buffer-substring' existed.

I might add too that my own impression is that Emacs Dev over the last few
releases has become more "generous" with such admonitions, prohibitions, and
prescriptions.  That's fine, as long as such are taken as guidance and not as
gospel.