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

This package exports file utility functions. BINARY-FILE-CONTENTS, SEXP-FILE-CONTENTS, TEXT-FILE-CONTENTS, and STRING-LIST-TEXT-FILE-CONTENTS are accessors. They can be used with setf to store data into the file. Examples: (setf (sexp-file-contents list-file) (cons 'hi (sexp-file-contents file :if-does-not-exist '()))) (incf (sexp-file-contents version-file :if-does-not-exist 0)) See also: COM.INFORMATIMAGO.COMMON-LISP.CESARUM.STREAM License: AGPL3 Copyright Pascal J. Bourguignon 2005 - 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

BINARY-FILE-CONTENTS (PATH &KEY (IF-DOES-NOT-EXIST ERROR) (ELEMENT-TYPE '(UNSIGNED-BYTE 8)) (EXTERNAL-FORMAT DEFAULT))

RETURN: The contents of the file at PATH as a VECTOR of (UNSIGNED-BYTE 8), or what is specified by IF-DOES-NOT-EXIST if it doesn't exist.

SETFBINARY-FILE-CONTENTS (NEW-CONTENTS PATH &KEY (IF-DOES-NOT-EXIST CREATE) (IF-EXISTS SUPERSEDE) (ELEMENT-TYPE '(UNSIGNED-BYTE 8)) (EXTERNAL-FORMAT DEFAULT))

RETURN: The NEW-CONTENTS, or if-exists or if-does-not-exist in case of error. DO: Store the NEW-CONTENTS into the file at PATH. By default, that file is created or superseded; this can be changed with the keyword IF-DOES-NOT-EXIST or IF-EXISTS. NEW-CONTENT: A sequence of ELEMENT-TYPE.

COPY-FILE (SRC DST &KEY (IF-EXISTS ERROR) (EXTERNAL-FORMAT DEFAULT) (ELEMENT-TYPE 'CHARACTER))

DO: Copy the contents of the file at path SRC to the file at path DST.

REMOVE-FIRST-LINES (FILE-NAME LINE-COUNT &KEY (ELEMENT-TYPE 'CHARACTER))

DO: Modifies the file at path FILE-NAME, removing the LINE-COUNT first lines. WARNING: There's no backup: if the COPY-OVER fails, the file will be left in an unspecified state.

SAFE-TEXT-FILE-TO-STRING-LIST (PATH &KEY (IF-DOES-NOT-EXIST ERROR))

DO: - Read the file at PATH as a binary file, - Remove all null bytes (handle UTF-16, UCS-2, etc), - Split 'lines' on CR, CR+LF or LF, - Replace all bytes less than 32 or greater than 126 by #?, - Convert the remaining bytes as ASCII codes into the CL standard set. RETURN: The contents of the file as a list of base-string lines.

SEXP-FILE-CONTENTS (PATH &KEY (IF-DOES-NOT-EXIST ERROR) (EXTERNAL-FORMAT DEFAULT))

RETURN: The first SEXP of the file at PATH, or what is specified by IF-DOES-NOT-EXIST if it doesn't exist.

SETFSEXP-FILE-CONTENTS (NEW-CONTENTS PATH &KEY (IF-DOES-NOT-EXIST CREATE) (IF-EXISTS SUPERSEDE) (EXTERNAL-FORMAT DEFAULT))

DO: Writes the NEW-CONTENTS SEXP readably into the file at PATH. By default, that file is created or superseded; this can be changed with the keyword IF-DOES-NOT-EXIST or IF-EXISTS. RETURN: The NEW-CONTENTS, or if-exists or if-does-not-exist in case of error.

STRING-LIST-TEXT-FILE-CONTENTS (PATH &KEY (IF-DOES-NOT-EXIST ERROR) (EXTERNAL-FORMAT DEFAULT))

RETURN: the list of lines collected from the file.

SETFSTRING-LIST-TEXT-FILE-CONTENTS (NEW-CONTENTS PATH &KEY (IF-DOES-NOT-EXIST CREATE) (IF-EXISTS SUPERSEDE) (EXTERNAL-FORMAT DEFAULT))

DO: Store the NEW-CONTENTS, into the file at PATH, each string on a line. By default, that file is created or superseded; this can be changed with the keyword IF-DOES-NOT-EXIST or IF-EXISTS. NEW-CONTENT: A sequence of strings, none of them should contain #newline, otherwise the mapping between strings and file lines won't be conserved. RETURN: The NEW-CONTENTS or if-exists or if-does-not-exist in case of error.

TEXT-FILE-CONTENTS (PATH &KEY (IF-DOES-NOT-EXIST ERROR) (EXTERNAL-FORMAT DEFAULT))

RETURN: The contents of the file at PATH as a LIST of STRING lines. or what is specified by IF-DOES-NOT-EXIST if it doesn't exist.

SETFTEXT-FILE-CONTENTS (NEW-CONTENTS PATH &KEY (IF-DOES-NOT-EXIST CREATE) (IF-EXISTS SUPERSEDE) (EXTERNAL-FORMAT DEFAULT))

RETURN: The NEW-CONTENTS, or if-exists or if-does-not-exist in case of error. DO: Store the NEW-CONTENTS into the file at PATH. By default, that file is created or superseded; this can be changed with the keyword IF-DOES-NOT-EXIST or IF-EXISTS.

Private

CONTENTS-FROM-STREAM (STREAM &KEY LENGTH (MIN-SIZE 256) MAX-EXTEND)

STREAM: May be a binary or character, file or non-file stream. LENGTH: NIL, or the number of stream elements to read. MIN-SIZE: Minimum pre-allocated buffer size. If LENGTH is given, or STREAM has a FILE-LENGTH, then the MIN-SIZE is ignored. MAX-EXTEND: NIL ==> double the buffer size, or double the buffer size until it's greater than MAX-EXTEND, and then increment by MAX-EXTEND. RETURN: A vector containing the elements read from the STREAM.

COPY-OVER (STREAM FROM-POS TO-POS &KEY (ELEMENT-TYPE 'CHARACTER))

DO: Copies elements from the FROM-POS to the end of the STREAM to the TO-POS. POST: (file-position stream) == (+ to-pos (- eof-pos from-ops)) NOTE: The file is not truncated.

COPY-STREAM (FROM TO)

Copy into TO from FROM until end of the input file. Do not translate or otherwise maul anything. AUTHORS: Daniel Barlow, Xarch

STREAM-TO-STRING-LIST (STREAM)

RETURN: the list of lines collected from stream.

Undocumented

TEST/ACCESSORS (PATH)