new repository

1 files changed, 66 insertions, 0 deletions

diff --git a/devdocs/elisp/list-variables.html b/devdocs/elisp/list-variables.html
new file mode 100644
index 00000000..37df9e3b
--- /dev/null
+++ b/devdocs/elisp/list-variables.html
@@ -0,0 +1,66 @@
+ <h3 class="section">Modifying List Variables</h3>   <p>These functions, and one macro, provide convenient ways to modify a list which is stored in a variable. </p> <dl> <dt id="push">Macro: <strong>push</strong> <em>element listname</em>
+</dt> <dd>
+<p>This macro creates a new list whose <small>CAR</small> is <var>element</var> and whose <small>CDR</small> is the list specified by <var>listname</var>, and saves that list in <var>listname</var>. In the simplest case, <var>listname</var> is an unquoted symbol naming a list, and this macro is equivalent to <code>(setq <var>listname</var> (cons <var>element</var> <var>listname</var>))</code>. </p> <div class="example"> <pre class="example">(setq l '(a b))
+     ⇒ (a b)
+(push 'c l)
+     ⇒ (c a b)
+l
+     ⇒ (c a b)
+</pre>
+</div> <p>More generally, <code>listname</code> can be a generalized variable. In that case, this macro does the equivalent of <code>(setf <var>listname</var> (cons <var>element</var> <var>listname</var>))</code>. See <a href="generalized-variables">Generalized Variables</a>. </p> <p>For the <code>pop</code> macro, which removes the first element from a list, See <a href="list-elements">List Elements</a>. </p>
+</dd>
+</dl> <p>Two functions modify lists that are the values of variables. </p> <dl> <dt id="add-to-list">Function: <strong>add-to-list</strong> <em>symbol element &amp;optional append compare-fn</em>
+</dt> <dd>
+<p>This function sets the variable <var>symbol</var> by consing <var>element</var> onto the old value, if <var>element</var> is not already a member of that value. It returns the resulting list, whether updated or not. The value of <var>symbol</var> had better be a list already before the call. <code>add-to-list</code> uses <var>compare-fn</var> to compare <var>element</var> against existing list members; if <var>compare-fn</var> is <code>nil</code>, it uses <code>equal</code>. </p> <p>Normally, if <var>element</var> is added, it is added to the front of <var>symbol</var>, but if the optional argument <var>append</var> is non-<code>nil</code>, it is added at the end. </p> <p>The argument <var>symbol</var> is not implicitly quoted; <code>add-to-list</code> is an ordinary function, like <code>set</code> and unlike <code>setq</code>. Quote the argument yourself if that is what you want. </p> <p>Do not use this function when <var>symbol</var> refers to a lexical variable. </p>
+</dd>
+</dl> <p>Here’s a scenario showing how to use <code>add-to-list</code>: </p> <div class="example"> <pre class="example">(setq foo '(a b))
+     ⇒ (a b)
+
+(add-to-list 'foo 'c)     ;; <span class="roman">Add <code>c</code>.</span>
+     ⇒ (c a b)
+
+(add-to-list 'foo 'b)     ;; <span class="roman">No effect.</span>
+     ⇒ (c a b)
+
+foo                       ;; <span class="roman"><code>foo</code> was changed.</span>
+     ⇒ (c a b)
+</pre>
+</div> <p>An equivalent expression for <code>(add-to-list '<var>var</var>
+<var>value</var>)</code> is this: </p> <div class="example"> <pre class="example">(if (member <var>value</var> <var>var</var>)
+    <var>var</var>
+  (setq <var>var</var> (cons <var>value</var> <var>var</var>)))
+</pre>
+</div> <dl> <dt id="add-to-ordered-list">Function: <strong>add-to-ordered-list</strong> <em>symbol element &amp;optional order</em>
+</dt> <dd>
+<p>This function sets the variable <var>symbol</var> by inserting <var>element</var> into the old value, which must be a list, at the position specified by <var>order</var>. If <var>element</var> is already a member of the list, its position in the list is adjusted according to <var>order</var>. Membership is tested using <code>eq</code>. This function returns the resulting list, whether updated or not. </p> <p>The <var>order</var> is typically a number (integer or float), and the elements of the list are sorted in non-decreasing numerical order. </p> <p><var>order</var> may also be omitted or <code>nil</code>. Then the numeric order of <var>element</var> stays unchanged if it already has one; otherwise, <var>element</var> has no numeric order. Elements without a numeric list order are placed at the end of the list, in no particular order. </p> <p>Any other value for <var>order</var> removes the numeric order of <var>element</var> if it already has one; otherwise, it is equivalent to <code>nil</code>. </p> <p>The argument <var>symbol</var> is not implicitly quoted; <code>add-to-ordered-list</code> is an ordinary function, like <code>set</code> and unlike <code>setq</code>. Quote the argument yourself if necessary. </p> <p>The ordering information is stored in a hash table on <var>symbol</var>’s <code>list-order</code> property. <var>symbol</var> cannot refer to a lexical variable. </p>
+</dd>
+</dl> <p>Here’s a scenario showing how to use <code>add-to-ordered-list</code>: </p> <div class="example"> <pre class="example">(setq foo '())
+     ⇒ nil
+
+(add-to-ordered-list 'foo 'a 1)     ;; <span class="roman">Add <code>a</code>.</span>
+     ⇒ (a)
+
+(add-to-ordered-list 'foo 'c 3)     ;; <span class="roman">Add <code>c</code>.</span>
+     ⇒ (a c)
+
+(add-to-ordered-list 'foo 'b 2)     ;; <span class="roman">Add <code>b</code>.</span>
+     ⇒ (a b c)
+
+(add-to-ordered-list 'foo 'b 4)     ;; <span class="roman">Move <code>b</code>.</span>
+     ⇒ (a c b)
+
+(add-to-ordered-list 'foo 'd)       ;; <span class="roman">Append <code>d</code>.</span>
+     ⇒ (a c b d)
+
+(add-to-ordered-list 'foo 'e)       ;; <span class="roman">Add <code>e</code></span>.
+     ⇒ (a c b e d)
+
+foo                       ;; <span class="roman"><code>foo</code> was changed.</span>
+     ⇒ (a c b e d)
+</pre>
+</div><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/List-Variables.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/List-Variables.html</a>
+  </p>
+</div>