Suggestion about text mode

[NightMachinery]

Make "-t" get the version of API as an argument, use semantic versioning for the API, and interpret no argument and zero as the latest version. Or make another flag -tv which accepts the version and reserve -t for the latest version.

[holgerbrandl]

I see the point.

Until now I was hoping to rather keep the text support API stable after some initial time of maturation. So far it worked for me as it is, but I have not received any external feedback.

It's a tradeoff of CLI complexity/simplicity and long-term reproducibility.

If you doubt the long-term stability, you could also just add the 3 lines it is injecting, manually to your script. But it would be clearly a bit more verbose and not a one-liner anymore.

Finally, from a user perspective, if the -t without argument would refer to the latest version, most users would go for it, without bothering to lookup the current version of the support API I guess. Making the version a mandatory argument, would be tedious and confusing for the user.

I'd suggest to implement the fix, the first time we roll out a backwards incompatible change to the text support API. What do you think?

[NightMachinery]

Perhaps printing a warning would do: “Text API version not supplied: This script may not work with future versions of kscript. Please use ‘-t <current-version-here>’. Alternatively, use ‘-tf’ not to see this warning.” This makes it very easy to add the version to the command, and anyone not using it has been warned. No need to break compatibility either. I think a huge number of usages don’t even need future compatibility and are one-time usages, so keeping ‘-tf’ is essential.

…

On Fri, Mar 23, 2018 at 1:58 AM Holger Brandl ***@***.***> wrote: I see the point. Until now I was hoping to rather keep the text support API stable after some initial time of maturation. So far it worked for me as it is, but I have not received any external feedback. It's a tradeoff of CLI complexity/simplicity and long-term reproducibility. If you doubt the long-term stability, you could also just add the 3 lines it is injecting, manually to your script. But it would be clearly a bit more verbose and not a one-liner anymore. Finally, from a user perspective, if the -t without argument would refer to the latest version, most users would go for it, without bothering to lookup the current version of the support API I guess. Making the version a mandatory argument, would be tedious and confusing for the user. I'd suggest to implement the fix, the first time we roll out a backwards incompatible change to the text support API. What do you think? — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub <#112 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/Aii--kFgXJ1iZ0yFUwwfvrA5l2kL96XQks5thBd8gaJpZM4S3y96> .

[NightMachinery]

PS: Change '-tf' to '-t 0', which can also be used as '-t0' anyways. This is simpler.

[holgerbrandl]

I think optional arguments can not have optional parameters. At least not when following posix conventions, and also not in docopt (which is used in kscript). So we we would need a dedicated option or make the version mandatory. None seems really attractive.

I still think that we should simply reiterate over the text-processing API to make it a bit more feature-rich/better-designed and then freeze the API using a set of regression tests. From then on it would be just bug-fixing.
Also when using awk or sed we basically trust the authors to ensure backward compatibly. With respect to text-processing mode kscript should be no different imho.

To be 100% backwards compatible, you could

• keep the current version of kscript under an alias such as kscript_2.4 and refer to this in case you wan guranteed API compatibility.
• skip the text-mode and declare the text-processing preamble yourself, or
• build a custom dsl wrapper with strict versioning on top of kscript via https://github.com/holgerbrandl/kscript/blob/master/docs/user_guide.md#create-interpreters-for-custom-dsls

[NightMachinery]

@holgerbrandl Hmm ... You are right, I didn't know that. I think the best option now is to require a version the first time you roll out a backwards incompatible change to the text support API, as you said. Writing -t0 is as easy as -t. Freezing the API is a very bad move IMO; It stops all innovation and sucks the dynamism out of the utility. We should strive to encourage progress.

[holgerbrandl]

Sure we should strive to encourage progress. Feel welcome to suggest features via or ticket to PR. Meanwhile, I'll try to formalize the API by writing unit-tests to cover the existing features. Because just when having a formal spec via testing, we can detect breaking changes.

The current version was more meant as a proof-of-concept, I'd be tempted to start the stable branch (e.g. kscript's non-versionable default) once we have cleared our minds about what it should include.

[holgerbrandl]

Another solution which crossed my mind would be to allow users to enforce a non-latest text-version api via a config annotation. Like

#!/usr/bin/env kscript

...
file:TextApiVersion("1.2.3")
...

This would keep the CLI more slim, but still enable a very defined setup for users that are more concerned about long term compatibility of kscriptlets.

[holgerbrandl]

Closed due to inactivity. Feel welcome to keep commenting on this thread.