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 - 2014
    
    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/>
(binary-file-contents path &key if-does-not-exist element-type external-format)
function
IF-DOES-NOT-EXIST:  Can be :error, :create, nil, or another value that
                    is returned instead of the content of the file if
                    it doesn't exist.

RETURN:             The contents of the file at PATH as a VECTOR of
                    (UNSIGNED-BYTE 8), or the value of
                    IF-DOES-NOT-EXIST when not :ERROR or :CREATE and
                    the file doesn't exist.
(setf (binary-file-contents path &key if-does-not-exist if-exists element-type external-format) new-contents)
function
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-directory src dst &key recursively verbose on-error if-exists external-format element-type)
function
DO:             Copy files from the directory SRC to the directory
                DST, using the specified key parameters.

RECURSIVELY:    When NIL, only the files directly under SRC are
                copied.  Otherwise, subdirectories and all their files
                are also copied.

IF-ERROR:       Can be :ERROR, then the error is signaled,
                :CONTINUE, then the error is ignored and copying continues,
                :ABORT, then the error is ignored, and copying is aborted.

RETURN:         list-of-destination-files-copied ; list-of-source-files-with-errors

NOTE:           Files are scanned with CL:DIRECTORY, so only those
                that are accessible from the CL implementation are
                copied.

NOTE:           Empty subdirectories are not copied.
(copy-file src dst &key if-exists external-format element-type)
function
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)
function
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)
function
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 external-format)
function
IF-DOES-NOT-EXIST:  Can be :error, :create, nil, or another value that
                    is returned instead of the content of the file if
                    it doesn't exist.

RETURN:             The first SEXP of the file at PATH, or the value
                    of IF-DOES-NOT-EXIST when not :ERROR or :CREATE
                    and the file doesn't exist.
(setf (sexp-file-contents path &key if-does-not-exist if-exists external-format) new-contents)
function
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.
(sexp-list-file-contents path &key if-does-not-exist external-format)
function
IF-DOES-NOT-EXIST:  Can be :error, :create, nil, or another value that
                    is returned instead of the content of the file if
                    it doesn't exist.

RETURN:             All the SEXPs of the file at PATH gathered in a
                    list, or the value of IF-DOES-NOT-EXIST when not
                    :ERROR or :CREATE and the file doesn't exist.
(setf (sexp-list-file-contents path &key if-does-not-exist if-exists external-format) new-contents)
function
NEW-CONTENTS:   A list of sexps.

DO:             Writes the NEW-CONTENTS SEXPs 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 external-format)
function
IF-DOES-NOT-EXIST:  Can be :error, :create, nil, or another value that
                    is returned instead of the content of the file if
                    it doesn't exist.

RETURN:             The list of lines collected from the file, or the
                    value of IF-DOES-NOT-EXIST when not :ERROR or
                    :CREATE and the file doesn't exist.
(setf (string-list-text-file-contents path &key if-does-not-exist if-exists external-format) new-contents)
function
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 external-format)
function
IF-DOES-NOT-EXIST:  Can be :error, :create, nil, or another value that
                    is returned instead of the content of the file if
                    it doesn't exist.

RETURN:             The contents of the file at PATH as a LIST of
                    STRING lines, or the value of IF-DOES-NOT-EXIST
                    when not :ERROR or :CREATE and the file doesn't
                    exist.
(setf (text-file-contents path &key if-does-not-exist if-exists external-format) new-contents)
function
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.