extensions/StringFunctionsEscaped/README

   1 {{Extension|templatemode=
   2 |name          = StringFunctionsEscaped
   3 |status        = beta
   4 |type1         = parser function
   5 |type2         =
   6 |hook1         = LanguageGetMagic
   7 |hook2         =
   8 |username      = [[user:jpond | Jack D. Pond ]]
   9 |author        =
  10 |description   = Defines a superset of string parser functions that allow character escaping in the 'search for' and 'replace with' arguments.
  11 |image         =
  12 |imagesize     =
  13 |version       = 1.0.0
  14 |update        = 2009-09-11
  15 |mediawiki     = Tested with 1.14,1.15,1.16A, Should work with all
  16 |php           =
  17 |license       = GNU Version 2
  18 |download      =
  19 |readme        =
  20 |changelog     =
  21 |parameters    = $wgPFEnableStringFunctions
  22 |tags          =
  23 |rights        =
  24 |example       =
  25 |compatibility =
  26 }}
  27
  28
  29
  30 ==What can this extension do?==
  31
  32 Wikitext allows the imbedding of certain control characters (newline, tab, etc.).  These parser functions allow them to be identified and used with standard c-type escape character sequence (/n,/t, etc.).
  33
  34 These can be used (among other things) to make infoblox-type templates much more WYSIWIG (see Examples) for novice/non-technical users.
  35
  36 ==Usage==
  37
  38 These functions are all invoked exactly as their string parser functions would be (except with the '_e' appended to distinguish).
  39
  40 ===  pos_e: (string position)===
  41
  42 <nowiki>{{#pos_e:value|key|offset}}</nowiki>
  43
  44 Returns the first position of key inside the given value, or an empty string.
  45 If offset is defined, this method will not search the first offset characters.
  46
  47 See: http://php.net/manual/function.strpos.php
  48
  49 === rpos_e: (string position, reverse) ===
  50 <nowiki>{{#rpos_e:value|key}}</nowiki>
  51 Returns the last position of key inside the given value, or -1 if the key is not found. When using this to search for the last delimiter, add +1 to the  result to retreive position after the last delimiter. This also works when the delimiter is not found, because "-1 + 1" is zero, which is the beginning of the given value.
  52
  53 See: http://php.net/manual/function.strrpos.php
  54
  55 === pad_e: (pad string) ===
  56 <nowiki>{{#pad_e:value|length|with|direction}}</nowiki>
  57
  58 Returns the value padded to the certain length with the given with string.
  59 If the with string is not given, spaces are used for padding. The direction may be specified as: 'left', 'center' or 'right'.
  60
  61 See: http://php.net/manual/function.str-pad.php
  62
  63 === replace_e: (string replace) ===
  64
  65 <nowiki>{{#replace_e:value|from|to}}</nowiki>
  66
  67 Returns the given value with all occurences of 'from' replaced with 'to'.
  68
  69 See: http://php.net/manual/function.str-replace.php
  70
  71 === explode_e: (explode string) ===
  72 <nowiki>{{#explode_e:value|delimiter|position}}</nowiki>
  73
  74 Splits the given value into pieces by the given delimiter and returns the position-th piece. Empty string is returned if there are not enough pieces.
  75
  76 Note: Pieces are counted from 0.<br>
  77 Note: A negative value can be used to count pieces from the end, instead of counting from the beginning. The last piece is at position -1.
  78
  79 See: http://php.net/manual/function.explode.php
  80
  81 ==Download instructions==
  82 <!-- revise these instructions if code is available via a download site -->
  83 Please cut and paste the code found [[#Code|below]] and place it in <code>$IP/extensions/ExtensionName/ExtensionName.php</code>.  ''Note: [[Manual:$IP|$IP]] stands for the root directory of your MediaWiki installation, the same directory that holds [[Manual:LocalSettings.php|LocalSettings.php]]''.
  84
  85 ==Installation==
  86 String functions were integrated into [[Extension:ParserFunctions]] extension as of [[Special:Code/MediaWiki/50997|r50997]]. This revision of [[Extension:ParserFunctions]] is designed for MediaWiki 1.16, but updating to the trunk version may work on previous versions.  If you are using a prior version of [[Extension:ParserFunctions]], you will also have to include [[Extension:StringFunctions]].
  87
  88 Install and test [[Extension:ParserFunctions]] and (if necessary) [[Extension:StringFunctions]] prior to installing this extension.
  89
  90 This extension must be included AFTER the invocation of the string parser functions.
  91 To install this extension, add the following to [[Manual:LocalSettings.php|LocalSettings.php]]:
  92
  93 === For MediaWiki 1.15.1 and before ===
  94 <source lang="php">
  95 require_once("$IP/extensions/ParserFunctions/ParserFunctions.php");
  96 require_once("$IP/extensions/StringFunctions/StringFunctions.php");
  97 require_once("$IP/extensions/StringFunctionsEscaped/StringFunctionsEscaped.php");
  98 </source>
  99
 100 === For MediaWiki 1.16a and after ===
 101 <source lang="php">
 102 require_once("$IP/extensions/ParserFunctions/ParserFunctions.php");
 103 $wgPFEnableStringFunctions = true;  // Note: this must be after ParserFunctions and before StringFunctionsEscaped
 104 require_once("$IP/extensions/StringFunctionsEscaped/StringFunctionsEscaped.php");
 105 </source>
 106 ==Examples==
 107
 108 === pos_e ===
 109
 110 <pre>
 111 {{#pos_e:Line 1
 112 Line 2
 113 Line 3|\n|7}}
 114
 115 Returns:
 116
 117 13
 118 </pre>
 119
 120 === rpos_e ===
 121 <pre>
 122 {{#rpos_e:Line 1
 123 Line 2
 124 Line 3|\n}}
 125
 126 Returns:
 127
 128 13
 129 </pre>
 130
 131 === pad_e ===
 132 <pre>
 133 ~~{{#pad_e:xox|9|\n|center}}~~
 134
 135 Returns:
 136
 137 ~~
 138
 139
 140 xox
 141
 142
 143 ~~
 144 </pre>
 145
 146 === replace_e ===
 147 <pre>
 148 {{#replace_e:Line 1
 149 Line 2
 150 Line 3|\n|<br>\n}}
 151
 152 Returns:
 153
 154 Line 1<br>
 155 Line 2<br>
 156 Line 3
 157
 158 Which would display as:
 159
 160 Line 1
 161 Line 2
 162 Line 3
 163
 164 Rather than the unescaped:
 165
 166 Line 1 Line 2 Line 3
 167
 168 </pre>
 169
 170 === explode_e ===
 171 <pre>
 172 {{#explode_e:Line 1
 173 Line 2
 174 Line 3|\n|1}}
 175
 176 Returns:
 177
 178 Line 2
 179
 180 </pre>
 181 ==See also==
 182
 183 * [[Extension:ParserFunctions]]
 184 * [[Extension:StringFunctions]]
 185 * [[Extension:Lua]]