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