This page is part of a static HTML representation of the TiddlyWiki at https://tiddlywiki.com/

Macro Definitions in WikiText

20th August 2018 at 4:51pm
WikiText

A macro is defined using a \define pragma. Like any pragma, this can only appear at the start of a tiddler.

The first line of the definition specifies the macro name and any parameters. Each parameter has a name and, optionally, a default value that is used if no value is supplied on a particular call to the macro. The lines that follow contain the text of the macro text (i.e. the snippet represented by the macro name), until \end appears on a line by itself:

\define sayhi(name:"Bugs Bunny" address:"Rabbit Hole Hill")
Hi, I'm $name$ and I live in $address$.
\end

Alternatively, the entire definition can be presented on a single line without an \end marker:

\define sayhi(name:"Bugs Bunny") Hi, I'm $name$.

A more formal presentation of this syntax is also available.

Accessing variables and parameters

Inside the macro there are several methods for accessing variables defined outside of the macro or parameters from the macro parameter list.

syntaxdescription
$...$Text substitution of a parameter defined in the macro parameters list
<<__...__>>Parameter-as-variable access to a parameter defined in the macro parameters list
$(...)$Text substitution of a variable defined outside of the macro
<<...>>Access to a variable (or other macro) defined outside of the macro

Placeholders $(...)$

The macro can contain placeholders for parameters. These consist of a parameter name between dollar signs, like $this$.

The macro can also contain placeholders for variables. These consist of a variable name (or macro name) between dollar signs and round brackets, like $(this)$.

The actual value of the parameter or variable is substituted for the placeholder whenever the macro is called:

\define say-hi-using-variables()
Hi, I'm $(name)$ and I live in $(address)$.
\end

\define name() Bugs
<$set name="address" value="Rabbit Hole Hill">
<<say-hi-using-variables>>
</$set>

Parameters as Variables <<__...__>>

Parameters in a wikitext macro can be accessed as variables by using the syntax <<__...__>>, i.e the parameter name surrounded by double underscores. For example, the example above could also be expressed as:

\define sayhi(name:"Bugs Bunny") Hi, I'm <$text text=<<__name__>>/>.

Accessing parameters as variables only works in macros that are wikified and not, for example, when a macro is used as an attribute value. The advantage of the technique is that it avoids the parameter value being substituted into the macro as a literal string, which in turn can help avoid issues with parameters that contain quotes.

For example, consider this macro. It invokes another macro using the single parameter as an argument for it:

\define film-quote(line) <$macrocall $name="anothermacro" actor="Bugs Bunny" line="""$line$"""/>

The code above will fail if the macro is invoked with the argument containing triple double quotes (for example <<film-quote 'I quote thrice """ - see!?'>>). Using parameter variables offers a workaround:

\define film-quote(line) <$macrocall $name="anothermacro" actor="Bugs Bunny" line=<<__line__>>/>

Scope

Macros are available to the tiddler that defines them, plus any tiddlers that it transcludes.

To make a macro available to all tiddlers, define it in a tiddler that has the tag $:/tags/Macro.

It is also possible to write a macro as a JavaScript module. JavaScript macros are available to all tiddlers, and offer the maximum flexibility.

A tiddler can manually import macro definitions from a selection of other tiddlers by using the $importvariables widget.