Author:         Donal K. Fellows <donal.k.fellows@manchester.ac.uk>
State:          Draft
Type:           Project
Vote:           Pending
Created:        13-Aug-2020
Post-History:
Keywords:       Tcl
Tcl-Version:    8.7
Tcl-Branch:     tip-582

Abstract

This TIP adds a comment syntax to Tcl's expression language.

Rationale

While not especially common, multiline expressions do occur in Tcl scripts. They are particularly likely to occur when an expression is complicated, and are often used for describing non-trivial conditions. These are situations where being able to put in a comment, especially for later stages of the expression, would be very useful. (The first line is usually best commented on the line before.) But we have no syntax for doing so! It's possible to hack it like this:

if {[info exists abc] && [info exists def] && [# The variables exist, so we can now use them in the test foobar $abc $def] > 123 } then { ...

But that's really strange and contorted, especially when you don't have a convenient command substitution to hide it inside. You might have to resort to something like this:

if {[info exists abc] && [info exists def] && "1[# The variables exist, so we can now use them in the test ]" && $abc($def) > 123 } then { ...

I think we can agree that that's suboptimal.

Note that expressions in real code often get quite a lot longer and more complicated than these examples.

Specification

There should be a comment format added to expressions. This will be done by making the # character, currently uninterpreted by expressions, be a comment introducing character whenever it is parsed at a point in the expression where it would be legal to have whitespace. It has the same lexical value as whitespace, never causing values to become spliced together. (Note that this does not include the content of command substitutions in expressions; they were already covered by Tcl's command parsing rules, and as such already had a comment format.) The comment will last from that character to the end of the line or the end of the expression, whichever comes first. Note that because expressions are often enclosed in braces, comments are very likely to have to obey usual brace balancing rules in practice: this is not a feature of comments themselves but rather of Tcl's general parsing.

As a bonus, most existing editors and IDEs will probably highlight the new syntax correctly without any change on their part.

Example

The above will allow us to rewrite our first expression from earlier as this:

if {[info exists abc] && [info exists def] && # The variables exist, so we can now use them in the test [foobar $abc $def] > 123 } then { ...

As you can see, we've got the bracket visually associated with the call of the subcommand again. The second expression becomes even clearer:

if {[info exists abc] && [info exists def] && # The variables exist, so we can now use them in the test $abc($def) > 123 } then { ...

Implementation

See the tip-582 branch for Tcl.

Copyright