path: root/devdocs/elisp/buffer-contents.html

 <h3 class="section">Examining Buffer Contents</h3>  <p>This section describes functions that allow a Lisp program to convert any portion of the text in the buffer into a string. </p> <dl> <dt id="buffer-substring">Function: <strong>buffer-substring</strong> <em>start end</em>
</dt> <dd>
<p>This function returns a string containing a copy of the text of the region defined by positions <var>start</var> and <var>end</var> in the current buffer. If the arguments are not positions in the accessible portion of the buffer, <code>buffer-substring</code> signals an <code>args-out-of-range</code> error. </p> <p>Here’s an example which assumes Font-Lock mode is not enabled: </p> <div class="example"> <pre class="example">---------- Buffer: foo ----------
This is the contents of buffer foo

---------- Buffer: foo ----------
</pre>

<pre class="example">(buffer-substring 1 10)
     ⇒ "This is t"
</pre>
<pre class="example">(buffer-substring (point-max) 10)
     ⇒ "he contents of buffer foo\n"
</pre>
</div> <p>If the text being copied has any text properties, these are copied into the string along with the characters they belong to. See <a href="text-properties">Text Properties</a>. However, overlays (see <a href="overlays">Overlays</a>) in the buffer and their properties are ignored, not copied. </p> <p>For example, if Font-Lock mode is enabled, you might get results like these: </p> <div class="example"> <pre class="example">(buffer-substring 1 10)
     ⇒ #("This is t" 0 1 (fontified t) 1 9 (fontified t))
</pre>
</div> </dd>
</dl> <dl> <dt id="buffer-substring-no-properties">Function: <strong>buffer-substring-no-properties</strong> <em>start end</em>
</dt> <dd><p>This is like <code>buffer-substring</code>, except that it does not copy text properties, just the characters themselves. See <a href="text-properties">Text Properties</a>. </p></dd>
</dl> <dl> <dt id="buffer-string">Function: <strong>buffer-string</strong>
</dt> <dd><p>This function returns the contents of the entire accessible portion of the current buffer, as a string. If the text being copied has any text properties, these are copied into the string along with the characters they belong to. </p></dd>
</dl> <p>If you need to make sure the resulting string, when copied to a different location, will not change its visual appearance due to reordering of bidirectional text, use the <code>buffer-substring-with-bidi-context</code> function (see <a href="bidirectional-display">buffer-substring-with-bidi-context</a>). </p> <dl> <dt id="filter-buffer-substring">Function: <strong>filter-buffer-substring</strong> <em>start end &amp;optional delete</em>
</dt> <dd>
<p>This function filters the buffer text between <var>start</var> and <var>end</var> using a function specified by the variable <code>filter-buffer-substring-function</code>, and returns the result. </p> <p>The default filter function consults the obsolete wrapper hook <code>filter-buffer-substring-functions</code> (see the documentation string of the macro <code>with-wrapper-hook</code> for the details about this obsolete facility), and the obsolete variable <code>buffer-substring-filters</code>. If both of these are <code>nil</code>, it returns the unaltered text from the buffer, i.e., what <code>buffer-substring</code> would return. </p> <p>If <var>delete</var> is non-<code>nil</code>, the function deletes the text between <var>start</var> and <var>end</var> after copying it, like <code>delete-and-extract-region</code>. </p> <p>Lisp code should use this function instead of <code>buffer-substring</code>, <code>buffer-substring-no-properties</code>, or <code>delete-and-extract-region</code> when copying into user-accessible data structures such as the kill-ring, X clipboard, and registers. Major and minor modes can modify <code>filter-buffer-substring-function</code> to alter such text as it is copied out of the buffer. </p>
</dd>
</dl> <dl> <dt id="filter-buffer-substring-function">Variable: <strong>filter-buffer-substring-function</strong>
</dt> <dd><p>The value of this variable is a function that <code>filter-buffer-substring</code> will call to do the actual work. The function receives three arguments, the same as those of <code>filter-buffer-substring</code>, which it should treat as per the documentation of that function. It should return the filtered text (and optionally delete the source text). </p></dd>
</dl> <p>The following two variables are obsoleted by <code>filter-buffer-substring-function</code>, but are still supported for backward compatibility. </p> <dl> <dt id="filter-buffer-substring-functions">Variable: <strong>filter-buffer-substring-functions</strong>
</dt> <dd>
<p>This obsolete variable is a wrapper hook, whose members should be functions that accept four arguments: <var>fun</var>, <var>start</var>, <var>end</var>, and <var>delete</var>. <var>fun</var> is a function that takes three arguments (<var>start</var>, <var>end</var>, and <var>delete</var>), and returns a string. In both cases, the <var>start</var>, <var>end</var>, and <var>delete</var> arguments are the same as those of <code>filter-buffer-substring</code>. </p> <p>The first hook function is passed a <var>fun</var> that is equivalent to the default operation of <code>filter-buffer-substring</code>, i.e., it returns the buffer-substring between <var>start</var> and <var>end</var> (processed by any <code>buffer-substring-filters</code>) and optionally deletes the original text from the buffer. In most cases, the hook function will call <var>fun</var> once, and then do its own processing of the result. The next hook function receives a <var>fun</var> equivalent to this, and so on. The actual return value is the result of all the hook functions acting in sequence. </p>
</dd>
</dl> <dl> <dt id="buffer-substring-filters">Variable: <strong>buffer-substring-filters</strong>
</dt> <dd><p>The value of this obsolete variable should be a list of functions that accept a single string argument and return another string. The default <code>filter-buffer-substring</code> function passes the buffer substring to the first function in this list, and the return value of each function is passed to the next function. The return value of the last function is passed to <code>filter-buffer-substring-functions</code>. </p></dd>
</dl> <dl> <dt id="current-word">Function: <strong>current-word</strong> <em>&amp;optional strict really-word</em>
</dt> <dd>
<p>This function returns the symbol (or word) at or near point, as a string. The return value includes no text properties. </p> <p>If the optional argument <var>really-word</var> is non-<code>nil</code>, it finds a word; otherwise, it finds a symbol (which includes both word characters and symbol constituent characters). </p> <p>If the optional argument <var>strict</var> is non-<code>nil</code>, then point must be in or next to the symbol or word—if no symbol or word is there, the function returns <code>nil</code>. Otherwise, a nearby symbol or word on the same line is acceptable. </p>
</dd>
</dl> <dl> <dt id="thing-at-point">Function: <strong>thing-at-point</strong> <em>thing &amp;optional no-properties</em>
</dt> <dd>
<p>Return the <var>thing</var> around or next to point, as a string. </p> <p>The argument <var>thing</var> is a symbol which specifies a kind of syntactic entity. Possibilities include <code>symbol</code>, <code>list</code>, <code>sexp</code>, <code>defun</code>, <code>filename</code>, <code>existing-filename</code>, <code>url</code>, <code>word</code>, <code>sentence</code>, <code>whitespace</code>, <code>line</code>, <code>page</code>, <code>string</code>, and others. </p> <p>When the optional argument <var>no-properties</var> is non-<code>nil</code>, this function strips text properties from the return value. </p> <div class="example"> <pre class="example">---------- 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
</pre>
</div> <dl> <dt id="thing-at-point-provider-alist">Variable: <strong>thing-at-point-provider-alist</strong>
</dt> <dd>
<p>This variable allows users and modes to tweak how <code>thing-at-point</code> works. It’s an association list of <var>thing</var>s and functions (called with zero parameters) to return that thing. Entries for <var>thing</var> will be evaluated in turn until a non-<code>nil</code> result is returned. </p> <p>For instance, a major mode could say: </p> <div class="lisp"> <pre class="lisp">(setq-local thing-at-point-provider-alist
            (append thing-at-point-provider-alist
                    '((url . my-mode--url-at-point))))
</pre>
</div> <p>If no providers have a non-<code>nil</code> return, the <var>thing</var> will be computed the standard way. </p>
</dd>
</dl> </dd>
</dl><div class="_attribution">
  <p class="_attribution-p">
    Copyright &copy; 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br>
    <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/Buffer-Contents.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Buffer-Contents.html</a>
  </p>
</div>