Docs: add Procedures railroad syntax description (#8061)
This commit is contained in:
parent
8f741e8e67
commit
ec0b264426
|
@ -0,0 +1,33 @@
|
||||||
|
created: 20240310165023000
|
||||||
|
modified: 20240310172648116
|
||||||
|
tags: [[Procedure Syntax]]
|
||||||
|
title: Procedure Call Syntax
|
||||||
|
type: text/vnd.tiddlywiki
|
||||||
|
|
||||||
|
<<.preamble """What follows is a formal presentation of the syntax of the WikiText syntax for procedure calls, using [[railroad diagrams|Railroad Diagrams]].""">>
|
||||||
|
|
||||||
|
!! procedure-name
|
||||||
|
|
||||||
|
<$railroad text="""
|
||||||
|
"<<" [[ procedure-name |Procedures]] [: [[whitespace|"Filter Whitespace"]] [:{param-value}] ]">>"
|
||||||
|
"""/>
|
||||||
|
|
||||||
|
* The [[procedure's|Procedures]] <<.place procedure-name>> is a sequence of non-whitespace characters other than `(` or `>`.
|
||||||
|
|
||||||
|
* <<.place whitespace>> denotes a sequence of [[whitespace characters|Filter Whitespace]].
|
||||||
|
|
||||||
|
!!! param-value
|
||||||
|
|
||||||
|
Each ''individual'' <<.place param-value>> has the following syntax:
|
||||||
|
|
||||||
|
<$railroad text="""
|
||||||
|
\start none
|
||||||
|
\end none
|
||||||
|
[: param-name [:[[whitespace|"Filter Whitespace"]]] ":" [:[[whitespace|"Filter Whitespace"]]] ] value [: [[whitespace|"Filter Whitespace"]] ]
|
||||||
|
"""/>
|
||||||
|
|
||||||
|
* The <<.place param-name>> is a sequence of letters (`A`--`Z`, `a`--`z`), digits (`0`--`9`), hyphens (`-`) and underscores (`_`).
|
||||||
|
|
||||||
|
* The <<.place value>> is specified as follows:
|
||||||
|
|
||||||
|
<$railroad text={{$:/editions/tw5.com/railroad/macro-parameter-value}}/>
|
|
@ -0,0 +1,93 @@
|
||||||
|
created: 20240310165023000
|
||||||
|
modified: 20240310175033730
|
||||||
|
tags: [[Procedure Syntax]]
|
||||||
|
title: Procedure Definition Syntax
|
||||||
|
type: text/vnd.tiddlywiki
|
||||||
|
|
||||||
|
<<.preamble """What follows is a formal presentation of the syntax of the [[Pragma: \procedure]], using [[railroad diagrams|Railroad Diagrams]]. """>>
|
||||||
|
|
||||||
|
! \procedure
|
||||||
|
|
||||||
|
There are 2 types of procedure definitions
|
||||||
|
|
||||||
|
* Single line definitions
|
||||||
|
* Multi line definitions
|
||||||
|
|
||||||
|
!! Single Line
|
||||||
|
|
||||||
|
Single line definitions should only be used for very short bodies, where the procedure name, params and the body fit into 1 line terminated with a line-feed.
|
||||||
|
|
||||||
|
<$railroad text="""
|
||||||
|
"\procedure"
|
||||||
|
[[<"space">|"Filter Whitespace"]]
|
||||||
|
"procedure-name"
|
||||||
|
<"(params)">
|
||||||
|
[:[[<"space">|"Filter Whitespace"]]]
|
||||||
|
"body"
|
||||||
|
"lf"
|
||||||
|
"""/>
|
||||||
|
|
||||||
|
!! Multi Line
|
||||||
|
|
||||||
|
The majority of procedure definitions will have a body, that spans over several lines of wikitext. Those procedure definitions are terminated using the "\end" pragma
|
||||||
|
|
||||||
|
<$railroad text="""
|
||||||
|
"\procedure"
|
||||||
|
[[<"space">|"Filter Whitespace"]]
|
||||||
|
"procedure-name"
|
||||||
|
<"(params)">
|
||||||
|
[:[[<"space">|"Filter Whitespace"]]]
|
||||||
|
body
|
||||||
|
"\end"
|
||||||
|
"""/>
|
||||||
|
|
||||||
|
The [[procedure-name|Procedures]] is a sequence of non-whitespace characters other than `(` or `>`.
|
||||||
|
|
||||||
|
|
||||||
|
* <<.place procedure-name>> is a sequence of letters (`A`--`Z`, `a`--`z`), digits (`0`--`9`), hyphens (`-`) and underscores (`_`)
|
||||||
|
* <<.place body>> is wikitext including [[nested procedures|Pragma: \procedure]]
|
||||||
|
* <<.place space>> denotes a sequence of [[whitespace characters|Filter Whitespace]]
|
||||||
|
|
||||||
|
!! params
|
||||||
|
|
||||||
|
The parameter declaration list <<.place (params)>> has the following syntax:
|
||||||
|
|
||||||
|
<$railroad text="""
|
||||||
|
\start none
|
||||||
|
\end none
|
||||||
|
"(" [:"sep"] [:{ parameter "sep" }] ")"
|
||||||
|
"""/>
|
||||||
|
|
||||||
|
* <<.place sep>> is any sequence of characters that does not match a <<.place param-name>>. <br>Among other things, this includes commas, spaces and linefeeds.
|
||||||
|
|
||||||
|
|
||||||
|
Each ''individual'' <<.place parameter>> has the following syntax:
|
||||||
|
|
||||||
|
<$railroad text="""
|
||||||
|
\start none
|
||||||
|
\end none
|
||||||
|
"param-name" [: [:[[<"space">|"Filter Whitespace"]]] ":" [:[[<"space">|"Filter Whitespace"]]] default ]
|
||||||
|
"""/>
|
||||||
|
|
||||||
|
* <<.place param-name>> is a sequence of letters (`A`--`Z`, `a`--`z`), digits (`0`--`9`), hyphens (`-`) and underscores (`_`).
|
||||||
|
|
||||||
|
* <<.place default>> is an optional value of a parameter is specified as follows:
|
||||||
|
|
||||||
|
<$railroad text={{$:/editions/tw5.com/railroad/macro-parameter-value}}/>
|
||||||
|
|
||||||
|
!! body
|
||||||
|
|
||||||
|
The <<.place body>> of the definition has the following syntax:
|
||||||
|
|
||||||
|
<$railroad text="""
|
||||||
|
\start none
|
||||||
|
\end none
|
||||||
|
{[[<"wikitext">|WikiText]] "lf"}
|
||||||
|
"""/>
|
||||||
|
|
||||||
|
* <<.place wikitext>> is any sequence of characters that doesn't terminate the macro definition.
|
||||||
|
** If [[nested procedures|Pragma: \procedure]] are used they need to be at the start of the wikitext. There are the same rules as if the wikitext would be in a tiddler.
|
||||||
|
** Pragmas need to be before standard wikitext.
|
||||||
|
|
||||||
|
* <<.place lf>> denotes a linefeed.
|
||||||
|
|
|
@ -0,0 +1,11 @@
|
||||||
|
created: 20240310165023000
|
||||||
|
modified: 20240310173318213
|
||||||
|
tags: Procedures
|
||||||
|
title: Procedure Syntax
|
||||||
|
type: text/vnd.tiddlywiki
|
||||||
|
|
||||||
|
Plain text description can be found at [[Procedures]]
|
||||||
|
|
||||||
|
<<list-links filter:"[tag[Procedure Syntax]]">>
|
||||||
|
|
||||||
|
<<.tip "The railroad boxes in the linked tiddlers can be used to navigate.">>
|
|
@ -1,5 +1,5 @@
|
||||||
created: 20221007124007426
|
created: 20221007124007426
|
||||||
modified: 20230419103154329
|
modified: 20240310173130052
|
||||||
tags: Concepts Reference
|
tags: Concepts Reference
|
||||||
title: Procedures
|
title: Procedures
|
||||||
type: text/vnd.tiddlywiki
|
type: text/vnd.tiddlywiki
|
||||||
|
@ -18,11 +18,13 @@ The name wrapped in double angled [[brackets|Brackets]] is used a shorthand way
|
||||||
|
|
||||||
```
|
```
|
||||||
<<my-procedure>>
|
<<my-procedure>>
|
||||||
<<my-procedure "The parameter">>
|
<<my-procedure parameter:"The parameter">>
|
||||||
```
|
```
|
||||||
|
|
||||||
The parameters that are specified in the procedure call are made available as variables.
|
The parameters that are specified in the procedure call are made available as variables.
|
||||||
|
|
||||||
|
<<.tip """If a procedure has more than 1 parameter, it is highly encouraged to use "named parameters", as shown in the second example above. Even if it is more to type, it will pay off in the long run.""">>
|
||||||
|
|
||||||
!! How Procedures Work
|
!! How Procedures Work
|
||||||
|
|
||||||
Procedures 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.
|
Procedures 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.
|
||||||
|
@ -32,4 +34,4 @@ Procedures are implemented as a special kind of [[variable|Variables]]. The only
|
||||||
* [[Procedure Definitions]] describes how to create procedures
|
* [[Procedure Definitions]] describes how to create procedures
|
||||||
* [[Procedure Calls]] describes how to use procedures
|
* [[Procedure Calls]] describes how to use procedures
|
||||||
* [[Procedure Parameter Handling]] describes how procedure parameters work
|
* [[Procedure Parameter Handling]] describes how procedure parameters work
|
||||||
|
* [[Procedure Syntax]] is a formal syntax description using railroad diagrams
|
||||||
|
|
Loading…
Reference in New Issue