www.delorie.com/gnu/docs/elisp-manual-21/elisp_416.html   search  
Buy the book!

GNU Emacs Lisp Reference Manual

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

27.3 Buffer Names

Each buffer has a unique name, which is a string. Many of the functions that work on buffers accept either a buffer or a buffer name as an argument. Any argument called buffer-or-name is of this sort, and an error is signaled if it is neither a string nor a buffer. Any argument called buffer must be an actual buffer object, not a name.

Buffers that are ephemeral and generally uninteresting to the user have names starting with a space, so that the list-buffers and buffer-menu commands don't mention them. A name starting with space also initially disables recording undo information; see 32.9 Undo.

Function: buffer-name &optional buffer
This function returns the name of buffer as a string. If buffer is not supplied, it defaults to the current buffer.

If buffer-name returns nil, it means that buffer has been killed. See section 27.10 Killing Buffers.

     => "buffers.texi"

(setq foo (get-buffer "temp"))
     => #<buffer temp>
(kill-buffer foo)
     => nil
(buffer-name foo)
     => nil
     => #<killed buffer>

Command: rename-buffer newname &optional unique
This function renames the current buffer to newname. An error is signaled if newname is not a string, or if there is already a buffer with that name. The function returns newname.

Ordinarily, rename-buffer signals an error if newname is already in use. However, if unique is non-nil, it modifies newname to make a name that is not in use. Interactively, you can make unique non-nil with a numeric prefix argument. (This is how the command rename-uniquely is implemented.)

Function: get-buffer buffer-or-name
This function returns the buffer specified by buffer-or-name. If buffer-or-name is a string and there is no buffer with that name, the value is nil. If buffer-or-name is a buffer, it is returned as given; that is not very useful, so the argument is usually a name. For example:

(setq b (get-buffer "lewis"))
     => #<buffer lewis>
(get-buffer b)
     => #<buffer lewis>
(get-buffer "Frazzle-nots")
     => nil

See also the function get-buffer-create in 27.9 Creating Buffers.

Function: generate-new-buffer-name starting-name &rest ignore
This function returns a name that would be unique for a new buffer--but does not create the buffer. It starts with starting-name, and produces a name not currently in use for any buffer by appending a number inside of `<...>'.

If the optional second argument ignore is non-nil, it should be a string; it makes a difference if it is a name in the sequence of names to be tried. That name will be considered acceptable, if it is tried, even if a buffer with that name exists. Thus, if buffers named `foo', `foo<2>', `foo<3>' and `foo<4>' exist,

(generate-new-buffer-name "foo")
     => "foo<5>"
(generate-new-buffer-name "foo" "foo<3>")
     => "foo<3>"
(generate-new-buffer-name "foo" "foo<6>")
     => "foo<5>"

See the related function generate-new-buffer in 27.9 Creating Buffers.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

  webmaster   donations   bookstore     delorie software   privacy  
  Copyright 2003   by The Free Software Foundation     Updated Jun 2003