1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
|
<h3 class="section">Shorthands</h3> <p>The symbol <em>shorthands</em>, sometimes known as “renamed symbols”, are symbolic forms found in Lisp source. They’re just like regular symbolic forms, except that when the Lisp reader encounters them, it produces symbols which have a different and usually longer <em>print name</em> (see <a href="symbol-components">Symbol Components</a>). </p> <p>It is useful to think of shorthands as <em>abbreviating</em> the full names of intended symbols. Despite this, do not confuse shorthands with the Abbrev system see <a href="abbrevs">Abbrevs</a>. </p> <p>Shorthands make Emacs Lisp’s <em>namespacing etiquette</em> easier to work with. Since all symbols are stored in a single obarray (see <a href="creating-symbols">Creating Symbols</a>), programmers commonly prefix each symbol name with the name of the library where it originates. For example, the functions <code>text-property-search-forward</code> and <code>text-property-search-backward</code> both belong to the <samp>text-property-search.el</samp> library (see <a href="loading">Loading</a>). By properly prefixing symbol names, one effectively prevents clashes between similarly named symbols which belong to different libraries and thus do different things. However, this practice commonly originates very long symbols names, which are inconvenient to type and read after a while. Shorthands solve these issues in a clean way. </p> <dl> <dt id="read-symbol-shorthands">Variable: <strong>read-symbol-shorthands</strong>
</dt> <dd>
<p>This variable’s value is an alist whose elements have the form <code>(<var>shorthand-prefix</var> . <var>longhand-prefix</var>)</code>. Each element instructs the Lisp reader to read every symbol form which starts with <var>shorthand-prefix</var> as if it started with <var>longhand-prefix</var> instead. </p> <p>This variable may only be set in file-local variables (see <a href="https://www.gnu.org/software/emacs/manual/html_node/emacs/File-Variables.html#File-Variables">Local Variables in Files</a> in <cite>The GNU Emacs Manual</cite>). </p>
</dd>
</dl> <p>Here’s an example of shorthands usage in a hypothetical string manipulating library <samp>some-nice-string-utils.el</samp>. </p> <div class="lisp"> <pre class="lisp">(defun some-nice-string-utils-split (separator s &optional omit-nulls)
"A match-data saving variant of `split-string'."
(save-match-data (split-string s separator omit-nulls)))
(defun some-nice-string-utils-lines (s)
"Split string S at newline characters into a list of strings."
(some-nice-string-utils-split "\\(\r\n\\|[\n\r]\\)" s))
</pre>
</div> <p>As can be seen, it’s quite tedious to read or develop this code since the symbol names to type are so long. We can use shorthands to alleviate that. </p> <div class="lisp"> <pre class="lisp">(defun snu-split (separator s &optional omit-nulls)
"A match-data saving variation on `split-string'."
(save-match-data (split-string s separator omit-nulls)))
(defun snu-lines (s)
"Split string S into a list of strings on newline characters."
(snu-split "\\(\r\n\\|[\n\r]\\)" s))
;; Local Variables:
;; read-symbol-shorthands: (("snu-" . "some-nice-string-utils-"))
;; End:
</pre>
</div> <p>Even though the two excerpts look different, they are quite identical after the Lisp reader processes them. Both will lead to the very same symbols being interned (see <a href="creating-symbols">Creating Symbols</a>). Thus loading or byte-compiling any of the two files has equivalent results. The shorthands <code>snu-split</code> and <code>snu-lines</code> used in the second version are <em>not</em> interned in the obarray. This is easily seen by moving point to the location where the shorthands are used and waiting for ElDoc (see <a href="https://www.gnu.org/software/emacs/manual/html_node/emacs/Lisp-Doc.html#Lisp-Doc">Local Variables in Files</a> in <cite>The GNU Emacs Manual</cite>) to hint at the true full name of the symbol under point in the echo area. </p> <p>Since <code>read-symbol-shorthands</code> is a file-local variable, it is possible that multiple libraries depending on <samp>some-nice-string-utils-lines.el</samp> refer to the same symbols under <em>different</em> shorthands, or not using shorthands at all. In the next example, the <samp>my-tricks.el</samp> library refers to the symbol <code>some-nice-string-utils-lines</code> using the <code>sns-</code> prefix instead of <code>snu-</code>. </p> <div class="example"> <pre class="example">(defun t-reverse-lines (s) (string-join (reverse (sns-lines s)) "\n")
;; Local Variables:
;; read-symbol-shorthands: (("t-" . "my-tricks-")
;; ("sns-" . "some-nice-string-utils-"))
;; End:
</pre>
</div> <h4 class="subsection">Exceptions</h4> <p>There are two exceptions to rules governing Shorthand transformations: </p> <ul> <li> Symbol forms comprised entirely of characters in the Emacs Lisp symbol constituent class (see <a href="syntax-class-table">Syntax Class Table</a>) are not transformed. For example, it’s possible to use <code>-</code> or <code>/=</code> as shorthand prefixes, but that won’t shadow the arithmetic <em>functions</em> of those names. </li>
<li> Symbol forms whose names start with ‘<samp>#_</samp>’ are not transformed. </li>
</ul><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/Shorthands.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Shorthands.html</a>
</p>
</div>
|
