mirrors/TiddlyWiki5
1
0
Fork 0
mirror of https://github.com/Jermolene/TiddlyWiki5 synced 2024-06-16 02:19:55 +00:00
Code Issues Releases Wiki Activity

Docs: Update Macro Definitions in WikiText.tid (#3381)

Browse Source 
* Update Macro Definitions in WikiText.tid

*The table is intended as an overview.
*The "Parameters as Variables" example is more clean cut than previously.

Please note that the text lacks an example of  direct `<<variable>>` invocation (because I'm not even sure I categorize or name this properly). Also my changes may contain factual errors or faulty lingo - please check!

* Update Macro Definitions in WikiText.tid
This commit is contained in:
twMat 2018-08-20 18:50:23 +02:00 committed by Jeremy Ruston
parent d96c844264
commit 9a2e2cd385
1 changed files with 20 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

38
editions/tw5.com/tiddlers/wikitext/Macro Definitions in WikiText.tid
View File

@ -7,11 +7,11 @@ type: text/vnd.tiddlywiki
A [[macro|Macros]] is defined using a `\define` [[pragma|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 macro's text (i.e. the snippet represented by the macro name), until `\end` appears on a line by itself:
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 macro's text (i.e. the snippet represented by the macro name), until `\end` appears on a line by itself:
<$codeblock code={{$:/editions/tw5.com/macro-examples/say-hi}}/>
Alternatively, the entire definition can be presented on a single line, without an `\end` marker:
Alternatively, the entire definition can be presented on a single line without an `\end` marker:
```
\define sayhi(name:"Bugs Bunny") Hi, I'm $name$.
@ -19,9 +19,19 @@ Alternatively, the entire definition can be presented on a single line, without
A more formal [[presentation|Macro Definition Syntax]] of this syntax is also available.
!! Placeholders
!! Accessing variables and parameters
Inside the macro there are a few methods for accessing variables and parameters defined outside of the macro or in the macro parameter list.
The snippet can contain placeholders for parameters. These consist of a parameter name between dollar signs, like `$this$`.
|syntax|description|h
|`$...$`|parameter defined in the macro parameters list|
|`<<__...__>>`|parameter defined in the macro parameters list but the syntax evaluates the parameter as it is invoked|
|`$(...)$`|variable placeholder to variable defined outside of the macro|
|`<<...>>`|variable invocation of variable (or other macro) defined outside of the macro|
<br>
!!! Placeholders `$(...)$`
The macro can contain placeholders for parameters. These consist of a parameter name between dollar signs, like `$this$`.
It can also contain placeholders for [[variables|Variables]]. These consist of a variable name (or macro name) between dollar signs and round brackets, like `$(this)$`.
@ -35,9 +45,9 @@ eg="""<$set name="address" value="Rabbit Hole Hill">
</$set>"""/>
</$importvariables>
!! Parameters as Variables
!!! Parameters as Variables `<<__...__>>`
The parameters to a wikitext macro are also available as special variables named as the parameter name wrapped in double underscores. For example, the example above could also be expressed as:
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__>>/>.
@ -45,24 +55,16 @@ The parameters to a wikitext macro are also available as special variables named
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 is intended to wrap a DIV around another macro invocation, passing through the single parameter to the inner macro:
For example, consider this macro. It invokes another macro using the single parameter as an argument for it:
```
\define related-tags(base-tag)
<div class="wrapper">
<$macrocall $name="anothermacro" param="""$base-tag$"""/>
</div>
\end
\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 `<<related-tags 'Triple """ Quotes'>>`). Using parameter variables offers a workaround:
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 related-tags(base-tag)
<div class="wrapper">
<$macrocall $name="anothermacro" param=<<__base-tag__>>/>
</div>
\end
\define film-quote(line) <$macrocall $name="anothermacro" actor="Bugs Bunny" line=<<__line__>>/>
```
!! Scope