Emacs Lisp: print, princ, prin1, format, message

By Xah Lee. Date: . Last updated: .

This is a short tutorial on printing in emacs lisp. If you don't know elisp, first take a look at Emacs Lisp Basics.

Simple Printing with “message”

The most basic printing function is message. Here's a example:

; printing
(message "hi")

; printing variable values
(message "Her age is: %d " 16)        ; %d is for number
(message "Her name is: %s " "Vicky")  ; %s is for string
(message "Her mid init is: %c " 86)   ; %c is for character in ASCII code

You can see past output of the message function in the buffer named “*Messages*”. You can view the buffer with view-echo-area-messagesCtrl+h e】.

The “*Messages*” buffer is a special buffer, because it is the general output destination for any messages from emacs.

For example, it automatically truncates the top entries when the buffer reaches some size (see variable messages-buffer-max-lines). Also, when a message is repeated many times, it automatically condenses the repeated lines. And if a message is a huge line, the line is truncated automatically. Here's a example.

;; print a line many times
(setq xx 1)
(while (< xx 20)
  (message "yay")
  (setq xx (1+ xx))
  )
(switch-to-buffer "*Messages*")

In the above example, it prints “yay [19 times]” instead of the “yay” line for 19 times.

(info "(elisp)Displaying Messages")

Print to Your Own Buffer

When writing a elisp script that does batch processing, it's best to print to your own buffer.

For example, suppose you have a elisp batch script that do find and replace on all files in a dir. For each file visited, it prints out the file path. If you use (message …), it prints to the “*Messages*” buffer, which automatically roll off the top if you have more than a hundred lines. Also, it may intermix your script's output with output from other emacs activities.

Here's a example of printing to your own buffer:

(require 'find-lisp)
(with-output-to-temp-buffer "*my output*" 
  (mapc 'my-process-file (find-lisp-find-files "~/" "\\.html$"))
  (princ "Done.\n")
  (switch-to-buffer "*my output*")
  )

In the above example, any call to print in “my-process-file” is output to your temp buffer.

“print” and “prin1” function

Elisp provides the print function. The basic syntax is this:

(print OBJECT)

The “OBJECT” is any elisp object you want to print. It can be any lisp datatype, such as string, number, list, buffer, frame, …, etc.

There's also a function named prin1. This is same as print except it doesn't add a newline.

“format” for Controlling Printing Detail

How a lisp object is converted to string for printing is done by the format function. It takes a input string, and several other arguments of lisp objects, and output a string. Call describe-function to lookup its inline doc. Here's a excerpt:

(format STRING &rest OBJECTS)

Format a string out of a format-string and arguments.
The first argument is a format control string.
The other arguments are substituted into it to make the result, a string.

The format control string may contain %-sequences meaning to substitute
the next available argument:

%s means print a string argument.  Actually, prints any object, with `princ'.
%d means print as number in decimal (%o octal, %x hex).
%X is like %x, but uses upper case.
%e means print a number in exponential notation.
%f means print a number in decimal-point notation.
%g means print a number in exponential notation
  or decimal-point notation, whichever uses fewer characters.
%c means print a number as a single character.
%S means print any object as an s-expression (using `prin1').

…

For example, if you want to print a date format in yyyy-mm-dd, padding with leading “0”, you can do:

;; format yyyy-mm-dd, ISO 8601 format
(print (format "%04d-%02d-%02d" 2012 4 10))

“princ” for Human-Friendly Output

The princ is similar to print, except that the output is meant to be human-friendly. For example, it does not print the delimiters of strings.

(princ '("x" "y")) ; result display is (x y)
(prin1 '("x" "y")) ; result display is ("x" "y")

Here's a summary:

Function NamePurposeComment
printprint lisp objectsoutput can be read back by function read.
prin1like print, but does not add newline at end.
princprint without newline nor delimiters.For human reading.

(info "(elisp) Output Functions")

Like it? Buy Xah Emacs Tutorial. Thanks.

or, buy something from my keyboard store.