diff options
Diffstat (limited to 'devdocs/elisp/examining-properties.html')
| -rw-r--r-- | devdocs/elisp/examining-properties.html | 42 |
1 files changed, 42 insertions, 0 deletions
diff --git a/devdocs/elisp/examining-properties.html b/devdocs/elisp/examining-properties.html new file mode 100644 index 00000000..953bf332 --- /dev/null +++ b/devdocs/elisp/examining-properties.html @@ -0,0 +1,42 @@ + <h4 class="subsection">Examining Text Properties</h4> <p>The simplest way to examine text properties is to ask for the value of a particular property of a particular character. For that, use <code>get-text-property</code>. Use <code>text-properties-at</code> to get the entire property list of a character. See <a href="property-search">Property Search</a>, for functions to examine the properties of a number of characters at once. </p> <p>These functions handle both strings and buffers. Keep in mind that positions in a string start from 0, whereas positions in a buffer start from 1. Passing a buffer other than the current buffer may be slow. </p> <dl> <dt id="get-text-property">Function: <strong>get-text-property</strong> <em>pos prop &optional object</em> +</dt> <dd> +<p>This function returns the value of the <var>prop</var> property of the character after position <var>pos</var> in <var>object</var> (a buffer or string). The argument <var>object</var> is optional and defaults to the current buffer. </p> <p>If there is no <var>prop</var> property strictly speaking, but the character has a property category that is a symbol, then <code>get-text-property</code> returns the <var>prop</var> property of that symbol. </p> +</dd> +</dl> <dl> <dt id="get-char-property">Function: <strong>get-char-property</strong> <em>position prop &optional object</em> +</dt> <dd> +<p>This function is like <code>get-text-property</code>, except that it checks overlays first and then text properties. See <a href="overlays">Overlays</a>. </p> <p>The argument <var>object</var> may be a string, a buffer, or a window. If it is a window, then the buffer displayed in that window is used for text properties and overlays, but only the overlays active for that window are considered. If <var>object</var> is a buffer, then overlays in that buffer are considered first, in order of decreasing priority, followed by the text properties. If <var>object</var> is a string, only text properties are considered, since strings never have overlays. </p> +</dd> +</dl> <dl> <dt id="get-pos-property">Function: <strong>get-pos-property</strong> <em>position prop &optional object</em> +</dt> <dd><p>This function is like <code>get-char-property</code>, except that it pays attention to properties’ stickiness and overlays’ advancement settings instead of the property of the character at (i.e., right after) <var>position</var>. </p></dd> +</dl> <dl> <dt id="get-char-property-and-overlay">Function: <strong>get-char-property-and-overlay</strong> <em>position prop &optional object</em> +</dt> <dd> +<p>This is like <code>get-char-property</code>, but gives extra information about the overlay that the property value comes from. </p> <p>Its value is a cons cell whose <small>CAR</small> is the property value, the same value <code>get-char-property</code> would return with the same arguments. Its <small>CDR</small> is the overlay in which the property was found, or <code>nil</code>, if it was found as a text property or not found at all. </p> <p>If <var>position</var> is at the end of <var>object</var>, both the <small>CAR</small> and the <small>CDR</small> of the value are <code>nil</code>. </p> +</dd> +</dl> <dl> <dt id="char-property-alias-alist">Variable: <strong>char-property-alias-alist</strong> +</dt> <dd><p>This variable holds an alist which maps property names to a list of alternative property names. If a character does not specify a direct value for a property, the alternative property names are consulted in order; the first non-<code>nil</code> value is used. This variable takes precedence over <code>default-text-properties</code>, and <code>category</code> properties take precedence over this variable. </p></dd> +</dl> <dl> <dt id="text-properties-at">Function: <strong>text-properties-at</strong> <em>position &optional object</em> +</dt> <dd><p>This function returns the entire property list of the character at <var>position</var> in the string or buffer <var>object</var>. If <var>object</var> is <code>nil</code>, it defaults to the current buffer. </p></dd> +</dl> <dl> <dt id="default-text-properties">Variable: <strong>default-text-properties</strong> +</dt> <dd> +<p>This variable holds a property list giving default values for text properties. Whenever a character does not specify a value for a property, neither directly, through a category symbol, or through <code>char-property-alias-alist</code>, the value stored in this list is used instead. Here is an example: </p> <div class="example"> <pre class="example">(setq default-text-properties '(foo 69) + char-property-alias-alist nil) +;; <span class="roman">Make sure character 1 has no properties of its own.</span> +(set-text-properties 1 2 nil) +;; <span class="roman">What we get, when we ask, is the default value.</span> +(get-text-property 1 'foo) + ⇒ 69 +</pre> +</div> </dd> +</dl> <dl> <dt id="object-intervals">Function: <strong>object-intervals</strong> <em>OBJECT</em> +</dt> <dd> +<p>This function returns a copy of the intervals (i.e., text properties) in <var>object</var> as a list of intervals. <var>object</var> must be a string or a buffer. Altering the structure of this list does not change the intervals in the object. </p> <div class="example"> <pre class="example">(object-intervals (propertize "foo" 'face 'bold)) + ⇒ ((0 3 (face bold))) +</pre> +</div> <p>Each element in the returned list represents one interval. Each interval has three parts: The first is the start, the second is the end, and the third part is the text property itself. </p> +</dd> +</dl><div class="_attribution"> + <p class="_attribution-p"> + Copyright © 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/Examining-Properties.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Examining-Properties.html</a> + </p> +</div> |