19.5 输出函数

本节描述了和输出有关的Lisp函数，这些函数将对象转换为对应的打印表示。

部分 Emacs 打印函数会自动给给输出添加引号，以方便阅读。这些引用符号为'""和'\'；它们可以区分字符串和符号，并防止字符串和符号中标点的混淆，查阅打印表示以获取完整解释。你可以传递参数，以控制是否使用引用符号。

若该文本需要再次被读回 Lisp，那你需要加上引号，以防止二义性。类似的，若该文本是用来给Lisp程序员提示的，那你也需要这么做。不过，若是为了更好的输出给普通人看，那最好不要使用引号。

Lisp 对象可以引用他们自己。打印这种自引用对象通常会陷入无限循环。Emcas 会自动检测这种递归，并使用 '#level' 来替代这样的循环引用。举个例子，这里 '#0' 表示再 0 level 层的递归引用：

(setq foo (list nil))
     ⇒ (nil)
(setcar foo foo)
     ⇒ (#0)

下面的函数中，stream 表示一个输出流（查阅前一节查看不同输出流的描述，也可以看看 external-debugging-output，这是一个调试时很有用的流。）若 stream 为 nil 或被略去，那默认使用变量 standard-output 的值。

Function: print object &optional stream

函数 print 是比较方便的打印方法。该函数会将 object 的打印表示输出到 stream，并会在结尾额外打印一个换行符。该函数默认使用引号。该函数会返回 object。

举个例子：

(progn (print 'The\ cat\ in)
       (print "the hat")
       (print " came back"))
     -|
     -| The\ cat\ in
     -|
     -| "the hat"
     -|
     -| " came back"
     ⇒ " came back"

Function: prin1 object &optional stream

该函数将 object 的打印表示输出到stream。该函数不会在结尾额外添加换行符，但会和 print 一样，使用引号。该函数返回 object。

(progn (prin1 'The\ cat\ in)
       (prin1 "the hat")
       (prin1 " came back"))
     -| The\ cat\ in"the hat"" came back"
     ⇒ " came back"

Function: princ object &optional stream

该函数将object的文本表示输出到 stream，干函数返回 object。

这个函数用于生成常人可读的输出，而不是 read 可读的输出，因此这个函数并不会插入引号，也不会使用双引号将输出引起来，而且每次调用间也不会插入空格。

(progn
  (princ 'The\ cat)
  (princ " in the \"hat\""))
     -| The cat in the "hat"
     ⇒ " in the \"hat\""

Function: terpri &optional stream ensure

该函数向 stream 输出 新行。其函数名表示 "terminate print"。若参数 ensure 为 non-nil，那么输出将不会作为新行。请注意，在这里，参数 stream 不能是函数，否则会抛出错误。当一个新行被打印出来后，该函数会返回 t。

Function: write-char character &optional stream

该函数将字符 character 输出到 stream。该函数返回 character。

Function: prin1-to-string object &optional noescape

这个函数返回 prin1 会打印的字符串。

(prin1-to-string 'foo)
     ⇒ "foo"
(prin1-to-string (mark-marker))
     ⇒ "#<marker at 2773 in strings.texi>"

若参数 noescape 为 non-nil，那么将会在输出中禁止引用符号。（这个参数在 Emacs 19 或更后的版本中提供）

(prin1-to-string "foo")
     ⇒ "\"foo\""
(prin1-to-string "foo" t)
     ⇒ "foo"

查阅函数 format 在章节格式化字符串，以获取其他的将Lisp对象转换为打印表示的方法。

Macro: with-output-to-string body...

这个宏会执行 body 表达式，并将 standard-output 作为字符串输出。此宏返回该字符串。

举个例子，假设当前缓冲区的名称为 "foo"

(with-output-to-string
  (princ "The buffer is ")
  (princ (buffer-name)))

返回 "The buffer is foo"。

Function: pp object &optional stream

此函数将object输出到stream中，和prin1 很像，但不同的是，此函数的输出会更漂亮。也就是说，该函数会自动添加缩紧，以此让输出对人更加友好。

如果你需要在批处理模式中使用二进制 I/O，举个例子，使用 本节介绍的函数将任意二进制数据，或 non-POSIX 标准下的新行符写出，请查阅 set-binary-mode章节。