# 32.2 缓冲区内容 (Buffer Contents)

这一小结介绍了几个函数, 用来将缓冲区中任意位置的文本转换为Lisp 中的字符串.

Function: buffer-substring start end\
 这个函数将当前缓冲区中, 位置 start 和 end 之间的文本作一份字符串拷贝, 并返回.如果任一个参数处在编辑范围之外, 那么 buffer-substring 会抛出 args-out-of-range 错误.

这里有一个例子, 其中 Font-Lock mode 未启用:

```
---------- Buffer: foo ----------
This is the contents of buffer foo

---------- Buffer: foo ----------

(buffer-substring 1 10)
    => "This is t"
(buffer-substring (point-max) 10)
    => "he contents of buffer foo\n"
```

如果被拷贝的文本具有文本属性, 那么这些属性会被一并拷贝过去. (详情查阅 文本属性). 不过, 缓冲区中被覆盖的属会被忽略.

比如, 在上面的例子中, 如果我们假设启用了 Font-Lock mode, 那你就会得到这样的输出:

```
(buffer-substring 1 10)
    => #("This is t" 0 1 (fontified t) 1 9 (fontified t))
```

Function: buffer-sbustring-no-properties start end\
  这个函数和 buffer-substring 很像, 而且顾名思义, 这个函数不会拷贝文本属性, 而是只拷贝字符本身.

Function: buffer-string\
  这个函数返回当前缓冲区编辑范围内所有的文本,并将它们整体作为一个字符串返回. 如果其中的文本具有文本属性, 那么它们也会被一并拷贝.

如果你需要确保将整个字符串拷贝到另一个位置, 并不改变视觉效果的话, 使用 buffer-substring-with-bidi-context 函数.

Function: filter-buffer-substring start end \&optional delete\
  这个函数使用由 变量 filter-buffer-substring-function 提供的函数, 对 start 到 end 范围内的文本进行过滤, 然后返回过滤结果.

默认的过滤函数一般是 (被遗弃) filter-buffer-substring-functions 以及 (被遗弃) buffer-substring-filters. 如果它们都是 nil, 那么就不会有任何过滤动作. 就和 buffer-substring 一样.

如果参数 delete 是非nil, 那么这个函数会在拷贝完文本后删除它. 和 delete-and-extract-region 类似.

当将文本拷贝进 用户缓存结构时(kill-环, X 粘贴板, 寄存器) 时, 需要使用这个函数, 而不是 buffer-substing, buffer-substring-no-properties 和 delete-and-extract-region. Majro mode 和 minor mode 都可以修改 filter-buffer-substring-function.

Variable: filter-buffer-substring-function\
  这个变量的值是一个函数, 而这个函数正是前面 filter-buffer-substring 将会调用的函数. 这个函数接受三个参数, 这三个参数和 filter-buffer-substring 一样. 这个函数应该返回过滤后的文本. (可选参数 delete 默认会删除原文本)

下面的两个变量已经被遗弃, 但是为了向后兼容而保留.

Variable: filter-buffer-substring-functions\
  这个被遗弃的变量是一个封装的 hook, 这个 hook 中的成员是接受四个参数的函数, 这些参数是: fun, start, end 和 delete. 其中参数 fun 是接受三个参数的函数(start, end 和 delete), 并且返回字符串. 这两组 start, end, delete 和 filter-buffer-substring 中的三个参数一样.\
~~第一个钩子函数会被传递一个和 filter-buffer-substring 函数相同的函数,也就是 返回 start 和 end 范围内, 并可选的删除原文本的那个函数. 绝大多数情况下, 钩子函数仅仅会调用 fun 一次, 然后得到结果, 并继续处理自己的事务. 接着下一个钩子函数会收到一个类似的 fun, 并继续处理. 因此最终返回的值是所有钩子函数依次作用之后所得到的值.~~

Variable: buffer-substring-filters\
&#x20; 这个被遗弃的变量是一个函数列表. 其中的函数接受一个字符串参数, 并返回另一个字符串. 默认情况下, filter-buffer-substring 函数会将 截取的字符串传给列表的第一个函数, 然后第一个函数的返回值传给第二个函数, 如此类推. 最后一个函数处理后的值便会再返还个 filter-buffer-substring-functions.<br>

Function: current-word \&optional strict really-word\
&#x20; 这个函数返回位置点附近的一个符号(或者说单词), 返回值不包含文本属性.\
&#x20; 如果可选参数 really-word 非nil, 那么这个函数会寻找一个单词, 否则仅仅返回一个符号.(符号可以是 单词字符和符号字符的混合体)\
&#x20; 如果可选参数 strict 非nil, 那么位置点必须要在一个符号或单词的内部或者附近, 否则会返回 nil. 如果为 nil, 这个函数会放宽条件,同一行的附近的符号或单词也是可以的.

Function: thing-at-point thin \&optional no-properties\
&#x20; 这个函数会检查紧挨着 位置点的 thing, 并将其作为字符串返回. 其中的参数 thing 时一系列特定的语法符号. 可能的取值有 symbol, list, sexp, defun, filename, url, word, sentence, whitespace, line, page等等. (你可以把它当成一个通用函数)\
&#x20; 如果可选参数 no-properties 非nil, 那么这个函数的返回值会去除文本属性.

```
---------- Buffer: foo ----------
Gentlemen may cry ``Pea∗ce! Peace!,''
but there is no peace.
---------- Buffer: foo ----------

(thing-at-point 'word)
    => "Peace"
(thing-at-point 'line)
    => "Gentlemen may cry ``Peace! Peace!,''\n"
(thing-at-point 'whitespace)
    => nil
```


---

# 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/wen-ben/untitled/32.2-huan-chong-qu-nei-rong-buffer-contents.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.