Doc/lib/libascii.tex

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