(******************************************************************************)
(*  ocaml-fileutils: files and filenames common operations                    *)
(*                                                                            *)
(*  Copyright (C) 2003-2014, Sylvain Le Gall                                  *)
(*                                                                            *)
(*  This library is free software; you can redistribute it and/or modify it   *)
(*  under the terms of the GNU Lesser General Public License as published by  *)
(*  the Free Software Foundation; either version 2.1 of the License, or (at   *)
(*  your option) any later version, with the OCaml static compilation         *)
(*  exception.                                                                *)
(*                                                                            *)
(*  This library 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 file         *)
(*  COPYING for more details.                                                 *)
(*                                                                            *)
(*  You should have received a copy of the GNU Lesser General Public License  *)
(*  along with this library; if not, write to the Free Software Foundation,   *)
(*  Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301 USA             *)
(******************************************************************************)

(** POSIX utilities for files and directories.

    A module to provide the core POSIX utilities to manipulate files and
    directories. All functions try to mimic common POSIX utilities but are
    written in pure OCaml.

    @author Sylvain Le Gall
  *)

open FilePath


(*********************************************************************)
(**

  {2 Types and exceptions }

  *)

exception FileDoesntExist of filename
exception RecursiveLink of filename

(** Generic error handling functions. Whenever such a function is available it
    helps report the error and allows to raise an exception. The [string]
    provided is the human readable version of ['a]. In most cases ['a] is a
    polymorphic variant.
  *)
type 'a error_handler = string -> 'a -> unit

(** Exception raised when after an [error_handler] the execution cannot
    continue. The rest of the workflow logic cannot handle the default case and
    the whole operation can be in the middle of transformation.
  *)
exception Fatal of string

(** Policy concerning links which are directories. *)
type action_link =
  | Follow
    (** We consider link as simple directory (it is dangerous) *)
  | Skip
    (** Just skip it *)
  | SkipInform of (filename -> unit)
    (** Skip and execute an action *)
  | AskFollow of (filename -> bool)
    (** Ask and wait for input, false means skip *)

(** For certain command, you should need to ask the user wether
    or not he wants to act.
  *)
type interactive =
  | Force (** Do it anyway *)
  | Ask of (filename -> bool) (** Promp the user *)


(*********************************************************************)
(**

   {2 Permission }

  *)

(** Base permission. This is the permission corresponding to one user or group.
  *)
type base_permission =
  {
    sticky: bool;
    exec: bool;
    write: bool;
    read: bool;
  }

(** Full permission. All the base permissions of a file.
  *)
type permission =
  {
    user: base_permission;
    group: base_permission;
    other: base_permission;
  }

(** Translate POSIX integer permission. *)
val permission_of_int: int -> permission

(** Return the POSIX integer permission *)
val int_of_permission: permission -> int

(** Permission symbolic mode. *)
module Mode:
sig
  type who = [`User | `Group | `Other | `All]
  type wholist = [ who | `List of who list ]
  type permcopy = [`User | `Group | `Other]
  type perm = [ `Read | `Write | `Exec | `ExecX | `Sticky | `StickyO ]
  type permlist = [ perm | `List of perm list ]
  type actionarg = [ permlist | permcopy ]
  type action = [ `Set of actionarg | `Add of actionarg | `Remove of actionarg]
  type actionlist = [ action | `List of action list ]
  type clause = [ `User of actionlist | `Group of actionlist
                | `Other of actionlist | `All of actionlist
                | `None of actionlist ]

  (** Typical symbolic mode:
   - g+r -> [`Group (`Add `Read)]
   - u=rw,g+rw,o-rwx ->
     [`User (`Set (`List [`Read; `Write]));
      `Group (`Add (`List [`Read; `Write]));
      `Other (`Remove (`List [`Read; `Write; `Exec]))]
   *)
  type t = clause list
end

(*********************************************************************)
(**

   {2 Size operation}
 
  *)

(** File size
  *)
type size =
    TB of int64 (** Tera bytes *)
  | GB of int64 (** Giga bytes *)
  | MB of int64 (** Mega bytes *)
  | KB of int64 (** Kilo bytes *)
  | B  of int64 (** Bytes *)

(** Convert size to bytes. *)
val byte_of_size: size -> int64

(** Add two sizes. *)
val size_add: size -> size -> size

(** Compare two sizes, using the classical compare function. If fuzzy is set to
    true, the comparison is done on the most significant size unit of both
    value.
  *)
val size_compare: ?fuzzy:bool -> size -> size -> int

(** Convert a value to a string representation. If fuzzy is set to true, only
    consider the most significant unit
  *)
val string_of_size: ?fuzzy:bool -> size -> string

(*********************************************************************)
(**

   {2 stat }

  *)

(** Kind of file. This set is a combination of all POSIX file, some of them
    doesn't exist at all on certain file system or OS.
  *)
type kind =
    Dir
  | File
  | Dev_char
  | Dev_block
  | Fifo
  | Socket
  | Symlink (** @since 0.4.6 *)


(** Information about a file. This type is derived from Unix.stat
  *)
type stat =
  {
    kind: kind;
    is_link: bool;
    permission: permission;
    size: size;
    owner: int;
    group_owner: int;
    access_time: float;
    modification_time: float;
    creation_time: float;
    device: int;
    inode: int;
  }


(** [stat fln] Return information about the file (like Unix.stat)
    Non POSIX command.
  *)
val stat: ?dereference:bool -> filename -> stat

(*********************************************************************)
(**
 
  {2 umask }
   
  *)

exception UmaskError of string

(** Possible umask errors. *)
type umask_error = [ `Exc of exn | `NoStickyBit of int ]

(** Get or set the file mode creation mask.
    See {{:http://pubs.opengroup.org/onlinepubs/007904875/utilities/umask.html}POSIX documentation}.
  *)
val umask:
  ?error:(umask_error error_handler) ->
  ?mode:[< `Octal of int | `Symbolic of Mode.t ] ->
  [< `Octal of int -> 'a | `Symbolic of Mode.t -> 'a] ->
  'a

(** Apply umask to a given file permission.
  *)
val umask_apply: int -> int

(*********************************************************************)
(**

  {2 test }

  *)

(** Pattern you can use to test file. If the file doesn't exist the result is
    always false.
  *)
type test_file =
  | Is_dev_block                 (** FILE is block special *)
  | Is_dev_char                  (** FILE is character special *)
  | Is_dir                       (** FILE is a directory *)
  | Exists                       (** FILE exists *)
  | Is_file                      (** FILE is a regular file *)
  | Is_set_group_ID              (** FILE is set-group-ID *)
  | Has_sticky_bit               (** FILE has its sticky bit set *)
  | Is_link                      (** FILE is a symbolic link *)
  | Is_pipe                      (** FILE is a named pipe *)
  | Is_readable                  (** FILE is readable *)
  | Is_writeable                 (** FILE is writeable *)
  | Size_not_null                (** FILE has a size greater than zero *)
  | Size_bigger_than of size     (** FILE has a size greater than given size *)
  | Size_smaller_than of size    (** FILE has a size smaller than given size *)
  | Size_equal_to of size        (** FILE has the same size as given size *)
  | Size_fuzzy_equal_to of size  (** FILE has approximatively the same size as
                                     given size *)
  | Is_socket                    (** FILE is a socket *)
  | Has_set_user_ID              (** FILE its set-user-ID bit is set *)
  | Is_exec                      (** FILE is executable *)
  | Is_owned_by_user_ID          (** FILE is owned by the effective user ID *)
  | Is_owned_by_group_ID         (** FILE is owned by the effective group ID *)
  | Is_newer_than of filename    (** FILE1 is newer (modification date) than
                                     FILE2 *)
  | Is_older_than of filename    (** FILE1 is older than FILE2 *)
  | Is_newer_than_date of float  (** FILE is newer than given date *)
  | Is_older_than_date of float  (** FILE is older than given date *)
  | And of test_file * test_file (** Result of TEST1 and TEST2 *)
  | Or of test_file * test_file  (** Result of TEST1 or TEST2 *)
  | Not of test_file             (** Result of not TEST *)
  | Match of string              (** Compilable match (Str or PCRE or ...) *)
  | True                         (** Always true *)
  | False                        (** Always false *)
  | Has_extension of extension   (** Check extension *)
  | Has_no_extension             (** Check absence of extension *)
  | Is_parent_dir                (** Basename is the parent dir *)
  | Is_current_dir               (** Basename is the current dir *)
  | Basename_is of filename      (** Check the basename *)
  | Dirname_is of filename       (** Check the dirname *)
  | Custom of (filename -> bool) (** Custom operation on filename *)


(** Test a file.
    See {{:http://pubs.opengroup.org/onlinepubs/007904875/utilities/test.html}POSIX documentation}.
  *)
val test:
  ?match_compile:(filename -> filename -> bool) ->
  test_file -> filename -> bool

(*********************************************************************)
(**

  {2 chmod }

  *)

exception ChmodError of string

(** Possible chmod errors. *)
type chmod_error = [`Exc of exn]

(** Change permissions of files.
    See {{:http://pubs.opengroup.org/onlinepubs/007904875/utilities/chmod.html}POSIX documentation}.
  *)
val chmod:
  ?error:(chmod_error error_handler) ->
  ?recurse:bool ->
  [< `Octal of Unix.file_perm | `Symbolic of Mode.t ] ->
  filename list -> unit

(*********************************************************************)
(**

  {2 mkdir }

  *)

exception MkdirError of string

(** Possible mkdir errors. *)
type mkdir_error =
  [ `DirnameAlreadyUsed of filename
  | `Exc of exn
  | `MissingComponentPath of filename
  | `MkdirChmod of filename * Unix.file_perm * string * chmod_error ]

(** Create the directory which name is provided. Set [~parent] to true
    if you also want to create every directory of the path. Use mode to
    provide some specific right.
    See {{:http://pubs.opengroup.org/onlinepubs/007904875/utilities/mkdir.html}POSIX documentation}.
  *)
val mkdir:
  ?error:(mkdir_error error_handler) ->
  ?parent:bool ->
  ?mode:[< `Octal of Unix.file_perm | `Symbolic of FileUtilMode.t ] ->
  filename -> unit

(*********************************************************************)
(**

    {2 rm }

  *)

exception RmError of string

(** Possible rm errors. *)
type rm_error =
  [ `DirNotEmpty of filename
  | `Exc of exn
  | `NoRecurse of filename ]

(** Remove the filename provided. Set [~recurse] to true in order to
    completely delete a directory.
    See {{:http://pubs.opengroup.org/onlinepubs/007904875/utilities/rm.html}POSIX documentation}.
  *)
val rm:
  ?error:(rm_error error_handler) ->
  ?force:interactive -> ?recurse:bool -> filename list -> unit

(*********************************************************************)
(**

    {2 cp }

  *)

exception CpError of string

(** Possible cp errors. *)
type cp_error =
  [ `CannotChmodDstDir of filename * exn
  | `CannotCopyDir of filename
  | `CannotCopyFilesToFile of filename list * filename
  | `CannotCreateDir of filename * exn
  | `CannotListSrcDir of filename * exn
  | `CannotOpenDstFile of filename * exn
  | `CannotOpenSrcFile of filename * exn
  | `CannotRemoveDstFile of filename * exn
  | `DstDirNotDir of filename
  | `ErrorRead of filename * exn
  | `ErrorWrite of filename * exn
  | `Exc of exn
  | `NoSourceFile of filename
  | `PartialWrite of filename * int * int
  | `SameFile of filename * filename
  | `UnhandledType of filename * kind ]

(** Copy the hierarchy of files/directory to another destination.
    See {{:http://pubs.opengroup.org/onlinepubs/007904875/utilities/cp.html}POSIX documentation}.
  *)
val cp:
  ?follow:action_link ->
  ?force:interactive ->
  ?recurse:bool ->
  ?preserve:bool ->
  ?error:(cp_error error_handler) ->
  filename list -> filename -> unit

(*********************************************************************)
(**

    {2 mv }

  *)

exception MvError of string

(** Possible mv errors. *)
type mv_error =
  [ `Exc of exn
  | `MvCp of filename * filename * string * cp_error
  | `MvRm of  filename * string * rm_error
  | `NoSourceFile ]

(** Move files/directories to another destination.
    See {{:http://pubs.opengroup.org/onlinepubs/007904875/utilities/mv.html}POSIX documentation}.
  *)
val mv:
  ?error:(mv_error error_handler) ->
  ?force:interactive -> filename -> filename -> unit


(*********************************************************************)
(**

   {2 touch }

  *)

(** Time for file *)
type touch_time_t =
  | Touch_now                   (** Use Unix.gettimeofday *)
  | Touch_file_time of filename (** Get mtime of file *)
  | Touch_timestamp of float    (** Use GMT timestamp *)


(** Modify the timestamp of the given filename.
    See {{:http://pubs.opengroup.org/onlinepubs/007904875/utilities/touch.html}POSIX documentation}.
    If atime and mtime are not specified, they are both considered true. If only
    atime or mtime is sepcified, the other is false.
    @param atime  modify access time.
    @param mtime  modify modification time.
    @param create if file doesn't exist, create it, default true
    @param time   what time to set, default Touch_now
  *)
val touch:
  ?atime:bool ->
  ?mtime:bool ->
  ?create:bool -> ?time:touch_time_t -> filename -> unit

(*********************************************************************)
(**

   {2 ls }

  *)

(** Apply a filtering pattern to a filename.
  *)
val filter: test_file -> filename list -> filename list

(** List the content of a directory.
    See {{:http://pubs.opengroup.org/onlinepubs/007904875/utilities/ls.html}POSIX documentation}.
  *)
val ls: filename -> filename list

(*********************************************************************)
(**

  {2 Misc operations }

  *)

(** Return the current dir.
    See {{:http://pubs.opengroup.org/onlinepubs/007904875/utilities/pwd.html}POSIX documentation}.
  *)
val pwd: unit -> filename

(** Resolve to the real filename removing symlink.
    Non POSIX command.
  *)
val readlink: filename -> filename

(** Try to find the executable in the PATH. Use environement variable
    PATH if none is provided.
    Non POSIX command.
  *)
val which:
  ?path:filename list -> filename -> filename

(** [cmp skip1 fln1 skip2 fln2] Compare files [fln1] and [fln2] starting at pos
    [skip1] [skip2] and returning the first octect where a difference occurs.
    Returns [Some -1] if one of the file is not readable or if it is not a
    file.
    See {{:http://pubs.opengroup.org/onlinepubs/007904875/utilities/cmp.html}POSIX documentation}.
  *)
val cmp:
  ?skip1:int ->
  filename -> ?skip2:int -> filename -> int option

(** [du fln_lst] Return the amount of space of all the file
    which are subdir of fln_lst. Also return details for each
    file scanned.
    See {{:http://pubs.opengroup.org/onlinepubs/007904875/utilities/du.html}POSIX documentation}.
  *)
val du: filename list -> size * (filename * size) list

(** [find ~follow:fol tst fln exec accu] Descend the directory tree starting
    from the given filename and using the test provided. You cannot match
    [current_dir] and [parent_dir]. For every file found, the action [exec] is
    done, using the [accu] to start. For a simple file listing, you can use
    [find True "." (fun x y -> y :: x) []]
    See {{:http://pubs.opengroup.org/onlinepubs/007904875/utilities/find.html}POSIX documentation}.
  *)
val find:
  ?follow:action_link ->
  ?match_compile:(filename -> filename -> bool) ->
  test_file ->
  filename -> ('a -> filename -> 'a) -> 'a -> 'a

(** For future release:
- [val pathchk: filename -> boolean * string], check whether file names are
  valid or portable
- [val setfacl: filename -> permission -> unit], set file access control
  lists (UNIX + extended attribute)
- [val getfacl: filename -> permission], get file access control lists

ACL related function will be handled through a plugin system to handle at
runtime which attribute can be read/write (i.e. Win32 ACL, NFS acl, Linux ACL --
or none).
*)