proposal: text/template: add table action

[heaths]

I'd like to propose adding a new node to text/template similar to {{range pipeline}} named {{table pipeline}}. Inspired by Docker CLI's pseudo-function to format an array using text/tabwriter, this could be a generally useful way to format an array as columnar data using elastic tabstops.

As noted in cli/cli#3488 (comment), Docker CLI checks if the template starts with "table" and does some simple string pre-parsing. The inherent problem is that the template must start with "table", so you can't first scope a pipeline with {{with pipeline}}, for example. You can't really do this wthin a string either because you need to know where the table columns should end, and only parse tree nodes have {{end}}.

I propose (and interested in contributing) something like range that works on an array, but lets you delimit columns like so:

nodes := []struct{
  Nodes []struct{
    Id string
    Name string
  }
  Description string
}{
  // ...
}

template.Must(template.New("main").Parse(`{{table .Nodes}}{{.Id}}{{"\t"}}{{.Name}}{{end}}`)).Execute(os.Stdout, nodes)

This would product output like:

123  Foo
4567 Bar
8    Baz

The {{end}} node would call Writer.Flush which should effectively set the final tabstops.

Ideally, it would be great to provide some control over tabwriter.NewWriter's arguments. Perhaps {{table}} could support variadic ...[]string arguments to set a few options, but columns can help support that on their own, like a user-defined pad function that prefixes or suffixes padding characters like "..", changing colors, etc. Another option might be to emit a header using the same tabstops so the headers align with the columns, much like Docker CLI does with their pseudo-function.

[ianlancetaylor]

Could you just feed the output of text/template into text/tabwriter?

[heaths]

From the perspective of providing useful template functions to users to simply format output without writing or installing another tool, that doesn't seem like a very useful approach. Both the Docker CLI and GitHub CLI (and likely many other tools accepting go templates) provide a templating. Seems making text/tabwriter available via this mechanism would be generally useful to provide tidy output to the console.

[heaths]

While I realize this proposal as written may not be acceptable because it emits formatted text directly instead of facilitating formatting, perhaps it would be better to consider alternatives that still provide the core formatting to functions.

For instance, if we were to try to do this in a function, something like this could work:

{{range .Nodes}}{{tableRow .Id .Name}}{{end}}

However, we lose any ability to pass fields to other custom functions. Perhaps we could consider something like this where parenthesis are parsed by the text/template engine:

{{range .Nodes}}{{tableRow (.Id | color "green") .Name}}{{end}}

Here, {{.Id}} would be passed to the custom color function before the resulting string is passed to the custom tableRow function.

[heaths]

I see you can already use parenthesis like that: cli/cli#3488 (comment)

While I'm tempted to just close this proposal out, I would like to still see if there's interest in it. While I have a solution (or workaround at least), I think this could still be useful, though I realize it might be out of scope since it would emit formatted text itself instead of merely facilitating in formatting.

[ianlancetaylor]

I'm not suggesting installing another tool, I'm suggesting something like (untested)

func TemplateTable(tmpl *template.Template, w io.Writer) error {
    var tabw tabwriter.Writer
    tabw.Init(w, ...)
    tmpl.Execute(&tabw, ...)
}

[heaths]

Ah, I see. That's clever and if a table format was all we wanted to support I agree that's very straight forward. In this case, I'm sure the CLI works want to keep the format open-ended.

[rsc]

This is a very specific instance of a general request to be able to pipe a block of template output through another function. If we could do that, then "table" could be defined as a function outside the template package. But that's not possible today.

[heaths]

I was able to devise a way: cli/cli#3488

Originally I used text/tabwriter, but after feedback switched over to the TablePrinter the GitHub CLI already used internally. I ended up adding just a row function since declaring and ending a table wasn't really necessary. It works with range like so:

{{range .}}{{row (printf "#%v" .id | autocolor "green") .title}}{{end}}

[rsc]

This proposal has been added to the active column of the proposals project
and will now be reviewed at the weekly proposal review meetings.
— rsc for the proposal review group