path: root/devdocs/elisp/case-tables.html

 <h3 class="section">The Case Table</h3> <p>You can customize case conversion by installing a special <em>case table</em>. A case table specifies the mapping between upper case and lower case letters. It affects both the case conversion functions for Lisp objects (see the previous section) and those that apply to text in the buffer (see <a href="case-changes">Case Changes</a>). Each buffer has a case table; there is also a standard case table which is used to initialize the case table of new buffers. </p> <p>A case table is a char-table (see <a href="char_002dtables">Char-Tables</a>) whose subtype is <code>case-table</code>. This char-table maps each character into the corresponding lower case character. It has three extra slots, which hold related tables: </p> <dl compact> <dt><var>upcase</var></dt> <dd><p>The upcase table maps each character into the corresponding upper case character. </p></dd> <dt><var>canonicalize</var></dt> <dd><p>The canonicalize table maps all of a set of case-related characters into a particular member of that set. </p></dd> <dt><var>equivalences</var></dt> <dd><p>The equivalences table maps each one of a set of case-related characters into the next character in that set. </p></dd> </dl> <p>In simple cases, all you need to specify is the mapping to lower-case; the three related tables will be calculated automatically from that one. </p> <p>For some languages, upper and lower case letters are not in one-to-one correspondence. There may be two different lower case letters with the same upper case equivalent. In these cases, you need to specify the maps for both lower case and upper case. </p> <p>The extra table <var>canonicalize</var> maps each character to a canonical equivalent; any two characters that are related by case-conversion have the same canonical equivalent character. For example, since ‘<samp>a</samp>’ and ‘<samp>A</samp>’ are related by case-conversion, they should have the same canonical equivalent character (which should be either ‘<samp>a</samp>’ for both of them, or ‘<samp>A</samp>’ for both of them). </p> <p>The extra table <var>equivalences</var> is a map that cyclically permutes each equivalence class (of characters with the same canonical equivalent). (For ordinary <acronym>ASCII</acronym>, this would map ‘<samp>a</samp>’ into ‘<samp>A</samp>’ and ‘<samp>A</samp>’ into ‘<samp>a</samp>’, and likewise for each set of equivalent characters.) </p> <p>When constructing a case table, you can provide <code>nil</code> for <var>canonicalize</var>; then Emacs fills in this slot from the lower case and upper case mappings. You can also provide <code>nil</code> for <var>equivalences</var>; then Emacs fills in this slot from <var>canonicalize</var>. In a case table that is actually in use, those components are non-<code>nil</code>. Do not try to specify <var>equivalences</var> without also specifying <var>canonicalize</var>. </p> <p>Here are the functions for working with case tables: </p> <dl> <dt id="case-table-p">Function: <strong>case-table-p</strong> <em>object</em>
</dt> <dd><p>This predicate returns non-<code>nil</code> if <var>object</var> is a valid case table. </p></dd>
</dl> <dl> <dt id="set-standard-case-table">Function: <strong>set-standard-case-table</strong> <em>table</em>
</dt> <dd><p>This function makes <var>table</var> the standard case table, so that it will be used in any buffers created subsequently. </p></dd>
</dl> <dl> <dt id="standard-case-table">Function: <strong>standard-case-table</strong>
</dt> <dd><p>This returns the standard case table. </p></dd>
</dl> <dl> <dt id="current-case-table">Function: <strong>current-case-table</strong>
</dt> <dd><p>This function returns the current buffer’s case table. </p></dd>
</dl> <dl> <dt id="set-case-table">Function: <strong>set-case-table</strong> <em>table</em>
</dt> <dd><p>This sets the current buffer’s case table to <var>table</var>. </p></dd>
</dl> <dl> <dt id="with-case-table">Macro: <strong>with-case-table</strong> <em>table body…</em>
</dt> <dd><p>The <code>with-case-table</code> macro saves the current case table, makes <var>table</var> the current case table, evaluates the <var>body</var> forms, and finally restores the case table. The return value is the value of the last form in <var>body</var>. The case table is restored even in case of an abnormal exit via <code>throw</code> or error (see <a href="nonlocal-exits">Nonlocal Exits</a>). </p></dd>
</dl> <p>Some language environments modify the case conversions of <acronym>ASCII</acronym> characters; for example, in the Turkish language environment, the <acronym>ASCII</acronym> capital I is downcased into a Turkish dotless i (‘<samp>ı</samp>’). This can interfere with code that requires ordinary <acronym>ASCII</acronym> case conversion, such as implementations of <acronym>ASCII</acronym>-based network protocols. In that case, use the <code>with-case-table</code> macro with the variable <var>ascii-case-table</var>, which stores the unmodified case table for the <acronym>ASCII</acronym> character set. </p> <dl> <dt id="ascii-case-table">Variable: <strong>ascii-case-table</strong>
</dt> <dd><p>The case table for the <acronym>ASCII</acronym> character set. This should not be modified by any language environment settings. </p></dd>
</dl> <p>The following three functions are convenient subroutines for packages that define non-<acronym>ASCII</acronym> character sets. They modify the specified case table <var>case-table</var>; they also modify the standard syntax table. See <a href="syntax-tables">Syntax Tables</a>. Normally you would use these functions to change the standard case table. </p> <dl> <dt id="set-case-syntax-pair">Function: <strong>set-case-syntax-pair</strong> <em>uc lc case-table</em>
</dt> <dd><p>This function specifies a pair of corresponding letters, one upper case and one lower case. </p></dd>
</dl> <dl> <dt id="set-case-syntax-delims">Function: <strong>set-case-syntax-delims</strong> <em>l r case-table</em>
</dt> <dd><p>This function makes characters <var>l</var> and <var>r</var> a matching pair of case-invariant delimiters. </p></dd>
</dl> <dl> <dt id="set-case-syntax">Function: <strong>set-case-syntax</strong> <em>char syntax case-table</em>
</dt> <dd><p>This function makes <var>char</var> case-invariant, with syntax <var>syntax</var>. </p></dd>
</dl> <dl> <dt id="describe-buffer-case-table">Command: <strong>describe-buffer-case-table</strong>
</dt> <dd><p>This command displays a description of the contents of the current buffer’s case table. </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/Case-Tables.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/Case-Tables.html</a>
  </p>
</div>