filepath.mli 7.92 KB
Newer Older
1
2
3
4
(**************************************************************************)
(*                                                                        *)
(*  This file is part of Frama-C.                                         *)
(*                                                                        *)
Andre Maroneze's avatar
Andre Maroneze committed
5
(*  Copyright (C) 2007-2020                                               *)
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
(*    CEA (Commissariat à l'énergie atomique et aux énergies              *)
(*         alternatives)                                                  *)
(*                                                                        *)
(*  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, version 2.1.                                              *)
(*                                                                        *)
(*  It 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 Lesser General Public License for more details.                   *)
(*                                                                        *)
(*  See the GNU Lesser General Public License version 2.1                 *)
(*  for more details (enclosed in the file licenses/LGPLv2.1).            *)
(*                                                                        *)
(**************************************************************************)

(** Functions manipulating filepaths.
    In these functions, references to the current working directory refer
    to the result given by function Sys.getcwd.

    NOTE: Prefer using the [Normalized] module whenever possible.
*)

Michele Alberti's avatar
Michele Alberti committed
30
31
32
33
34
(** Existence requirement on a file. *)
type existence =
  | Must_exist      (** File must exist. *)
  | Must_not_exist  (** File must not exist. *)
  | Indifferent     (** No requirement. *)
35
36

exception No_file
Michele Alberti's avatar
Michele Alberti committed
37
(** Raised whenever no file exists and [existence] is [Must_exist]. *)
38
39

exception File_exists
Michele Alberti's avatar
Michele Alberti committed
40
(** Raised whenever some file exists and [existence] is [Must_not_exist]. *)
41

42
43
44
45
46
47
48
49
50
(** Returns an absolute path leading to the given file.
    The result is similar to [realpath --no-symlinks].
    Some special behaviors include:
    - [normalize ""] (empty string) returns ""
      (realpath returns an error);
    - [normalize] preserves multiple sequential '/' characters,
      unlike [realpath];
    - non-existing directories in [realpath] may lead to ENOTDIR errors,
      but [normalize] may accept them.
51

52
    @modify Aluminium-20160501 optional base_name.
Andre Maroneze's avatar
Andre Maroneze committed
53
    @modify 21.0-Scandium optional existence.
54
*)
55
val normalize: ?existence:existence -> ?base_name:string -> string -> string
56
57
58
59
60
61
62
63
64

(** [relativize base_name file_name] returns a relative path name of
    [file_name] w.r.t. [base_name], if [base_name] is a prefix of [file];
    otherwise, returns [file_name] unchanged.
    The default base name is the current working directory name.
    @since Aluminium-20160501 *)
val relativize: ?base_name:string -> string -> string

(** returns true if the file is relative to [base]
65
66
    (that is, it is prefixed by [base_name]), or to the current
    working directory if no base is specified.
67
68
69
70
71
72
73
74
75
76
    @since Aluminium-20160501 *)
val is_relative: ?base_name:string -> string -> bool

(** DEPRECATED: use [Normalized.to_pretty_string] instead.
    Pretty-print a path according to these rules:
    - relative filenames are kept, except for leading './', which are stripped;
    - absolute filenames are relativized if their prefix is included in the
      current working directory; also, symbolic names are resolved,
      i.e. the result may be prefixed by known aliases (e.g. FRAMAC_SHARE).
      See {!add_symbolic_dir} for more details.
77
78
      Therefore, the result of this function may not designate a valid name
      in the filesystem.
79
80
81
82
83
84
85
86
87
88
89
90
91

    @since Neon-20140301
    @deprecated since 18.0-Argon
*)
val pretty: string -> string
[@@deprecated "Use Filepath.Normalized.to_pretty_string instead."]

(** [add_symbolic_dir name dir] indicates that the (absolute) path [dir] must
    be replaced by [name] when pretty-printing paths.
    This alias ensures that system-dependent paths such as FRAMAC_SHARE are
    printed identically in different machines. *)
val add_symbolic_dir: string -> string -> unit

92
93
94
(** Returns the list of symbolic dirs added via [add_symbolic_dir], plus
    preexisting ones (e.g. FRAMAC_SHARE), as pairs (name, dir).

95
    @since 22.0-Titanium
96
97
98
*)
val all_symbolic_dirs: unit -> (string * string) list

99
100
101
102
103
104
105
106
107
(** The [Normalized] module is simply a wrapper that ensures that paths are
    always normalized. Used by [Datatype.Filepath].
    @since 18.0-Argon *)
module Normalized: sig

  (** The normalized (absolute) path. *)
  type t = private string

  (** [of_string s] converts [s] into a normalized path.
108
      @raise Invalid_argument if [s] is the empty string.
Andre Maroneze's avatar
Andre Maroneze committed
109
      @modify 21.0-Scandium add optional existence parameter.
110
  *)
111
  val of_string: ?existence:existence -> ?base_name:string -> string -> t
112

113
114
115
116
  (** [concat ~existence dir file] returns the normalized path
      resulting from the concatenation of [dir] ^ "/" ^ [file].
      The resulting path must respect [existence].

117
      @since 22.0-Titanium
118
  *)
119
120
  val concat: ?existence:existence -> t -> string -> t

121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
  (** [to_pretty_string p] returns [p] prettified,
      that is, a relative path-like string.
      Note that this prettified string may contain symbolic dirs and is thus
      is not a path.
      See [pretty] for details about usage. *)
  val to_pretty_string: t -> string

  val equal: t -> t -> bool

  (** Compares normalized paths *)
  val compare: t -> t -> int

  (** Compares prettified (i.e. relative) paths, with or without
      case sensitivity (by default, [case_sensitive = false]). *)
  val compare_pretty : ?case_sensitive:bool -> t -> t -> int

  (** Pretty-print a path according to these rules:
      - relative filenames are kept, except for leading './',
        which are stripped;
      - absolute filenames are relativized if their prefix is included in the
        current working directory; also, symbolic names are resolved,
        i.e. the result may be prefixed by known aliases (e.g. FRAMAC_SHARE).
        See {!add_symbolic_dir} for more details.
144
145
146
        Therefore, the result of this function may not designate a valid name
        in the filesystem and must ONLY be used to pretty-print information;
        it must NEVER to be converted back to a filepath later.
147
148
149
150
151
152
153
154
  *)
  val pretty: Format.formatter -> t -> unit

  (** Pretty-prints the normalized (absolute) path. *)
  val pp_abs: Format.formatter -> t -> unit

  (** Unknown filepath, used as 'dummy' for [Datatype.Filepath]. *)
  val unknown: t
155

Andre Maroneze's avatar
Andre Maroneze committed
156
  (** @since 20.0-Calcium *)
157
  val is_unknown: t -> bool
158
159
160
161

  (** [is_file f] returns [true] iff [f] points to a regular file
      (or a symbolic link pointing to a file).
      Returns [false] if any errors happen when [stat]'ing the file.
162
      @since 22.0-Titanium *)
163
  val is_file: t -> bool
164
165
166

  (** [to_base_uri path] returns a pair [prefix, rest], according to the
      prettified value of [path]:
167
168
169
      - if it starts with symbolic path SYMB, prefix is Some "SYMB";
      - if it is a relative path, prefix is Some "PWD";
      - else (an absolute path), prefix is None.
170
171
172
173
        [rest] contains everything after the '/' following the prefix.
        E.g. for the path "FRAMAC_SHARE/libc/string.h", returns
        ("FRAMAC_SHARE", "libc/string.h").

174
      @since 22.0-Titanium
175
  *)
176
  val to_base_uri: t -> string option * string
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
end

(** Describes a position in a source file.
    @since 18.0-Argon
*)
type position =
  {
    pos_path : Normalized.t;
    pos_lnum : int;
    pos_bol : int;
    pos_cnum : int;
  }

(** Pretty-prints a position, in the format file:line.
    @since 18.0-Argon
*)
val pp_pos : Format.formatter -> position -> unit

(*
  Local Variables:
  compile-command: "make -C ../../.."
  End:
*)