9.5 Shorthands

The symbol shorthands, 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 print name (see Symbol Components).

It is useful to think of shorthands as abbreviating the full names of intended symbols. Despite this, do not confuse shorthands with the Abbrev system (see Abbrevs and Abbrev Expansion).

Shorthands make Emacs Lisp’s namespacing etiquette easier to work with. Since all symbols are stored in a single obarray (see Creating and Interning Symbols), programmers commonly prefix each symbol name with the name of the library where it originates. For example, the functions text-property-search-forward and text-property-search-backward both belong to the text-property-search.el library (see Loading). 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.

Variable: read-symbol-shorthands ¶

This variable’s value is an alist whose elements have the form (shorthand-prefix . longhand-prefix). Each element instructs the Lisp reader to read every symbol form which starts with shorthand-prefix as if it started with longhand-prefix instead.

This variable may only be set in file-local variables (see Local Variables in Files in The GNU Emacs Manual).

Here’s an example of shorthands usage in a hypothetical string manipulating library some-nice-string-utils.el.

(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))

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.

(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:

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 Creating and Interning Symbols). Thus loading or byte-compiling any of the two files has equivalent results. The shorthands snu-split and snu-lines used in the second version are not interned in the obarray. This is easily seen by moving point to the location where the shorthands are used and waiting for ElDoc (see Local Variables in Files in The GNU Emacs Manual) to hint at the true full name of the symbol under point in the echo area.

Since read-symbol-shorthands is a file-local variable, it is possible that multiple libraries depending on some-nice-string-utils-lines.el refer to the same symbols under different shorthands, or not using shorthands at all. In the next example, the my-tricks.el library refers to the symbol some-nice-string-utils-lines using the sns- prefix instead of snu-.

(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:

• Exceptions