Common Lisp Package: UK.CO.DEOXYBYTE-IO

The deoxybyte-io system is a selection of utility code focused on transfer of data between Lisp and its environment. It includes: - IO and parser conditions - File and directory utilities - Command line interface definition utilities - Stream classes and methods - Tabular text parsing - Binary encoding and decoding

README:

FUNCTION

Public

ABSOLUTE-PATHNAME-P (PATHNAME)

Returns T if PATHSPEC is a pathname designator for an absolute file or directory, or NIL otherwise.

DECODE-FLOAT32BE (BUFFER &OPTIONAL (INDEX 0))

Decodes 4 byte float stored as consecutive bytes in BUFFER, in big-endian byte order, starting at INDEX.

DECODE-FLOAT32LE (BUFFER &OPTIONAL (INDEX 0))

Decodes 4 byte float stored as consecutive bytes in BUFFER, in little-endian byte order, starting at INDEX.

DECODE-FLOAT64BE (BUFFER &OPTIONAL (INDEX 0))

Decodes 8 byte float stored as consecutive bytes in BUFFER, in big-endian byte order, starting at INDEX.

DECODE-FLOAT64LE (BUFFER &OPTIONAL (INDEX 0))

Decodes 8 byte float stored as consecutive bytes in BUFFER, in little-endian byte order, starting at INDEX.

DECODE-IEEE-FLOAT32 (N)

Decodes an IEEE 754 encoded single-float from 32-bit integer N. NaN, +Inf and -Inf are represented by the keywords :not-a-number :positive-infinity or :negative-infinity respectively.

DECODE-IEEE-FLOAT64 (N)

Decodes an IEEE 754 encoded double-float from 64-bit integer N. NaN, +Inf and -Inf are represented by the keywords :not-a-number :positive-infinity or :negative-infinity respectively.

DECODE-INT16BE (BUFFER &OPTIONAL (INDEX 0))

Decodes a signed 2 byte integer stored as consecutive bytes in BUFFER, in big-endian byte order, starting at INDEX.

DECODE-INT16LE (BUFFER &OPTIONAL (INDEX 0))

Decodes a signed 2 byte integer stored as consecutive bytes in BUFFER, in little-endian byte order, starting at INDEX.

DECODE-INT32BE (BUFFER &OPTIONAL (INDEX 0))

Decodes a signed 4 byte integer stored as consecutive bytes in BUFFER, in big-endian byte order, starting at INDEX.

DECODE-INT32LE (BUFFER &OPTIONAL (INDEX 0))

Decodes a signed 4 byte integer stored as consecutive bytes in BUFFER, in little-endian byte order, starting at INDEX.

DECODE-INT64BE (BUFFER &OPTIONAL (INDEX 0))

Decodes a signed 8 byte integer stored as consecutive bytes in BUFFER, in big-endian byte order, starting at INDEX.

DECODE-INT64LE (BUFFER &OPTIONAL (INDEX 0))

Decodes a signed 8 byte integer stored as consecutive bytes in BUFFER, in little-endian byte order, starting at INDEX.

DECODE-INT8BE (BUFFER &OPTIONAL (INDEX 0))

Decodes a signed 1 byte integer stored as consecutive bytes in BUFFER, in big-endian byte order, starting at INDEX.

DECODE-INT8LE (BUFFER &OPTIONAL (INDEX 0))

Decodes a signed 1 byte integer stored as consecutive bytes in BUFFER, in little-endian byte order, starting at INDEX.

DECODE-UINT16BE (BUFFER &OPTIONAL (INDEX 0))

Decodes an unsigned 2 byte integer stored as consecutive bytes in BUFFER, in big-endian byte order, starting at INDEX.

DECODE-UINT16LE (BUFFER &OPTIONAL (INDEX 0))

Decodes an unsigned 2 byte integer stored as consecutive bytes in BUFFER, in little-endian byte order, starting at INDEX.

DECODE-UINT32BE (BUFFER &OPTIONAL (INDEX 0))

Decodes an unsigned 4 byte integer stored as consecutive bytes in BUFFER, in big-endian byte order, starting at INDEX.

DECODE-UINT32LE (BUFFER &OPTIONAL (INDEX 0))

Decodes an unsigned 4 byte integer stored as consecutive bytes in BUFFER, in little-endian byte order, starting at INDEX.

DECODE-UINT64BE (BUFFER &OPTIONAL (INDEX 0))

Decodes an unsigned 8 byte integer stored as consecutive bytes in BUFFER, in big-endian byte order, starting at INDEX.

DECODE-UINT64LE (BUFFER &OPTIONAL (INDEX 0))

Decodes an unsigned 8 byte integer stored as consecutive bytes in BUFFER, in little-endian byte order, starting at INDEX.

DECODE-UINT8BE (BUFFER &OPTIONAL (INDEX 0))

Decodes an unsigned 1 byte integer stored as consecutive bytes in BUFFER, in big-endian byte order, starting at INDEX.

DECODE-UINT8LE (BUFFER &OPTIONAL (INDEX 0))

Decodes an unsigned 1 byte integer stored as consecutive bytes in BUFFER, in little-endian byte order, starting at INDEX.

DEFAULT-FLOAT-PARSER (FIELD-NAME STR &KEY (START 0) END (NULL-STR *EMPTY-FIELD*))

Returns a float parsed from simple-base-string record STR between START and END, or NIL if STR is STRING= to NULL-STR between START and END.

DEFAULT-INTEGER-PARSER (FIELD-NAME STR &KEY (START 0) END (NULL-STR *EMPTY-FIELD*))

Returns an integer parsed from simple-base-string record STR between START and END, or NIL if STR is STRING= to NULL-STR between START and END.

DELETE-TMP-DIRECTORY (CONDITION)

Invokes the DELETE-TMP-DIRECTORY restart, if established.

DELETE-TMP-PATHNAME (CONDITION)

Invokes the DELETE-TMP-PATHNAME restart, if established.

DIRECTORY-PATHNAME (PATHNAME)

Returns a new pathname that represents the directory component of PATHSPEC.

ENCODE-FLOAT32BE (VALUE BUFFER &OPTIONAL (INDEX 0))

Encodes 4 byte float as consecutive bytes in BUFFER, in big-endian byte order, starting at INDEX.

ENCODE-FLOAT32LE (VALUE BUFFER &OPTIONAL (INDEX 0))

Encodes 4 byte float as consecutive bytes in BUFFER, in little-endian byte order, starting at INDEX.

ENCODE-FLOAT64BE (VALUE BUFFER &OPTIONAL (INDEX 0))

Encodes 8 byte float as consecutive bytes in BUFFER, in big-endian byte order, starting at INDEX.

ENCODE-FLOAT64LE (VALUE BUFFER &OPTIONAL (INDEX 0))

Encodes 8 byte float as consecutive bytes in BUFFER, in little-endian byte order, starting at INDEX.

ENCODE-IEEE-FLOAT32 (F)

Encodes single-float F as a 32-bit integer using IEEE 754 encoding. NaN, +Inf and -Inf may be represented by using the keywords :not-a-number :positive-infinity or :negative-infinity respectively, as an argument.

ENCODE-IEEE-FLOAT64 (F)

Encodes double-float F as a 64-bit integer using IEEE 754 encoding. NaN, +Inf and -Inf may be represented by using the keywords :not-a-number :positive-infinity or :negative-infinity respectively, as an argument.

ENCODE-INT16BE (VALUE BUFFER &OPTIONAL (INDEX 0))

Encodes a 2 byte integer as consecutive bytes in BUFFER, in big-endian byte order, starting at INDEX.

ENCODE-INT16LE (VALUE BUFFER &OPTIONAL (INDEX 0))

Encodes a 2 byte integer as consecutive bytes in BUFFER, in little-endian byte order, starting at INDEX.

ENCODE-INT32BE (VALUE BUFFER &OPTIONAL (INDEX 0))

Encodes a 4 byte integer as consecutive bytes in BUFFER, in big-endian byte order, starting at INDEX.

ENCODE-INT32LE (VALUE BUFFER &OPTIONAL (INDEX 0))

Encodes a 4 byte integer as consecutive bytes in BUFFER, in little-endian byte order, starting at INDEX.

ENCODE-INT64BE (VALUE BUFFER &OPTIONAL (INDEX 0))

Encodes a 8 byte integer as consecutive bytes in BUFFER, in big-endian byte order, starting at INDEX.

ENCODE-INT64LE (VALUE BUFFER &OPTIONAL (INDEX 0))

Encodes a 8 byte integer as consecutive bytes in BUFFER, in little-endian byte order, starting at INDEX.

ENCODE-INT8BE (VALUE BUFFER &OPTIONAL (INDEX 0))

Encodes a 1 byte integer as consecutive bytes in BUFFER, in big-endian byte order, starting at INDEX.

ENCODE-INT8LE (VALUE BUFFER &OPTIONAL (INDEX 0))

Encodes a 1 byte integer as consecutive bytes in BUFFER, in little-endian byte order, starting at INDEX.

ENCODE-UINT16BE (VALUE BUFFER &OPTIONAL (INDEX 0))

Encodes a 2 byte integer as consecutive bytes in BUFFER, in big-endian byte order, starting at INDEX.

ENCODE-UINT16LE (VALUE BUFFER &OPTIONAL (INDEX 0))

Encodes a 2 byte integer as consecutive bytes in BUFFER, in little-endian byte order, starting at INDEX.

ENCODE-UINT32BE (VALUE BUFFER &OPTIONAL (INDEX 0))

Encodes a 4 byte integer as consecutive bytes in BUFFER, in big-endian byte order, starting at INDEX.

ENCODE-UINT32LE (VALUE BUFFER &OPTIONAL (INDEX 0))

Encodes a 4 byte integer as consecutive bytes in BUFFER, in little-endian byte order, starting at INDEX.

ENCODE-UINT64BE (VALUE BUFFER &OPTIONAL (INDEX 0))

Encodes a 8 byte integer as consecutive bytes in BUFFER, in big-endian byte order, starting at INDEX.

ENCODE-UINT64LE (VALUE BUFFER &OPTIONAL (INDEX 0))

Encodes a 8 byte integer as consecutive bytes in BUFFER, in little-endian byte order, starting at INDEX.

ENCODE-UINT8BE (VALUE BUFFER &OPTIONAL (INDEX 0))

Encodes a 1 byte integer as consecutive bytes in BUFFER, in big-endian byte order, starting at INDEX.

ENCODE-UINT8LE (VALUE BUFFER &OPTIONAL (INDEX 0))

Encodes a 1 byte integer as consecutive bytes in BUFFER, in little-endian byte order, starting at INDEX.

ENSURE-FILE-EXISTS (FILESPEC)

Creates the file designated by FILESPEC, if it does not exist. Returns the pathname of FILESPEC.

ENVIRONMENT-VARIABLE (VARIABLE-NAME)

Returns the string value of VARIABLE-NAME, or NIL.

SETFENVIRONMENT-VARIABLE (VALUE VARIABLE-NAME)

Sets the value of VARIABLE-NAME to VALUE, which maye be a string or a symbol.

FILE-PATHNAME (PATHNAME)

Returns a new pathname that represents the file component of PATHSPEC.

LEAF-DIRECTORY-PATHNAME (PATHNAME)

Returns a new relative pathname that represents the leaf directory component of PATHSPEC.

LEAVE-TMP-DIRECTORY (CONDITION)

Invokes the LEAVE-TMP-DIRECTORY restart, if established.

LEAVE-TMP-PATHNAME (CONDITION)

Invokes the LEAVE-TMP-PATHNAME restart, if established.

MAKE-TMP-DIRECTORY (&KEY (TMPDIR *DEFAULT-TMPDIR*) (BASENAME ) (IF-EXISTS ERROR) MODE)

Creates a new temporary directory and returns its pathname. The new directory's pathname is created using {defun tmp-pathname} . The IF-EXISTS keyword argument determines what happens if a directory by that name already exists; options are :error which causes a FILE-ERROR to be raised, :supersede which causes the existing directory to be deleted and a new, empty one created and NIL where no directory is created an NIL is returned to indicate failure.

OPTION-VALUE (KEY PARSED-ARGS &OPTIONAL (DEFAULT NIL DEFAULT-SUPPLIED-P))

Returns the value from alist PARSED-ARGS for the option named by the symbol KEY.

PARSE-FLOAT (STRING &KEY (START 0) END (RADIX 10) JUNK-ALLOWED)

Converts a substring of STRING, as delimited by START and END, to a floating point number, if possible. START and END default to the beginning and end of the string. RADIX must be between 2 and 36. A floating point number will be returned if the string consists of an optional string of spaces and an optional sign, followed by a string of digits optionally containing a decimal point, and an optional e or E followed by an optionally signed integer. The use of e/E to indicate an exponent only works for RADIX = 10. Returns the floating point number, if any, and the index for the first character after the number.

PATHNAME-EXTENDER (PATHNAME &KEY TYPE SEPARATOR GENERATOR)

Returns a function of zero arity that returns modified copies of a pathname argument. The pathname is modified by extending its namestring. The new namestring is composed of the original namestring SEPARATOR (defaults to NIL) and a value taken from calling the function GENERATOR (defaults to a numeric generator starting from 0, incrementing by 1). TYPE may be used to specify the type of the new pathname, otherwise the original type will be used.

PATHNAME-GENERATOR (DIRECTORY NAME &KEY TYPE SEPARATOR GENERATOR)

Returns a function of zero arity that generates pathnames when called. The generated pathnames are relative to DIRECTORY and have a namestring composed of NAME, SEPARATOR (defaults to NIL) and a value taken from calling the function GENERATOR (defaults to a numeric generator starting from 0, incrementing by 1). TYPE may be used to specify the type of the new pathnames.

PATHSTRING (PATHNAME)

Returns a string representing PATHNAME. This function is similar to CL:NAMESTRING, but is designed to be portable whereas the return value of CL:NAMESTRING is implementation-dependent.

RELATIVE-PATHNAME-P (PATHNAME)

Returns T if PATHSPEC is a pathname designator for a relative file or directory, or NIL otherwise.

TMP-PATHNAME (&KEY (TMPDIR *DEFAULT-TMPDIR*) (BASENAME ) TYPE)

Returns a pathname suitable for use as a temporary file or directory. The directory component of the new pathname is TMPDIR, defaulting to *DEFAULT-TMPDIR*. The NAME component of the new pathname is a concatenation of BASENAME, defaulting to an empty string, and a pseudo-random number. The type component of the new pathname is TYPE, defaulting to NIL.

Undocumented

QUIT-LISP (&KEY (STATUS 0))

STREAMP (STREAM)

Private

COLLECT-CONSTRAINT-ARGS (FORM)

Returns an argument list form to be used by CROSS-VALIDATE by quoting the field-names in FORM and re-ordering the elements.

COLLECT-PARSER-ARGS (FIELD)

Returns an argument list form for FIELD to be used by PARSE-FIELD which has suitable parsers and validators set up for the standard field types: :string , :integer and :float .

DEFAULT-STRING-PARSER (FIELD-NAME STR &KEY (START 0) END (NULL-STR *EMPTY-FIELD*))

Returns a string subsequence from simple-string record STR between START and END, or NIL if STR is STRING= to NULL-STR between START and END.

DEFAULT-VALIDATOR (VALUE)

The default validator always returns T.

MERGE-ELEMENT (MERGE-STREAMS PREDICATE KEY)

Returns the next element from one of MERGE-STREAMS. The returned element is the on that sorts first according to PREDICATE and KEY, as required by the merge-sort algorithm.

MERGE-PATHSTRINGS (PATHNAME &OPTIONAL (DEFAULT-PATHNAME *DEFAULT-PATHNAME-DEFAULTS*) (DEFAULT-VERSION NEWEST))

Merges PATHNAME with defaults, using CL:MERGE-PATHNAMES, and calls {defun pathstring} on the result.

PARSE-CHARACTER (STRING)

Returns a character parsed from STRING of length 1 character.

PARSE-CHARACTER-LIST (STRING)

Returns a list of integers parsed from STRING after splitting on the *list-separator-char* character.

PARSE-FIELD (FIELD-NAME LINE START END NULL-STR PARSER &OPTIONAL (VALIDATOR #'DEFAULT-VALIDATOR))

Returns a value parsed from LINE between START and END using PARSER and VALIDATOR.

PARSE-FLOAT-LIST (STRING)

Returns a list of floats parsed from STRING after splitting on the *list-separator-char* character.

PARSE-INTEGER-LIST (STRING)

Returns a list of integers parsed from STRING after splitting on the *list-separator-char* character.

PARSE-STRING-LIST (STRING)

Returns a list of strings parsed from STRING by splitting on the *list-separator-char* character.

READ-OCTET-LINE (STREAM)

Reads chunks of bytes up to the next newline or end of stream, returning them in a list. The newline is not included. Returns two values - a list of chunks and either NIL or T to indicate whether a terminating newline was missing. When the stream underlying the buffer is exhausted the list of chunks will be empty.

SIGNAL-MALFORMED-FIELD (FIELD STR START END REASON)

Signals a MALFORMED-FIELD-ERROR for FIELD in STR between START and END for REASON.

SUBST-CHARS (STR CHAR &REST CHARS)

Returns a copy of STR where any occurrence of CHARS are substituted by CHAR.

VALIDATE-RECORD (NAME FIELDS VALIDATOR &REST FIELD-NAMES)

Returns a pair of constraint NAME and either T or NIL, indicating the result of applying VALIDATOR to values from the alist of parsed FIELDS named by FIELD-NAMES.

WRAP-STRING (STR &OPTIONAL STREAM)

Format STR, wrapped at 70 characters, to STREAM.

Undocumented

%STREAM-READ-SEQUENCE (STREAM SEQUENCE START END)

%STREAM-WRITE-SEQUENCE (STREAM SEQUENCE START END)

GET-SYSTEM-ARGV

KEY-STRING (OPTION)

NORMALISE-WHITESPACE (STR)

VALUE-TYPE-STRING (OPTION)

WHITESPACEP (CHAR)

MACRO

Public

CHECK-FIELD (TEST-FORM RECORD FIELD &OPTIONAL ERROR-MESSAGE &REST MESSAGE-ARGUMENTS)

Checks FIELD of RECORD. If TEST-FORM returns false a {define-condition malformed-field-error} is raised. The default error message may be refined with an additional ERROR-MESSAGE. Arguments: - test-form (form): A form to be evaluated. If the form returns NIL, an error is raised. - record (form): A form that evaluates to a record. - field (form): A form that evaluates to a field in RECORD. Optional: - error-message (string): An error message string. Rest: - message-arguments (forms): Forms that evaluate to arguments for the error message.

CHECK-RECORD (TEST-FORM RECORD &OPTIONAL ERROR-MESSAGE &REST MESSAGE-ARGUMENTS)

Checks RECORD. If TEST-FORM returns false a {define-condition malformed-record-error} is raised. The default error message may be refined with an additional ERROR-MESSAGE. Arguments: - test-form (form): A form to be evaluated. If the form returns NIL, an error is raised. - record (form): A form that evaluates to a record. Optional: - error-message (string): An error message string. Rest: - message-arguments (forms): Forms that evaluate to arguments for the error message.

DEFINE-CLI (NAME DIRECT-SUPERCLASSES OPTION-SPECS &REST OPTIONS)

Defines a new CLI class NAME. Arguments: - name (symbol): The class name. - direct-superclasses (list symbols): The direct superclasses. - option-specs (list option-specs): The CLI option specifiers. Each option-spec specifies a slot and its corresponding CLI option instance. Arguments: - slot-name (symbol) - option-name (string) Rest: - cl-option instance initargs Key: - documentation (string): Slot (and hence cli-option) documentation. e.g. ;;; (a "a" :required-option t :value-type 'string ;;; :documentation "Required option A.") Rest: - class-options as in defclass. e.g. ;;; (define-cli example-cli (cli) ;;; ((a "a" :required-option t :value-type 'string ;;; :documentation "Required option A.") ;;; (b "b" :required-option nil :value-type 'integer :value-default 99 ;;; :documentation "Required option D.")) ;;; (:documentation "An example CLI class definition."))

DEFINE-INTEGER-DECODER (NAME &KEY (BYTES 1) (ORDER LITTLE-ENDIAN) SIGNED)

Defines a function NAME with one mandatory argument, a simple-array of unsigned-byte 8, and one optional argument, a fixnum index in that array that defaults to 0. The function returns the Lisp integer whose value is given by the bytes at that index in the byte array. Key: - bytes (fixnum): the number of bytes that comprise the number. - order (sumbol): the byte order of the array, may be one of :little-endian or :big-endian ( :network-byte-order may be used as a synonym for :big-endian ). - signed (boolean): T if the bytes are a two's complement representation of a signed integer.

DEFINE-INTEGER-ENCODER (NAME &KEY (BYTES 1) (ORDER LITTLE-ENDIAN) SIGNED)

Defines a function NAME with two mandatory arguments, an integer and a simple-array of unsigned-byte 8, and one optional argument, a fixnum index in that array that defaults to 0. The function returns the buffer containing the encoded integer. Key: - bytes (fixnum): the number of bytes that comprise the number. - order (sumbol): the byte order of the array, may be one of :little-endian or :big-endian ( :network-byte-order may be used as a synonym for :big-endian ).

DEFINE-LINE-PARSER (PARSER-NAME DELIMITER FIELDS &OPTIONAL CONSTRAINTS)

Defines a line parser function that splits lines and then parses and validates fields according to the FIELDS contraints and validates combinations of fields according to CONSTRAINTS. Arguments: - parser-name (symbol): a symbol naming the new function. - delimiter (character): a character used to split the lines being parsed. - fields (list list): a list of field definition lists. The form of a definition list is ;;; (symbolic-field-name &keys type ignore parser validator null-str) which indicates the symbol to which the parsed field value will be stored in the alist returned by the function - parser-name (symbol): the expected type of the field value ( :string, :integer or :float, defaulting to :string), an optional boolean flag indicating that the field should be ignored, an optional parser function (defaults to a pass-through string parser), an optional validator function that returns T when the parsed field is valid and an optional string to indicate an null field (defaults to {defparameter *empty-field*} ). Optional: - constraints (list list): a list of field constraint definition lists. The form of a constraint definition list is ;;; (symbolic-constraint-name (symbolic-field-name list) validator) The symbolic-field-name list should contain names of one or more fields and the validator must then be a function which accepts the parsed values of those fields in the same order and returns T when those fields have acceptable values.

WITH-ARGV ((ARGV) &BODY BODY)

Executes BODY with ARGV bound to system argv list.

WITH-TMP-DIRECTORY ((DIRECTORY &REST REST) &BODY BODY)

Executes BODY with DIRECTORY bound to a temporary directory that has been created with the MAKE-TMP-DIRECTORY function. If BODY executes without error, the temporary directory is deleted. If an error occurs, restarts DELETE-TMP-DIRECTORY and LEAVE-TMP-DIRECTORY are provided to control what happens.

WITH-TMP-PATHNAME ((PATHNAME &REST REST) &BODY BODY)

Executes BODY with DIRECTORY bound to a pathname of a temporary file that has been created with the MAKE-TMP-PATHNAME function. If BODY executes without error, any file denoted by the temporary pathname is deleted. If an error occurs, restarts DELETE-TMP-PATHNAME and LEAVE-TMP-PATHNAME are provided to control what happens.

Private

DEFINE-FLOAT-DECODER (NAME &KEY (BYTES 4) (ORDER LITTLE-ENDIAN))

Defines a function NAME with one mandatory argument, a simple-array of unsigned-byte 8, and one optional argument, a fixnum index in that array that defaults to 0. The function returns the Lisp float whose value is given by the bytes at that index in the byte array. Key: - bytes (fixnum): the number of bytes that comprise the number. - order (sumbol): the byte order of the array, may be one of :little-endian or :big-endian ( :network-byte-order may be used as a synonym for :big-endian ).

DEFINE-FLOAT-ENCODER (NAME &KEY (BYTES 4) (ORDER LITTLE-ENDIAN))

Defines a function NAME with two mandatory arguments, a float and a simple-array of unsigned-byte 8, and one optional argument, a fixnum index in that array that defaults to 0. The function returns the buffer containing the encoded float. Key: - bytes (fixnum): the number of bytes that comprise the number. - order (sumbol): the byte order of the array, may be one of :little-endian or :big-endian ( :network-byte-order may be used as a synonym for :big-endian ).

GENERIC-FUNCTION

Public

BOOLEAN-OPTION-P (OPTION)

Returns T if OPTION does not require a value, or NIL otherwise.

CLI-HELP (CLI &OPTIONAL STREAM)

Prints the help string for CLI to STREAM (which defaults to *ERROR-OUTPUT*). This is usually the class documentation string of CLI, plus all of the option help.

DOCUMENTATION-OF (CLI &OPTIONAL NAME)

Returns documentation of CLI or a CLI option identified by NAME.

EXTERNAL-MERGE-SORT (SORT-INPUT-STREAM SORT-OUTPUT-STREAM PREDICATE &KEY KEY BUFFER-SIZE (BUFFER-SIZE 100000))

Performs an external merge sort on the elements read from SORT-INPUT-STREAM and writes the sorted elements to SORT-OUTPUT-STREAM. Arguments: - sort-input-stream (sort-input-stream): The stream whose elements are to be sorted. - sort-output-stream (sort-output-stream): A stream whose elements are sorted. - predicate (function designator): The sorting predicate, as in CL:SORT, a function of two arguments that returns a generalized boolean. Key: - key (function designator): A function of one argument, or nil. - buffer-size (fixnum): The size of the in-memory sort buffer and hence the number of elements written to disk in the external merge file. Returns: - The total number of elements sorted (fixnum). - The number of {defclass merge-stream} s used in sorting (fixnum).

FIND-LINE (LINE-INPUT-STREAM TEST &OPTIONAL MAX-LINES)

Iterates through lines read from LINE-INPUT-STREAM until a line matching predicate TEST is found or until a number of lines equal to MAX-LINES have been examined.

HELP-MESSAGE (CLI MESSAGE &OPTIONAL STREAM)

Prints a help MESSAGE and help for each avaliable option in CLI to STREAM.

INPUT-STREAM-P (STREAM)

Can STREAM perform input operations?

MAKE-LINE-STREAM (STREAM)

Returns a new {defclass line-stream} created from STREAM.

MAKE-MERGE-STREAM (SORT-INPUT-STREAM PREDICATE &KEY KEY BUFFER-SIZE (BUFFER-SIZE 100000))

Returns a new {defclass merge-stream} appropriate to SORT-INPUT-STREAM. The new stream must return sorted elements read from SORT-INPUT-STREAM. Arguments: - sort-input-stream (sort-input-stream): The stream whose elements are to be sorted. - predicate (function designator): The sorting predicate, as in CL:SORT, a function of two arguments that returns a generalized boolean. Key: - key (function designator): A function of one argument, or nil. - buffer-size (fixnum): The size of the in-memory sort buffer and hence the number of elements written to disk in the external merge file. Returns: - a {defclass merge-stream} from which sorted elements may be read.

MORE-LINES-P (LINE-INPUT-STREAM)

Returns T if {defclass line-input-stream} contains unread data.

OPEN-STREAM-P (STREAM)

Return true if STREAM is not closed. A default method is provided by class FUNDAMENTAL-STREAM which returns true if CLOSE has not been called on the stream.

OPTION-HELP (CLI NAME &OPTIONAL STREAM)

Prints the help string for option NAME to STREAM (which defaults to *ERROR-OUTPUT*).

OPTION-OF (CLI NAME)

Returns the CLI option identified by NAME.

OPTION-SLOT-P (CLI SLOT)

Returns T if SLOT is an option slot in CLI, or NIL otherwise. The default implementation returns T, meaning that all slots are expected to contain option objects. Overriding this method means that slots may be added for other purposes.

OPTION-SLOTS-OF (CLI)

Returns a new, sorted list of CLI option slots.

OPTIONS-OF (CLI)

Returns a new, sorted list of CLI options.

OUTPUT-STREAM-P (STREAM)

Can STREAM perform output operations?

PARSE-COMMAND-LINE (CLI ARGLIST)

Parses a system command line to create a mapping of option keywords to Lisp objects. Where multiple values are to be accepted for an argument e.g. 'integer-list , they must be comma-separated on the command line e.g. 1,2,3,4. Arguments: - cli (object): A CLI instance. - arglist (list string): A list of CLI string arguments. Returns: - alist mapping slots to parsed values - list of unmatched argument strings - list of unknown argument strings e.g ;;; (define-cli example-cli (cli) ;;; ((a "a" :required-option t :value-type 'string ;;; :documentation "Required option A.") ;;; (b "b" :required-option t :value-type 'integer ;;; :documentation "Required option D.") ;;; (c "c" :required-option nil :value-type 'string :default "foo" ;;; :documentation "Option C.")) ;;; (:documentation "An example CLI class definition.")) ;;; (parse-command-line (make-instance 'example-cli) ;;; (list "--a" "aaa" "--b" "1")))

POP-LINE (LINE-INPUT-STREAM LINE)

Pops one line from {defclass line-input-stream} .

PUSH-LINE (LINE-INPUT-STREAM LINE)

Pushes LINE back onto {defclass line-input-stream} .

REQUIRED-VALUE-P (OPTION)

Returns T if OPTION requires a value, or NIL otherwise.

STREAM-ADVANCE-TO-COLUMN (STREAM COLUMN)

Write enough blank space so that the next character will be written at the specified column. Returns true if the operation is successful, or NIL if it is not supported for this stream. This is intended for use by by PPRINT and FORMAT ~T. The default method uses STREAM-LINE-COLUMN and repeated calls to STREAM-WRITE-CHAR with a #SPACE character; it returns NIL if STREAM-LINE-COLUMN returns NIL.

STREAM-CLEAR-INPUT (STREAM)

This is like CL:CLEAR-INPUT, but for Gray streams, returning NIL. The default method does nothing.

STREAM-CLEAR-OUTPUT (STREAM)

This is like CL:CLEAR-OUTPUT, but for Gray streams: clear the given output STREAM. The default method does nothing.

STREAM-CLOSE (STREAM &KEY ABORT)

Closes STREAM, returning T if STREAM was open. If ABORT is T, attempts to clean up any side effects of having created stream.

STREAM-ELEMENT-TYPE (STREAM)

Return a type specifier for the kind of object returned by the STREAM. The class FUNDAMENTAL-CHARACTER-STREAM provides a default method which returns CHARACTER.

STREAM-FILE-POSITION (STREAM &OPTIONAL POSITION-SPEC)

Used by FILE-POSITION. Returns or changes the current position within STREAM.

STREAM-FINISH-OUTPUT (STREAM)

Attempts to ensure that all output sent to the Stream has reached its destination, and only then returns false. Implements FINISH-OUTPUT. The default method does nothing.

STREAM-FORCE-OUTPUT (STREAM)

Attempts to force any buffered output to be sent. Implements FORCE-OUTPUT. The default method does nothing.

STREAM-FRESH-LINE (STREAM)

Outputs a new line to the Stream if it is not positioned at the begining of a line. Returns T if it output a new line, nil otherwise. Used by FRESH-LINE. The default method uses STREAM-START-LINE-P and STREAM-TERPRI.

STREAM-LINE-COLUMN (STREAM)

Return the column number where the next character will be written, or NIL if that is not meaningful for this stream. The first column on a line is numbered 0. This function is used in the implementation of PPRINT and the FORMAT ~T directive. For every character output stream class that is defined, a method must be defined for this function, although it is permissible for it to always return NIL.

STREAM-LISTEN (STREAM)

This is used by LISTEN. It returns true or false. The default method uses STREAM-READ-CHAR-NO-HANG and STREAM-UNREAD-CHAR. Most streams should define their own method since it will usually be trivial and will always be more efficient than the default method.

STREAM-MERGE (MERGE-STREAM)

Returns the next element from MERGE-STREAM as part of the a merging operation between several {defclass merge-stream } s.

STREAM-OPEN (FILESPEC CLASS &REST INITARGS)

Returns a Gray stream of CLASS

STREAM-PEEK-CHAR (STREAM)

This is used to implement PEEK-CHAR; this corresponds to PEEK-TYPE of NIL. It returns either a character or :EOF. The default method calls STREAM-READ-CHAR and STREAM-UNREAD-CHAR.

STREAM-READ-BYTE (STREAM)

Used by READ-BYTE; returns either an integer, or the symbol :EOF if the stream is at end-of-file.

STREAM-READ-CHAR (STREAM)

Read one character from the stream. Return either a character object, or the symbol :EOF if the stream is at end-of-file. Every subclass of FUNDAMENTAL-CHARACTER-INPUT-STREAM must define a method for this function.

STREAM-READ-CHAR-NO-HANG (STREAM)

This is used to implement READ-CHAR-NO-HANG. It returns either a character, or NIL if no input is currently available, or :EOF if end-of-file is reached. The default method provided by FUNDAMENTAL-CHARACTER-INPUT-STREAM simply calls STREAM-READ-CHAR; this is sufficient for file streams, but interactive streams should define their own method.

STREAM-READ-ELEMENT (SORT-INPUT-STREAM)

Returns the next element from SORT-INPUT-STREAM.

STREAM-READ-LINE (STREAM)

This is used by READ-LINE. A string is returned as the first value. The second value is true if the string was terminated by end-of-file instead of the end of a line. The default method uses repeated calls to STREAM-READ-CHAR.

STREAM-READ-SEQUENCE (STREAM SEQ &OPTIONAL START END)

This is like CL:READ-SEQUENCE, but for Gray streams.

STREAM-START-LINE-P (STREAM)

Is STREAM known to be positioned at the beginning of a line? It is permissible for an implementation to always return NIL. This is used in the implementation of FRESH-LINE. Note that while a value of 0 from STREAM-LINE-COLUMN also indicates the beginning of a line, there are cases where STREAM-START-LINE-P can be meaningfully implemented although STREAM-LINE-COLUMN can't be. For example, for a window using variable-width characters, the column number isn't very meaningful, but the beginning of the line does have a clear meaning. The default method for STREAM-START-LINE-P on class FUNDAMENTAL-CHARACTER-OUTPUT-STREAM uses STREAM-LINE-COLUMN, so if that is defined to return NIL, then a method should be provided for either STREAM-START-LINE-P or STREAM-FRESH-LINE.

STREAM-TERPRI (STREAM)

Writes an end of line, as for TERPRI. Returns NIL. The default method does (STREAM-WRITE-CHAR stream #NEWLINE).

STREAM-UNREAD-CHAR (STREAM CHARACTER)

Un-do the last call to STREAM-READ-CHAR, as in UNREAD-CHAR. Return NIL. Every subclass of FUNDAMENTAL-CHARACTER-INPUT-STREAM must define a method for this function.

STREAM-WRITE-BYTE (STREAM INTEGER)

Implements WRITE-BYTE; writes the integer to the stream and returns the integer as the result.

STREAM-WRITE-CHAR (STREAM CHARACTER)

Write CHARACTER to STREAM and return CHARACTER. Every subclass of FUNDAMENTAL-CHARACTER-OUTPUT-STREAM must have a method defined for this function.

STREAM-WRITE-ELEMENT (ELEMENT SORT-OUTPUT-STREAM)

Writes ELEMENT to SORT-OUTPUT-STREAM.

STREAM-WRITE-SEQUENCE (STREAM SEQ &OPTIONAL START END)

This is like CL:WRITE-SEQUENCE, but for Gray streams.

STREAM-WRITE-STRING (STREAM STRING &OPTIONAL START END)

This is used by WRITE-STRING. It writes the string to the stream, optionally delimited by start and end, which default to 0 and NIL. The string argument is returned. The default method provided by FUNDAMENTAL-CHARACTER-OUTPUT-STREAM uses repeated calls to STREAM-WRITE-CHAR.

Undocumented

FIELD-OF (CONDITION)

RECORD-OF (CONDITION)

Private

FIND-OPTION-SLOT (CLI NAME)

Returns the slot named NAME from CLI.

PARSE-SAFELY (CLI OPTION VALUE)

Returns a parsed VALUE of the correct Lisp type for OPTION or raises an {define-condition incompatible-argument} error.

STREAM-DELETE-FILE (STREAM)

Equivalent to CL:DELETE-FILE.

Undocumented

CLI-OF (CONDITION)

COMMAND-OF (CONDITION)

FILE-OF (CONDITION)

STREAM-WRITE-LINE (STRING STREAM &OPTIONAL START END)

TYPE-OF (CONDITION)

VALUE-OF (CONDITION)

SLOT-ACCESSOR

Public

LINE-STACK-OF (OBJECT)

A list of lines that have been pushed back into the stream to be read again.

SETFLINE-STACK-OF (NEW-VALUE OBJECT)

A list of lines that have been pushed back into the stream to be read again.

NAME-OF (CONDITION)

The name string of the option.

REQUIRED-OPTION-P (OBJECT)

T if option is required on the command line, or NIL otherwise.

STREAM-HEAD-OF (OBJECT)

Returns the next element from MERGE-STREAM without removing it. Part of the external merge sort protocol.

SETFSTREAM-HEAD-OF (NEW-VALUE OBJECT)

Returns the next element from MERGE-STREAM without removing it. Part of the external merge sort protocol.

STREAM-OF (OBJECT)

The underlying stream from which data are read.

TEST-OF (OBJECT)

A function designator for a test that returns T when the next datum read from the stream is to be ignored.

VALUE-DEFAULT-OF (OBJECT)

A default value of the required value-type.

VALUE-PARSER-OF (OBJECT)

A value parser function for option that is capable of parsing a string to the correct type.

VALUE-TYPE-OF (OBJECT)

The type of the value of the option. A type of T indicates a boolean option. Valid types are the symbols string, integer, character, float, string-list, integer-list, character-list, float-list and T (indicating boolean, i.e. no value).

VARIABLE

Public

*DEFAULT-TMPDIR*

The default temporary file directory pathname.

*DEFAULT-TMPFILE-DEFAULTS*

The defaults used to fill in temporary file pathnames.

*EMPTY-FIELD*

The default empty field string.

Private

*LIST-SEPARATOR-CHAR*

The separator character used in multi-value arguments.

Undocumented

*WHITESPACE-CHARS*

CLASS

Public

CLI

The base class of all command line interfaces. Command line options are added as slots, the slot documentation acting as the coomand line option documentation.

CLI-OPTION

The base class of all command line options.

FUNDAMENTAL-BINARY-INPUT-STREAM

a superclass of all Gray input streams whose element-type is a subtype of unsigned-byte or signed-byte

FUNDAMENTAL-BINARY-OUTPUT-STREAM

a superclass of all Gray output streams whose element-type is a subtype of unsigned-byte or signed-byte

FUNDAMENTAL-BINARY-STREAM

a superclass of all Gray streams whose element-type is a subtype of unsigned-byte or signed-byte

FUNDAMENTAL-CHARACTER-INPUT-STREAM

a superclass of all Gray input streams whose element-type is a subtype of character

FUNDAMENTAL-CHARACTER-OUTPUT-STREAM

a superclass of all Gray output streams whose element-type is a subtype of character

FUNDAMENTAL-CHARACTER-STREAM

a superclass of all Gray streams whose element-type is a subtype of character

FUNDAMENTAL-INPUT-STREAM

a superclass of all Gray input streams

FUNDAMENTAL-OUTPUT-STREAM

a superclass of all Gray output streams

FUNDAMENTAL-STREAM

the base class for all Gray streams

LINE-INPUT-STREAM

A line-based stream that allows lines to be pushed back into a stack to be re-read.

LINE-STREAM

A line-based stream. Useful for building readers and writers for ad-hoc text data sources.

MERGE-STREAM

An IO stream for merging sorted data.

OCTET-LINE-INPUT-STREAM

A {defclass line-input-stream} whose lines are arrays of bytes. Allows buffered reading of lines of (unsigned-byte 8) from a stream.

SORT-INPUT-STREAM

An input stream for reading and sorting the stream contents.

SORT-OUTPUT-STREAM

An output stream for sorting and writing the stream contents.

STREAM-FILTER-MIXIN

A mixin that provides a filtering function for streams. Any data encountered while reading or writing for which the test returns T are ignored and skipped.

WRAPPED-STREAM-MIXIN

A Gray-stream wrapping a standard Lisp stream.

Undocumented

CHARACTER-LINE-INPUT-STREAM

IO-STREAM-MIXIN

LINE-MERGE-STREAM

LINE-OUTPUT-STREAM

LINE-SORT-INPUT-STREAM

LINE-SORT-OUTPUT-STREAM

Private

Undocumented

CHARACTER-LINE-OUTPUT-STREAM

OCTET-LINE-OUTPUT-STREAM

CONDITION

Public

CLI-ERROR

The parent type of all CLI error conditions.

CLI-OPTION-ERROR

The parent type of all CLI option error conditions.

CLI-OPTION-WARNING

The parent type of all CLI option warning conditions.

CLI-WARNING

The parent type of all CLI warning conditions.

FIELD-VALIDATION-ERROR

An error that is raised when a record field fails validation.

GENERAL-PARSE-ERROR

The parent type of all parse error conditions.

INCOMPATIBLE-VALUE

An error that is raised when an option is supplied with an invalid value.

IO-ERROR

The parent type of all IO error conditions.

IO-WARNING

The parent type of all IO warning conditions.

MALFORMED-FIELD-ERROR

An error that is raised when a field-based record contains a malformed field within it.

MALFORMED-FILE-ERROR

An error that is raised when a file is malformed for any reason.

MALFORMED-RECORD-ERROR

An error that is raised when a record is malformed for any reason.

MISSING-REQUIRED-OPTION

An error that is raised when a required option is missing.

MISSING-REQUIRED-VALUE

An error that is raised when a required value for an option is missing.

RECORD-VALIDATION-ERROR

An error that is raised when a record fails validation of one or more of its parts.

UNKNOWN-COMMAND

An error that is raised when the main command is not recognised.

Undocumented

UNKNOWN-OPTION

UNMATCHED-OPTION

CONSTANT

Private

+EXPONENT-BIAS-32+

Exponent bias for float32

+EXPONENT-BIAS-64+

Exponent bias for float64

+FRAC-FACTOR-32+

Mantissa fraction float32 multiplication factor

+FRAC-FACTOR-64+

Mantissa fraction float64 multiplication factor

+MIN-NORM-EXPONENT-32+

Smallest normalized float32 exponent

+MIN-NORM-EXPONENT-64+

Smallest normalized float64 exponent

+OCTET-BUFFER-SIZE+

Buffer size for {defclass octet-line-input-stream} internal buffer.

Undocumented

+NEGATIVE-INFINITY-32+

+NEGATIVE-INFINITY-64+

+NOT-A-NUMBER-32+

+NOT-A-NUMBER-64+

+POSITIVE-INFINITY-32+

+POSITIVE-INFINITY-64+