Debian Codegraph @

vendor/opam/src/core/opamFilename.mli

raw
1 (**************************************************************************)
2 (* *)
3 (* Copyright 2012-2019 OCamlPro *)
4 (* Copyright 2012 INRIA *)
5 (* *)
6 (* All rights reserved. This file is distributed under the terms of the *)
7 (* GNU Lesser General Public License version 2.1, with the special *)
8 (* exception on linking described in the file LICENSE. *)
9 (* *)
10 (**************************************************************************)
11
12 (** Higher level file and directory name manipulation AND file operations,
13 wrappers on OpamSystem using the filename type *)
14
15 (** Basenames *)
16 module Base: sig
17 include OpamStd.ABSTRACT
18
19 (** Check whether a basename has a given suffix *)
20 val check_suffix: t -> string -> bool
21
22 (** Add a file extension *)
23 val add_extension: t -> string -> t
24 end
25
26 (** Directory names *)
27 module Dir: OpamStd.ABSTRACT
28
29 (** Return the current working directory *)
30 val cwd: unit -> Dir.t
31
32 (** Remove a directory *)
33 val rmdir: Dir.t -> unit
34
35 (** Cleans the contents of a directory, but keeps the directory in place.
36 Noop if directory doesn't exists. *)
37 val cleandir: Dir.t -> unit
38
39 (** Removes an empty directory, as well as any empty leading path components.
40 Must be called only on a directory that is known to not have empty parents,
41 only internal opam directory (and not tmp dir). *)
42 val rmdir_cleanup: Dir.t -> unit
43
44 (** Create a directory *)
45 val mkdir: Dir.t -> unit
46
47 (** List the sub-directory recursively *)
48 val rec_dirs: Dir.t -> Dir.t list
49
50 val dir_is_empty: Dir.t -> bool
51
52 (** List the sub-directory (do not recurse) *)
53 val dirs: Dir.t -> Dir.t list
54
55 (** Evaluate a function in a given directory *)
56 val in_dir: Dir.t -> (unit -> 'a) -> 'a
57
58 (** Turns an assoc list into an array suitable to be provided as environment *)
59 val env_of_list: (string * string) list -> string array
60
61 (** Move a directory *)
62 val move_dir: src:Dir.t -> dst:Dir.t -> unit
63
64 (** Copy directory [src] to [dst], that is, recursively copy the contents of
65 [src] into [dst], overwriting any existing files. *)
66 val copy_dir: src:Dir.t -> dst:Dir.t -> unit
67
68 (** Link a directory *)
69 val link_dir: target:Dir.t -> link:Dir.t -> unit
70
71 (** Does the directory exist? *)
72 val exists_dir: Dir.t -> bool
73
74 (** Returns the argument as option, if the directory exists *)
75 val opt_dir: Dir.t -> Dir.t option
76
77 (** Return the parent directory *)
78 val dirname_dir: Dir.t -> Dir.t
79
80 (** Return the deeper directory name *)
81 val basename_dir: Dir.t -> Base.t
82
83 (** Turn a full path into a list of directory names *)
84 val to_list_dir: Dir.t -> Dir.t list
85
86 (** Creation from a raw string, without resolving symlinks etc. *)
87 val raw_dir: string -> Dir.t
88
89 (** Execute a function in a temp directory *)
90 val with_tmp_dir: (Dir.t -> 'a) -> 'a
91
92 (** Raw function to create a temporary directory. No automatic cleanup *)
93 val mk_tmp_dir: unit -> Dir.t
94
95 (** Create a new Dir.t and resolve symlinks *)
96 val concat_and_resolve: Dir.t -> string -> Dir.t
97
98 include OpamStd.ABSTRACT
99
100 (** Generic filename *)
101 type generic_file =
102 | D of Dir.t
103 | F of t
104
105 (** Create a filename from a Dir.t and a basename *)
106 val create: Dir.t -> Base.t -> t
107
108 (** Create a file from a basename and the current working directory
109 as dirname *)
110 val of_basename: Base.t -> t
111
112 (** Creation from a raw string, without resolving symlinks, etc. *)
113 val raw: string -> t
114
115 (** Prettify a filename:
116 - replace /path/to/opam/foo by <opam>/foo
117 - replace /path/to/home/foo by ~/foo *)
118 val prettify: t -> string
119
120 (** Prettify a dirname. *)
121 val prettify_dir: Dir.t -> string
122
123
124 (** Return the directory name *)
125 val dirname: t -> Dir.t
126
127 (** Return the base name *)
128 val basename: t -> Base.t
129
130 (** Retrieves the contents from the hard disk. *)
131 val read: t -> string
132
133 (** Open a channel from a given file. *)
134 val open_in: t -> in_channel
135 val open_in_bin: t -> in_channel
136 val open_out: t -> out_channel
137 val open_out_bin: t -> out_channel
138
139 (** [with_open_out_bin filename f] opens [f] and passes the out_channel to [f].
140 If [f] raises an exception, then [filename] is deleted and then exception is
141 propagated. The out_channel does not have to be closed by [f]. *)
142 val with_open_out_bin: t -> (out_channel -> unit) -> unit
143
144 (** As {!with_open_out_bin} except that the file is written atomically. If [f]
145 raises an exception, then [filename] will be unaltered. *)
146 val with_open_out_bin_atomic: t -> (out_channel -> unit) -> unit
147
148 (** Removes everything in [filename] if existed. *)
149 val remove: t -> unit
150
151 (** Removes everything in [filename] if existed, then write [contents] instead. *)
152 val write: t -> string -> unit
153
154 (** Returns true if the file exists and is a regular file or a symlink to one *)
155 val exists: t -> bool
156
157 (** Returns the argument as option if it exists and is either a regular file or
158 a symlink to one *)
159 val opt_file: t -> t option
160
161 (** Check whether a file has a given suffix *)
162 val check_suffix: t -> string -> bool
163
164 (** Adds a dot and the given file extension *)
165 val add_extension: t -> string -> t
166
167 (** Remove the file extension *)
168 val chop_extension: t -> t
169
170 (** List all the filenames, recursively *)
171 val rec_files: Dir.t -> t list
172
173 (** List all the filename. Do not recurse. *)
174 val files: Dir.t -> t list
175
176 (** Returns alll the files, including dangling symlinks (which means that
177 not all entries will satisfy {!exists}). *)
178 val files_and_links: Dir.t -> t list
179
180 (** Apply a function on the contents of a file *)
181 val with_contents: (string -> 'a) -> t -> 'a
182
183 (** Copy a file in a directory. If [root] is set, copy also the
184 sub-directories. For instance, [copy_in ~root:"/foo" "/foo/bar/gni"
185 "/toto"] creates ["/toto/bar/gni"]. *)
186 val copy_in: ?root:Dir.t -> t -> Dir.t -> unit
187
188 (** Move a file *)
189 val move: src:t -> dst:t -> unit
190
191 (** Read a symlinked file *)
192 val readlink: t -> t
193
194 (** Is a symlink? *)
195 val is_symlink: t -> bool
196
197 val is_symlink_dir: Dir.t -> bool
198
199 (** Is an executable? *)
200 val is_exec: t -> bool
201
202 (** Copy a file *)
203 val copy: src:t -> dst:t -> unit
204
205 (** Installs a file to a destination. Optionally set if the destination should
206 be set executable *)
207 val install: ?warning:OpamSystem.install_warning_fn -> ?exec:bool -> src:t -> dst:t -> unit -> unit
208
209 (** Symlink a file. If symlink is not possible on the system, use copy instead.
210 With [relative], creates a relative link through the closest common ancestor
211 directory if possible. Otherwise, the symlink is absolute. *)
212 val link: ?relative:bool -> target:t -> link:t -> unit
213
214 (** Returns true if the given file is an archive (zip or tar) *)
215 val is_archive: t -> bool
216
217 (** Extract a generic file *)
218 val extract_generic_file: generic_file -> Dir.t -> unit
219
220 (** Check whether a filename starts by a given Dir.t *)
221 val starts_with: Dir.t -> t -> bool
222
223 (** Check whether a filename ends with a given suffix *)
224 val ends_with: string -> t -> bool
225
226 (** [dir starts_with pfx dir] Check whether [dir] starts with [pfx] *)
227 val dir_starts_with: Dir.t -> Dir.t -> bool
228
229 (** Check whether a dirname ends with a given suffix *)
230 val dir_ends_with: string -> Dir.t -> bool
231
232 (** Remove a prefix from a file name *)
233 val remove_prefix: Dir.t -> t -> string
234
235 val remove_prefix_dir: Dir.t -> Dir.t -> string
236
237 (** Remove a suffix from a filename *)
238 val remove_suffix: Base.t -> t -> string
239
240 (** Create an empty file *)
241 val touch: t -> unit
242
243 (** Change file permissions *)
244 val chmod: t -> int -> unit
245
246 (** Returns delay since last file update, based on mtime *)
247 val written_since: t -> float
248
249 (** Returns the closest parent of a directory (including itself) for which the
250 predicate holds, if any *)
251 val find_in_parents: (Dir.t -> bool) -> Dir.t -> Dir.t option
252
253 (** {2 Locking} *)
254
255 (** See [OpamSystem.flock]. Prefer the higher level [with_flock] functions when
256 possible *)
257 val flock: [< OpamSystem.lock_flag ] -> ?dontblock:bool -> t -> OpamSystem.lock
258
259 (** Calls [f] while holding a lock file. Ensures the lock is properly released
260 on [f] exit. Raises [OpamSystem.Locked] if [dontblock] is set and the lock
261 can't be acquired. [f] is passed the file_descr of the lock. *)
262 val with_flock: [< OpamSystem.lock_flag ] -> ?dontblock:bool -> t ->
263 (Unix.file_descr -> 'a) -> 'a
264
265 (** Calls [f] with the file lock upgraded to at least [flag], then restores the
266 previous lock level. Upgrade to [`Lock_write] should never be used in
267 blocking mode as it would deadlock. Raises [OpamSystem.Locked] (but keeps
268 the lock as is) if [dontblock] is set and the lock can't be upgraded. *)
269 val with_flock_upgrade:
270 [< OpamSystem.actual_lock_flag ] -> ?dontblock:bool -> OpamSystem.lock -> (Unix.file_descr -> 'a) -> 'a
271
272 (** Runs first function with a write lock on the given file, then releases it to
273 a read lock and runs the second function. *)
274 val with_flock_write_then_read:
275 ?dontblock:bool -> t -> (Unix.file_descr -> 'a) -> ('a -> 'b) -> 'b
276
277 module Op: sig
278
279 (** Create a new directory *)
280 val (/): Dir.t -> string -> Dir.t
281
282 (** Create a new filename *)
283 val (//): Dir.t -> string -> t
284
285 end
286
287 (** Simple structure to handle file attributes *)
288 module Attribute: sig
289
290 include OpamStd.ABSTRACT
291
292 val to_string_list: t -> string list
293
294 val of_string_list: string list -> t
295
296 (** Get remote filename *)
297 val base: t -> Base.t
298
299 (** MD5 digest of the remote file *)
300 val md5: t -> OpamHash.t
301
302 (** File permission *)
303 val perm: t -> int option
304
305 (** Constructor*)
306 val create: Base.t -> OpamHash.t -> int option -> t
307
308 end
309
310 (* Subpathes handling *)
311 module SubPath: sig
312
313 include OpamStd.ABSTRACT
314
315 (* Directory concatenation *)
316 val (/): Dir.t -> t -> Dir.t
317
318 (* Directory concatenation with an optional argument *)
319 val (/?): Dir.t -> t option -> Dir.t
320
321 (* Subpath string with no file separator conversion *)
322 val normalised_string: t -> string
323
324 end
325
326 (** Convert a filename to an attribute, relatively to a root *)
327 val to_attribute: Dir.t -> t -> Attribute.t