new repository

1 files changed, 60 insertions, 0 deletions

diff --git a/devdocs/elisp/eval.html b/devdocs/elisp/eval.html
new file mode 100644
index 00000000..6c924118
--- /dev/null
+++ b/devdocs/elisp/eval.html
@@ -0,0 +1,60 @@
+ <h3 class="section">Eval</h3> <p>Most often, forms are evaluated automatically, by virtue of their occurrence in a program being run. On rare occasions, you may need to write code that evaluates a form that is computed at run time, such as after reading a form from text being edited or getting one from a property list. On these occasions, use the <code>eval</code> function. Often <code>eval</code> is not needed and something else should be used instead. For example, to get the value of a variable, while <code>eval</code> works, <code>symbol-value</code> is preferable; or rather than store expressions in a property list that then need to go through <code>eval</code>, it is better to store functions instead that are then passed to <code>funcall</code>. </p> <p>The functions and variables described in this section evaluate forms, specify limits to the evaluation process, or record recently returned values. Loading a file also does evaluation (see <a href="loading">Loading</a>). </p> <p>It is generally cleaner and more flexible to store a function in a data structure, and call it with <code>funcall</code> or <code>apply</code>, than to store an expression in the data structure and evaluate it. Using functions provides the ability to pass information to them as arguments. </p> <dl> <dt id="eval">Function: <strong>eval</strong> <em>form &amp;optional lexical</em>
+</dt> <dd>
+<p>This is the basic function for evaluating an expression. It evaluates <var>form</var> in the current environment, and returns the result. The type of the <var>form</var> object determines how it is evaluated. See <a href="forms">Forms</a>. </p> <p>The argument <var>lexical</var> specifies the scoping rule for local variables (see <a href="variable-scoping">Variable Scoping</a>). If it is omitted or <code>nil</code>, that means to evaluate <var>form</var> using the default dynamic scoping rule. If it is <code>t</code>, that means to use the lexical scoping rule. The value of <var>lexical</var> can also be a non-empty alist specifying a particular <em>lexical environment</em> for lexical bindings; however, this feature is only useful for specialized purposes, such as in Emacs Lisp debuggers. See <a href="lexical-binding">Lexical Binding</a>. </p> <p>Since <code>eval</code> is a function, the argument expression that appears in a call to <code>eval</code> is evaluated twice: once as preparation before <code>eval</code> is called, and again by the <code>eval</code> function itself. Here is an example: </p> <div class="example"> <pre class="example">(setq foo 'bar)
+     ⇒ bar
+</pre>
+<pre class="example">(setq bar 'baz)
+     ⇒ baz
+;; <span class="roman">Here <code>eval</code> receives argument <code>foo</code></span>
+(eval 'foo)
+     ⇒ bar
+;; <span class="roman">Here <code>eval</code> receives argument <code>bar</code>, which is the value of <code>foo</code></span>
+(eval foo)
+     ⇒ baz
+</pre>
+</div> <p>The number of currently active calls to <code>eval</code> is limited to <code>max-lisp-eval-depth</code> (see below). </p>
+</dd>
+</dl> <dl> <dt id="eval-region">Command: <strong>eval-region</strong> <em>start end &amp;optional stream read-function</em>
+</dt> <dd>
+<p>This function evaluates the forms in the current buffer in the region defined by the positions <var>start</var> and <var>end</var>. It reads forms from the region and calls <code>eval</code> on them until the end of the region is reached, or until an error is signaled and not handled. </p> <p>By default, <code>eval-region</code> does not produce any output. However, if <var>stream</var> is non-<code>nil</code>, any output produced by output functions (see <a href="output-functions">Output Functions</a>), as well as the values that result from evaluating the expressions in the region are printed using <var>stream</var>. See <a href="output-streams">Output Streams</a>. </p> <p>If <var>read-function</var> is non-<code>nil</code>, it should be a function, which is used instead of <code>read</code> to read expressions one by one. This function is called with one argument, the stream for reading input. You can also use the variable <code>load-read-function</code> (see <a href="how-programs-do-loading#Definition-of-load_002dread_002dfunction">How Programs Do Loading</a>) to specify this function, but it is more robust to use the <var>read-function</var> argument. </p> <p><code>eval-region</code> does not move point. It always returns <code>nil</code>. </p>
+</dd>
+</dl>  <dl> <dt id="eval-buffer">Command: <strong>eval-buffer</strong> <em>&amp;optional buffer-or-name stream filename unibyte print</em>
+</dt> <dd>
+<p>This is similar to <code>eval-region</code>, but the arguments provide different optional features. <code>eval-buffer</code> operates on the entire accessible portion of buffer <var>buffer-or-name</var> (see <a href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Narrowing.html#Narrowing">Narrowing</a> in <cite>The GNU Emacs Manual</cite>). <var>buffer-or-name</var> can be a buffer, a buffer name (a string), or <code>nil</code> (or omitted), which means to use the current buffer. <var>stream</var> is used as in <code>eval-region</code>, unless <var>stream</var> is <code>nil</code> and <var>print</var> non-<code>nil</code>. In that case, values that result from evaluating the expressions are still discarded, but the output of the output functions is printed in the echo area. <var>filename</var> is the file name to use for <code>load-history</code> (see <a href="unloading">Unloading</a>), and defaults to <code>buffer-file-name</code> (see <a href="buffer-file-name">Buffer File Name</a>). If <var>unibyte</var> is non-<code>nil</code>, <code>read</code> converts strings to unibyte whenever possible. </p>  <p><code>eval-current-buffer</code> is an alias for this command. </p>
+</dd>
+</dl> <dl> <dt id="max-lisp-eval-depth">User Option: <strong>max-lisp-eval-depth</strong>
+</dt> <dd>
+<p>This variable defines the maximum depth allowed in calls to <code>eval</code>, <code>apply</code>, and <code>funcall</code> before an error is signaled (with error message <code>"Lisp nesting exceeds max-lisp-eval-depth"</code>). </p> <p>This limit, with the associated error when it is exceeded, is one way Emacs Lisp avoids infinite recursion on an ill-defined function. If you increase the value of <code>max-lisp-eval-depth</code> too much, such code can cause stack overflow instead. On some systems, this overflow can be handled. In that case, normal Lisp evaluation is interrupted and control is transferred back to the top level command loop (<code>top-level</code>). Note that there is no way to enter Emacs Lisp debugger in this situation. See <a href="error-debugging">Error Debugging</a>. </p>  <p>The depth limit counts internal uses of <code>eval</code>, <code>apply</code>, and <code>funcall</code>, such as for calling the functions mentioned in Lisp expressions, and recursive evaluation of function call arguments and function body forms, as well as explicit calls in Lisp code. </p> <p>The default value of this variable is 800. If you set it to a value less than 100, Lisp will reset it to 100 if the given value is reached. Entry to the Lisp debugger increases the value, if there is little room left, to make sure the debugger itself has room to execute. </p> <p><code>max-specpdl-size</code> provides another limit on nesting. See <a href="local-variables#Definition-of-max_002dspecpdl_002dsize">Local Variables</a>. </p>
+</dd>
+</dl> <dl> <dt id="values">Variable: <strong>values</strong>
+</dt> <dd>
+<p>The value of this variable is a list of the values returned by all the expressions that were read, evaluated, and printed from buffers (including the minibuffer) by the standard Emacs commands which do this. (Note that this does <em>not</em> include evaluation in <samp>*ielm*</samp> buffers, nor evaluation using <kbd>C-j</kbd>, <kbd>C-x C-e</kbd>, and similar evaluation commands in <code>lisp-interaction-mode</code>.) </p> <p>This variable is obsolete, and will be removed in a future version, since it constantly enlarges the memory footprint of the Emacs process. For that reason, we recommend against using it. </p> <p>The elements of <code>values</code> are ordered most recent first. </p> <div class="example"> <pre class="example">(setq x 1)
+     ⇒ 1
+</pre>
+<pre class="example">(list 'A (1+ 2) auto-save-default)
+     ⇒ (A 3 t)
+</pre>
+<pre class="example">values
+     ⇒ ((A 3 t) 1 …)
+</pre>
+</div> <p>This variable could be useful for referring back to values of forms recently evaluated. It is generally a bad idea to print the value of <code>values</code> itself, since this may be very long. Instead, examine particular elements, like this: </p> <div class="example"> <pre class="example">;; <span class="roman">Refer to the most recent evaluation result.</span>
+(nth 0 values)
+     ⇒ (A 3 t)
+</pre>
+<pre class="example">;; <span class="roman">That put a new element on,</span>
+;;   <span class="roman">so all elements move back one.</span>
+(nth 1 values)
+     ⇒ (A 3 t)
+</pre>
+<pre class="example">;; <span class="roman">This gets the element that was next-to-most-recent</span>
+;;   <span class="roman">before this example.</span>
+(nth 3 values)
+     ⇒ 1
+</pre>
+</div> </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/Eval.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Eval.html</a>
+  </p>
+</div>