Common Lisp Package: COM.INFORMATIMAGO.COMMON-LISP.CESARUM.ASCII

Some ASCII code utilities, to process sequences of ASCII code bytes as easily as strings. Examples: (bytes= buffer #.(ascii-bytes "HELO ") :end1 (min 5 (length buffer))) (bytes= (read-ascii-line) #"HELO " :end1 (min 5 (length buffer))) License: AGPL3 Copyright Pascal J. Bourguignon 2006 - 2012 This program is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more details. You should have received a copy of the GNU Affero General Public License along with this program. If not, see <http://www.gnu.org/licenses/>

README:

FUNCTION

Public

ASCII-BYTES (STRING &KEY (NEWLINE *NEWLINE*) (START 0) (END (LENGTH STRING)))

RETURN: A byte vector containing the ASCII codes of the characters in the string. Only printable character and #newline are accepted in the string. #newline is translated to either CR+LF, CR, or LF according to the NEWLINE parameter. NEWLINE: (member :crlf :cr :lf) ; the default is *NEWLINE*.

ASCII-CODE (CH)

RETURN: The ASCII code of the character ch, or raise an error if the character has no ascii code. Only printable characters are accepted. No control code.

ASCII-CONTROL-CODE-P (CODE)

RETURN: Whether CODE is an ASCII control code.

ASCII-DISPATCH-MACRO (STREAM SUB-CHAR ARGUMENT)

DO: Read a string and converts it to an ASCII byte sequence. ARGUMENT: If NIL, #newline are encoded according to *NEWLINE*. If 0, #newline are encoded to CR-LF. If 1, #newline are encoded to LF. If 2, #newline are encoded to CR. Otherwise an error is issued. SUB-CHAR: If it is #" then it's considered the start of the string, otherwise we expect to read a full string next. This allow to set dispatch macro characters for: #"abc" or #Y"abc" EXAMPLES: (set-dispatch-macro-character ## #Y (function ascii-dispatch-macro) *readtable*) (set-dispatch-macro-character ## #" (function ascii-dispatch-macro) *readtable*)

ASCII-FORMAT (DESTINATION CTRL-STRING &REST ARGUMENTS)

DO: Format the CTRL-STRING and the ARGUMENTS with FORMAT, convert the resulting string to a vector of ASCII bytes and send it to the DESTINATION. RETURN: NIL if DESTINATION is not NIL, a byte vector otherwise. DESTINATION: T -> *STANDARD-OUTPUT* NIL -> A vector of bytes is returned. STREAM -> An output binary stream to which the bytes are written. CTRL-STRING: A FORMAT control string (contaiing only characters in the ASCII character set). ARGUMENTS: Arguments to be formated with FORMAT. SEE ALSO: FORMAT

ASCII-PRINTABLE-CODE-P (CODE)

RETURN: Whether CODE is the code of an ASCII printable character.

ASCII-STRING (BYTES &KEY (NEWLINE *NEWLINE*) (START 0) (END (LENGTH BYTES)))

DO: Converts the ASCII bytes to a string. If there are control codes, an error is signaled. RETURN: A string containing the characters encoded in the ASCII bytes. NEWLINE: (member :crlf :cr :lf :any) ; the default is *NEWLINE*. If lone CR or LF are present, then an error is signaled. START: index of the first byte to be converted. END: index beyond the last byte to be converted.

BYTES/= (V1 V2 &KEY (START1 0) (START2 0) (END1 NIL) (END2 NIL))

like string/=, but for byte vectors.

BYTES< (V1 V2 &KEY (START1 0) (START2 0) (END1 NIL) (END2 NIL))

like string<, but for byte vectors.

BYTES<= (V1 V2 &KEY (START1 0) (START2 0) (END1 NIL) (END2 NIL))

like string<=, but for byte vectors.

BYTES= (V1 V2 &KEY (START1 0) (START2 0) (END1 NIL) (END2 NIL))

like string=, but for byte vectors.

BYTES> (V1 V2 &KEY (START1 0) (START2 0) (END1 NIL) (END2 NIL))

like string<, but for byte vectors.

BYTES>= (V1 V2 &KEY (START1 0) (START2 0) (END1 NIL) (END2 NIL))

like string>=, but for byte vectors.

CODE-ASCII (CODE)

RETURN: The character corresponding to the given ASCII code. Only codes for printable characters are accepted, and both CR and LF are mapped to #newline.

CODE-ASCII-DIGIT-P (CODE)

RETURN: The decimal digit value of the character encoded by the ASCII CODE, or NIL if CODE is not the ASCII code of a digit character.

READ-ASCII-LINE (STREAM &OPTIONAL (EOF-ERROR T) (EOF-VALUE NIL) (NEWLINE *NEWLINE*))

newline: (member :crlf :cr :lf) ; the defaultl is :CRLF since that's what's used in internet binary protocols using ascii.

Private

TEST

DO: test the ascii package; signal an error if something is wrong. RETURN: :success

Undocumented

ASCII-ERROR (CODE)

INPUT-NEWLINE (NEWLINE)

OUTPUT-NEWLINE (NEWLINE)

GENERIC-FUNCTION

Public

DECODING-ERROR-CODE (ERR)

The code that corresponds to no character.

DECODING-ERROR-CODING-SYSTEM (ERR)

A keyword denoting the coding system which cannot decode the code.

DECODING-ERROR-MESSAGE (ERR)

The error message.

ENCODING-ERROR-CHARACTER (ERR)

The character that cannot be encoded.

ENCODING-ERROR-CODING-SYSTEM (ERR)

A keyword denoting the coding system which cannot encode the character.

ENCODING-ERROR-MESSAGE (ERR)

The error message.

VARIABLE

Public

*ASCII-CHARACTERS*

A string containing all the ASCII characters in lexical order.

*HEXADECIMAL-DIGITS*

A string contaiing the hexadecimal digits (lower case letters) in order.

*NEWLINE*

(OR (MEMBER :CRLF :CR :LF) (CONS (MEMBER :CRLF :CR :LF) (MEMBER :CRLF :CR :LF :ANY)) The encoding used for #newline for output and for input. If it's a keyword, it's used for both output and input. If it's a CONS cell, the CAR specifies the newline encoding for output and the CDR specifies the newline encoding for input (it may be :ANY to accept any of CR-LF, CR or LF; LF-CR would read as two newlines).

CONDITION

Public

DECODING-ERROR

The condition denoting a decoding error.

ENCODING-ERROR

The condition denoting an encoding error.

CONSTANT

Public

ACK

^F ASCII Control Code Acknowledgement

BEL

^G ASCII Control Code Bell

BS

^H ASCII Control Code Backspace

CAN

^X ASCII Control Code Cancel

CR

^M ASCII Control Code Carriage return

DC1

^Q ASCII Control Code Device Control 1 (X-ON)

DC2

^R ASCII Control Code Device Control 2

DC3

^S ASCII Control Code Device Control 3 (X-OFF)

DC4

^T ASCII Control Code Device Control 4

DEL

^? ASCII Control Code Delete

DLE

^P ASCII Control Code Data Link Escape

EM

^Y ASCII Control Code End of Medium

ENQ

^E ASCII Control Code Enquiry

EOT

^D ASCII Control Code End of Transmission

ESC

^[ ASCII Control Code Escape

ETB

^W ASCII Control Code End of Transmision Block

ETX

^C ASCII Control Code End of Text

FF

^L ASCII Control Code Form feed

FS

^ ASCII Control Code File Separator

GS

^] ASCII Control Code Group Separator

HT

^I ASCII Control Code Horizontal Tab

LF

^J ASCII Control Code Line feed

NAK

^U ASCII Control Code Negative Acknowledge

NUL

^@ ASCII Control Code Null character

RS

^^ ASCII Control Code Record Separator

SI

^O ASCII Control Code Shift In

SO

^N ASCII Control Code Shift Out

SOH

^A ASCII Control Code Start of Header

SP

Code of ASCII Character SPACE

STX

^B ASCII Control Code Start of Text

SUB

^Z ASCII Control Code Substitute

SYN

^V ASCII Control Code Synchronous Idle

US

^_ ASCII Control Code Unit Separator

VT

^K ASCII Control Code Vectical Tab