build: Allow 'make quickcheck' test-tool args to be overridden.
[libguestfs.git] / generator / generator_utils.mli
1 (* libguestfs
2  * Copyright (C) 2009-2011 Red Hat Inc.
3  *
4  * This program is free software; you can redistribute it and/or modify
5  * it under the terms of the GNU General Public License as published by
6  * the Free Software Foundation; either version 2 of the License, or
7  * (at your option) any later version.
8  *
9  * This program is distributed in the hope that it will be useful,
10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12  * GNU General Public License for more details.
13  *
14  * You should have received a copy of the GNU General Public License
15  * along with this program; if not, write to the Free Software
16  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
17  *)
18
19 (* Please read generator/README first. *)
20
21 (** Useful utility functions. *)
22
23 val errcode_of_ret : Generator_types.ret -> Generator_types.errcode
24 (** Map [ret] type to the error indication that the action returns,
25     eg. [errcode_of_ret RErr] => [`ErrorIsMinusOne] (meaning that
26     these actions return [-1]).
27
28     Note that [RConstOptString] cannot return an error indication, and
29     this returns [`CannotReturnError].  Callers must deal with it. *)
30
31 val string_of_errcode : [`ErrorIsMinusOne|`ErrorIsNULL] -> string
32 (** Return errcode as a string.  Untyped for [`CannotReturnError]. *)
33
34 val uuidgen : unit -> string
35 (** Generate a random UUID (used in tests). *)
36
37 type rstructs_used_t = RStructOnly | RStructListOnly | RStructAndList
38 (** Return type of {!rstructs_used_by}. *)
39
40 val rstructs_used_by : Generator_types.action list -> (string * rstructs_used_t) list
41 (** Returns a list of RStruct/RStructList structs that are returned
42     by any function. *)
43
44 val failwithf : ('a, unit, string, 'b) format4 -> 'a
45 (** Like [failwith] but supports printf-like arguments. *)
46
47 val unique : unit -> int
48 (** Returns a unique number each time called. *)
49
50 val replace_char : string -> char -> char -> string
51 (** Replace character in string. *)
52
53 val isspace : char -> bool
54 (** Return true if char is a whitespace character. *)
55
56 val triml : ?test:(char -> bool) -> string -> string
57 (** Trim left. *)
58
59 val trimr : ?test:(char -> bool) -> string -> string
60 (** Trim right. *)
61
62 val trim : ?test:(char -> bool) -> string -> string
63 (** Trim left and right. *)
64
65 val find : string -> string -> int
66 (** [find str sub] searches for [sub] in [str], returning the index
67     or -1 if not found. *)
68
69 val replace_str : string -> string -> string -> string
70 (** [replace_str str s1 s2] replaces [s1] with [s2] throughout [str]. *)
71
72 val string_split : string -> string -> string list
73 (** [string_split sep str] splits [str] at [sep]. *)
74
75 val files_equal : string -> string -> bool
76 (** [files_equal filename1 filename2] returns true if the files contain
77     the same content. *)
78
79 val filter_map : ('a -> 'b option) -> 'a list -> 'b list
80
81 val find_map : ('a -> 'b option) -> 'a list -> 'b
82
83 val iteri : (int -> 'a -> unit) -> 'a list -> unit
84
85 val mapi : (int -> 'a -> 'b) -> 'a list -> 'b list
86
87 val count_chars : char -> string -> int
88 (** Count number of times the character occurs in string. *)
89
90 val explode : string -> char list
91 (** Explode a string into a list of characters. *)
92
93 val map_chars : (char -> 'a) -> string -> 'a list
94 (** Explode string, then map function over the characters. *)
95
96 val name_of_argt : Generator_types.argt -> string
97 (** Extract argument name. *)
98
99 val seq_of_test : Generator_types.test -> Generator_types.seq
100 (** Extract test sequence from a test. *)
101
102 val c_quote : string -> string
103 (** Perform quoting on a string so it is safe to include in a C source file. *)
104
105 val pod2text : ?width:int -> ?trim:bool -> ?discard:bool -> string -> string -> string list
106   (** [pod2text ?width ?trim ?discard name longdesc] converts the POD in
107       [longdesc] to plain ASCII lines of text.
108
109       [width] is the width in characters.  If not specified, then
110       use the pod2text default.
111
112       [trim] means trim the left margin (useful when including the
113       output inside comments, as in Java generator).
114
115       [discard] means discard the first heading.
116
117       This is the slowest part of autogeneration, so the results are
118       memoized into a temporary file. *)
119
120 val action_compare : Generator_types.action -> Generator_types.action -> int
121   (** Compare the names of two actions, for sorting. *)
122
123 val chars : char -> int -> string
124 (** [chars c n] creates a string containing character c repeated n times. *)
125
126 val spaces : int -> string
127 (** [spaces n] creates a string of n spaces. *)