diff options
Diffstat (limited to 'devdocs/elisp/setting-generalized-variables.html')
| -rw-r--r-- | devdocs/elisp/setting-generalized-variables.html | 31 |
1 files changed, 31 insertions, 0 deletions
diff --git a/devdocs/elisp/setting-generalized-variables.html b/devdocs/elisp/setting-generalized-variables.html new file mode 100644 index 00000000..d3efaf79 --- /dev/null +++ b/devdocs/elisp/setting-generalized-variables.html @@ -0,0 +1,31 @@ + <h4 class="subsection">The setf Macro</h4> <p>The <code>setf</code> macro is the most basic way to operate on generalized variables. The <code>setf</code> form is like <code>setq</code>, except that it accepts arbitrary place forms on the left side rather than just symbols. For example, <code>(setf (car a) b)</code> sets the car of <code>a</code> to <code>b</code>, doing the same operation as <code>(setcar a b)</code>, but without you having to use two separate functions for setting and accessing this type of place. </p> <dl> <dt id="setf">Macro: <strong>setf</strong> <em>[place form]…</em> +</dt> <dd><p>This macro evaluates <var>form</var> and stores it in <var>place</var>, which must be a valid generalized variable form. If there are several <var>place</var> and <var>form</var> pairs, the assignments are done sequentially just as with <code>setq</code>. <code>setf</code> returns the value of the last <var>form</var>. </p></dd> +</dl> <p>The following Lisp forms are the forms in Emacs that will work as generalized variables, and so may appear in the <var>place</var> argument of <code>setf</code>: </p> <ul> <li> A symbol. In other words, <code>(setf x y)</code> is exactly equivalent to <code>(setq x y)</code>, and <code>setq</code> itself is strictly speaking redundant given that <code>setf</code> exists. Most programmers will continue to prefer <code>setq</code> for setting simple variables, though, for stylistic and historical reasons. The macro <code>(setf x y)</code> actually expands to <code>(setq x y)</code>, so there is no performance penalty for using it in compiled code. </li> +<li> A call to any of the following standard Lisp functions: <div class="example"> <pre class="example">aref cddr symbol-function +car elt symbol-plist +caar get symbol-value +cadr gethash +cdr nth +cdar nthcdr +</pre> +</div> </li> +<li> A call to any of the following Emacs-specific functions: <div class="example"> <pre class="example">alist-get process-get +frame-parameter process-sentinel +terminal-parameter window-buffer +keymap-parent window-display-table +match-data window-dedicated-p +overlay-get window-hscroll +overlay-start window-parameter +overlay-end window-point +process-buffer window-start +process-filter default-value +</pre> +</div> </li> +</ul> <p><code>setf</code> signals an error if you pass a <var>place</var> form that it does not know how to handle. </p> <p>Note that for <code>nthcdr</code>, the list argument of the function must itself be a valid <var>place</var> form. For example, <code>(setf (nthcdr +0 foo) 7)</code> will set <code>foo</code> itself to 7. </p> <p>The macros <code>push</code> (see <a href="list-variables">List Variables</a>) and <code>pop</code> (see <a href="list-elements">List Elements</a>) can manipulate generalized variables, not just lists. <code>(pop <var>place</var>)</code> removes and returns the first element of the list stored in <var>place</var>. It is analogous to <code>(prog1 (car <var>place</var>) (setf <var>place</var> (cdr <var>place</var>)))</code>, except that it takes care to evaluate all subforms only once. <code>(push <var>x</var> <var>place</var>)</code> inserts <var>x</var> at the front of the list stored in <var>place</var>. It is analogous to <code>(setf +<var>place</var> (cons <var>x</var> <var>place</var>))</code>, except for evaluation of the subforms. Note that <code>push</code> and <code>pop</code> on an <code>nthcdr</code> place can be used to insert or delete at any position in a list. </p> <p>The <samp>cl-lib</samp> library defines various extensions for generalized variables, including additional <code>setf</code> places. See <a href="https://www.gnu.org/software/emacs/manual/html_node/cl/Generalized-Variables.html#Generalized-Variables">Generalized Variables</a> in <cite>Common Lisp Extensions</cite>. </p><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/Setting-Generalized-Variables.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Setting-Generalized-Variables.html</a> + </p> +</div> |