TIP #144: ARGUMENT EXPANSION SYNTAX 
=====================================
 Version:      $Revision: 1.8 $
 Author:       Peter Spjuth <peter.spjuth_at_space.se>
               Donal K. Fellows <donal.k.fellows_at_man.ac.uk>
               <dgp_at_users.sf.net>
 State:        Withdrawn
 Type:         Project
 Tcl-Version:  8.5
 Vote:         Pending
 Created:      Saturday, 26 July 2003
 URL:          https://tip.tcl-lang.org144.html
 Post-History: 
 Obsoleted-By: TIP #157

-------------------------------------------------------------------------

 ABSTRACT 
==========

 This TIP proposes to add syntax in Tcl to perform argument expansion in 
 a safe and efficient manner. 

 INTRODUCTION 
==============

 Many commands take a variable number of arguments and often you find 
 yourself with those arguments in a list. This list must then be 
 expanded into individual arguments to the command. This is currently 
 done with eval: 

   eval destroy [winfo children .]

 This is a bit obscure and also very error prone when the command 
 becomes more complex. It is also inefficient and not object safe, why 
 something specialised in doing this would be better. 

 BACKGROUND 
============

 See also [TIP #103]. Please also see a summary of a poll of TCLCORE 
 readers taken after [TIP #103] was rejected. 
 <URL:http://wiki.tcl.tk/9462> 

 RATIONALE 
===========

 For examples three statements are used. This is the eval version: 

   eval destroy [winfo children .]
   eval button .b $stdargs -text \$mytext -bd $border
   eval exec \$prog $opts1 [getMoreopts] \$file1 \$file2

 The eval version would be even more complex if the lists that are to be 
 expanded are not known to be pure. To be really safe the last would be: 

   eval exec \$prog [lrange $opts1 0 end] [lrange [getMoreopts] 0 end] \$file1 \$file2

 With the proposed syntax they become: 

   destroy {}[winfo children .]
   button .b {}$stdargs -text $mytext -bd $border
   exec $prog {}$opts1 {}[getMoreopts] $file1 $file2

 The advantage of using syntax for this is that the command do not get 
 obscured. In the examples destroy/button/exec is the most important 
 information on each line and it gets to be first on the line. 

 SPECIFICATION 
===============

 If a word starts with a pair of braces, "{}", and is followed by a non 
 whitespace character it signifies argument expansion. The braces are 
 removed and the rest of the word is parsed and substituted as any other 
 word. The character after the removed "{}" counts as a first character 
 in the rules about open braces and double quotes. After substitution, 
 the word is then parsed as a list (as if with /Tcl_SplitList()/ or 
 /Tcl_GetListFromObj/) and each element of the list is added to the 
 command being built as a separate word with no further parsing. 

 Before executing the command any word to be expanded is treated as a 
 list where each element becomes one separate argument to the command. 

 /Note 1:/ A word should really start with {} to trigger expansion which 
 means that words like these are not expanded: 

   cmd "{}$temp" \{}[something]

 /Note 2:/ Expansion is typically most useful with words like: 

   cmd {}$var {}[somecmd $arg] {}$arr([cmd $arg])

 But things like this are also legal: 

   cmd {}word {}$x,$y {}[foo]xy[apa] {}{apa bepa}

 MOTIVATING EXAMPLES 
=====================

 Many of the examples that make this TIP the way it is come from either 
 advanced usage of commands like [exec] or from Tk. 

 Consider the case where you have lists of options for several external 
 commands that are to be executed together in a pipeline. With expansion 
 it becomes easy to execute such things: 

   exec prog1 {}$optlist1 | prog2 {}$optlist2 | prog3 -staticOption

 As you can see, without expansion building this pipeline would be quite 
 a complex task and would make what is going on much more obscure. 

 With Tk, there are many examples. Here's one from the creation of lines 
 on a canvas: 

   set id [$canv create polygon {}$coords -fill {} {}$opts -tags {foo bar}]

 In this case, there is a fair amount of material before the coordinate 
 list, some static options (which act like defaults) between the coords 
 list and the user-supplied options list, and some further options 
 (which act like overrides for semantically-significant bits) after that 
 which need careful space handling. This also demonstrates why having a 
 command with a list of expanding indices is not a good idea, since it 
 is plain to see that ongoing maintenance might place extra 
 non-expanding arguments in various places through the command. 

 Another example demonstrates why having commands as well as variables 
 expanded is a good idea: 

   namespace eval my {
      variable defaults {
         -bg white
         -fg black
      }
      proc entry {path args} {
         variable defaults
         ::entry $path {}$defaults {}[platformOpts $::tcl_platform(platform)] {}$args
      }
   }

 This illustrates why just plain [concat] doesn't work, demonstrates 
 that having a way to do commands can be very useful, and also shows 
 that having multiple expansion operations in a row is potentially 
 useful. 

 A final example (deleting discontiguous ranges of characters with a 
 particular tag) shows that this is not just useful in Tk for when 
 creating widgets and canvas items: 

   $text delete {}[$text tag ranges $tagToCleanUp]

 In this case, the obvious alternative: 

   foreach {s e} [$text tag ranges $theTag] { $text delete $s $e }

 is wrong, because the positions of the tags move with each deletion (by 
 contrast, the [$text delete] operation is careful in this regard.) 

 REFERENCE IMPLEMENTATION 
==========================

 Not done yet. 

 COPYRIGHT 
===========

 This document has been placed in the public domain. 

-------------------------------------------------------------------------

 TIP AutoGenerator - written by Donal K. Fellows