Debian Codegraph @

vendor/opam/src/core/opamUrl.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 (** URL parsing and printing, with support for our different backends *)
13
14 type version_control = [ `git | `darcs | `hg ]
15
16 type backend = [ `http | `rsync | version_control ]
17
18 val string_of_backend: backend -> string
19
20 exception Parse_error of string
21
22 (** Tolerates lots of backward compatibility names;
23 @raise Parse_error on unknown protocol *)
24 val backend_of_string: string -> [> backend]
25
26 type t = {
27 transport: string; (** the part just before '://' *)
28 path: string; (** the part after '://' *)
29 hash: string option; (** the optional branch/ref specification,
30 at the end after a '#' *)
31 backend: backend; (** the backend that opam should use to handle this
32 url *)
33 }
34
35 (** Same as [of_string], but allows enforcing the expected backend, and may
36 otherwise guess version control from the suffix by default (for e.g.
37 https://foo/bar.git). (this should be disabled when parsing from files).
38 Note that [handle_suffix] also handles user-name in ssh addresses (e.g.
39 "ssh://[email protected]/..."). If [from_file] is set to false, it resolves
40 rsync/file relative path.
41 @raise Parse_error *)
42 val parse:
43 ?backend:backend -> ?handle_suffix:bool -> ?from_file:bool -> string -> t
44
45 (** Same as [parse], but catch [Parse_error]. In this case, display a warning
46 if [quiet] is not set to true. *)
47 val parse_opt:
48 ?quiet:bool -> ?backend:backend -> ?handle_suffix:bool -> ?from_file:bool
49 -> string -> t option
50
51 include OpamStd.ABSTRACT with type t := t
52
53 (* [to_string_w_subpath subpath url] Return string of [url] with [subpath]
54 integrated *)
55 val to_string_w_subpath: OpamFilename.SubPath.t option -> t -> string
56
57 (** Dummy filler url *)
58 val empty: t
59
60 (** Returns the url string without the VC part (i.e. "git+foo://bar" returns
61 "foo://bar") *)
62 val base_url: t -> string
63
64 (** The last part of the url path, e.g. ["http://foo/bar/this"] or
65 ["http://that.here/"] *)
66 val basename: t -> string
67
68 (** Returns the url with all path components but the first one (the hostname)
69 dropped, e.g. ["http://some.host/some/path"] becomes ["http://some.host"] *)
70 val root: t -> t
71
72 val has_trailing_slash: t -> bool
73
74 (** Check if the URL matches an existing local directory, and return it *)
75 val local_dir: t -> OpamFilename.Dir.t option
76
77 (** Check if the URL matches an existing local file, and return it *)
78 val local_file: t -> OpamFilename.t option
79
80 (** If the given url-string has no 'transport://' specification and corresponds
81 to an existing local path, check for version-control clues at that path *)
82 val guess_version_control: string -> [> version_control ] option
83
84 (** [map_file_url f url] applies [f] to the [path] portion of [url] if
85 [transport] is ["file"]. *)
86 val map_file_url : (string -> string) -> t -> t
87
88 module Op: sig
89
90 (** Appends at the end of an URL path with '/' separator. Gets back to the
91 root if the second argument starts with '/' *)
92 val ( / ) : t -> string -> t
93
94 end