(******************************************************************************)
(* 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 *)
(******************************************************************************)
(** Operations on abstract filenames.
This module allow to manipulate string or abstract representation of a
filename.
Abstract representation of a filename allow to decode it only once, and
should speed up further operation on it (comparison in particular). If you
intend to do a lot of processing on filename, you should consider using its
abstract representation.
This module manipulate abstract path that are not bound to a real
filesystem. In particular, it makes the assumption that there is no
symbolic link that should modify the meaning of a path. If you intend to use
this module against a real set of filename, the best solution is to apply to
every filename to solve symbolic link through {!FileUtil.readlink}.
@author Sylvain Le Gall
*)
(** Filename type. *)
type filename = string
(** Extension type. *)
type extension = string
(** {2 Exceptions and types} *)
(** Cannot pass a base filename which is relative. *)
exception BaseFilenameRelative of filename
(** We do not have recognized any OS, please contact upstream. *)
exception UnrecognizedOS of string
(** The filename use was empty. *)
exception EmptyFilename
(** The last component of the filename does not support extension (Root,
ParentDir...)
*)
exception NoExtension of filename
(** The filename used is invalid. *)
exception InvalidFilename of filename
(** {2 Ordering} *)
(** [is_subdir fl1 fl2] Is [fl2] a sub directory of [fl1] *)
val is_subdir: filename -> filename -> bool
(** [is_updir fl1 fl2] Is [fl1] a sub directory of [fl2] *)
val is_updir: filename -> filename -> bool
(** [compare fl1 fl2] Give an order between the two filename. The
classification is done by sub directory relation, [fl1] < [fl2] iff [fl1] is
a subdirectory of [fl2], and lexicographical order of each part of the
reduce filename when [fl1] and [fl2] has no hierarchical relation
*)
val compare: filename -> filename -> int
(** {2 Standard operations } *)
(** Current dir. *)
val current_dir: filename
(** Upper dir. *)
val parent_dir: filename
(** Make a filename from a set of strings. *)
val make_filename: string list -> filename
(** Extract only the file name of a filename. *)
val basename: filename -> filename
(** Extract the directory name of a filename. *)
val dirname: filename -> filename
(** Append a filename to a filename. *)
val concat: filename -> filename -> filename
(** Return the shortest filename which is equal to the filename given. It remove
the "." in Unix filename, for example.
If [no_symlink] flag is set, consider that the path doesn't contain symlink
and in this case ".." for Unix filename are also reduced.
*)
val reduce: ?no_symlink:bool -> filename -> filename
(** Create an absolute filename from a filename relative and an absolute base
filename.
*)
val make_absolute: filename -> filename -> filename
(** Create a filename which is relative to the base filename. *)
val make_relative: filename -> filename -> filename
(** [reparent fln_src fln_dst fln] Return the same filename as [fln]
but the root is no more [fln_src] but [fln_dst]. It replaces the
[fln_src] prefix by [fln_dst].
*)
val reparent: filename -> filename -> filename -> filename
(** Identity for testing the stability of implode/explode. *)
val identity: filename -> filename
(** Test if the filename is a valid one. *)
val is_valid: filename -> bool
(** Check if the filename is relative to a dir or not.
*)
val is_relative: filename -> bool
(** Check if the filename is the current directory.
*)
val is_current: filename -> bool
(** Check if the filename is the parent directory.
*)
val is_parent: filename -> bool
(** {2 Extension}*)
(** Extension is define as the suffix of a filename, just after the last ".".
*)
(** Remove extension and the trailing ".". *)
val chop_extension: filename -> filename
(** Extract the extension. *)
val get_extension: filename -> extension
(** Check the extension. *)
val check_extension: filename -> extension -> bool
(** Add an extension with a "." before. *)
val add_extension: filename -> extension -> filename
(** Replace extension. *)
val replace_extension: filename -> extension -> filename
(** {2 PATH-like operation}*)
(** PATH-like refers the environment variable PATH. This variable holds a list
of filename. The functions [string_of_path] and [path_of_string] allow to
convert this kind of list by using the good separator between filename.
*)
(** Create a PATH-like string. *)
val string_of_path: filename list -> string
(** Extract filenames from a PATH-like string. *)
val path_of_string: string -> filename list
(** {2 Filename specifications} *)
(** Definition of operations for path manipulation. *)
(** Generic operations. *)
module type PATH_SPECIFICATION =
sig
type filename
type extension
(** {3 Converting abstract type from/to string } *)
(** Create a filename from a string. *)
val string_of_filename: filename -> string
(** Create a string from a filename. *)
val filename_of_string: string -> filename
(** Create an extension from a string. *)
val extension_of_string: string -> extension
(** Return string representation of an extension. *)
val string_of_extension: extension -> string
(** {3 Standard operations} *)
(** See {!FilePath.make_filename} *)
val make_filename: string list -> filename
(** See {!FilePath.is_subdir} *)
val is_subdir: filename -> filename -> bool
(** See {!FilePath.is_updir} *)
val is_updir: filename -> filename -> bool
(** See {!FilePath.compare} *)
val compare: filename -> filename -> int
(** See {!FilePath.basename} *)
val basename: filename -> filename
(** See {!FilePath.dirname} *)
val dirname: filename -> filename
(** See {!FilePath.concat} *)
val concat: filename -> filename -> filename
(** See {!FilePath.reduce} *)
val reduce: ?no_symlink:bool -> filename -> filename
(** See {!FilePath.make_absolute} *)
val make_absolute: filename -> filename -> filename
(** See {!FilePath.make_relative} *)
val make_relative: filename -> filename -> filename
(** See {!FilePath.reparent} *)
val reparent: filename -> filename -> filename -> filename
(** See {!FilePath.identity} *)
val identity: filename -> filename
(** See {!FilePath.is_valid} *)
val is_valid: filename -> bool
(** See {!FilePath.is_relative} *)
val is_relative: filename -> bool
(** See {!FilePath.is_current} *)
val is_current: filename -> bool
(** See {!FilePath.is_parent} *)
val is_parent: filename -> bool
(** See {!FilePath.chop_extension} *)
val chop_extension: filename -> filename
(** See {!FilePath.get_extension} *)
val get_extension: filename -> extension
(** See {!FilePath.check_extension} *)
val check_extension: filename -> extension -> bool
(** See {!FilePath.add_extension} *)
val add_extension: filename -> extension -> filename
(** See {!FilePath.replace_extension} *)
val replace_extension: filename -> extension -> filename
(** See {!FilePath.string_of_path} *)
val string_of_path: filename list -> string
(** See {!FilePath.path_of_string} *)
val path_of_string: string -> filename list
(** See {!FilePath.current_dir} *)
val current_dir: filename
(** See {!FilePath.parent_dir} *)
val parent_dir: filename
end
(** Generic operations, with type filename and extension as strings. *)
module type PATH_STRING_SPECIFICATION =
sig
module Abstract: PATH_SPECIFICATION
include PATH_SPECIFICATION with
type filename = string and
type extension = string
end
(** Operations on filenames for other OS. The {!DefaultPath} always match the
current OS.
*)
(** Default operating system. *)
module DefaultPath: PATH_STRING_SPECIFICATION
(** Unix operating system. *)
module UnixPath: PATH_STRING_SPECIFICATION
(** MacOS operating system. *)
module MacOSPath: PATH_STRING_SPECIFICATION
(** Win32 operating system. *)
module Win32Path: PATH_STRING_SPECIFICATION
(** Cygwin operating system. *)
module CygwinPath: PATH_STRING_SPECIFICATION