new repository

1 files changed, 78 insertions, 0 deletions

diff --git a/devdocs/elisp/creating-symbols.html b/devdocs/elisp/creating-symbols.html
new file mode 100644
index 00000000..e51a8827
--- /dev/null
+++ b/devdocs/elisp/creating-symbols.html
@@ -0,0 +1,78 @@
+ <h3 class="section">Creating and Interning Symbols</h3>  <p>To understand how symbols are created in GNU Emacs Lisp, you must know how Lisp reads them. Lisp must ensure that it finds the same symbol every time it reads the same sequence of characters in the same context. Failure to do so would cause complete confusion. </p>     <p>When the Lisp reader encounters a name that references a symbol in the source code, it reads all the characters of that name. Then it looks up that name in a table called an <em>obarray</em> to find the symbol that the programmer meant. The technique used in this lookup is called “hashing”, an efficient method of looking something up by converting a sequence of characters to a number, known as a “hash code”. For example, instead of searching a telephone book cover to cover when looking up Jan Jones, you start with the J’s and go from there. That is a simple version of hashing. Each element of the obarray is a <em>bucket</em> which holds all the symbols with a given hash code; to look for a given name, it is sufficient to look through all the symbols in the bucket for that name’s hash code. (The same idea is used for general Emacs hash tables, but they are a different data type; see <a href="hash-tables">Hash Tables</a>.) </p> <p>When looking up names, the Lisp reader also considers “shorthands”. If the programmer supplied them, this allows the reader to find a symbol even if its name isn’t present in its full form in the source code. Of course, the reader needs to be aware of some pre-established context about such shorthands, much as one needs context to be to able to refer uniquely to Jan Jones by just the name “Jan”: it’s probably fine when amongst the Joneses, or when Jan has been mentioned recently, but very ambiguous in any other situation. See <a href="shorthands">Shorthands</a>. </p>  <p>If a symbol with the desired name is found, the reader uses that symbol. If the obarray does not contain a symbol with that name, the reader makes a new symbol and adds it to the obarray. Finding or adding a symbol with a certain name is called <em>interning</em> it, and the symbol is then called an <em>interned symbol</em>. </p> <p>Interning ensures that each obarray has just one symbol with any particular name. Other like-named symbols may exist, but not in the same obarray. Thus, the reader gets the same symbols for the same names, as long as you keep reading with the same obarray. </p> <p>Interning usually happens automatically in the reader, but sometimes other programs may want to do it. For example, after the <kbd>M-x</kbd> command obtains the command name as a string using the minibuffer, it then interns the string, to get the interned symbol with that name. As another example, a hypothetical telephone book program could intern the name of each looked up person’s name as a symbol, even if the obarray did not contain it, so that it could attach information to that new symbol, such as the last time someone looked it up. </p>   <p>No obarray contains all symbols; in fact, some symbols are not in any obarray. They are called <em>uninterned symbols</em>. An uninterned symbol has the same four cells as other symbols; however, the only way to gain access to it is by finding it in some other object or as the value of a variable. Uninterned symbols are sometimes useful in generating Lisp code, see below. </p> <p>In Emacs Lisp, an obarray is actually a vector. Each element of the vector is a bucket; its value is either an interned symbol whose name hashes to that bucket, or 0 if the bucket is empty. Each interned symbol has an internal link (invisible to the user) to the next symbol in the bucket. Because these links are invisible, there is no way to find all the symbols in an obarray except using <code>mapatoms</code> (below). The order of symbols in a bucket is not significant. </p> <p>In an empty obarray, every element is 0, so you can create an obarray with <code>(make-vector <var>length</var> 0)</code>. <strong>This is the only valid way to create an obarray.</strong> Prime numbers as lengths tend to result in good hashing; lengths one less than a power of two are also good. </p> <p><strong>Do not try to put symbols in an obarray yourself.</strong> This does not work—only <code>intern</code> can enter a symbol in an obarray properly. </p>  <blockquote> <p><b>Common Lisp note:</b> Unlike Common Lisp, Emacs Lisp does not provide for interning the same name in several different “packages”, thus creating multiple symbols with the same name but different packages. Emacs Lisp provides a different namespacing system called “shorthands” (see <a href="shorthands">Shorthands</a>). </p>
+</blockquote> <p>Most of the functions below take a name and sometimes an obarray as arguments. A <code>wrong-type-argument</code> error is signaled if the name is not a string, or if the obarray is not a vector. </p> <dl> <dt id="symbol-name">Function: <strong>symbol-name</strong> <em>symbol</em>
+</dt> <dd>
+<p>This function returns the string that is <var>symbol</var>’s name. For example: </p> <div class="example"> <pre class="example">(symbol-name 'foo)
+     ⇒ "foo"
+</pre>
+</div> <p><strong>Warning:</strong> Changing the string by substituting characters does change the name of the symbol, but fails to update the obarray, so don’t do it! </p>
+</dd>
+</dl>  <p>Creating an uninterned symbol is useful in generating Lisp code, because an uninterned symbol used as a variable in the code you generate cannot clash with any variables used in other Lisp programs. </p> <dl> <dt id="make-symbol">Function: <strong>make-symbol</strong> <em>name</em>
+</dt> <dd>
+<p>This function returns a newly-allocated, uninterned symbol whose name is <var>name</var> (which must be a string). Its value and function definition are void, and its property list is <code>nil</code>. In the example below, the value of <code>sym</code> is not <code>eq</code> to <code>foo</code> because it is a distinct uninterned symbol whose name is also ‘<samp>foo</samp>’. </p> <div class="example"> <pre class="example">(setq sym (make-symbol "foo"))
+     ⇒ foo
+(eq sym 'foo)
+     ⇒ nil
+</pre>
+</div> </dd>
+</dl> <dl> <dt id="gensym">Function: <strong>gensym</strong> <em>&amp;optional prefix</em>
+</dt> <dd><p>This function returns a symbol using <code>make-symbol</code>, whose name is made by appending <code>gensym-counter</code> to <var>prefix</var> and incrementing that counter, guaranteeing that no two calls to this function will generate a symbol with the same name. The prefix defaults to <code>"g"</code>. </p></dd>
+</dl> <p>To avoid problems when accidentally interning printed representation of generated code (see <a href="printed-representation">Printed Representation</a>), it is recommended to use <code>gensym</code> instead of <code>make-symbol</code>. </p> <dl> <dt id="intern">Function: <strong>intern</strong> <em>name &amp;optional obarray</em>
+</dt> <dd>
+<p>This function returns the interned symbol whose name is <var>name</var>. If there is no such symbol in the obarray <var>obarray</var>, <code>intern</code> creates a new one, adds it to the obarray, and returns it. If <var>obarray</var> is omitted, the value of the global variable <code>obarray</code> is used. </p> <div class="example"> <pre class="example">(setq sym (intern "foo"))
+     ⇒ foo
+(eq sym 'foo)
+     ⇒ t
+
+(setq sym1 (intern "foo" other-obarray))
+     ⇒ foo
+(eq sym1 'foo)
+     ⇒ nil
+</pre>
+</div> </dd>
+</dl>  <blockquote> <p><b>Common Lisp note:</b> In Common Lisp, you can intern an existing symbol in an obarray. In Emacs Lisp, you cannot do this, because the argument to <code>intern</code> must be a string, not a symbol. </p>
+</blockquote> <dl> <dt id="intern-soft">Function: <strong>intern-soft</strong> <em>name &amp;optional obarray</em>
+</dt> <dd>
+<p>This function returns the symbol in <var>obarray</var> whose name is <var>name</var>, or <code>nil</code> if <var>obarray</var> has no symbol with that name. Therefore, you can use <code>intern-soft</code> to test whether a symbol with a given name is already interned. If <var>obarray</var> is omitted, the value of the global variable <code>obarray</code> is used. </p> <p>The argument <var>name</var> may also be a symbol; in that case, the function returns <var>name</var> if <var>name</var> is interned in the specified obarray, and otherwise <code>nil</code>. </p> <div class="example"> <pre class="example">(intern-soft "frazzle")        ; <span class="roman">No such symbol exists.</span>
+     ⇒ nil
+(make-symbol "frazzle")        ; <span class="roman">Create an uninterned one.</span>
+     ⇒ frazzle
+</pre>
+<pre class="example">(intern-soft "frazzle")        ; <span class="roman">That one cannot be found.</span>
+     ⇒ nil
+</pre>
+<pre class="example">(setq sym (intern "frazzle"))  ; <span class="roman">Create an interned one.</span>
+     ⇒ frazzle
+</pre>
+<pre class="example">(intern-soft "frazzle")        ; <span class="roman">That one can be found!</span>
+     ⇒ frazzle
+</pre>
+<pre class="example">(eq sym 'frazzle)              ; <span class="roman">And it is the same one.</span>
+     ⇒ t
+</pre>
+</div> </dd>
+</dl> <dl> <dt id="obarray">Variable: <strong>obarray</strong>
+</dt> <dd><p>This variable is the standard obarray for use by <code>intern</code> and <code>read</code>. </p></dd>
+</dl> <dl> <dt id="mapatoms">Function: <strong>mapatoms</strong> <em>function &amp;optional obarray</em>
+</dt> <dd>
+<p>This function calls <var>function</var> once with each symbol in the obarray <var>obarray</var>. Then it returns <code>nil</code>. If <var>obarray</var> is omitted, it defaults to the value of <code>obarray</code>, the standard obarray for ordinary symbols. </p> <div class="example"> <pre class="example">(setq count 0)
+     ⇒ 0
+(defun count-syms (s)
+  (setq count (1+ count)))
+     ⇒ count-syms
+(mapatoms 'count-syms)
+     ⇒ nil
+count
+     ⇒ 1871
+</pre>
+</div> <p>See <code>documentation</code> in <a href="accessing-documentation">Accessing Documentation</a>, for another example using <code>mapatoms</code>. </p>
+</dd>
+</dl> <dl> <dt id="unintern">Function: <strong>unintern</strong> <em>symbol obarray</em>
+</dt> <dd>
+<p>This function deletes <var>symbol</var> from the obarray <var>obarray</var>. If <code>symbol</code> is not actually in the obarray, <code>unintern</code> does nothing. If <var>obarray</var> is <code>nil</code>, the current obarray is used. </p> <p>If you provide a string instead of a symbol as <var>symbol</var>, it stands for a symbol name. Then <code>unintern</code> deletes the symbol (if any) in the obarray which has that name. If there is no such symbol, <code>unintern</code> does nothing. </p> <p>If <code>unintern</code> does delete a symbol, it returns <code>t</code>. Otherwise it returns <code>nil</code>. </p>
+</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/Creating-Symbols.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Creating-Symbols.html</a>
+  </p>
+</div>