stdlib/filename.mli

   1 (***********************************************************************)
   2 (*                                                                     *)
   3 (*                           Objective Caml                            *)
   4 (*                                                                     *)
   5 (*            Xavier Leroy, projet Cristal, INRIA Rocquencourt         *)
   6 (*                                                                     *)
   7 (*  Copyright 1996 Institut National de Recherche en Informatique et   *)
   8 (*  en Automatique.  All rights reserved.  This file is distributed    *)
   9 (*  under the terms of the GNU Library General Public License, with    *)
  10 (*  the special exception on linking described in file ../LICENSE.     *)
  11 (*                                                                     *)
  12 (***********************************************************************)
  13
  14 (* $Id$ *)
  15
  16 (** Operations on file names. *)
  17
  18 val current_dir_name : string
  19 (** The conventional name for the current directory (e.g. [.] in Unix). *)
  20
  21 val parent_dir_name : string
  22 (** The conventional name for the parent of the current directory
  23    (e.g. [..] in Unix). *)
  24
  25 val concat : string -> string -> string
  26 (** [concat dir file] returns a file name that designates file
  27    [file] in directory [dir]. *)
  28
  29 val is_relative : string -> bool
  30 (** Return [true] if the file name is relative to the current
  31    directory, [false] if it is absolute (i.e. in Unix, starts
  32    with [/]). *)
  33
  34 val is_implicit : string -> bool
  35 (** Return [true] if the file name is relative and does not start
  36    with an explicit reference to the current directory ([./] or
  37    [../] in Unix), [false] if it starts with an explicit reference
  38    to the root directory or the current directory. *)
  39
  40 val check_suffix : string -> string -> bool
  41 (** [check_suffix name suff] returns [true] if the filename [name]
  42    ends with the suffix [suff]. *)
  43
  44 val chop_suffix : string -> string -> string
  45 (** [chop_suffix name suff] removes the suffix [suff] from
  46    the filename [name]. The behavior is undefined if [name] does not
  47    end with the suffix [suff]. *)
  48
  49 val chop_extension : string -> string
  50 (** Return the given file name without its extension. The extension
  51    is the shortest suffix starting with a period and not including
  52    a directory separator, [.xyz] for instance.
  53
  54    Raise [Invalid_argument] if the given name does not contain
  55    an extension. *)
  56
  57 val basename : string -> string
  58 (** Split a file name into directory name / base file name.
  59    [concat (dirname name) (basename name)] returns a file name
  60    which is equivalent to [name]. Moreover, after setting the
  61    current directory to [dirname name] (with {!Sys.chdir}),
  62    references to [basename name] (which is a relative file name)
  63    designate the same file as [name] before the call to {!Sys.chdir}.
  64
  65    The result is not specified if the argument is not a valid file name
  66    (for example, under Unix if there is a NUL character in the string). *)
  67
  68 val dirname : string -> string
  69 (** See {!Filename.basename}. *)
  70
  71 val temp_file : string -> string -> string
  72 (** [temp_file prefix suffix] returns the name of a
  73    fresh temporary file in the temporary directory.
  74    The base name of the temporary file is formed by concatenating
  75    [prefix], then a suitably chosen integer number, then [suffix].
  76    The temporary file is created empty, with permissions [0o600]
  77    (readable and writable only by the file owner).  The file is
  78    guaranteed to be different from any other file that existed when
  79    [temp_file] was called.
  80 *)
  81
  82 val open_temp_file :
  83       ?mode: open_flag list -> string -> string -> string * out_channel
  84 (** Same as {!Filename.temp_file}, but returns both the name of a fresh
  85    temporary file, and an output channel opened (atomically) on
  86    this file.  This function is more secure than [temp_file]: there
  87    is no risk that the temporary file will be modified (e.g. replaced
  88    by a symbolic link) before the program opens it.  The optional argument
  89    [mode] is a list of additional flags to control the opening of the file.
  90    It can contain one or several of [Open_append], [Open_binary],
  91    and [Open_text].  The default is [[Open_text]] (open in text mode). *)
  92
  93 val temp_dir_name : string
  94 (** The name of the temporary directory:
  95     Under Unix, the value of the [TMPDIR] environment variable, or "/tmp"
  96     if the variable is not set.
  97     Under Windows, the value of the [TEMP] environment variable, or "."
  98     if the variable is not set.
  99 *)
 100
 101 val quote : string -> string
 102 (** Return a quoted version of a file name, suitable for use as
 103     one argument in a command line, escaping all meta-characters.
 104     Warning: under Windows, the output is only suitable for use
 105     with programs that follow the standard Windows quoting
 106     conventions.
 107  *)