mirror of
https://github.com/libguestfs/libguestfs.git
synced 2026-03-21 22:53:37 +00:00
02b64d5cec
This change was done almost entirely automatically using the script
below. This uses the OCaml lexer to read the source files and extract
the strings and locations. Strings which are "candidates" (in this
case, longer than 3 lines) are replaced in the output with quoted
string literals.
Since the OCaml lexer is used, it already substitutes all escape
sequences correctly. I diffed the output of the generator and it is
identical after this change, except for UUIDs, which change because of
how Utils.stable_uuid is implemented.
Thanks: Nicolas Ojeda Bar
$ ocamlfind opt -package unix,compiler-libs.common find_strings.ml \
-o find_strings.opt -linkpkg
$ for f in $( git ls-files -- \*.ml ) ; do ./find_strings.opt $f ; done
open Printf
let read_whole_file path =
let buf = Buffer.create 16384 in
let chan = open_in path in
let maxlen = 16384 in
let b = Bytes.create maxlen in
let rec loop () =
let r = input chan b 0 maxlen in
if r > 0 then (
Buffer.add_substring buf (Bytes.to_string b) 0 r;
loop ()
)
in
loop ();
close_in chan;
Buffer.contents buf
let count_chars c str =
let count = ref 0 in
for i = 0 to String.length str - 1 do
if c = String.unsafe_get str i then incr count
done;
!count
let subs = ref []
let consider_string str loc =
let nr_lines = count_chars '\n' str in
if nr_lines > 3 then
subs := (str, loc) :: !subs
let () =
Lexer.init ();
let filename = Sys.argv.(1) in
let content = read_whole_file filename in
let lexbuf = Lexing.from_string content in
let rec loop () =
let token = Lexer.token lexbuf in
(match token with
| Parser.EOF -> ();
| STRING (s, loc, sopt) ->
consider_string s loc; (* sopt? *)
loop ();
| token ->
loop ();
)
in
loop ();
(* The list of subs is already reversed, which is convenient
* because we must the file substitutions in reverse order.
*)
let subs = !subs in
let new_content = ref content in
List.iter (
fun (str, loc) ->
let { Location.loc_start = { pos_cnum = p1 };
loc_end = { pos_cnum = p2 } } = loc in
let len = String.length !new_content in
let before = String.sub !new_content 0 (p1-1) in
let after = String.sub !new_content (p2+1) (len - p2 - 1) in
new_content := before ^ "{|" ^ str ^ "|}" ^ after
) subs;
let new_content = !new_content in
if content <> new_content then (
(* Update the file in place. *)
let new_filename = filename ^ ".new"
and backup_filename = filename ^ ".bak" in
let chan = open_out new_filename in
fprintf chan "%s" new_content;
close_out chan;
Unix.rename filename backup_filename;
Unix.rename new_filename filename
)
This program generates a large amount of code and documentation for all the daemon actions. To add a new action there are only two files you need to change, 'actions_*.ml' to describe the interface, and daemon/<somefile>.c to write the implementation. After editing these files, build it (make -C generator) to regenerate all the output files. 'make' will rerun this automatically when necessary. IMPORTANT: This program should NOT print any warnings at compile time or run time. If it prints warnings, you should treat them as errors. OCaml tips: (1) In emacs, install tuareg-mode to display and format OCaml code correctly. 'vim' comes with a good OCaml editing mode by default. (2) Read the resources at http://ocaml.org/learn/ (3) A module called 'Foo' is defined in one or two files called 'foo.mli' and 'foo.ml' (NB: lowercase first letter). The *.mli file, if present, defines the public interface for the module. The *.ml file is the implementation. If the *.mli file is missing then everything is exported. Some notable files in this directory: actions_*.ml The libguestfs API. proc_nr.ml Procedure numbers associated with each API. structs.ml Structures returned by the API. c.ml Generate C API. <lang>.ml Generate bindings for <lang>. main.ml The main generator program. Note about long descriptions: When referring to another action, use the format C<guestfs_other> (ie. the full name of the C function). This will be replaced as appropriate in other language bindings. Apart from that, long descriptions are just perldoc paragraphs. Note about extending functions: In general you cannot change the name, number of required arguments or type of required arguments of a function, since this would break backwards compatibility. You may add another optional argument, *if* the function has >= 1 optional arguments already. Add it at the end of the list. You may add optional arguments to a function that doesn't have any. However you *must* set the once_had_no_optargs flag to true, so that the relevant backwards compatibility bindings can be added.