Add support for variable interpolation in message strings.

[bobtiernay-okta]

Similar in spirit to ${DEFAULT-VALUE} and ${COMPLETION-CANDIDATES}, it would be very useful to allow a set of variables to be registered that could then be used in message strings.

For example, currently I need to do this on my command methods in a hierarchy:

@Override
@Command(description = "Tails the " + App.SERVICE + " docker logs")
public Status logs() {
    return super.logs();
}

what would be nicer is:

@Command(description = "Tails the ${PARENT-COMMAND-NAME} docker logs")
public Status logs() {
  // ...
}

This would allow inheritance chains to allow for encapsulating command methods in the base class and thus the need to override just to change the variable value statically.

It would be nice to have some predefined variables for common things like parent command name and current command name, as well as the ability to generalize to support this use case and others.

[remkop]

Would #428 be sufficient?

[bobtiernay-okta]

Although system properties could work for one aspect, I don't think it's a general solution since:

• It requires a global scope and doesn't compartmentalize for reuse (same issue in Add support for globally registering color schemes #516)
• It doesn't handle command context where the value of a variable is relative to the active parent and current command

Ideally there would be a way to register something similar to a PropertySource in Spring in a similar fashion to IFactory, IVersionProvider or IDefaultValueProvider. SystemPropertySource could be one, CommandPropertySource could be another for example. The basic premise would be to combine all these use cases into the same underlying mechanism.

[remkop]

I see your point. On the other hand I'm not yet convinced that this needs first-class support with a public API like PropertySource.

Providing a system property lookup like ${sys:app-service:-defaultvalue} initially will cover a lot of ground, and can later be extended with things like ${env:key:-default} for environment variables. If more people express a need for custom lookups, then we can add API and support ${custom:key:-default} lookups (prefix name tbd).

[bobtiernay-okta]

That's fair, was just relaying where my mind was at.

I was also wondering if binding variables from the command itself might be an option, either by an interface or an annotation.

[remkop]

I was also wondering if binding variables from the command itself might be an option, either by an interface or an annotation.

Unsure what you mean...
Something like ${option:outputFile} would render /a/b/c if the user specified --outputFile=/a/b/c on the command line?

[bobtiernay-okta]

No something like:

@Command(...)
public class MyCommand {

   @Var("foo")
   String foo;

   //
   // Set foo on construction.
   //

  @Command(description = "Uses ${foo} to describe things")
  public void action() {
    // ...
  }

}

[remkop]

That can be achieved by selecting good system property names when using the ${sys:key} lookup...

[bobtiernay-okta]

I'm not sure I follow, you mean something like:

@Command(...)
public class MyCommand {

   {
       System.setProperty("foo", "bar");
   }

  @Command(description = "Uses ${foo} to describe things")
  public void action() {
    // ...
  }

}

If so, how does something like this work with inheritance where the base class is defining the method? Wouldn't it be unreconcilable with multiple commands?

[remkop]

We could have a method:

@Command(description = "Uses ${sys:foo} to describe things")
class BaseApp {
  String getFooValue() { return "basebar"; }
}
class Subclass extends BaseApp {
  @Override String getFooValue() { return "subbar"; }
}

// at app initialization
System.setProperty("foo", getBaseApp().getFooValue());

[bobtiernay-okta]

I think this is less than ideal since this information must be controlled at the app level and thus cannot be encapsulated in commands. Second, it assumes no command delegation which I assume is a common pattern (it is for us). Lastly it suffers from all the general problems of singletons and global variables.

[remkop]

Would a custom lookup ${custom:key} with a PropertySource-like API solve this?

[bobtiernay-okta]

Indeed it would. Something like IPropertyProvider would be great.

[remkop]

I just realized that picocli already has PropertySource-like API, in the form of a ResourceBundle.
In addition to ${sys:key} lookups, we could support ${resource:key} lookups that would get the value from the ResourceBundle of that command.

[bobtiernay-okta]

Ya that might work. I assume it possible to add a bundle programmatically?

[remkop]

After thinking about this some more, I realized that #480 would also benefit from a ${COMMAND-NAME} variable. Especially a ${FULL-COMMAND-NAME} variable that would render the whole command hierarchy (like git commit) would be useful.

Would that meet your requirements?

[bobtiernay-okta]

I think this plus programmatic message bundles would probably be sufficient. I think having a full parent command path might be more useful than the full command path to the current command. The place this would come in handy is command methods that need to reference peers.

[remkop]

I have an implementation for String interpolation but still thinking of how to integrate this. Can I bounce this off you:

Should the methods in the model return the original Strings, so CommandSpec.description() would return {"${COMMAND-NAME} does blah and ${sys:myKey} does foo"}, and it is up to the client code where these strings are used to call Interpolator.interpolate(String) to render the variables? Or should the model methods return the strings with variables already rendered?

I don't like losing information, so I would like to do the variable replacement as late as possible, but on the other hand it becomes a bit inconvenient to use...

[bobtiernay-okta]

Hmm. I guess it is preferred to keep the API surface area as small as possible hence you would just add an overload: CommandSpec.description(boolean interpolate). The other option is having a setting to change this behavior globally.

[remkop]

I'll probably use a flag like CommandLine.setInterpolateVariables(boolean). I am generally not a fan of "modal" functionality but I liked the alternatives less. (The alternatives I could think of were to increase the API surface by a lot or change the return value from String/String[] to some other object that would have separate methods to provide the interpolated and the non-interpolated values: a breaking change.)

The default will be to interpolate. Setting this to false is useful for testing.

[remkop]

By the way, for anyone who reads this, would you prefer ${resource:key} or ${bundle:key} as the variable naming scheme to get property values from the command’s ResourceBundle?

[remkop]

TODO:

• allow variables to be escaped (with either $${variable} or \${variable})
• add CommandLine.setInterpolateVariables(boolean)
• rename CommandSpec.get/setInterpolateVariables to CommandSpec.interpolateVariables
• implement variable expansion in index and arity attributes
• docs for default values can link to Swift or Bash (StackOverflow or Bash Hackers Wiki)

[remkop]

An initial implementation of this (without the above TODOs) has landed in master.
I still need to do documentation.

This will be included in the upcoming 4.0-alpha-2 release. If anyone can try this out in the next few days and provide feedback that would be great!

Update: the above TODOs have been addressed.

TODO:

• interpolating an escaped variable should reduce leading $: replace $${VAR} with ${VAR}
• document escaping behaviour
• documentation in user manual

[remkop]

All of the above has been implemented and documented.
Please verify.

[remkop]

See draft release notes for details.

[bobtiernay-okta]

Very nice work on this, and much appreciated! Will be certain to give feedback as time affords.