From 6e2e25b381efa47beeef81e6da25f36897b08af9 Mon Sep 17 00:00:00 2001 From: Andrey Zherikov Date: Thu, 31 Oct 2024 10:39:56 -0400 Subject: [PATCH] Rename HideFromHelp to Hidden (#182) --- README.md | 2 ++ docs/code_snippets/help_example.d | 2 +- docs/topics/Help-generation.md | 2 +- docs/topics/Shell-completion.md | 5 +++++ docs/topics/reference/PositionalNamedArgument.md | 8 ++++---- source/argparse/api/argument.d | 10 +++++----- source/argparse/internal/arguments.d | 2 +- source/argparse/internal/command.d | 2 +- source/argparse/internal/help.d | 6 +++--- source/argparse/package.d | 7 +++++-- 10 files changed, 28 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 2bb0f18..94a6667 100644 --- a/README.md +++ b/README.md @@ -72,6 +72,8 @@ .Validation((char v) { return v >= '0' && v <= '9'; }) ``` +* `HideFromHelp` is renamed to `Hidden` and now also hides an argument from shell completion. + * Dropped support for DMD-2.099. ### Enhancements and bug fixes diff --git a/docs/code_snippets/help_example.d b/docs/code_snippets/help_example.d index 48ee652..ca0719b 100644 --- a/docs/code_snippets/help_example.d +++ b/docs/code_snippets/help_example.d @@ -9,7 +9,7 @@ struct T @NamedArgument string s; @(NamedArgument.Placeholder("VALUE")) string p; - @(NamedArgument.HideFromHelp) string hidden; + @(NamedArgument.Hidden) string hidden; enum Fruit { apple, pear }; @(NamedArgument("f","fruit").Required.Description("This is a help text for fruit. Very very very very very very very very very very very very very very very very very very very long text")) Fruit f; diff --git a/docs/topics/Help-generation.md b/docs/topics/Help-generation.md index 117ec0c..04188c4 100644 --- a/docs/topics/Help-generation.md +++ b/docs/topics/Help-generation.md @@ -27,7 +27,7 @@ There are some customizations supported on argument level for both `PositionalAr - `Description` – provides brief description of the argument. This text is printed next to the argument in the argument-list section of a help message. `Description` takes either `string` or `string function()` value – the latter can be used to return a value that is not known at compile time. -- `HideFromHelp` – can be used to indicate that the argument shouldn’t be printed in help message. +- `Hidden` – can be used to indicate that the argument shouldn’t be printed in help message. - `Placeholder` – provides custom text that is used to indicate the value of the argument in help message. ## Help text styling diff --git a/docs/topics/Shell-completion.md b/docs/topics/Shell-completion.md index 95195a4..253fc61 100644 --- a/docs/topics/Shell-completion.md +++ b/docs/topics/Shell-completion.md @@ -3,6 +3,11 @@ `argparse` supports tab completion of last argument for certain shells (see below). However, this support is limited to the names of arguments and subcommands. +> Note that hidden arguments are not shown in shell completion. See [Hidden()](PositionalNamedArgument.md#hidden) for details. +> +{style="note"} +or returned in shell completion + ## Wrappers for main function If you are using `CLI!(...).main(alias newMain)` mixin template in your code then you can easily build a completer diff --git a/docs/topics/reference/PositionalNamedArgument.md b/docs/topics/reference/PositionalNamedArgument.md index edb81df..7753bc6 100644 --- a/docs/topics/reference/PositionalNamedArgument.md +++ b/docs/topics/reference/PositionalNamedArgument.md @@ -57,14 +57,14 @@ struct my_command } ``` -### HideFromHelp +### Hidden -`HideFromHelp` can be used to indicate that the argument should not be printed in help message. +`Hidden` can be used to indicate that the argument should not be printed in help message or returned in shell completion. **Signature** ```C++ -HideFromHelp(auto ref ... argument, bool hide = true) +Hidden(auto ref ... argument, bool hide = true) ``` **Parameters** @@ -78,7 +78,7 @@ HideFromHelp(auto ref ... argument, bool hide = true) ```C++ struct my_command { - @(NamedArgument.HideFromHelp) + @(NamedArgument.Hidden) int a; } ``` diff --git a/source/argparse/api/argument.d b/source/argparse/api/argument.d index fe68220..b004e61 100644 --- a/source/argparse/api/argument.d +++ b/source/argparse/api/argument.d @@ -40,9 +40,9 @@ auto ref Optional(T)(auto ref ArgumentUDA!T uda) return uda; } -auto ref HideFromHelp(T)(auto ref ArgumentUDA!T uda, bool hide = true) +auto ref Hidden(T)(auto ref ArgumentUDA!T uda, bool hide = true) { - uda.info.hideFromHelp = hide; + uda.info.hidden = hide; return uda; } @@ -86,7 +86,7 @@ auto ref MaxNumberOfValues(T)(auto ref ArgumentUDA!T uda, size_t max) unittest { ArgumentUDA!(ValueParser!(void, void)) arg; - assert(!arg.info.hideFromHelp); + assert(!arg.info.hidden); assert(!arg.info.required); assert(arg.info.minValuesCount.isNull); assert(arg.info.maxValuesCount.isNull); @@ -98,8 +98,8 @@ unittest arg = arg.Description(() => "qwer").Placeholder("text"); assert(arg.info.description.get == "qwer"); - arg = arg.HideFromHelp.Required.NumberOfValues(10); - assert(arg.info.hideFromHelp); + arg = arg.Hidden.Required.NumberOfValues(10); + assert(arg.info.hidden); assert(arg.info.required); assert(arg.info.minValuesCount.get == 10); assert(arg.info.maxValuesCount.get == 10); diff --git a/source/argparse/internal/arguments.d b/source/argparse/internal/arguments.d index 00b11b9..b845a41 100644 --- a/source/argparse/internal/arguments.d +++ b/source/argparse/internal/arguments.d @@ -25,7 +25,7 @@ package(argparse) struct ArgumentInfo string memberSymbol; - bool hideFromHelp = false; // if true then this argument is not printed on help page + bool hidden = false; // if true then this argument is not printed on help page bool required; diff --git a/source/argparse/internal/command.d b/source/argparse/internal/command.d index 53e2b2f..cfef64d 100644 --- a/source/argparse/internal/command.d +++ b/source/argparse/internal/command.d @@ -149,7 +149,7 @@ package struct Command import std.array: array, join; // suggestions are names of all arguments and subcommands - auto suggestions_ = chain(arguments.namedArguments.map!(_ => _.displayNames).join, subCommands.byName.keys); + auto suggestions_ = chain(arguments.namedArguments.filter!((ref _) => !_.hidden).map!((ref _) => _.displayNames).join, subCommands.byName.keys); // empty prefix means that we need to provide all suggestions, otherwise they are filtered return prefix == "" ? suggestions_.array : suggestions_.filter!(_ => _.startsWith(prefix)).array; diff --git a/source/argparse/internal/help.d b/source/argparse/internal/help.d index 37371ad..95bdfc5 100644 --- a/source/argparse/internal/help.d +++ b/source/argparse/internal/help.d @@ -461,7 +461,7 @@ private void createUsage(void delegate(string) sink, const ref Style style, stri import std.algorithm: filter, each; alias print = (r) => r - .filter!((ref _) => !_.hideFromHelp) + .filter!((ref _) => !_.hidden) .each!((ref _) { sink(" "); @@ -510,7 +510,7 @@ private auto getSections(const ref Style style, const(Arguments*)[] arguments) alias showArg = (ref _) { - if(_.hideFromHelp) + if(_.hidden) return false; if(_.shortNames.length > 0 && isHelpArgument(_.shortNames[0]) || @@ -573,7 +573,7 @@ private auto getSection(const ref Style style, in CommandInfo[] commands) alias showArg = (ref _) { - //if(_.hideFromHelp) + //if(_.hidden) // return false; return _.displayNames.length > 0 && _.displayNames[0].length > 0; diff --git a/source/argparse/package.d b/source/argparse/package.d index 5daa32c..df957dd 100644 --- a/source/argparse/package.d +++ b/source/argparse/package.d @@ -432,6 +432,9 @@ unittest @NamedArgument string b = "dummyB"; + @(NamedArgument.Hidden) + string hidden; + SubCommand!(cmd1, cmd2) cmd; } @@ -751,7 +754,7 @@ unittest @Command("MYPROG") struct T { - @(NamedArgument.HideFromHelp) string s; + @(NamedArgument.Hidden) string s; } assert(CLI!T.parseArgs!((T t) { assert(false); })(["-h","-s","asd"]) == 0); @@ -871,7 +874,7 @@ unittest @NamedArgument string s; @(NamedArgument.Placeholder("VALUE")) string p; - @(NamedArgument.HideFromHelp) string hidden; + @(NamedArgument.Hidden) string hidden; enum Fruit { apple, pear }; @(NamedArgument(["f","fruit"]).Required.Description("This is a help text for fruit. Very very very very very very very very very very very very very very very very very very very long text")) Fruit f;