1:mod:`curses.ascii` --- Utilities for ASCII characters
2======================================================
3
4.. module:: curses.ascii
5   :synopsis: Constants and set-membership functions for ASCII characters.
6
7.. moduleauthor:: Eric S. Raymond <esr@thyrsus.com>
8.. sectionauthor:: Eric S. Raymond <esr@thyrsus.com>
9
10--------------
11
12The :mod:`curses.ascii` module supplies name constants for ASCII characters and
13functions to test membership in various ASCII character classes.  The constants
14supplied are names for control characters as follows:
15
16+--------------+----------------------------------------------+
17| Name         | Meaning                                      |
18+==============+==============================================+
19| :const:`NUL` |                                              |
20+--------------+----------------------------------------------+
21| :const:`SOH` | Start of heading, console interrupt          |
22+--------------+----------------------------------------------+
23| :const:`STX` | Start of text                                |
24+--------------+----------------------------------------------+
25| :const:`ETX` | End of text                                  |
26+--------------+----------------------------------------------+
27| :const:`EOT` | End of transmission                          |
28+--------------+----------------------------------------------+
29| :const:`ENQ` | Enquiry, goes with :const:`ACK` flow control |
30+--------------+----------------------------------------------+
31| :const:`ACK` | Acknowledgement                              |
32+--------------+----------------------------------------------+
33| :const:`BEL` | Bell                                         |
34+--------------+----------------------------------------------+
35| :const:`BS`  | Backspace                                    |
36+--------------+----------------------------------------------+
37| :const:`TAB` | Tab                                          |
38+--------------+----------------------------------------------+
39| :const:`HT`  | Alias for :const:`TAB`: "Horizontal tab"     |
40+--------------+----------------------------------------------+
41| :const:`LF`  | Line feed                                    |
42+--------------+----------------------------------------------+
43| :const:`NL`  | Alias for :const:`LF`: "New line"            |
44+--------------+----------------------------------------------+
45| :const:`VT`  | Vertical tab                                 |
46+--------------+----------------------------------------------+
47| :const:`FF`  | Form feed                                    |
48+--------------+----------------------------------------------+
49| :const:`CR`  | Carriage return                              |
50+--------------+----------------------------------------------+
51| :const:`SO`  | Shift-out, begin alternate character set     |
52+--------------+----------------------------------------------+
53| :const:`SI`  | Shift-in, resume default character set       |
54+--------------+----------------------------------------------+
55| :const:`DLE` | Data-link escape                             |
56+--------------+----------------------------------------------+
57| :const:`DC1` | XON, for flow control                        |
58+--------------+----------------------------------------------+
59| :const:`DC2` | Device control 2, block-mode flow control    |
60+--------------+----------------------------------------------+
61| :const:`DC3` | XOFF, for flow control                       |
62+--------------+----------------------------------------------+
63| :const:`DC4` | Device control 4                             |
64+--------------+----------------------------------------------+
65| :const:`NAK` | Negative acknowledgement                     |
66+--------------+----------------------------------------------+
67| :const:`SYN` | Synchronous idle                             |
68+--------------+----------------------------------------------+
69| :const:`ETB` | End transmission block                       |
70+--------------+----------------------------------------------+
71| :const:`CAN` | Cancel                                       |
72+--------------+----------------------------------------------+
73| :const:`EM`  | End of medium                                |
74+--------------+----------------------------------------------+
75| :const:`SUB` | Substitute                                   |
76+--------------+----------------------------------------------+
77| :const:`ESC` | Escape                                       |
78+--------------+----------------------------------------------+
79| :const:`FS`  | File separator                               |
80+--------------+----------------------------------------------+
81| :const:`GS`  | Group separator                              |
82+--------------+----------------------------------------------+
83| :const:`RS`  | Record separator, block-mode terminator      |
84+--------------+----------------------------------------------+
85| :const:`US`  | Unit separator                               |
86+--------------+----------------------------------------------+
87| :const:`SP`  | Space                                        |
88+--------------+----------------------------------------------+
89| :const:`DEL` | Delete                                       |
90+--------------+----------------------------------------------+
91
92Note that many of these have little practical significance in modern usage.  The
93mnemonics derive from teleprinter conventions that predate digital computers.
94
95The module supplies the following functions, patterned on those in the standard
96C library:
97
98
99.. function:: isalnum(c)
100
101   Checks for an ASCII alphanumeric character; it is equivalent to ``isalpha(c) or
102   isdigit(c)``.
103
104
105.. function:: isalpha(c)
106
107   Checks for an ASCII alphabetic character; it is equivalent to ``isupper(c) or
108   islower(c)``.
109
110
111.. function:: isascii(c)
112
113   Checks for a character value that fits in the 7-bit ASCII set.
114
115
116.. function:: isblank(c)
117
118   Checks for an ASCII whitespace character; space or horizontal tab.
119
120
121.. function:: iscntrl(c)
122
123   Checks for an ASCII control character (in the range 0x00 to 0x1f or 0x7f).
124
125
126.. function:: isdigit(c)
127
128   Checks for an ASCII decimal digit, ``'0'`` through ``'9'``.  This is equivalent
129   to ``c in string.digits``.
130
131
132.. function:: isgraph(c)
133
134   Checks for ASCII any printable character except space.
135
136
137.. function:: islower(c)
138
139   Checks for an ASCII lower-case character.
140
141
142.. function:: isprint(c)
143
144   Checks for any ASCII printable character including space.
145
146
147.. function:: ispunct(c)
148
149   Checks for any printable ASCII character which is not a space or an alphanumeric
150   character.
151
152
153.. function:: isspace(c)
154
155   Checks for ASCII white-space characters; space, line feed, carriage return, form
156   feed, horizontal tab, vertical tab.
157
158
159.. function:: isupper(c)
160
161   Checks for an ASCII uppercase letter.
162
163
164.. function:: isxdigit(c)
165
166   Checks for an ASCII hexadecimal digit.  This is equivalent to ``c in
167   string.hexdigits``.
168
169
170.. function:: isctrl(c)
171
172   Checks for an ASCII control character (ordinal values 0 to 31).
173
174
175.. function:: ismeta(c)
176
177   Checks for a non-ASCII character (ordinal values 0x80 and above).
178
179These functions accept either integers or single-character strings; when the argument is a
180string, it is first converted using the built-in function :func:`ord`.
181
182Note that all these functions check ordinal bit values derived from the
183character of the string you pass in; they do not actually know anything about
184the host machine's character encoding.
185
186The following two functions take either a single-character string or integer
187byte value; they return a value of the same type.
188
189
190.. function:: ascii(c)
191
192   Return the ASCII value corresponding to the low 7 bits of *c*.
193
194
195.. function:: ctrl(c)
196
197   Return the control character corresponding to the given character (the character
198   bit value is bitwise-anded with 0x1f).
199
200
201.. function:: alt(c)
202
203   Return the 8-bit character corresponding to the given ASCII character (the
204   character bit value is bitwise-ored with 0x80).
205
206The following function takes either a single-character string or integer value;
207it returns a string.
208
209
210.. index::
211   single: ^ (caret); in curses module
212   single: ! (exclamation); in curses module
213
214.. function:: unctrl(c)
215
216   Return a string representation of the ASCII character *c*.  If *c* is printable,
217   this string is the character itself.  If the character is a control character
218   (0x00--0x1f) the string consists of a caret (``'^'``) followed by the
219   corresponding uppercase letter. If the character is an ASCII delete (0x7f) the
220   string is ``'^?'``.  If the character has its meta bit (0x80) set, the meta bit
221   is stripped, the preceding rules applied, and ``'!'`` prepended to the result.
222
223
224.. data:: controlnames
225
226   A 33-element string array that contains the ASCII mnemonics for the thirty-two
227   ASCII control characters from 0 (NUL) to 0x1f (US), in order, plus the mnemonic
228   ``SP`` for the space character.
229
230