Version 33 of Tcl Minimal Escaping Style

Updated 2015-05-18 03:04:13 by pooryorick

A minimal Tcl escaping style is a code style that eschews unnecessary Tcl escaping syntax.

Description

In some languages such as C, Javascript, Lisp, and Python, double quotes indicate a certain type of value: a string. In Tcl all values are already strings, so double quotes do not have that function. Instead, they provide an environment in which whitespace characters are ordinary characters rather than word delimiters. Braces do the same, but additionally inhibit the standard substitutions. It's technically possible to use backslash substitution to accomplish the same thing that quotes or braces do, but in all non-trivial cases this results in unreadable scripts.

A lot of Tcl code that one encounters employs double quotes even when not strictly necessary. Sometimes this is done to make a text editor highlight those values; other times to make Tcl seem more like C or a Unix shell. Such usage can be confusing to the beginner who is trying to understand the intended use of double quotes, braces, and backslash substitution. Furthermore, the use of these characters can at times have a performance impact that the beginner may find subtle and surprising.

The minimal Tcl escaping style presented on this page results in Tcl code that only employs Tcl escape environments where semantically necessary, resulting in code that naturally avoids the pitfalls of extraneous escaping.

Here are the rules of the minimal escaping style:

braces
Don't use braces where no backslash substitutions are otherwise needed.
quotes
Don't use quotes where braces could be used.

That's it. If your code follows this style, you can avoid potential performance issues like "[unintended shimmering]", as well as whatever miniscule performance improvement that comes from minimizing double quote processing by the Tcl interpreter. This minimal style also "scales" better as one moves into more complex forms of Tcl scripting such as code generation. Best of all , beginners will be able to learn by reading your code when braces and quotes are actually needed. It also helps to disabuse them of that all-to-common misunderstanding that braces mean "list".

For example, if a value contains whitespace and also substitutions , quotes would be the way to go, since braces would over-escape the value, preventing the substitutions from occurring.

MS dons his evil hat and remarks: in that case, really minimal style could be without quotes or braces, just backslash-escape the whitespaces! Of course, it depends on how you define minimal ...

PYK 2015-04-30: Except that braces and quotes were presumably introduced into the language specifically to alleviate backslash pain. This minimal escaping style merely advocates using them only for their respective intended purposes. Note that the minimal escaping style says nothing about backslash escaping, which is always fair game!

Counterpoint

The above discussion might imply that this style is widely accepted or endorsed. As discussion on the Tcl Chatroom has revealed, it is not. Cursory examination of the majority of code on this wiki, or published in tcllib and elsewhere shows the same. A few reasons to use a less grammar-bound style of quoting:

  • syntax highlighting and "type" identification. Writing strings quoted with "" generally causes editors to highlight them differently, and conveys to the reader that the value is intended to be treated as a string. The visual cues make code easier to read on the wiki, in an editor or printed on paper.
  • it's arguably more common to make a change like "Hello, world!" -> "Hello, $whom!". Not having to change delimiters makes such changes easier and less bug-prone.
  • proc foo {a} {...} is another case where leaving out the first set of {} just makes later edits more cumbersome.

These points can be summarised in the famous Abelson and Sussman quote: "Programs must be written for people to read, and only incidentally for machines to execute." Optimise for the human reader, not the mechanical parser.

aspect can see the minimal escaping style as a useful pedagogical device for users who haven't yet internalised the dodekalogue, but finds its use elsewhere rather bizarre. Changing existing examples to this style without specific justification for that example seems gratuitous and potentially harmful.

This might be a good place to collect other examples of divergent coding styles .. Heronian triangles uses some short definitions to make equations work with minimal punctuation, at the cost of performance and safety.

Discussion

EMJ (2015-04-22) Re "Sometimes this is done..." near the beginning: it might be done to clarify the purpose of a string, or with an eye on a future change (and so is about program maintainability). And I just don't believe the "seem more like C" bit.

PYK 2015-04-30: Anyone who thinks they can improve this page is free to dive in and rewrite it wholesale as far as I'm concerned....

EMJ 2015-04-30: No they can't, you'll put their name on the rewrites and try to turn them into another bit of your own private but global edit war!

PYK 2015-04-30: I added your name to your comments because they were in discussion format, expressing a different opinion. In that case, the speakers need to be labeled so the reader can understand that it's different people talking. If you don't want to attribute yourself, you could always defer to anonymous coward or something. In any case, other readers already aren't going to understand what we're discussing here because the page has already taken on another form. That's cool. It'll just need some cleanup later.

RS 2015-05-13: Some exceptions:

  • semicolons must be quoted/braced if not used as statement separators:
set x [split $y ";"]
  • small characters are better visible if redundantly quoted/braced: e.g. "."

PYK 2015-05-13: To conform to the minimal escaping style, that would either be

set x [split $y \;]

or

set x [split $y {;}]

The idea behind the minimal escaping style is specifically to not use braces quotes or backslash for side purposes such as increasing visibility of characters, appeasing syntax highlighters, or posing as another language. To be justified under the minimal escaping style, a brace, quote, or backslash must have a programmatic effect. Says me :)

Examples

#instead of
puts "Hello!"

#use
puts Hello!
#instead of 
puts "Hello World."

#use
puts {Hello, World.}
#instead of 
proc {x} { ... }

#use
proc x { ... }

See also