%--------------------------------------------------%
% vim: ft=mercury ts=4 sw=4 et
%--------------------------------------------------%
% Copyright (C) 1993-2012 The University of Melbourne.
% Copyright (C) 2013-2025 The Mercury team.
% This file is distributed under the terms specified in COPYING.LIB.
%--------------------------------------------------%
%
% File: io.file.m.
% Stability: high.
%
% This module provides operations on files other than input/output.
%
%--------------------------------------------------%
%--------------------------------------------------%

:- module io.file.
:- interface.

:- import_module time.

%--------------------------------------------------%
%
% File handling predicates.
%

    % remove_file(FileName, Result, !IO):
    %
    % Attempt to remove the file FileName, binding Result to ok/0
    % if this succeeds, or error/1 if it fails. If FileName names a file
    % that is currently open, the behaviour is implementation-dependent.
    %
    % If FileName names a directory, the behavior is currently
    % implementation-dependent. On most platforms, an empty directory
    % will be deleted.
    %
:- pred remove_file(string::in, io.res::out, io::di, io::uo) is det.

    % remove_file_recursively(FileName, Result, !IO):
    %
    % Attempt to remove the file FileName, binding Result to ok/0
    % if this succeeds, or error/1 if it fails. If FileName names a file
    % that is currently open, the behaviour is implementation-dependent.
    %
    % Unlike remove_file, this predicate will attempt to remove non-empty
    % directories (recursively). If it fails, some of the directory elements
    % may already have been removed.
    %
:- pred remove_file_recursively(string::in, io.res::out, io::di, io::uo)
    is det.

%--------------------------------------------------%

    % rename_file(OldFileName, NewFileName, Result, !IO):
    %
    % Attempt to rename the file or directory OldFileName as NewFileName,
    % binding Result to ok/0 if this succeeds, or error/1 if it fails.
    % If OldFileName names a file that is currently open, the behaviour is
    % implementation-dependent. If NewFileName names a file that already
    % exists, the behaviour is also implementation-dependent; on some systems,
    % the file previously named NewFileName will be deleted and replaced
    % with the file previously named OldFileName.
    %
:- pred rename_file(string::in, string::in, io.res::out, io::di, io::uo)
    is det.

%--------------------------------------------------%

    % Succeed if and only if the current platform can read and create
    % symbolic links.
    %
:- pred have_symlinks is semidet.

    % make_symlink(FileName, LinkFileName, Result, !IO).
    %
    % Attempts to make LinkFileName be a symbolic link to FileName.
    % If FileName is a relative path, it is interpreted relative
    % to the directory containing LinkFileName.
    %
:- pred make_symlink(string::in, string::in, io.res::out, io::di, io::uo)
    is det.

    % read_symlink(FileName, Result, !IO):
    %
    % Return ok(LinkTarget) if FileName is a symbolic link
    % pointing to LinkTarget, and error(Error) otherwise.
    %
    % If the returned LinkTarget is a relative path, it should be interpreted
    % relative to the directory containing FileName, not
    % relative to the current directory.
    %
:- pred read_symlink(string::in, io.res(string)::out, io::di, io::uo) is det.

%--------------------------------------------------%

    % check_file_accessibility(FileName, AccessTypes, Result):
    %
    % Check whether the current process can perform the operations given
    % in AccessTypes on FileName.
    %
    % The C# implementation is limited:
    %
    % - The "execute" access check passes for a regular file if we can read
    %   from the file, and have unrestricted permissions to execute unmanaged
    %   code.
    %
    % - The "write" access check passes for a directory if the directory does
    %   not have the ReadOnly attribute, which does *not* necessarily mean
    %   that we can write to it.
    %
    % - The "execute" access check is ignored for directories.
    %
:- pred check_file_accessibility(string::in, list(access_type)::in,
    io.res::out, io::di, io::uo) is det.

    % file_type(FollowSymLinks, FileName, TypeResult):
    %
    % Return the type of the given file.
    %
:- pred file_type(bool::in, string::in, io.res(file_type)::out,
    io::di, io::uo) is det.

    % file_modification_time(FileName, TimeResult):
    %
    % Return the time of the last modification to the contents
    % of the given file.
    %
:- pred file_modification_time(string::in, io.res(time_t)::out,
    io::di, io::uo) is det.

%--------------------------------------------------%
%
% Predicates for handling temporary files.
%

    % make_temp_file(Result, !IO):
    %
    % Create an empty file whose name differs from the name of
    % any existing file. The file will be placed in the directory
    % specified by get_temp_directory/3.
    %
    % If successful, return the name of the file in Result.
    %
    % It is the responsibility of the caller to delete the file
    % when it is no longer required.
    %
:- pred make_temp_file(io.res(string)::out, io::di, io::uo) is det.

    % make_temp_file(Dir, Prefix, Suffix, Result, !IO):
    %
    % Create an empty file whose name is differs from the name
    % of any existing file.
    %
    % The file will reside in the directory specified by Dir, and
    % will have a prefix using up to the first 5 code units of Prefix.
    % If successful, Result returns the name of the file.
    %
    % The reason for truncating Prefix is historical, and in future,
    % the behaviour may be changed.
    %
    % Note that the truncation is done without regard for the boundaries
    % between code points. We recommend that the prefix should contain
    % only printable ASCII characters.
    %
    % The C backend has the following limitations:
    %   - Suffix may be ignored.
    %
    % The C# backend has the following limitations:
    %   - Dir is ignored.
    %   - Prefix is ignored.
    %   - Suffix is ignored.
    %
    % It is the responsibility of the caller to delete the file
    % when it is no longer required.
    %
:- pred make_temp_file(string::in, string::in, string::in, io.res(string)::out,
    io::di, io::uo) is det.

    % make_temp_directory(Result, !IO):
    %
    % Create an empty directory whose name differs from the name
    % of any existing directory.
    %
:- pred make_temp_directory(io.res(string)::out, io::di, io::uo) is det.

    % make_temp_directory(ParentDirName, Prefix, Suffix, Result, !IO):
    %
    % Create an empty directory whose name differs from the name
    % of any existing directory.
    %
    % The new directory will reside in the existing directory
    % specified by ParentDirName, and will have a prefix (using up to the
    % first 5 characters of Prefix) and a Suffix. Result returns the name
    % of the new directory.
    %
    % It is the responsibility of the caller to delete the directory
    % when it is no longer required.
    %
    % The C backend has the following limitations:
    %   - Suffix is ignored.
    %
    % The C# backend has the following limitations:
    %   - Prefix is ignored.
    %   - Suffix is ignored.
    %
    % The Java backend has the following limitation:
    %  - Suffix is ignored.
    %
:- pred make_temp_directory(string::in, string::in, string::in,
    io.res(string)::out, io::di, io::uo) is det.

    % Test if the make_temp_directory predicates are available.
    % This is false for C backends without support for mkdtemp(3).
    %
:- pred have_make_temp_directory is semidet.

    % get_temp_directory(DirName, !IO):
    %
    % DirName is the name of a directory where applications should put
    % temporary files.
    %
    % This is implementation-dependent. For current Mercury implementations,
    % it is determined as follows:
    %
    % 1. For the non-Java back-ends:
    %
    %    - On Microsoft Windows systems, DirName will be set
    %       - to the directory named by the TMP environment variable,
    %         if that environment variable exists and names a directory, and
    %       - to the current directory otherwise.
    %
    %    - On Unix systems, DirName will be set
    %       - to the directory named by the TMPDIR environment variable,
    %         if that environment variable exists and names a directory, and
    %       - to the /tmp directory otherwise.
    %
    % 2. For the Java back-end, DirName will be set to the system-dependent
    %    default temporary-file directory, specified by the Java system
    %    property java.io.tmpdir.
    %
    %    - On Microsoft Windows systems, the default value of this property
    %      is typically "c:\\temp".
    %
    %    - On UNIX systems, the default value of this property
    %      is typically "/tmp" or "/var/tmp".
    %
:- pred get_temp_directory(string::out, io::di, io::uo) is det.

%--------------------------------------------------%
%--------------------------------------------------%