Doc/library/curses.ascii.rst

   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
  13 The :mod:`curses.ascii` module supplies name constants for ASCII characters and
  14 functions to test membership in various ASCII character classes.  The constants
  15 supplied 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
  93 Note that many of these have little practical significance in modern usage.  The
  94 mnemonics derive from teleprinter conventions that predate digital computers.
  95
  96 The module supplies the following functions, patterned on those in the standard
  97 C 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.
 120
 121
 122 .. function:: iscntrl(c)
 123
 124    Checks for an ASCII control character (in the range 0x00 to 0x1f).
 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
 180 These functions accept either integers or strings; when the argument is a
 181 string, it is first converted using the built-in function :func:`ord`.
 182
 183 Note that all these functions check ordinal bit values derived from the  first
 184 character of the string you pass in; they do not actually know anything about
 185 the host machine's character encoding.  For functions  that know about the
 186 character encoding (and handle internationalization properly) see the
 187 :mod:`string` module.
 188
 189 The following two functions take either a single-character string or integer
 190 byte 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
 209 The following function takes either a single-character string or integer value;
 210 it 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