Add builders for table function arguments

[kasiafi]

Adds builders for

• table function argument specifications
• table function passed arguments

Makes constructors of those classes private.

This is a SPI change. No release notes needed if this change is merged before the upcoming release (the main change has not been yet released)

This change has to be taken into account in the documentation (#12338)

[findepi]

I think putting required fields in a builder() constructor kind of defeats of the purposes of a builder, which is readability ("named parameters"). I know we do so in some places, but i don't think we should, especially for code that's written very rarely and read much more often, as the one here.

[kasiafi]

I saw that pattern in Trino and found it good because it keeps the usage concise. Also, it gives the notion that name is not optional, while the other field is.

[losipiuk]

You can enforce optionality by throwing in build(). Yet I came ok with SINGLE argument passed to builder() method as we have here.

[kasiafi]

It is enforced anyway by throwing in the DescriptorArgumentSpecification constructor. I wasn't trying here to enforce the semantics, but to convey it clearly to the user of the builder. If you still think that builder shouldn't take name in the constructor, I'll remove it.

[losipiuk]

Up to me it is fine to have this arg (as stated above) :)

[kasiafi]

@findepi is it acceptable for you to leave the argument?

[kasiafi]

While rebasing, I decided to remove the argument name from the Builder constructor. The code didn't render good that way.

[findepi]

That looks like a typed value. I wouldn't foresee additional parameters here, and so the builder looks like an overkill

[kasiafi]

Not really. At some point, we will allow arbitrary expressions as scalar arguments.

[kasiafi]

Applied or answered all comments. @losipiuk @findepi please take a look and let us decide on the remaining questions. There's another PR pending on this change, and I'm trying to get them both in soon so that we don't have to announce a SPI change in the next release.

[dain]

Generally I prefer boolean methods to have a good default and then a no-arg method to change tha behavior, so I would make this:

public Builder pruneWhenEmpty()
{
    this.pruneWhenEmpty = true;
    return this;
}

[kasiafi]

It was the initial approach. I changed it according to #12350 (comment)