created: 20140211171341271
modified: 20240422084520179
tags: Concepts [[Core Macros]]
title: Macros
type: text/vnd.tiddlywiki

!! Important

<<.from-version "5.3.0">> Macros have been [[superseded|Macro Pitfalls]] by [[Procedures]], [[Functions]] and [[Custom Widgets]] which together provide more robust and flexible ways to encapsulate and re-use code. 

For text substitutions it is now recommended to use: [[Substituted Attribute Values]], [[substitute Operator]] and [[Transclusion and Substitution]]

!! Introduction

A <<.def macro>> is a named snippet of text. They are typically defined with the [[Pragma: \define]]:

```
\define my-macro(parameter:"Default value")
This is the macro, and the parameter is $parameter$.
\end
```

The name wrapped in double angled [[brackets|Brackets]] is used a shorthand way of [[transcluding|Transclusion]] the snippet. Such transclusions are known as <<.def "macro calls">>, and each call can supply a different set of parameters:

```
<<my-macro>>
<<my-macro "The parameter">>
```

The parameters that are specified in the macro call are substituted for special placeholders within the snippet:

*  `$parameter-name$` is replaced with the value of the named parameter
* `$(variable-name)$` is replaced with the value of the named [[variable|Variables]]).

!! How Macros Work

Macros are implemented as a special kind of [[variable|Variables]]. The only thing that distinguishes them from ordinary variables is the way that the parameters are handled.

!! Using Macros

* [[Macro Definitions]] describes how to create macros
* [[Macro Calls]] describes how to use macros
* [[Macro Parameter Handling]] describes how macro parameters work
* [[Macro Pitfalls]] describes some of the pitfalls of using macros
* [[Core Macros]] lists the built-in core macros