Feature Proposal: Adding arguments to (user-defined) variables

Motivation

This would allow some TWiki programming tasks to be done in a clearer and more efficient manner.

Description and Documentation

It should be possible for a TWiki user to define a variable that has arguments, as some built-in variables do. The closest functional equivalent to this (that I know of) is parameterized INCLUDE calls. However, the calling sequence for this is a bit verbose and it forces TWiki to go off to another page.

Examples

Let's say that we have a pair of TWiki INCLUDE sections of the form:

%STARTSECTION{"tt_beg"}%
%TWISTY{mode="div"
  showlink="<tt>%NAME%</tt>"
  hidelink="<tt>%NAME%</tt>"
  showimgleft="%ICONURLPATH{toggleopen-small}%" 
  hideimgleft="%ICONURLPATH{toggleclose-small}%"
}% <pre>
mysql> describe %NAME%; %ENDSECTION{"tt_beg"}%

%STARTSECTION{"tt_end"}%
</pre> %ENDTWISTY% %ENDSECTION{"tt_end"}%

To use these, the user must enter:

%INCLUDE{"AddingArgumentsToVariables" section="tt_beg" NAME="schema_info"}%
+---------+---------+------+-----+---------+-------+
| Field   | Type    | Null | Key | Default | Extra |
+---------+---------+------+-----+---------+-------+
| version | int(11) | YES  |     | NULL    |       | 
+---------+---------+------+-----+---------+-------+
%INCLUDE{"AddingArgumentsToVariables" section="tt_end"}%

Giving the result:

schema_info schema_info

mysql> describe schema_info; 
+---------+---------+------+-----+---------+-------+
| Field   | Type    | Null | Key | Default | Extra |
+---------+---------+------+-----+---------+-------+
| version | int(11) | YES  |     | NULL    |       | 
+---------+---------+------+-----+---------+-------+

With this proposal, a TWiki programmer could write (say):

   * Set TT_BEG{name} =  %INCLUDE{"AddingArgumentsToVariables" section="tt_beg" NAME="$name$"}%
   * Set TT_END       =  %INCLUDE{"AddingArgumentsToVariables" section="tt_end"}%

and the usage would reduce to:

%TT_BEG{name="schema_info"}%
+---------+---------+------+-----+---------+-------+
| Field   | Type    | Null | Key | Default | Extra |
+---------+---------+------+-----+---------+-------+
| version | int(11) | YES  |     | NULL    |       | 
+---------+---------+------+-----+---------+-------+
%TT_END%

Details

The exact syntax for using argument values isn't critical, as long as it allows juxtaposition of argument names with alphanumeric text. So, for example, either $name$text, %name%text, or ${name}text would be fine.

There should be a way to specify default values, as:

   * Set ABC{foo, bar="42"} =  ...

For this feature to be most useful, there should be a way to create multi-line definitions. Interestingly, I found this relevant comment:

"To be honest, our not supporting TWikiVariables over multiple lines seems like lazyness."

Sven Dowdeit, Codev/AddGluePluginToCore

Impact

Implementation

I have not examined the relevant code, so I have nothing to offer in this area.

-- Contributors: Main.RichMorin - 27 Jul 2008

Discussion

I've thought about this kind of functionality before, but haven't researched any prior discussion on the topic - it seems intuitive enough that I wonder if it hasn't come up before, somewhere else. Either way, it seems like it would be very useful.

-- Main.RasmusPraestholm - 27 Jul 2008

While using $ and { or % may seem tempting, I would avoid $ because its going to make it confusing wrt formating definitions.

The { and % makes me think - why not implement the arguments as 'Settings' that are local to the macro call - thus extening how SnazzyRoundedCornersContrib works now.

It would be good to define what should happen for error and warning conditions such as when non-defaulted parameters are not set, or when there are non-specified parameters set.

wrt my mulit-line comment - it refers to being able to break up TWikiVariable usages over mulitple lines (as you show in your TWISTY eg) - something we fixed in twiki-4. Defining TWikiVariables in the Set over multiple lines has been possible for much longer - using the same spacing syntax as used to write a bullet point over multiple lines - indent using the same number of spaces.

-- SvenDowideit - 28 Jul 2008

I swear that it was discussed somewhere else a "adding macros to TWiki" or something like that.

-- RafaelAlvarez - 28 Jul 2008

This is implemented in the mean time with the ParameterizedVariables feature.

-- PeterThoeny - 2011-01-04