From ca056d53bdfd2967be8a0d6908d658e25571878d Mon Sep 17 00:00:00 2001 From: Matthew Booth Date: Mon, 4 Feb 2013 14:11:57 +0000 Subject: [PATCH] generator: Add visibility to action struct The visibility field in action replaces in_fish, in_docs and internal. The defined types are: VPublic: A public API. This is exported and documented in all language bindings, and in guestfish. VStateTest: A public API which queries the library state machine. It is exported and documented in all language bindings, but not guestfish. VBindTest: An internal API used only for testing language bindings. It is guarded by GUESTFS_PRIVATE in the C api, but exported by all other language bindings as it is required for testing. If language bindings offer any way to guard use of these apis, that mechanism should be used. It is not documented anywhere. VDebug: A debugging API. It is exported by all language bindings, and in guestfish, but is not documented anywhere. VInternal: An internal-only API. It is guarded by GUESTFS_PRIVATE in the C api, and not exported at all in any other language binding. It is not documented anywhere. --- generator/actions.ml | 84 +++++++++++++++++++++++++++++-------------- generator/actions.mli | 24 +++++++++++++ generator/c.ml | 27 +++++++++----- generator/csharp.ml | 4 +-- generator/erlang.ml | 10 +++--- generator/fish.ml | 46 +++++++++--------------- generator/gobject.ml | 6 ++-- generator/haskell.ml | 4 +-- generator/java.ml | 52 +++++++++++++-------------- generator/lua.ml | 8 ++--- generator/main.ml | 4 +-- generator/ocaml.ml | 18 +++++----- generator/perl.ml | 14 ++++---- generator/php.ml | 6 ++-- generator/python.ml | 26 +++++++------- generator/ruby.ml | 35 +++++++++--------- generator/types.ml | 13 ++++--- 17 files changed, 218 insertions(+), 163 deletions(-) diff --git a/generator/actions.ml b/generator/actions.ml index b884e4985..96702f758 100644 --- a/generator/actions.ml +++ b/generator/actions.ml @@ -27,8 +27,8 @@ open Utils let defaults = { name = ""; style = RErr, [], []; proc_nr = None; tests = []; shortdesc = ""; longdesc = ""; protocol_limit_warning = false; fish_alias = []; - fish_output = None; in_fish = true; in_docs = true; - internal = false; deprecated_by = None; optional = None; + fish_output = None; visibility = VPublic; + deprecated_by = None; optional = None; progress = false; camel_name = ""; cancellable = false; config_only = false; once_had_no_optargs = false; blocking = true; @@ -76,7 +76,7 @@ let test_functions = [ { defaults with name = "internal_test"; style = RErr, test_all_args, test_all_optargs; - in_fish = false; in_docs = false; internal = true; cancellable = true; + visibility = VBindTest; cancellable = true; blocking = false; shortdesc = "internal test function - do not use"; longdesc = "\ @@ -92,7 +92,7 @@ You probably don't want to call this function." }; { defaults with name = "internal_test_only_optargs"; style = RErr, [], [OInt "test"]; - in_fish = false; in_docs = false; internal = true; cancellable = true; + visibility = VBindTest; cancellable = true; blocking = false; shortdesc = "internal test function - do not use"; longdesc = "\ @@ -108,7 +108,7 @@ You probably don't want to call this function." }; { defaults with name = "internal_test_63_optargs"; style = RErr, [], [OInt "opt1"; OInt "opt2"; OInt "opt3"; OInt "opt4"; OInt "opt5"; OInt "opt6"; OInt "opt7"; OInt "opt8"; OInt "opt9"; OInt "opt10"; OInt "opt11"; OInt "opt12"; OInt "opt13"; OInt "opt14"; OInt "opt15"; OInt "opt16"; OInt "opt17"; OInt "opt18"; OInt "opt19"; OInt "opt20"; OInt "opt21"; OInt "opt22"; OInt "opt23"; OInt "opt24"; OInt "opt25"; OInt "opt26"; OInt "opt27"; OInt "opt28"; OInt "opt29"; OInt "opt30"; OInt "opt31"; OInt "opt32"; OInt "opt33"; OInt "opt34"; OInt "opt35"; OInt "opt36"; OInt "opt37"; OInt "opt38"; OInt "opt39"; OInt "opt40"; OInt "opt41"; OInt "opt42"; OInt "opt43"; OInt "opt44"; OInt "opt45"; OInt "opt46"; OInt "opt47"; OInt "opt48"; OInt "opt49"; OInt "opt50"; OInt "opt51"; OInt "opt52"; OInt "opt53"; OInt "opt54"; OInt "opt55"; OInt "opt56"; OInt "opt57"; OInt "opt58"; OInt "opt59"; OInt "opt60"; OInt "opt61"; OInt "opt62"; OInt "opt63"]; - in_fish = false; in_docs = false; internal = true; cancellable = true; + visibility = VBindTest; cancellable = true; blocking = false; shortdesc = "internal test function - do not use"; longdesc = "\ @@ -128,7 +128,7 @@ You probably don't want to call this function." } { defaults with name = name; style = ret, [String "val"], []; - in_fish = false; in_docs = false; internal = true; + visibility = VBindTest; blocking = false; shortdesc = "internal test function - do not use"; longdesc = "\ @@ -142,7 +142,7 @@ You probably don't want to call this function." }; { defaults with name = name ^ "err"; style = ret, [], []; - in_fish = false; in_docs = false; internal = true; + visibility = VBindTest; blocking = false; shortdesc = "internal test function - do not use"; longdesc = "\ @@ -166,7 +166,7 @@ let non_daemon_functions = test_functions @ [ { defaults with name = "internal_test_set_output"; style = RErr, [String "filename"], []; - in_fish = false; in_docs = false; internal = true; + visibility = VBindTest; blocking = false; shortdesc = "internal test function - do not use"; longdesc = "\ @@ -181,7 +181,7 @@ You probably don't want to call this function." }; { defaults with name = "internal_test_close_output"; style = RErr, [], []; - in_fish = false; in_docs = false; internal = true; + visibility = VBindTest; blocking = false; shortdesc = "internal test function - do not use"; longdesc = "\ @@ -214,7 +214,8 @@ very cheap to create, so create a new one for each launch." }; { defaults with name = "wait_ready"; style = RErr, [], []; - in_fish = false; deprecated_by = Some "launch"; + visibility = VStateTest; + deprecated_by = Some "launch"; blocking = false; shortdesc = "wait until the qemu subprocess launches (no op)"; longdesc = "\ @@ -434,6 +435,7 @@ This returns the verbose messages flag." }; { defaults with name = "is_ready"; style = RBool "ready", [], []; + visibility = VStateTest; blocking = false; tests = [ InitNone, Always, TestOutputTrue ( @@ -464,6 +466,7 @@ For more information on states, see L." }; { defaults with name = "is_launching"; style = RBool "launching", [], []; + visibility = VStateTest; blocking = false; tests = [ InitNone, Always, TestOutputFalse ( @@ -479,7 +482,7 @@ For more information on states, see L." }; { defaults with name = "is_busy"; style = RBool "busy", [], []; - in_docs = false; + visibility = VStateTest; blocking = false; tests = [ InitNone, Always, TestOutputFalse ( @@ -487,13 +490,15 @@ For more information on states, see L." }; ]; shortdesc = "is busy processing a command"; longdesc = "\ -This always returns false. Do not use this function. +This always returns false. This function is deprecated with no +replacement. Do not use this function. For more information on states, see L." }; { defaults with name = "get_state"; style = RInt "state", [], []; + visibility = VStateTest; blocking = false; shortdesc = "get the current state"; longdesc = "\ @@ -1344,7 +1349,7 @@ Please read L for more details." }; { defaults with name = "debug_drives"; style = RStringList "cmdline", [], []; - in_docs = false; + visibility = VDebug; blocking = false; shortdesc = "debug the drives (internal use only)"; longdesc = "\ @@ -4232,7 +4237,7 @@ as for the L I<-o> and I<-t> flags." }; name = "debug"; style = RString "result", [String "subcmd"; StringList "extraargs"], []; proc_nr = Some 76; - in_docs = false; + visibility = VDebug; shortdesc = "debugging and internals"; longdesc = "\ The C command exposes some internals of @@ -6826,7 +6831,7 @@ yourself (Augeas support makes this relatively easy)." }; name = "internal_lstatlist"; style = RStructList ("statbufs", "stat"), [Pathname "path"; StringList "names"], []; proc_nr = Some 204; - in_docs = false; in_fish = false; internal = true; + visibility = VInternal; shortdesc = "lstat on multiple files"; longdesc = "\ This call allows you to perform the C operation @@ -6850,7 +6855,7 @@ into smaller groups of names." }; name = "internal_lxattrlist"; style = RStructList ("xattrs", "xattr"), [Pathname "path"; StringList "names"], []; proc_nr = Some 205; - in_docs = false; in_fish = false; internal = true; + visibility = VInternal; optional = Some "linuxxattrs"; shortdesc = "lgetxattr on multiple files"; longdesc = "\ @@ -6880,7 +6885,7 @@ into smaller groups of names." }; name = "internal_readlinklist"; style = RStringList "links", [Pathname "path"; StringList "names"], []; proc_nr = Some 206; - in_docs = false; in_fish = false; internal = true; + visibility = VInternal; shortdesc = "readlink on multiple files"; longdesc = "\ This call allows you to do a C operation @@ -7603,7 +7608,8 @@ unless it has been set by calling C." }; name = "debug_upload"; style = RErr, [FileIn "filename"; String "tmpname"; Int "mode"], []; proc_nr = Some 241; - in_docs = false; cancellable = true; + visibility = VDebug; + cancellable = true; shortdesc = "upload a file to the appliance (internal use only)"; longdesc = "\ The C command uploads a file to @@ -7678,7 +7684,7 @@ to ensure the length of the file is exactly C bytes." }; name = "internal_write"; style = RErr, [Pathname "path"; BufferIn "content"], []; proc_nr = Some 246; - in_fish = false; in_docs = false; internal = true; + visibility = VInternal; protocol_limit_warning = true; tests = [ InitScratchFS, Always, TestOutput ( @@ -8394,7 +8400,7 @@ See also L." }; name = "internal_autosync"; style = RErr, [], []; proc_nr = Some 282; - in_fish = false; in_docs = false; internal = true; + visibility = VInternal; shortdesc = "internal autosync operation"; longdesc = "\ This command performs the autosync operation just before the @@ -8540,7 +8546,7 @@ See also L." }; name = "internal_write_append"; style = RErr, [Pathname "path"; BufferIn "content"], []; proc_nr = Some 290; - in_fish = false; in_docs = false; internal = true; + visibility = VInternal; protocol_limit_warning = true; tests = [ InitScratchFS, Always, TestOutput ( @@ -10302,7 +10308,7 @@ are the full raw block device and partition names name = "internal_hot_add_drive"; style = RErr, [String "label"], []; proc_nr = Some 370; - in_fish = false; in_docs = false; internal = true; + visibility = VInternal; tests = []; shortdesc = "internal hotplugging operation"; longdesc = "\ @@ -10312,7 +10318,7 @@ This function is used internally when hotplugging drives." }; name = "internal_hot_remove_drive_precheck"; style = RErr, [String "label"], []; proc_nr = Some 371; - in_fish = false; in_docs = false; internal = true; + visibility = VInternal; tests = []; shortdesc = "internal hotplugging operation"; longdesc = "\ @@ -10322,7 +10328,7 @@ This function is used internally when hotplugging drives." }; name = "internal_hot_remove_drive"; style = RErr, [String "label"], []; proc_nr = Some 372; - in_fish = false; in_docs = false; internal = true; + visibility = VInternal; tests = []; shortdesc = "internal hotplugging operation"; longdesc = "\ @@ -11054,11 +11060,31 @@ let non_daemon_functions, daemon_functions = (* All functions. *) let all_functions = non_daemon_functions @ daemon_functions +let is_external { visibility = v } = match v with + | VPublic | VStateTest | VBindTest | VDebug -> true + | VInternal -> false + +let is_internal f = not (is_external f) + +let is_documented { visibility = v } = match v with + | VPublic | VStateTest -> true + | VBindTest | VDebug | VInternal -> false + +let is_fish { visibility = v } = match v with + | VPublic | VDebug -> true + | VStateTest | VBindTest | VInternal -> false + let external_functions = - List.filter (fun x -> not x.internal) all_functions + List.filter is_external all_functions let internal_functions = - List.filter (fun x -> x.internal) all_functions + List.filter is_internal all_functions + +let documented_functions = + List.filter is_documented all_functions + +let fish_functions = + List.filter is_fish all_functions (* In some places we want the functions to be displayed sorted * alphabetically, so this is useful: @@ -11071,6 +11097,12 @@ let external_functions_sorted = let internal_functions_sorted = List.sort action_compare internal_functions +let documented_functions_sorted = + List.sort action_compare documented_functions + +let fish_functions_sorted = + List.sort action_compare fish_functions + (* This is used to generate the src/MAX_PROC_NR file which * contains the maximum procedure number, a surrogate for the * ABI version number. See src/Makefile.am for the details. diff --git a/generator/actions.mli b/generator/actions.mli index e5f05a281..eb96b4908 100644 --- a/generator/actions.mli +++ b/generator/actions.mli @@ -29,12 +29,30 @@ val daemon_functions : Types.action list val all_functions : Types.action list (** Concatenation of [non_daemon_functions] and [daemon_functions] lists. *) +val is_external : Types.action -> bool +(** Returns true if function is external, false otherwise *) + +val is_internal : Types.action -> bool +(** Returns true if function is internal, false otherwise *) + +val is_documented : Types.action -> bool +(** Returns true if function should be documented, false otherwise *) + +val is_fish : Types.action -> bool +(** Returns true if function should be in guestfish, false otherwise *) + val external_functions : Types.action list (** [all_functions] filtered for external functions **) val internal_functions : Types.action list (** [all_functions] filtered for internal functions **) +val documented_functions : Types.action list +(** [all_functions] filtered for functions requiring documentation **) + +val fish_functions : Types.action list +(** [all_functions] filtered for functions in guestfish **) + val all_functions_sorted : Types.action list (** [all_functions] but sorted by name. *) @@ -44,6 +62,12 @@ val external_functions_sorted : Types.action list val internal_functions_sorted : Types.action list (** [internal_functions] but sorted by name. *) +val documented_functions_sorted : Types.action list +(** [documented_functions] but sorted by name. *) + +val fish_functions_sorted : Types.action list +(** [fish_functions] but sorted by name. *) + val test_functions : Types.action list (** Internal test functions used to test the language bindings. *) diff --git a/generator/c.ml b/generator/c.ml index 47df9e451..518ac1bab 100644 --- a/generator/c.ml +++ b/generator/c.ml @@ -44,6 +44,18 @@ let hash_matches h { name = name } = type optarg_proto = Dots | VA | Argv +let is_public { visibility = v } = match v with + | VPublic | VStateTest | VDebug -> true + | VBindTest | VInternal -> false + +let is_private f = not (is_public f) + +let public_functions_sorted = + List.filter is_public all_functions_sorted + +let private_functions_sorted = + List.filter is_private all_functions_sorted + (* Generate a C function prototype. *) let rec generate_prototype ?(extern = true) ?(static = false) ?(semicolon = true) @@ -186,13 +198,12 @@ and generate_c_call_args ?handle ?(implicit_size_ptr = "&size") and generate_actions_pod () = List.iter ( function - | { in_docs = false } -> () - | ({ in_docs = true; once_had_no_optargs = false } as f) -> + | ({ once_had_no_optargs = false } as f) -> generate_actions_pod_entry f - | ({ in_docs = true; once_had_no_optargs = true } as f) -> + | ({ once_had_no_optargs = true } as f) -> generate_actions_pod_back_compat_entry f; generate_actions_pod_entry f - ) all_functions_sorted + ) documented_functions_sorted and generate_actions_pod_entry ({ c_name = c_name; style = ret, args, optargs as style } as f) = @@ -679,7 +690,7 @@ extern GUESTFS_DLL_PUBLIC void *guestfs_next_private (guestfs_h *g, const char * generate_action_header f ) in - generate_all_headers external_functions_sorted; + generate_all_headers public_functions_sorted; pr "\ #if GUESTFS_PRIVATE @@ -694,7 +705,7 @@ extern GUESTFS_DLL_PUBLIC int guestfs___for_each_disk (guestfs_h *g, /* virDomai "; - generate_all_headers internal_functions_sorted; + generate_all_headers private_functions_sorted; pr "\ /* Private structures. */ @@ -711,7 +722,7 @@ pr "\ List.iter ( fun { name = shortname } -> pr "#define LIBGUESTFS_HAVE_%s 1\n" (String.uppercase shortname); - ) internal_functions_sorted; + ) private_functions_sorted; pr "\ @@ -738,7 +749,7 @@ pr "\ List.iter ( fun { name = shortname } -> pr "#define LIBGUESTFS_HAVE_%s 1\n" (String.uppercase shortname); - ) external_functions_sorted; + ) public_functions_sorted; pr " /* End of deprecated macros. */ diff --git a/generator/csharp.ml b/generator/csharp.ml index d2268d14b..de54e6281 100644 --- a/generator/csharp.ml +++ b/generator/csharp.ml @@ -131,7 +131,7 @@ namespace Guestfs ) cols; pr " }\n"; pr "\n" - ) structs; + ) external_structs; (* Generate C# function bindings. *) List.iter ( @@ -282,7 +282,7 @@ namespace Guestfs pr "\n"; List.iter generate_alias non_c_aliases - ) all_functions_sorted; + ) external_functions_sorted; pr " } } diff --git a/generator/erlang.ml b/generator/erlang.ml index 68418fb87..357335b86 100644 --- a/generator/erlang.ml +++ b/generator/erlang.ml @@ -50,7 +50,7 @@ let rec generate_erlang_erl () = in export name; List.iter export aliases - ) all_functions_sorted; + ) external_functions_sorted; pr "\n"; @@ -178,7 +178,7 @@ loop(Port) -> ) aliases; pr "\n" - ) all_functions_sorted + ) external_functions_sorted and generate_erlang_c () = generate_header CStyle GPLv2plus; @@ -279,7 +279,7 @@ extern void free_strings (char **r); (* generate the function for typ *) emit_copy_list_function typ | typ, _ -> () (* empty *) - ) (rstructs_used_by all_functions); + ) (rstructs_used_by external_functions); (* The wrapper functions. *) List.iter ( @@ -460,7 +460,7 @@ extern void free_strings (char **r); pr "}\n"; pr "\n"; - ) all_functions_sorted; + ) external_functions_sorted; pr "\ @@ -479,7 +479,7 @@ dispatch (ETERM *message) pr "if (atom_equals (fun, \"%s\"))\n" name; pr " return run_%s (message);\n" name; pr " else "; - ) all_functions_sorted; + ) external_functions_sorted; pr "return unknown_function (fun); } diff --git a/generator/fish.ml b/generator/fish.ml index a6a1ee3bc..b93f4fc15 100644 --- a/generator/fish.ml +++ b/generator/fish.ml @@ -31,6 +31,9 @@ open Prepopts open C open Events +let fish_functions_and_commands_sorted = + List.sort action_compare (fish_functions_sorted @ fish_commands) + let doc_opttype_of = function | OBool n -> "true|false" | OInt n @@ -47,13 +50,6 @@ let get_aliases { fish_alias = fish_alias; non_c_aliases = non_c_aliases } = let generate_fish_cmds () = generate_header CStyle GPLv2plus; - let all_functions = - List.filter (fun { in_fish = b } -> b) all_functions in - let all_functions_sorted = - List.filter (fun { in_fish = b } -> b) all_functions_sorted in - - let all_functions_and_fish_commands_sorted = - List.sort action_compare (all_functions_sorted @ fish_commands) in pr "#include \n"; pr "\n"; @@ -84,7 +80,7 @@ let generate_fish_cmds () = fun { name = name } -> pr "static int run_%s (const char *cmd, size_t argc, char *argv[]);\n" name - ) all_functions; + ) fish_functions; pr "\n"; @@ -174,7 +170,7 @@ Guestfish will prompt for these separately." pr " .run = run_%s\n" name; pr "};\n"; pr "\n"; - ) all_functions; + ) fish_functions; (* list_commands function, which implements guestfish -h *) pr "void\n"; @@ -187,7 +183,7 @@ Guestfish will prompt for these separately." let name = replace_char name '_' '-' in pr " printf (\"%%-20s %%s\\n\", \"%s\", _(\"%s\"));\n" name shortdesc - ) all_functions_and_fish_commands_sorted; + ) fish_functions_and_commands_sorted; pr " printf (\" %%s\\n\","; pr " _(\"Use -h / help to show detailed help for a command.\"));\n"; pr "}\n"; @@ -288,7 +284,7 @@ Guestfish will prompt for these separately." (* generate the function for typ *) emit_print_list_function typ | typ, _ -> () (* empty *) - ) (rstructs_used_by all_functions); + ) (rstructs_used_by fish_functions); (* Emit a print_TYPE function definition only if that function is used. *) List.iter ( @@ -301,7 +297,7 @@ Guestfish will prompt for these separately." pr "}\n"; pr "\n"; | typ, _ -> () (* empty *) - ) (rstructs_used_by all_functions); + ) (rstructs_used_by fish_functions); (* run_ actions *) List.iter ( @@ -647,7 +643,7 @@ Guestfish will prompt for these separately." pr " return ret;\n"; pr "}\n"; pr "\n" - ) all_functions; + ) fish_functions; (* run_action function *) pr "int\n"; @@ -686,12 +682,6 @@ and generate_fish_cmds_h () = and generate_fish_cmds_gperf () = generate_header CStyle GPLv2plus; - let all_functions_sorted = - List.filter (fun { in_fish = b } -> b) all_functions_sorted in - - let all_functions_and_fish_commands_sorted = - List.sort action_compare (all_functions_sorted @ fish_commands) in - pr "\ %%language=ANSI-C %%define lookup-function-name lookup_fish_command @@ -713,7 +703,7 @@ and generate_fish_cmds_gperf () = List.iter ( fun { name = name } -> pr "extern struct command_entry %s_cmd_entry;\n" name - ) all_functions_and_fish_commands_sorted; + ) fish_functions_and_commands_sorted; pr "\ %%} @@ -740,15 +730,12 @@ struct command_table; fun alias -> pr "%s, &%s_cmd_entry\n" alias name; ) aliases; - ) all_functions_and_fish_commands_sorted + ) fish_functions_and_commands_sorted (* Readline completion for guestfish. *) and generate_fish_completion () = generate_header CStyle GPLv2plus; - let all_functions = - List.filter (fun { in_fish = b } -> b) all_functions in - pr "\ #include @@ -777,7 +764,7 @@ static const char *const commands[] = { let aliases = get_aliases f in let name2 = replace_char name '_' '-' in name2 :: aliases - ) (all_functions @ fish_commands) in + ) (fish_functions_and_commands_sorted) in let commands = List.flatten commands in List.iter (pr " \"%s\",\n") commands; @@ -837,10 +824,9 @@ do_completion (const char *text, int start, int end) (* Generate the POD documentation for guestfish. *) and generate_fish_actions_pod () = - let all_functions_sorted = - List.filter ( - fun { in_fish = in_fish; in_docs = in_docs } -> in_fish && in_docs - ) all_functions_sorted in + let fishdoc_functions_sorted = + List.filter is_documented fish_functions_sorted + in let rex = Str.regexp "C]+\\)>" in @@ -902,7 +888,7 @@ Guestfish will prompt for these separately.\n\n"; match deprecation_notice ~replace_underscores:true f with | None -> () | Some txt -> pr "%s\n\n" txt - ) all_functions_sorted + ) fishdoc_functions_sorted (* Generate documentation for guestfish-only commands. *) and generate_fish_commands_pod () = diff --git a/generator/gobject.ml b/generator/gobject.ml index 516956465..9b18de156 100644 --- a/generator/gobject.ml +++ b/generator/gobject.ml @@ -115,7 +115,7 @@ let filenames = function | { style = _, _, (_::_) } -> true | { style = _, _, [] } -> false - ) all_functions + ) external_functions ) let header_start filename = @@ -697,7 +697,7 @@ gboolean guestfs_session_close(GuestfsSession *session, GError **err); fun ({ name = name; style = style } as f) -> generate_gobject_proto name style f; pr ";\n"; - ) all_functions; + ) external_functions; header_end filename @@ -1276,4 +1276,4 @@ guestfs_session_close(GuestfsSession *session, GError **err) ); pr "}\n"; - ) all_functions + ) external_functions diff --git a/generator/haskell.ml b/generator/haskell.ml index 317184017..dc1925980 100644 --- a/generator/haskell.ml +++ b/generator/haskell.ml @@ -60,7 +60,7 @@ module Guestfs ( List.iter ( fun { name = name; style = style } -> if can_generate style then pr ",\n %s" name - ) all_functions; + ) external_functions; pr " ) where @@ -205,7 +205,7 @@ assocListOfHashtable (a:b:rest) = (a,b) : assocListOfHashtable rest ); pr "\n"; ) - ) all_functions + ) external_functions and generate_haskell_prototype ~handle ?(hs = false) (ret, args, optargs) = pr "%s -> " handle; diff --git a/generator/java.ml b/generator/java.ml index a7ad39a36..75732e811 100644 --- a/generator/java.ml +++ b/generator/java.ml @@ -246,11 +246,11 @@ public class GuestFS { (* Methods. *) List.iter ( - fun ({ name = name; style = (ret, args, optargs as style); - in_docs = in_docs; shortdesc = shortdesc; - longdesc = longdesc; non_c_aliases = non_c_aliases } as f) -> - if in_docs then ( - let doc = replace_str longdesc "C + let ret, args, optargs = f.style in + + if is_documented f then ( + let doc = replace_str f.longdesc "C [] then doc ^ "\n\nOptional arguments are supplied in the final Map parameter, which is a hash of the argument name to its value (cast to Object). Pass an empty Map or null for no optional arguments." @@ -263,7 +263,7 @@ public class GuestFS { match deprecation_notice f with | None -> doc | Some txt -> doc ^ "\n\n" ^ txt in - let doc = pod2text ~width:60 name doc in + let doc = pod2text ~width:60 f.name doc in let doc = List.map ( (* RHBZ#501883 *) function | "" -> "

" @@ -272,19 +272,19 @@ public class GuestFS { let doc = String.concat "\n * " doc in pr " /**\n"; - pr " * %s\n" shortdesc; + pr " * %s\n" f.shortdesc; pr " *

\n"; pr " * %s\n" doc; pr " * @throws LibGuestFSException\n"; pr " */\n"; ); pr " "; - generate_java_prototype ~public:true ~semicolon:false name style; + generate_java_prototype ~public:true ~semicolon:false f.name f.style; pr "\n"; pr " {\n"; pr " if (g == 0)\n"; pr " throw new LibGuestFSException (\"%s: handle is closed\");\n" - name; + f.name; if optargs <> [] then ( pr "\n"; pr " /* Unpack optional args. */\n"; @@ -313,12 +313,12 @@ public class GuestFS { pr "\n"; (match ret with | RErr -> - pr " _%s " name; - generate_java_call_args ~handle:"g" style; + pr " _%s " f.name; + generate_java_call_args ~handle:"g" f.style; pr ";\n" | RHashtable _ -> - pr " String[] r = _%s " name; - generate_java_call_args ~handle:"g" style; + pr " String[] r = _%s " f.name; + generate_java_call_args ~handle:"g" f.style; pr ";\n"; pr "\n"; pr " HashMap rhash = new HashMap ();\n"; @@ -326,8 +326,8 @@ public class GuestFS { pr " rhash.put (r[i], r[i+1]);\n"; pr " return rhash;\n" | _ -> - pr " return _%s " name; - generate_java_call_args ~handle:"g" style; + pr " return _%s " f.name; + generate_java_call_args ~handle:"g" f.style; pr ";\n" ); pr " }\n"; @@ -340,14 +340,14 @@ public class GuestFS { if optargs <> [] then ( pr " "; generate_java_prototype ~public:true ~semicolon:false - name (ret, args, []); + f.name (ret, args, []); pr "\n"; pr " {\n"; (match ret with | RErr -> pr " " | _ -> pr " return " ); - pr "%s (" name; + pr "%s (" f.name; List.iter (fun arg -> pr "%s, " (name_of_argt arg)) args; pr "null);\n"; pr " }\n"; @@ -358,14 +358,14 @@ public class GuestFS { List.iter ( fun alias -> pr " "; - generate_java_prototype ~public:true ~semicolon:false alias style; + generate_java_prototype ~public:true ~semicolon:false alias f.style; pr "\n"; pr " {\n"; (match ret with | RErr -> pr " " | _ -> pr " return " ); - pr "%s (" name; + pr "%s (" f.name; let needs_comma = ref false in List.iter ( fun arg -> @@ -392,20 +392,20 @@ public class GuestFS { | RErr -> pr " " | _ -> pr " return " ); - pr "%s (" name; + pr "%s (" f.name; List.iter (fun arg -> pr "%s, " (name_of_argt arg)) args; pr "null);\n"; pr " }\n"; pr "\n" ) - ) non_c_aliases; + ) f.non_c_aliases; (* Prototype for the native method. *) pr " "; - generate_java_prototype ~privat:true ~native:true name style; + generate_java_prototype ~privat:true ~native:true f.name f.style; pr "\n"; pr "\n"; - ) all_functions; + ) external_functions; pr "}\n" @@ -1100,7 +1100,7 @@ get_all_event_callbacks (guestfs_h *g, size_t *len_rtn) pr "}\n"; pr "\n" - ) all_functions + ) external_functions and generate_java_struct_return typ jtyp cols = pr " cl = (*env)->FindClass (env, \"com/redhat/et/libguestfs/%s\");\n" jtyp; @@ -1191,7 +1191,7 @@ and generate_java_struct_list_return typ jtyp cols = and generate_java_makefile_inc () = generate_header HashStyle GPLv2plus; - let jtyps = List.map (fun { s_camel_name = jtyp } -> jtyp) structs in + let jtyps = List.map (fun { s_camel_name = jtyp } -> jtyp) external_structs in let jtyps = List.sort compare jtyps in pr "java_built_sources = \\\n"; @@ -1201,7 +1201,7 @@ and generate_java_makefile_inc () = pr "\tcom/redhat/et/libguestfs/GuestFS.java\n" and generate_java_gitignore () = - let jtyps = List.map (fun { s_camel_name = jtyp } -> jtyp) structs in + let jtyps = List.map (fun { s_camel_name = jtyp } -> jtyp) external_structs in let jtyps = List.sort compare jtyps in List.iter (pr "%s.java\n") jtyps diff --git a/generator/lua.ml b/generator/lua.ml index c4e346331..691b966ae 100644 --- a/generator/lua.ml +++ b/generator/lua.ml @@ -107,7 +107,7 @@ static void free_strings (char **r); | typ, (RStructListOnly | RStructAndList) -> pr "static void push_%s (lua_State *L, struct guestfs_%s *v);\n" typ typ; pr "static void push_%s_list (lua_State *L, struct guestfs_%s_list *v);\n" typ typ - ) (rstructs_used_by all_functions); + ) (rstructs_used_by external_functions); pr "\ @@ -626,7 +626,7 @@ guestfs_lua_delete_event_callback (lua_State *L) pr " return 1;\n"; pr "}\n"; pr "\n" - ) all_functions_sorted; + ) external_functions_sorted; pr "\ static struct userdata * @@ -863,7 +863,7 @@ push_event (lua_State *L, uint64_t event) | typ, (RStructListOnly | RStructAndList) -> generate_push_struct typ; generate_push_struct_list typ - ) (rstructs_used_by all_functions); + ) (rstructs_used_by external_functions); pr "\ void @@ -901,7 +901,7 @@ static luaL_Reg methods[] = { List.iter ( fun { name = name } -> pr " { \"%s\", guestfs_lua_%s },\n" name name - ) all_functions_sorted; + ) external_functions_sorted; pr "\ diff --git a/generator/main.ml b/generator/main.ml index 59ed060bd..f4f05fb74 100644 --- a/generator/main.ml +++ b/generator/main.ml @@ -136,7 +136,7 @@ Run it from the top source directory using the command let cols = cols_of_struct typ in let filename = sprintf "java/com/redhat/et/libguestfs/%s.java" jtyp in output_to filename (generate_java_struct jtyp cols) - ) structs; + ) external_structs; delete_except_generated ~skip:["java/com/redhat/et/libguestfs/LibGuestFSException.java"; "java/com/redhat/et/libguestfs/EventCallback.java"] @@ -186,7 +186,7 @@ Run it from the top source directory using the command output_to filename (generate_gobject_optargs_source short name optargs f) | { style = _, _, [] } -> () - ) all_functions; + ) external_functions; delete_except_generated "gobject/include/guestfs-gobject/optargs-*.h"; delete_except_generated "gobject/src/optargs-*.c"; diff --git a/generator/ocaml.ml b/generator/ocaml.ml index 1771bc97e..80ab59600 100644 --- a/generator/ocaml.ml +++ b/generator/ocaml.ml @@ -130,12 +130,12 @@ val user_cancel : t -> unit (* The actions. *) List.iter ( - fun { name = name; style = style; deprecated_by = deprecated_by; + fun ({ name = name; style = style; deprecated_by = deprecated_by; non_c_aliases = non_c_aliases; - in_docs = in_docs; shortdesc = shortdesc } -> + shortdesc = shortdesc } as f) -> generate_ocaml_prototype name style; - if in_docs then ( + if is_documented f then ( pr "(** %s" shortdesc; (match deprecated_by with | None -> () @@ -152,7 +152,7 @@ val user_cancel : t -> unit generate_ocaml_prototype alias style; pr "\n"; ) non_c_aliases; - ) all_functions_sorted; + ) external_functions_sorted; pr "\ (** {2 Object-oriented API} @@ -203,7 +203,7 @@ class guestfs : ?environment:bool -> ?close_on_exit:bool -> unit -> object generate_ocaml_function_type style; pr "\n" ) non_c_aliases - ) all_functions_sorted; + ) external_functions_sorted; pr "end\n" @@ -268,7 +268,7 @@ let () = fun { name = name; style = style; non_c_aliases = non_c_aliases } -> generate_ocaml_prototype ~is_external:true name style; List.iter (fun alias -> pr "let %s = %s\n" alias name) non_c_aliases - ) all_functions_sorted; + ) external_functions_sorted; (* OO API. *) pr " @@ -297,7 +297,7 @@ class guestfs ?environment ?close_on_exit () = ); List.iter (fun alias -> pr " method %s = self#%s\n" alias name) non_c_aliases - ) all_functions_sorted; + ) external_functions_sorted; pr " end\n" @@ -431,7 +431,7 @@ copy_table (char * const * argv) (* generate the function for typ *) emit_ocaml_copy_list_function typ | typ, _ -> () (* empty *) - ) (rstructs_used_by all_functions); + ) (rstructs_used_by external_functions); (* The wrappers. *) List.iter ( @@ -668,7 +668,7 @@ copy_table (char * const * argv) pr "}\n"; pr "\n" ) - ) all_functions_sorted + ) external_functions_sorted and generate_ocaml_structure_decls () = List.iter ( diff --git a/generator/perl.ml b/generator/perl.ml index ae247e4d1..db11cb603 100644 --- a/generator/perl.ml +++ b/generator/perl.ml @@ -562,7 +562,7 @@ user_cancel (g) ); pr "\n" - ) all_functions + ) external_functions and generate_perl_struct_list_code typ cols name style n = pr " if (r == NULL)\n"; @@ -860,10 +860,8 @@ handlers and threads. * they are pulled in from the XS code automatically. *) List.iter ( - function - | { in_docs = false } -> () - | ({ name = name; style = style; in_docs = true; - longdesc = longdesc; non_c_aliases = non_c_aliases } as f) -> + fun ({ name = name; style = style; + longdesc = longdesc; non_c_aliases = non_c_aliases } as f) -> let longdesc = replace_str longdesc "C" in pr "=item "; generate_perl_prototype name style; @@ -893,7 +891,7 @@ handlers and threads. pr "=pod\n"; pr "\n"; ) non_c_aliases - ) all_functions_sorted; + ) documented_functions_sorted; pr "=cut\n\n"; @@ -955,7 +953,7 @@ handlers and threads. pr " name => \"%s\",\n" name; pr " description => %S,\n" shortdesc; pr " },\n"; - ) all_functions_sorted; + ) external_functions_sorted; pr ");\n\n"; pr "# Add aliases to the introspection hash.\n"; @@ -968,7 +966,7 @@ handlers and threads. pr "$guestfs_introspection{%s} = \\%%ielem%d;\n" alias !i; incr i ) non_c_aliases - ) all_functions_sorted; + ) external_functions_sorted; pr "\n"; (* End of file. *) diff --git a/generator/php.ml b/generator/php.ml index 6c31d12f7..6618ce55b 100644 --- a/generator/php.ml +++ b/generator/php.ml @@ -53,7 +53,7 @@ PHP_FUNCTION (guestfs_last_error); List.iter ( fun { name = name } -> pr "PHP_FUNCTION (guestfs_%s);\n" name - ) all_functions_sorted; + ) external_functions_sorted; pr "\ @@ -113,7 +113,7 @@ static zend_function_entry guestfs_php_functions[] = { List.iter ( fun { name = name } -> pr " PHP_FE (guestfs_%s, NULL)\n" name - ) all_functions_sorted; + ) external_functions_sorted; pr " { NULL, NULL, NULL } }; @@ -501,7 +501,7 @@ PHP_FUNCTION (guestfs_last_error) pr "}\n"; pr "\n" - ) all_functions_sorted + ) external_functions_sorted and generate_php_struct_code typ cols = pr " array_init (return_value);\n"; diff --git a/generator/python.ml b/generator/python.ml index 91e037f2d..9bff5b9e8 100644 --- a/generator/python.ml +++ b/generator/python.ml @@ -249,7 +249,7 @@ free_strings (char **argv) (* generate the function for typ *) emit_put_list_function typ | typ, _ -> () (* empty *) - ) (rstructs_used_by all_functions); + ) (rstructs_used_by external_functions); (* Python wrapper functions. *) List.iter ( @@ -523,7 +523,7 @@ free_strings (char **argv) pr " return py_r;\n"; pr "}\n"; pr "\n" - ) all_functions; + ) external_functions; (* Table of functions. *) pr "static PyMethodDef methods[] = {\n"; @@ -537,7 +537,7 @@ free_strings (char **argv) fun { name = name } -> pr " { (char *) \"%s\", py_guestfs_%s, METH_VARARGS, NULL },\n" name name - ) all_functions; + ) external_functions; pr " { NULL, NULL, 0, NULL }\n"; pr "};\n"; pr "\n"; @@ -729,9 +729,9 @@ class GuestFS(object): "; List.iter ( - fun ({ name = name; style = ret, args, optargs; in_docs = in_docs; - longdesc = longdesc; non_c_aliases = non_c_aliases } as f) -> - pr " def %s (self" name; + fun f -> + let ret, args, optargs = f.style in + pr " def %s (self" f.name; List.iter (fun arg -> pr ", %s" (name_of_argt arg)) args; List.iter ( fun optarg -> @@ -739,8 +739,8 @@ class GuestFS(object): ) optargs; pr "):\n"; - if in_docs then ( - let doc = replace_str longdesc "C doc | Some txt -> doc ^ "\n\n" ^ txt in - let doc = pod2text ~width:60 name doc in + let doc = pod2text ~width:60 f.name doc in let doc = List.map (fun line -> replace_str line "\\" "\\\\") doc in let doc = String.concat "\n " doc in pr " \"\"\"%s\"\"\"\n" doc; @@ -780,7 +780,7 @@ class GuestFS(object): pr " %s = list (%s)\n" n n ) args; pr " self._check_not_closed ()\n"; - pr " return libguestfsmod.%s (self._o" name; + pr " return libguestfsmod.%s (self._o" f.name; List.iter (fun arg -> pr ", %s" (name_of_argt arg)) (args @ args_of_optargs optargs); pr ")\n\n"; @@ -788,6 +788,6 @@ class GuestFS(object): (* Aliases. *) List.iter ( fun alias -> - pr " %s = %s\n\n" alias name - ) non_c_aliases - ) all_functions + pr " %s = %s\n\n" alias f.name + ) f.non_c_aliases + ) external_functions diff --git a/generator/ruby.ml b/generator/ruby.ml index ee8be4ea0..23ce1fe28 100644 --- a/generator/ruby.ml +++ b/generator/ruby.ml @@ -399,13 +399,12 @@ ruby_user_cancel (VALUE gv) "; List.iter ( - fun ({ name = name; style = (ret, args, optargs as style); - in_docs = in_docs; - c_function = c_function; c_optarg_prefix = c_optarg_prefix; - shortdesc = shortdesc; longdesc = longdesc } as f) -> + fun f -> + let ret, args, optargs = f.style in + (* Generate rdoc. *) - if in_docs then ( - let doc = replace_str longdesc "C [] then doc ^ "\n\nOptional arguments are supplied in the final hash parameter, which is a hash of the argument name to its value. Pass an empty {} for no optional arguments." @@ -418,7 +417,7 @@ ruby_user_cancel (VALUE gv) match deprecation_notice f with | None -> doc | Some txt -> doc ^ "\n\n" ^ txt in - let doc = pod2text ~width:60 name doc in + let doc = pod2text ~width:60 f.name doc in let doc = String.concat "\n * " doc in let doc = trim doc in @@ -458,7 +457,7 @@ ruby_user_cancel (VALUE gv) * (For the C API documentation for this function, see * +guestfs_%s+[http://libguestfs.org/guestfs.3.html#guestfs_%s]). */ -" name args ret shortdesc doc name name +" f.name args ret f.shortdesc doc f.name f.name ); (* Generate the function. Prototype is completely different @@ -468,7 +467,7 @@ ruby_user_cancel (VALUE gv) * http://stackoverflow.com/questions/7626745/extending-ruby-in-c-how-to-specify-default-argument-values-to-function *) pr "static VALUE\n"; - pr "ruby_guestfs_%s (" name; + pr "ruby_guestfs_%s (" f.name; if optargs = [] then ( pr "VALUE gv"; List.iter @@ -482,7 +481,7 @@ ruby_user_cancel (VALUE gv) pr " Data_Get_Struct (gv, guestfs_h, g);\n"; pr " if (!g)\n"; pr " rb_raise (rb_eArgError, \"%%s: used handle after closing it\", \"%s\");\n" - name; + f.name; pr "\n"; (* For optargs case, get the arg VALUEs into local variables. @@ -514,7 +513,7 @@ ruby_user_cancel (VALUE gv) pr " const char *%s = RSTRING_PTR (%sv);\n" n n; pr " if (!%s)\n" n; pr " rb_raise (rb_eTypeError, \"expected string for parameter %%s of %%s\",\n"; - pr " \"%s\", \"%s\");\n" n name; + pr " \"%s\", \"%s\");\n" n f.name; pr " size_t %s_size = RSTRING_LEN (%sv);\n" n n | OptString n -> pr " const char *%s = !NIL_P (%sv) ? StringValueCStr (%sv) : NULL;\n" n n n @@ -546,8 +545,8 @@ ruby_user_cancel (VALUE gv) (* Optional arguments are passed in a final hash parameter. *) if optargs <> [] then ( pr " Check_Type (optargsv, T_HASH);\n"; - pr " struct %s optargs_s = { .bitmask = 0 };\n" c_function; - pr " struct %s *optargs = &optargs_s;\n" c_function; + pr " struct %s optargs_s = { .bitmask = 0 };\n" f.c_function; + pr " struct %s *optargs = &optargs_s;\n" f.c_function; pr " volatile VALUE v;\n"; List.iter ( fun argt -> @@ -580,7 +579,7 @@ ruby_user_cancel (VALUE gv) pr " optargs_s.%s = r;\n" n; pr " }\n" ); - pr " optargs_s.bitmask |= %s_%s_BITMASK;\n" c_optarg_prefix uc_n; + pr " optargs_s.bitmask |= %s_%s_BITMASK;\n" f.c_optarg_prefix uc_n; pr " }\n"; ) optargs; pr "\n"; @@ -602,8 +601,8 @@ ruby_user_cancel (VALUE gv) ); pr "\n"; - pr " r = %s " c_function; - generate_c_call_args ~handle:"g" style; + pr " r = %s " f.c_function; + generate_c_call_args ~handle:"g" f.style; pr ";\n"; List.iter ( @@ -678,7 +677,7 @@ ruby_user_cancel (VALUE gv) pr "}\n"; pr "\n" - ) all_functions; + ) external_functions; pr "\ extern void Init__guestfs (void); /* keep GCC warnings happy */ @@ -731,7 +730,7 @@ Init__guestfs (void) pr " rb_define_method (c_guestfs, \"%s\",\n" alias; pr " ruby_guestfs_%s, %d);\n" name nr_args ) non_c_aliases - ) all_functions; + ) external_functions; pr "}\n" diff --git a/generator/types.ml b/generator/types.ml index 961e998a1..c618add10 100644 --- a/generator/types.ml +++ b/generator/types.ml @@ -368,6 +368,14 @@ and test_init = and seq = cmd list and cmd = string list +type visibility = + | VPublic (* Part of the public API *) + | VStateTest (* A function which tests the state + of the appliance *) + | VBindTest (* Only used for testing language bindings *) + | VDebug (* Exported everywhere, but not documented *) + | VInternal (* Not exported *) + (* Type of an action as declared in Actions module. *) type action = { name : string; (* name, not including "guestfs_" *) @@ -381,10 +389,7 @@ type action = { protocol_limit_warning : bool; (* warn about protocol size limits *) fish_alias : string list; (* alias(es) for this cmd in guestfish *) fish_output : fish_output_t option; (* how to display output in guestfish *) - in_fish : bool; (* export via guestfish *) - in_docs : bool; (* add this function to documentation *) - internal: bool; (* function is not part of the - external api *) + visibility: visibility; (* The visbility of function *) deprecated_by : string option; (* function is deprecated, use .. instead *) optional : string option; (* function is part of an optional group *) progress : bool; (* function can generate progress messages *)