| 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 |