diff options
| -rw-r--r-- | Doc/Makefile.deps | 1 | ||||
| -rw-r--r-- | Doc/lib/libascii.tex | 142 |
2 files changed, 93 insertions, 50 deletions
diff --git a/Doc/Makefile.deps b/Doc/Makefile.deps index 2ad97e9..7fbdd6b 100644 --- a/Doc/Makefile.deps +++ b/Doc/Makefile.deps @@ -218,6 +218,7 @@ LIBFILES= $(MANSTYLES) $(COMMONTEX) \ ../lib/libchunk.tex \ ../lib/libcodeop.tex \ ../lib/libcurses.tex \ + ../lib/libascii.tex \ ../lib/libdl.tex \ ../lib/libmutex.tex \ ../lib/libnis.tex \ diff --git a/Doc/lib/libascii.tex b/Doc/lib/libascii.tex index 5159804..afb3595 100644 --- a/Doc/lib/libascii.tex +++ b/Doc/lib/libascii.tex @@ -1,131 +1,173 @@ \section{\module{curses.ascii} --- - Constants and set-membership functions for ASCII characters.} + Utilities for ASCII characters} \declaremodule{standard}{curses.ascii} -\modulesynopsis{Constants and set-membership functions for ASCII characters.} +\modulesynopsis{Constants and set-membership functions for + \ASCII{} characters.} \moduleauthor{Eric S. Raymond}{esr@thyrsus.com} \sectionauthor{Eric S. Raymond}{esr@thyrsus.com} \versionadded{1.6} -The \module{curses.ascii} module supplies name constants for ASCII characters -and functions to test membership in various ASCII character classes. -The constants supplied are names for control characters as follows: +The \module{curses.ascii} module supplies name constants for +\ASCII{} characters and functions to test membership in various +\ASCII{} character classes. The constants supplied are names for +control characters as follows: + +\begin{tableii}{l|l}{constant}{Name}{Meaning} + \lineii{NUL}{} + \lineii{SOH}{Start of heading, console interrupt} + \lineii{STX}{Start of text} + \lineii{ETX}{Ennd of text} + \lineii{EOT}{End of transmission} + \lineii{ENQ}{Enquiry, goes with \constant{ACK} flow control} + \lineii{ACK}{Acknowledgement} + \lineii{BEL}{Bell} + \lineii{BS}{Backspace} + \lineii{TAB}{Tab} + \lineii{HT}{Alias for \constant{TAB}: ``Horizontal tab''} + \lineii{LF}{Line feed} + \lineii{NL}{Alias for \constant{LF}: ``New line''} + \lineii{VT}{Vertical tab} + \lineii{FF}{Form feed} + \lineii{CR}{Carriage return} + \lineii{SO}{Shift-out, begin alternate character set} + \lineii{SI}{Shift-in, resume default character set} + \lineii{DLE}{Data-link escape} + \lineii{DC1}{XON, for flow control} + \lineii{DC2}{Device control 2, block-mode flow control} + \lineii{DC3}{XOFF, for flow control} + \lineii{DC4}{Device control 4} + \lineii{NAK}{Negative acknowledgement} + \lineii{SYN}{Synchronous idle} + \lineii{ETB}{End transmission block} + \lineii{CAN}{Cancel} + \lineii{EM}{End of medium} + \lineii{SUB}{Substitute} + \lineii{ESC}{Escape} + \lineii{FS}{File separator} + \lineii{GS}{Group separator} + \lineii{RS}{Record separator, block-mode terminator} + \lineii{US}{Unit separator} + \lineii{SP}{Space} + \lineii{DEL}{Delete} +\end{tableii} + +Note that many of these have little practical use in modern usage. + +The module supplies the following functions, patterned on those in the +standard C library: -NUL, SOH, STX, ETX, EOT, ENQ, ACK, BEL, BS, TAB, HT, LF, NL, VT, FF, CR, -SO, SI, DLE, DC1, DC2, DC3, DC4, NAK, SYN, ETB, CAN, EM, SUB, ESC, FS, -GS, RS, US, SP, DEL. - -NL and LF are synonyms; so are HT and TAB. The module also supplies -the following functions, patterned on those in the standard C library: \begin{funcdesc}{isalnum}{c} -Checks for an ASCII alphanumeric character; it is equivalent to -isalpha(c) or isdigit(c)) +Checks for an \ASCII{} alphanumeric character; it is equivalent to +\samp{isalpha(\var{c}) or isdigit(\var{c})}. \end{funcdesc} \begin{funcdesc}{isalpha}{c} -Checks for an ASCII alphabetic character; it is equivalent to -isupper(c) or islower(c)) +Checks for an \ASCII{} alphabetic character; it is equivalent to +\samp{isupper(\var{c}) or islower(\var{c})}. \end{funcdesc} \begin{funcdesc}{isascii}{c} -Checks for a character value that fits in the 7-bit ASCII set. +Checks for a character value that fits in the 7-bit \ASCII{} set. \end{funcdesc} \begin{funcdesc}{isblank}{c} -Checks for an ASCII alphanumeric character; it is equivalent to -isalpha(c) or isdigit(c)) +Checks for an \ASCII{} whitespace character. \end{funcdesc} \begin{funcdesc}{iscntrl}{c} -Checks for an ASCII control character (range 0x00 to 0x1f). +Checks for an \ASCII{} control character (in the range 0x00 to 0x1f). \end{funcdesc} \begin{funcdesc}{isdigit}{c} -Checks for an ASCII decimal digit, 0 through 9. +Checks for an \ASCII{} decimal digit, \character{0} through +\character{9}. This is equivalent to \samp{\var{c} in string.digits}. \end{funcdesc} \begin{funcdesc}{isgraph}{c} -Checks for ASCII any printable character except space. +Checks for \ASCII{} any printable character except space. \end{funcdesc} \begin{funcdesc}{islower}{c} -Checks for an ASCII lower-case character. +Checks for an \ASCII{} lower-case character. \end{funcdesc} \begin{funcdesc}{isprint}{c} -Checks for any ASCII printable character including space. +Checks for any \ASCII{} printable character including space. \end{funcdesc} \begin{funcdesc}{ispunct}{c} -Checks for any printable ASCII character which is not a space or an +Checks for any printable \ASCII{} character which is not a space or an alphanumeric character. \end{funcdesc} \begin{funcdesc}{isspace}{c} -Checks for ASCII white-space characters; space, tab, line feed, +Checks for \ASCII{} white-space characters; space, tab, line feed, carriage return, form feed, horizontal tab, vertical tab. \end{funcdesc} \begin{funcdesc}{isupper}{c} -Checks for an ASCII uppercase letter. +Checks for an \ASCII{} uppercase letter. \end{funcdesc} \begin{funcdesc}{isxdigit}{c} -Checks for an ASCII hexadecimal digit, i.e. one of 0123456789abcdefABCDEF. +Checks for an \ASCII{} hexadecimal digit. This is equivalent to +\samp{\var{c} in string.hexdigits}. \end{funcdesc} \begin{funcdesc}{isctrl}{c} -Checks for an ASCII control character, bit values 0 to 31. +Checks for an \ASCII{} control character (ordinal values 0 to 31). \end{funcdesc} \begin{funcdesc}{ismeta}{c} -Checks for a (non-ASCII) character, bit values 0x80 and above. +Checks for a non-\ASCII{} character (ordinal values 0x80 and above). \end{funcdesc} These functions accept either integers or strings; when the argument -is a string, it is first converted using the built-in function ord(). +is a string, it is first converted using the built-in function +\function{ord()}. Note that all these functions check ordinal bit values derived from the first character of the string you pass in; they do not actually know anything about the host machine's character encoding. For functions that know about the character encoding (and handle -internationalization properly) see the string module. +internationalization properly) see the \refmodule{string} module. The following two functions take either a single-character string or integer byte value; they return a value of the same type. \begin{funcdesc}{ascii}{c} -Return the ASCII value corresponding to the low 7 bits of c. +Return the ASCII value corresponding to the low 7 bits of \var{c}. \end{funcdesc} \begin{funcdesc}{ctrl}{c} Return the control character corresponding to the given character -(the character bit value is logical-anded with 0x1f). +(the character bit value is bitwise-anded with 0x1f). \end{funcdesc} \begin{funcdesc}{alt}{c} Return the 8-bit character corresponding to the given ASCII character -(the character bit value is logical-ored with 0x80). +(the character bit value is bitwise-ored with 0x80). \end{funcdesc} The following function takes either a single-character string or -integer byte value; it returns a string. +integer value; it returns a string. \begin{funcdesc}{unctrl}{c} -Return a string representation of the ASCII character c. If c is -printable, this string is the character itself. If the character -is a control character (0x00-0x1f) the string consists of a caret -(^) followed by the corresponding uppercase letter. If the character -is an ASCII delete (0x7f) the string is "^?". If the character has -its meta bit (0x80) set, the meta bit is stripped, the preceding rules -applied, and "!" prepended to the result. -\end{funcdesc} - -Finally, the module supplies a 33-element string array -called controlnames that contains the ASCII mnemonics for the -thirty-two ASCII control characters from 0 (NUL) to 0x1f (US), -in order, plus the mnemonic "SP" for space. - - +Return a string representation of the \ASCII{} character \var{c}. If +\var{c} is printable, this string is the character itself. If the +character is a control character (0x00-0x1f) the string consists of a +caret (\character{\^}) followed by the corresponding uppercase letter. +If the character is an \ASCII{} delete (0x7f) the string is +\code{'\^{}?'}. If the character has its meta bit (0x80) set, the meta +bit is stripped, the preceding rules applied, and +\character{!} prepended to the result. +\end{funcdesc} + +\begin{datadesc}{controlnames} +A 33-element string array that contains the \ASCII{} mnemonics for the +thirty-two \ASCII{} control characters from 0 (NUL) to 0x1f (US), in +order, plus the mnemonic \samp{SP} for the space character. +\end{datadesc} |