Emacs Lisp: print, princ, prin1, format, message
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-messages 【Ctrl+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.
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
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
“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
princ is similar to
(princ '("x" "y")) ; result display is (x y) (prin1 '("x" "y")) ; result display is ("x" "y")
Here's a summary:
|print lisp objects||output can be read back by function |
|like print, but does not add newline at end.||◇|
|print without newline nor delimiters.||For human reading.|