Matthew Booth
2013-Feb-04 14:18 UTC
[Libguestfs] [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 | 90 ++++++++++++++++++++++++++++++++++++---------------
generator/actions.mli | 24 ++++++++++++++
generator/c.ml | 7 ++--
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, 208 insertions(+), 159 deletions(-)
diff --git a/generator/actions.ml b/generator/actions.ml
index a97b867..8d31317 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<guestfs(3)>." };
{ 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<guestfs(3)>." };
{ 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<guestfs(3)>." };
];
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<guestfs(3)>." };
{ defaults with
name = "get_state";
style = RInt "state", [], [];
+ visibility = VStateTest;
blocking = false;
shortdesc = "get the current state";
longdesc = "\
@@ -1345,7 +1350,7 @@ Please read L<guestfs(3)/INSPECTION> 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 = "\
@@ -4231,7 +4236,7 @@ as for the L<mount(8)> 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<guestfs_debug> command exposes some internals of
@@ -6825,7 +6830,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<guestfs_lstat> operation
@@ -6849,7 +6854,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 = "\
@@ -6879,7 +6884,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<readlink> operation
@@ -7602,7 +7607,8 @@ unless it has been set by calling
C<guestfs_umask>." };
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<guestfs_debug_upload> command uploads a file to
@@ -7677,7 +7683,7 @@ to ensure the length of the file is exactly C<len>
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 (
@@ -8391,7 +8397,7 @@ See also L<guestfs(3)/RESIZE2FS ERRORS>." };
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
@@ -8537,7 +8543,7 @@ See also L<btrfs(8)>." };
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,37 @@ let non_daemon_functions, daemon_functions (* All
functions. *)
let all_functions = non_daemon_functions @ daemon_functions
+let is_external + fun x -> match x.visibility with
+ | VPublic | VStateTest | VBindTest | VDebug -> true
+ | VInternal -> false
+
+let is_internal + fun x -> match x.visibility with
+ | VPublic | VStateTest | VBindTest | VDebug -> false
+ | VInternal -> true
+
+let is_documented + fun x -> match x.visibility with
+ | VPublic | VStateTest -> true
+ | VBindTest | VDebug | VInternal -> false
+
+let is_fish + fun x -> match x.visibility 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 +11103,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 26ae7e9..5641e57 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 e0ce7e1..9ca477b 100644
--- a/generator/c.ml
+++ b/generator/c.ml
@@ -196,13 +196,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)
diff --git a/generator/csharp.ml b/generator/csharp.ml
index bc92cf1..0fbd02c 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 (
@@ -286,7 +286,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 b7d4e6c..6242338 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 (
@@ -461,7 +461,7 @@ extern void free_strings (char **r);
pr "}\n";
pr "\n";
- ) all_functions_sorted;
+ ) external_functions_sorted;
pr "\
@@ -480,7 +480,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 077a0b4..411cf11 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 <config.h>\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 <cmd> / help <cmd> 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_<action> actions *)
List.iter (
@@ -639,7 +635,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";
@@ -678,12 +674,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
@@ -705,7 +695,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 "\
%%}
@@ -732,15 +722,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 <config.h>
@@ -769,7 +756,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;
@@ -829,10 +816,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<guestfs_\\([^>]+\\)>" in
@@ -895,7 +881,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 519cb26..801ffb4 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
@@ -1279,4 +1279,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 396eeb7..cee9e28 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
@@ -208,7 +208,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 4375b81..45fb569 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<guestfs_"
"C<g." in
+ fun f ->
+ let ret, args, optargs = f.style in
+
+ if is_documented f then (
+ let doc = replace_str f.longdesc "C<guestfs_"
"C<g." in
let doc if optargs <> [] then
doc ^ "\n\nOptional arguments are supplied in the final
Map<String,Object> 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
| "" -> "<p>"
@@ -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 " * <p>\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<String, String> rhash = new
HashMap<String, String> ();\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"
@@ -1099,7 +1099,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;
@@ -1190,7 +1190,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";
@@ -1200,7 +1200,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 042a8a0..1878844 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 "\
@@ -629,7 +629,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 *
@@ -866,7 +866,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
@@ -904,7 +904,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 1d35a53..0216140 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 0b1f96b..d922c0f 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 (
@@ -669,7 +669,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 ddae5bb..9133bcf 100644
--- a/generator/perl.ml
+++ b/generator/perl.ml
@@ -560,7 +560,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";
@@ -858,10 +858,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<guestfs_"
"C<$g-E<gt>" in
pr "=item ";
generate_perl_prototype name style;
@@ -891,7 +889,7 @@ handlers and threads.
pr "=pod\n";
pr "\n";
) non_c_aliases
- ) all_functions_sorted;
+ ) documented_functions_sorted;
pr "=cut\n\n";
@@ -956,7 +954,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";
@@ -969,7 +967,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 4ed7b30..d457507 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 }
};
@@ -506,7 +506,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 3863c71..64c5a8d 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 (
@@ -528,7 +528,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";
@@ -542,7 +542,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";
@@ -734,9 +734,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 ->
@@ -744,8 +744,8 @@ class GuestFS(object):
) optargs;
pr "):\n";
- if in_docs then (
- let doc = replace_str longdesc "C<guestfs_"
"C<g." in
+ if is_documented f then (
+ let doc = replace_str f.longdesc "C<guestfs_"
"C<g." in
let doc match ret with
| RErr | RInt _ | RInt64 _ | RBool _
@@ -767,7 +767,7 @@ class GuestFS(object):
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 (fun line -> replace_str line "\\"
"\\\\") doc in
let doc = String.concat "\n " doc in
pr " \"\"\"%s\"\"\"\n"
doc;
@@ -786,7 +786,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";
@@ -794,6 +794,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 0114aca..706c726 100644
--- a/generator/ruby.ml
+++ b/generator/ruby.ml
@@ -393,13 +393,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<guestfs_"
"C<g." in
+ if is_documented f then (
+ let doc = replace_str f.longdesc "C<guestfs_"
"C<g." in
let doc if optargs <> [] 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."
@@ -412,7 +411,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
@@ -452,7 +451,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
@@ -462,7 +461,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
@@ -476,7 +475,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.
@@ -509,7 +508,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
@@ -541,8 +540,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 ->
@@ -575,7 +574,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";
@@ -597,8 +596,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 (
@@ -674,7 +673,7 @@ ruby_user_cancel (VALUE gv)
pr "}\n";
pr "\n"
- ) all_functions;
+ ) external_functions;
pr "\
extern void Init__guestfs (void); /* keep GCC warnings happy */
@@ -727,7 +726,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 26bf746..c809d2b 100644
--- a/generator/types.ml
+++ b/generator/types.ml
@@ -370,6 +370,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_"
*)
@@ -383,10 +391,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 *)
--
1.8.1
Richard W.M. Jones
2013-Feb-05 14:40 UTC
[Libguestfs] [PATCH] generator: Add visibility to action struct
On Mon, Feb 04, 2013 at 02:18:48PM +0000, Matthew Booth wrote:> +let is_external > + fun x -> match x.visibility with > + | VPublic | VStateTest | VBindTest | VDebug -> true > + | VInternal -> falseI know we discussed this on IRC, but seeing the whole function I now realise you could write: let is_external { visibility = v } match v with | VPublic | VStateTest | VBindTest | VDebug -> true | VInternal -> false Or: let is_external = function { visibility = (VPublic | VStateTest | VBindTest | VDebug) } -> true { visibility = VInternal } -> false Whether you prefer this or not is up to you :-) Anyway, this all looks a lot more sensible. One check you could do is to diff the generator output before and after the change. Basically, reset to before your patch, and do: make -C generator for f in `cat generator/files-generated.txt`; do cp $f $f.orig; done Then apply your patch, and do: make -C generator for f in `cat generator/files-generated.txt`; do diff -u $f.orig $f; done \ | less Assuming that diff looks sensible to your eyes, then ACK. Rich. -- Richard Jones, Virtualization Group, Red Hat http://people.redhat.com/~rjones virt-p2v converts physical machines to virtual machines. Boot with a live CD or over the network (PXE) and turn machines into KVM guests. http://libguestfs.org/virt-v2v
Apparently Analagous Threads
- [PATCH] Make internal-only functions and structures private
- [PATCH 0/4] generator: Some work to split large C files
- [PATCH 2/2] ocaml: Improve ocamldoc.
- [PATCH 3/3] ocaml: hide internal methods from apidocs
- [PATCH 0/6] Allow non-optargs functions to gain optional arguments.