====== ParserFunctions Plugin ====== ---- plugin ---- description: Provides additional parser functions for DokuWiki author : Daniel "Nerun" Rodrigues email : danieldiasr@gmail.com type : syntax lastupdate : 2024-05-19 compatible : Jack Jackrum, Kaos depends : conflicts : similar : tags : template, include, variables, !experimental downloadurl: https://github.com/nerun/dokuwiki-plugin-parserfunctions/zipball/master bugtracker : https://github.com/nerun/dokuwiki-plugin-parserfunctions/issues sourcerepo : https://github.com/nerun/dokuwiki-plugin-parserfunctions donationurl: https://www.paypal.com/donate/?hosted_button_id=T95ZWHGTG2GT2 screenshot_img : https://i.imgur.com/xHMt5P5.png ---- ===== Description ===== Provides additional parser functions for DokuWiki inspired by the [[https://www.mediawiki.org/wiki/Help:Extension:ParserFunctions|MediaWiki ParserFunctions Extension]]. For now, **just ''[[#if|#if]]'', ''[[#ifeq|#ifeq]]'' and ''[[#switch|#switch]]'' functions are available,** but it works very well and is a perfect companion for [[Templater]] and [[WST]] plugins (tested). ===== Installation ===== Please refer to [[plugin:extension|Extension Manager]] for additional info on how to search and install extensions in DokuWiki. Refer to [[:Plugins]] on how to install plugins manually. ===== Syntax ===== **Basic syntax:** * ''%%{{#functionname: argument 1 | argument 2 | argument 3 ... #}}%%'' :!: **Please, note that:** * This plugin starts with ''%%{{#%%'' and ends with ''%%#}}%%''. MediaWiki ends with ''%%}}%%'', don't forget the difference! * White spaces at the beginning and end of the arguments are ignored. The middle ones are ok. To include white spaces at the beginning and/or end, enclose the argument between double quotes:\\ ''%%" string "%%'' * To pass double quotes to the argument, add them inside double quotes:\\ ''%%"This is "phrase" with quotes."%%'' * Functions **can not** be __nested__! === Escape Sequences === These characters: * raw equals ''='' * vertical bar (a.k.a. pipe) ''%%|%%'' * number sign (a.k.a. sharp, hash or pound sign) ''#'' Are special characters for most of the functions. The raw equal ''='' can be used outside ''#switch'' whithout need of any escape sequence. So you can use it in ''#if'' or ''#ifeq''. But inside a ''#switch'', it need to be escaped. However, ''%%|%%'' and ''#'' need to be escaped in all the functions if you wish to add them to your string value or even a case. Here is how: ^ character ^ sequence ^ | = | ''%%=%%'' | | %%|%% | ''%%|%%'' | | # | ''%%#%%'' | New escapes are easy to be added. In ''lib/plugins/parserfunctions/syntax.php'', search for ''function _escape($data)'' and add escapes to the ''$escapes'' array. You can refer to [[https://www.freeformatter.com/html-entities.html|HTML Entity List]]. But replace any ''#'' by ''#''. Alternatively, talk to me and ask me to include the characters you need to escape. ==== #if ==== This function evaluates a test string and determines whether or not it is empty. A test string containing only white space is considered to be empty. ''%%{{#if: test string | value if test string is not empty | value if test string is empty (or only white space) #}}%%'' ''%%{{#if: first parameter | second parameter | third parameter #}}%%'' This function first tests whether the first parameter is not empty. If the first parameter is not empty, the function displays the second argument. If the first parameter is empty or contains only whitespace characters (spaces, newlines, etc.) it displays the third argument. It can be written in many ways: with or without spaces, line breaks, etc. {{#if: | yes | no#}} → no {{#if: string | yes | no#}} → yes {{#if: | yes | no#}} → no {{#if: | yes | no#}} → no The test string is always interpreted as pure text, so mathematical expressions are not evaluated (see ''#ifexpr'' ((Under development!)) for that): {{#if: 1==2 | yes | no #}} → yes {{#if: 0 | yes | no #}} → yes The last parameter (false) may be omitted. It's usefull when user wants the result to be null if the test string is empty: {{#if: foo | yes #}} → yes {{#if: | yes #}} → {{#if: foo | | no#}} → If you are using [[Templater]] or [[WST]] plugins, you can also use a parameter as the test string in your ''#if'' statement. Templater uses ''%%@parameter@%%'' and WST adopts ''%%{{{parameter}}}%%''. {{#if:{{{1}}}|You entered text in variable 1|There is no text in variable 1#}} {{#if:@1@|You entered text in variable 1|There is no text in variable 1#}} To return the same text as the one given in the parameter just repete the string in the second field. You can use the third field as a "default" parameter or leave it blank to hide it. {{#if: {{{1}}} | {{{1}}} | #}} → use {{{1}}} or hide if blank {{#if: @1@ | @1@ | default value #}} → use @1@ or "default value" if blank ==== #ifeq ==== This parser function compares two input strings, determines whether they are identical, and returns one of two strings based on the result. If more comparisons and output strings are required, consider using ''#switch''. {{#ifeq: string 1 | string 2 | value if identical | value if different #}} If both strings are valid numerical values, the strings are compared numerically: {{#ifeq: 01 | 1 | equal | not equal#}} → equal {{#ifeq: 0 | -0 | equal | not equal#}} → equal {{#ifeq: 1e3 | 1000 | equal | not equal#}} → equal {{#ifeq: {{#expr:10^3#}} | 1000 | equal | not equal#}} → DOUBLE BUG :!: **BUG 1**: function ''#expr'' was not implemented yet.\\ :!: **BUG 2**: functions can not be nested yet. Otherwise, the comparison is made as text; this comparison is case-sensitive: {{#ifeq: foo | bar | equal | not equal#}} → not equal {{#ifeq: foo | Foo | equal | not equal#}} → not equal {{#ifeq: "01" | "1" | equal | not equal#}} → not equal [^1] {{#ifeq: 10^3 | 1000 | equal | not equal#}} → not equal [^2] ''[^1]'': compare to similar example above, without the quotes.\\ ''[^2]'': compare to similar example above, with ''#expr'' returning a valid number first. There is no convention for the order, but it is simpler to read if the parameter goes first. For example, in a [[WST]] template, whose parameters are enclosed by ''%%{{{params}}}%%'': This {{#ifeq: {{{1}}} | short | 20 | 40 #}} is equal to this {{#ifeq: short | {{{1}}} | 20 | 40 #}}, order does not matter! ==== #switch ==== This function compares one input value against several test cases, returning an associated string if a match is found. {{#switch: comparison string | case = result | case = result | ... | case = result | default result #}} Examples: {{#switch: baz | foo = Foo | baz = Baz | Bar #}} → Baz {{#switch: foo | foo = Foo | baz = Baz | Bar #}} → Foo {{#switch: zzz | foo = Foo | baz = Baz | Bar #}} → Bar === Default === The ''default result'' is returned if no ''case'' string matches the ''comparison string'': {{#switch: test | foo = Foo | baz = Baz | Bar #}} → Bar In this syntax, the default result must be the last parameter and must not contain a raw equals sign (an equals sign without ''{{}}''). If it does, it will be treated as a case comparison, and no text will display if no cases match. This is because the default value has not been defined (is empty). If a case matches however, its associated string will be returned. {{#switch: test | Bar | foo = Foo | baz = Baz #}} → {{#switch: test | foo = Foo | baz = Baz | B=ar #}} → {{#switch: test | test = Foo | baz = Baz | B=ar #}} → Foo :!: Unlike MediaWiki, the default value cannot be explicitly declared as a case string. You cannot use ''#default = value''. Additionally, the default result can be omitted if you do not wish to return anything if the test parameter value does not match any of the cases. All of these situations are the same: {{#switch: zoo | foo = Foo | bar = Bar #}} → {{#switch: zoo | foo = Foo | bar = Bar | #}} → === Grouping results === It is __**not**__ possible to have 'fall through' values, where several ''case'' strings return the same ''result'' string. This minimizes duplication. __**But this is not implemented in this plugin yet**__. {{#switch: comparison string | case1 = result1 | case2 | case3 | case4 = result234 | case5 = result5 | case6 | case7 = result67 | #default = default result #}} Here cases 2, 3 and 4 **__should__** all return ''result234''; cases 6 and 7 both **__should__** return ''result67''. **__But they will not, because 'fall through' was not implemented yet__**. The "''#default = ''" in the last parameter may **__must__** be omitted in the above case. === Use with template parameters === This plugin is compatible with [[Templater]] and [[WST]]. This is because ParserFunctions are rendered after them. WST template → {{#switch: {{{1}}} | foo = Foo | baz = Baz | Bar #}} Templater template → {{#switch: @1@ | foo = Foo | baz = Baz | Bar #}} In the above case, if ''%%{{{1}}}%%'' or ''%%@1@%%'' equals ''foo'', the function will return ''Foo''. If it equals ''baz'', the function will return ''Baz''. If the parameter is empty or does not exist, the function will return ''Bar''. Works with named case strings of course: ''%%{{{parameter}}}%%'' or ''%%@parameter@%%''. Function evaluates the parameter's value, not the parameter itself. If parameter is empty, it will return the default value. If there is no default value, it is ''null'' (= ''%%""%%''). === Comparison behavior=== As with ''#ifeq'', the comparison is made numerically if both the comparison string and the case string being tested are numeric. === Raw equal signs === Remember that raw equals signs ''='' can be escaped by ''%%=%%''. === Replacing #ifeq === :!: ''#switch'' can be used to reduce expansion depth, but **__can not be nested__** (as any other function): function inside function, ''#switch'' inside another ''#switch'' or an ''#if'' inside a ''#switch'' etc, are not possible. ===== Development ===== The source code of the plugin is available at GitHub: https://github.com/nerun/dokuwiki-plugin-parserfunctions. === Changelog === {{rss>https://github.com/nerun/dokuwiki-plugin-parserfunctions/commits/master.atom date 8}} === Known Bugs and Issues === * //none for now.// === ToDo/Wish List === * [[https://www.mediawiki.org/wiki/Help:Extension:ParserFunctions]] * Allow nested functions. * ''#switch'': add "fall through" ''values'', where several ''case strings'' return the same ''result string''. ===== FAQ ===== //[discussions should ideally be deleted and turned into FAQ entries along the way]//