path: root/devdocs/elisp/setting-generalized-variables.html

 <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 &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/Setting-Generalized-Variables.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Setting-Generalized-Variables.html</a>
  </p>
</div>