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