Migrating from 3.5.3 to 4.0.0

[paulduffin]

We recently, last few months, started using Clikt in https://cs.android.com/android/platform/superproject/+/master:tools/metalava/. Feel free to take a look and see how we hack it around to do all sorts of nasty things with help in order to try and get it to behave well with our existing non-Clikt options processor. Maybe it will give you some ideas for improvements you could make, or maybe you could point out improvements we could make.

BTW. Clikt is awesome. For all the pain (fun?) I have had trying to twist it to do things it was not designed to do, it has been a pleasure to use and saved me a lot of tedium.

I started looking at migrating https://cs.android.com/android/platform/superproject/+/master:tools/metalava/ from 3.5.3 to 4.0.0 and I hit the following compile time issues::

• NoSuchOptions.givenName renamed to paramName
• CliktHelpFormatter replaced with MordantHelpFormatter
  • no localization constructor parameter.
  • no width constructor parameter.
  • no maxWidth constructor parameter.
  • additional context constructor parameter.
  • formatHelp() - takes an additional first argument which is UsageError?.
  • renderArgument - replaced with renderArguments or maybe styleArgumentName.
  • renderHelpText - gone.
  • renderOptionName - gone, possibly replaced with styleOptionName.
  • renderSubcommandName - gone, possibly replaced with styleSubcommandName.
• ContextBuilder
  • No console - needed to intercept stdout and stderr.
  • helpFormatter - changed from HelpFormatter? to ((Context) -> HelpFormatter)?.
• PrintHelpMessage
  • command: CliktCommand gone, presumably replaced with context?.command which is CliktCommand?.
• PrintMessage.error appears to have been renamed to printError.
• UsageError.helpMessage() gone, might have been replaced with message or formatMessage is unclear but probably the first.
• Option
  • val optionHelp became optionHelp(Context).
  • provideDelegate changed parameter name from prop to property.
• CliktCommand.commandHelp val replaced with commandHelp(Context).

Any advice/clarification on the appropriate mapping to use would be really helpful. Of particular concern is:

• width, maxWidth - I have to be able to set a maximum width for the purposes of testing to match other non-Clikt help output that has not yet been migrated.
• Intercepting stdout and stderr, it looks as though the code directly calls System.err (and maybe System.out) and I can't use those to intercept what previously went to the console as I need to be able to intercept both separately.

What makes upgrading of anything tricky is the number of additional changes you have to make atomically with the upgrade. Any reductions in those makes the process a lot easier. Easier upgrades means less people left behind. It would be really helpful if you could provide support to aid in the migration. I was thinking along the lines of adding code to 3.5.5 and 4.0.1 to close the gap between them.

Some suggestions as to changes that would help:

• Simple changes to 3.5.5 to handle renames or replacing properties with functions that take a Context, e.g.
  • Add Option.optionHelp(Context) as an alias for Option.optionHelp.
  • Rename NoSuchOptions.givenName to paramName, it will require a change to upgrade to 3.5.5 but it will be one less change to make when going to 4.0.1.
• You could add a CliktCommand40 class to both 3.5.5 and 4.0.0.
  • It would provide a 4.0 API on top of 3.5.5 and 4.0.0 respectively.
  • It might need some extra support like say helpFormatter = contextAwareFormatter {...}. On 3.5.5 that would create a HelpFormatter that encapsulates the calling CliktCommand and when called can retrieve command.currentContext and then pass that into the factory method. On 4.0.1 it would just return the factory lambda.

I'm going to do something like that myself, so if you are interested then I am happy to work with you to contribute it to help anyone else dealing with similar issues.

I'll be AFK for a week so there is no rush.

[ajalt]

Hi, thanks for taking the time to write this all up!

As you've noticed, the CliktConsole was replaced with mordant's Terminal, so intercepting stdout and setting the width is going use mordant.

Setting the width

context {
    terminal = Terminal(width = myWidth)
}

Intercepting stdout

If you're just doing this for tests, 4.0 added the CliktCommand.test extension which handles capturing everything for you. You can also use it to set the width: val result = command.test("--foo --bar", width=40)

If you need something more avanced, you can write your own TerminalInterface. Take a look at mordant's TerminalRecorder for an example (the test extension uses the TerminalRecorder to capture output).

[paulduffin]

No problem. I needed to take a record for my own needs so it seemed to make sense to do it here just in case you found it useful.

Another problem:

• CliktCommand.getFormattedHelp() used to return String, now it returns String?

I've managed to get my code to almost compile with both 3.5.3 and 4.0.0 using a compatibility layer. The remaining issues are minor and should not be an issue.

Rather than wait to do it properly I've hacked my way through to running with Clikt 4.0.0 just to see what the effect would be.

1. It completely trashes a couple of my customizations which is expected, I do some really hacky things to get the formatting I wanted.
2. It uses different column widths in each group (I don't know if that was the same behavior in 3.5.3 as I hacked fixed column widths. I noticed it now because that is one of my hacks that it breaks).
3. It puts a box around the epilog.

One of my hacks was to force a fixed column width. The problem with a dynamic column width per group is:

1. Adding a new longest option or removing the existing longest option causes lots of churn in tests for the help.
2. I have some legacy help (in the epilog) that has a fixed column width and I want to be consistent with that.
3. Different column widths across groups makes it harder to read (for me at least).

I had a look around and Mordant looks like you can specify widths for the columns in table layouts but I cannot get to the ones that Clikt uses.

I was wondering if there's any way to get a fixed column width across all option groups?

I'll probably be unresponsive for a week.

[ajalt]

I was wondering if there's any way to get a fixed column width across all option groups?

Yes, and this is much easier in 4.0. The MordantHelpFormatter uses a DefinitionList by default, which as you noticed has (deliberately) dynamic column widths. You can use a table instead to make everything consistent:

class TableHelpFormatter(context: Context) : MordantHelpFormatter(context) {
    override fun buildParameterList(rows: List<DefinitionRow>): Widget  = table {
        column(0) { width = ColumnWidth.Fixed(20) }
        column(1) { width = ColumnWidth.Expand() }
        body {
            for (row in rows) {
                row(renderDefinitionTerm(row), renderDefinitionDescription(row))
            }
        }
    }
}

Fixed columns often don't display well on narrow terminal widths, which is why it isn't the default.

It puts a box around the epilog.

Does your epilog string have leading whitespace? Try adding a trimIndent(). All help strings are rendered as markdown now, so your epilog might be getting interpreted as a code block.