Global Options in help text

[wayneyaoo]

Hi, thanks for making the lib. It looks decent!

I have a question on how "global option" should be achieved. I understand using Interceptor at root command and the AssignToExecutableSubcommands we can "pass" that option down to the leaf command. But the thing is that in the leaf command help text, it never shows that option. Am I doing something wrong here?

The example is basically from the doc here: https://commanddotnet.bilal-fazlani.com/arguments/argument-models/#accessing-from-interceptors-and-middleware.

In my case it only shows that option in root command help text but not in subcommand.

[drewburlingame]

Hi @wayneyaoo,

If that's the case, it's a bug. We have tests for this scenario that show the AssignToExecutableSubcommands option is printed in the help.

• https://github.com/bilal-fazlani/commanddotnet/blob/master/CommandDotNet.Tests/FeatureTests/ClassCommands/InterceptorExecutionWithInheritedOptionsTests.cs#L61
• https://github.com/bilal-fazlani/commanddotnet/blob/master/CommandDotNet.Tests/FeatureTests/ClassCommands/InterceptorExecutionWithInheritedOptionsTests.cs#L106
• https://github.com/bilal-fazlani/commanddotnet/blob/master/CommandDotNet.Tests/FeatureTests/ClassCommands/InterceptorExecutionWithDefaultMethodTests.cs#L95 (although the test is poorly named)

The way the command is generated, the help generator doesn't need to know about AssignToExecutableSubcommands so I'm stumped on why you might be seeing this.

Do you have a git repo I can look at?

[wayneyaoo]

I realized that I made a mistake when I try to repro this.. I define a sub command class but did not define [DefaultCommand]. In that case the helptext will not show the global option when only the subcommand -h is specified. If I explicitly get helptext of a specific command app.exe subcommand ls -h and the ls is end executable command, the global option shows up.

My bad. Thanks for confirmation!

[wayneyaoo]

Thank you very much for the reply @drewburlingame. I mark the it as answered.

Another question: how can I achieve something like .. -v -vv and -vvv to increase verbosity? It's like specifying the same option multiple times. Is this something the framework can support?

[wayneyaoo]

I'm not sure if it's "common" but this should be a pattern in Unix/Linux world. See https://stackoverflow.com/questions/24402473/what-is-meaning-of-vvv-option-in-curl-request.

And indeed it's sightly awkward to support this in framework. System.Commandline has similar ask but still, people hacks. What basically they did is to somehow surface this information to the help text, and hook into the context to manipulate or count the token. I can imagine the same in this library, like hooking into somewhere at the token processing pipeline, count the number of "v", and then make it one to make the pipeline happy. It just needs some work.

Anyway if this is too complicated to add I totally understand.

[drewburlingame]

This is interesting. Thanks for pointing this out. Currently flags are inferred as boolean options. I could see this implemented as an integer option the CommandParser would increment. We'd need to attribute it so the framework would know to treat it as a flag and increment the value. I'm wondering what to name the attribute. Is there a name for this pattern? If not, maybe an attribute named [IncrementingFlag]?

A benefit of the integer is that property could be defined as an enum so the level would be already mapped based on the value, but raises the question. How does the user know how many times the option can be repeated? I assume it's from the help docs. More importantly, what's the common convention if the users specify it more often than the tool supports? Do the tools fail with an error or do they use the max verbosity level? If they use the max verbosity level, defining with an enum wouldn't really worked unless the framework had special handling to stop incrementing if the type was an enum.

Another option to implement this is to create an extensibility point in the CommandParser where an function could be injected handle custom logic like this and the implementation of the IncrementingFlag could be provided as the example.

Implementing this won't by my top priority, but I would be willing to accept a PR for it.

If not going the extensibility route, the work required include

• add the attribute
• change the way flags are defined
  • update the way Option.IsFlag is calculated. Probably needs to be passed into ctor so would need to be handled by definition mapping layer
  • update definition mapping
    • add IArgumentDef.IsFlag
    • MethodDef.GetArgsFromParameter & MethodDef.GetArgsFromProperty set IsFlag property
      • when Option.IsFlag criteria is met
      • when IncrementingFlag is defined
        • arity remains 0 since no values will be provided.
  • TypeInfo.Flag is for Single. create TypeInfo.IncrementingFlag properties for short,int,long.
• update CommandParser to increment the option value
• tests. look at Options_Flags_Tests as the example.
• documentation
  • https://commanddotnet.bilal-fazlani.com/arguments/arguments/#flags

[wayneyaoo]

Or does the idea of framework adding a support specifically for verbosity sound good to you? if so then we don't need to worry about questions like "How does the user know how many times the option can be repeated?". It's all about verbosity. The frameworks expose configuration for verbosity specifically, including

• How many "v"s the user wants to define
• Handling of unexpected number of v.
• The description
• Or even mode: "-v" and "-q" mode, or "v/vv/vvv" mode.
• whatever else but all about verbosity.

This design narrows it down and is more compact, so .. has less impact to the overall structure. We can add options to AppSettings enable or disable the feature. What do you think?

[drewburlingame]

While it narrows down the work, it also forces a specific version of the verbosity feature on consumers of the framework.

• Given it's one of at least 3 patterns for the feature and not a common one in the dotnet space, it wouldn't be in the flexible and extensible ethos of this framework to force that choice.
• Given the other two patterns are trivial to add within an app via an argument model and they provide flexibility for many variants of those patterns, I don't see worthwhile value in shutting them down in favor of this one.

[drewburlingame]

I had another thought about how you could implement this for your applications using a token transformer. This gives you access to the tokens before they are parsed by the CommandParser and you could convert -v to something like --verbosity=quiet, -vv to --verbosity=medium and -vvv to --verbosity=verbose. This would require defining the verbosity option and that's what would show up in help. You could indicate the -vvv convention in the help for that option. since it requires converting to an application defined option, it's not something we'd put in the framework, but it is something you could implement fairly easily and reuse in your applications.