# 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章节。


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://emacs-lisp.ivory.cafe/du-qu-he-da-yin-lisp-dui-xiang/19.5-shu-chu-han-shu.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.