TWiki/TWikiFuncDotPm.mdwn

   1 # <a name="Package &lt;code&gt;TWiki::Func="></a> Package =TWiki::Func
   2
   3 _Official list of stable TWiki functions for Plugin developers_
   4
   5 This module defines official functions that [[Plugins|TWiki/TWikiPlugins]] can use to interact with the TWiki engine and content.
   6
   7 Refer to [[EmptyPlugin]] and lib/TWiki/Plugins/EmptyPlugin.pm for a template Plugin and documentation on how to write a Plugin.
   8
   9 Plugins should **only** use functions published in this module. If you use functions in other TWiki libraries you might create a security hole and you will probably need to change your Plugin when you upgrade TWiki.
  10
  11 Deprecated functions will still work in older code, though they should _not_ be called in new Plugins and should be replaced in older Plugins as soon as possible.
  12
  13 The version of the TWiki::Func module is defined by the VERSION number of the TWiki::Plugins module, currently 1.11. This can be shown by the `%PLUGINVERSION%` variable. The 'Since' field in the function documentation refers to the VERSION number and the date that the function was addded.
  14
  15 **_Note:_** Beware! These methods should only ever be called from the context of a TWiki Plugin. They require a Plugins SESSION context to be established before they are called, and will not work if simply called from another TWiki module. For example,
  16
  17     use TWiki;
  18     print TWiki::Func::getSkin(),"\n";
  19
  20 will fail with `Can't call method "getSkin" on an undefined value at TWiki/Func.pm line 83`.
  21
  22 If you want to call the methods outside the context of a plugin, you can create a Plugins SESSION object. For example, the script:
  23
  24     use TWiki:
  25     $TWiki::Plugins::SESSION = new TWiki();
  26     print TWiki::Func::getSkin(),"\n";
  27
  28 will work happily.
  29
  30 <div>
  31   <ul>
  32     <li><a href="#Package =TWiki::Func="> Package TWiki::Func</a><ul>
  33         <li><a href="#Environment"> Environment</a><ul>
  34             <li><a href="#getSkin( ) -> $skin"> getSkin( ) -&gt; $skin</a></li>
  35             <li><a href="#get_UrlHost( ) -> $host"> getUrlHost( ) -&gt; $host</a></li>
  36             <li><a href="#get_ScriptUrl( $web, $topic, $sc"> getScriptUrl( $web, $topic, $script, ... ) -&gt; $url</a></li>
  37             <li><a href="#get_ViewUrl( $web, $topic ) -> $"> getViewUrl( $web, $topic ) -&gt; $url</a></li>
  38             <li><a href="#get_OopsUrl( $web, $topic, $temp"> getOopsUrl( $web, $topic, $template, $param1, $param2, $param3, $param4 ) -&gt; $url</a></li>
  39             <li><a href="#get_PubUrlPath( ) -> $path"> getPubUrlPath( ) -&gt; $path</a></li>
  40             <li><a href="#get_CgiQuery( ) -> $query"> getCgiQuery( ) -&gt; $query</a></li>
  41             <li><a href="#get_SessionValue( $key ) -> $val"> getSessionValue( $key ) -&gt; $value</a></li>
  42             <li><a href="#set_SessionValue( $key, $value )"> setSessionValue( $key, $value ) -&gt; $boolean</a></li>
  43             <li><a href="#clear_SessionValue( $key ) -> $b"> clearSessionValue( $key ) -&gt; $boolean</a></li>
  44             <li><a href="#getContext() -> \%hash"> getContext() -&gt; \%hash</a></li>
  45           </ul>
  46         </li>
  47         <li><a href="#Preferences"> Preferences</a><ul>
  48             <li><a href="#get_PreferencesValue( $key, $web"> getPreferencesValue( $key, $web ) -&gt; $value</a></li>
  49             <li><a href="#get_PluginPreferencesValue( $key"> getPluginPreferencesValue( $key ) -&gt; $value</a></li>
  50             <li><a href="#get_PreferencesFlag( $key, $web"> getPreferencesFlag( $key, $web ) -&gt; $value</a></li>
  51             <li><a href="#get_PluginPreferencesFlag( $key"> getPluginPreferencesFlag( $key ) -&gt; $boolean</a></li>
  52             <li><a href="#get_WikiToolName( ) -> $name"> getWikiToolName( ) -&gt; $name</a></li>
  53             <li><a href="#get_MainWebname( ) -> $name"> getMainWebname( ) -&gt; $name</a></li>
  54             <li><a href="#get_TwikiWebname( ) -> $name"> getTwikiWebname( ) -&gt; $name</a></li>
  55           </ul>
  56         </li>
  57         <li><a href="#User Handling and Access Control"> User Handling and Access Control</a><ul>
  58             <li><a href="#get_DefaultUserName( ) -> $login"> getDefaultUserName( ) -&gt; $loginName</a></li>
  59             <li><a href="#get_WikiName( ) -> $wikiName"> getWikiName( ) -&gt; $wikiName</a></li>
  60             <li><a href="#get_WikiUserName( ) -> $wikiName"> getWikiUserName( ) -&gt; $wikiName</a></li>
  61             <li><a href="#wiki_ToUserName( $wikiName ) ->"> wikiToUserName( $wikiName ) -&gt; $loginName</a></li>
  62             <li><a href="#user_ToWikiName( $loginName, $do"> userToWikiName( $loginName, $dontAddWeb ) -&gt; $wikiName</a></li>
  63             <li><a href="#isGuest( ) -> $boolean"> isGuest( ) -&gt; $boolean</a></li>
  64             <li><a href="#permissionsSet( $web ) -> $boole"> permissionsSet( $web ) -&gt; $boolean</a></li>
  65             <li><a href="#check_AccessPermission( $type, $"> checkAccessPermission( $type, $wikiName, $text, $topic, $web, $meta ) -&gt; $boolean</a></li>
  66           </ul>
  67         </li>
  68         <li><a href="#Webs, Topics and Attachments"> Webs, Topics and Attachments</a><ul>
  69             <li><a href="#get_ListOfWebs( $filter ) -> @we"> getListOfWebs( $filter ) -&gt; @webs</a></li>
  70             <li><a href="#webExists( $web ) -> $boolean"> webExists( $web ) -&gt; $boolean</a></li>
  71             <li><a href="#createWeb( $newWeb, $baseWeb, $o"> createWeb( $newWeb, $baseWeb, $opts )</a></li>
  72             <li><a href="#moveWeb( $oldName, $newName )"> moveWeb( $oldName, $newName )</a></li>
  73             <li><a href="#get_TopicList( $web ) -> @topics"> getTopicList( $web ) -&gt; @topics</a></li>
  74             <li><a href="#topicExists( $web, $topic ) -> $"> topicExists( $web, $topic ) -&gt; $boolean</a></li>
  75             <li><a href="#check_TopicEditLock( $web, $topi"> checkTopicEditLock( $web, $topic, $script ) -&gt; ( $oopsUrl, $loginName, $unlockTime )</a></li>
  76             <li><a href="#set_TopicEditLock( $web, $topic,"> setTopicEditLock( $web, $topic, $lock )</a></li>
  77             <li><a href="#saveTopic( $web, $topic, $meta,"> saveTopic( $web, $topic, $meta, $text, $options ) -&gt; $error</a></li>
  78             <li><a href="#save_TopicText( $web, $topic, $t"> saveTopicText( $web, $topic, $text, $ignorePermissions, $dontNotify ) -&gt; $oopsUrl</a></li>
  79             <li><a href="#moveTopic( $web, $topic, $newWeb"> moveTopic( $web, $topic, $newWeb, $newTopic )</a></li>
  80             <li><a href="#get_RevisionInfo($web, $topic, $"> getRevisionInfo($web, $topic, $rev, $attachment ) -&gt; ( $date, $user, $rev, $comment ) </a></li>
  81             <li><a href="#get_RevisionAtTime( $web, $topic"> getRevisionAtTime( $web, $topic, $time ) -&gt; $rev</a></li>
  82             <li><a href="#readTopic( $web, $topic, $rev )"> readTopic( $web, $topic, $rev ) -&gt; ( $meta, $text )</a></li>
  83             <li><a href="#read_TopicText( $web, $topic, $r"> readTopicText( $web, $topic, $rev, $ignorePermissions ) -&gt; $text</a></li>
  84             <li><a href="#attachmentExists( $web, $topic,"> attachmentExists( $web, $topic, $attachment ) -&gt; $boolean</a></li>
  85             <li><a href="#readAttachment( $web, $topic, $n"> readAttachment( $web, $topic, $name, $rev ) -&gt; $data</a></li>
  86             <li><a href="#saveAttachment( $web, $topic, $a"> saveAttachment( $web, $topic, $attachment, $opts )</a></li>
  87             <li><a href="#moveAttachment( $web, $topic, $a"> moveAttachment( $web, $topic, $attachment, $newWeb, $newTopic, $newAttachment )</a></li>
  88           </ul>
  89         </li>
  90         <li><a href="#Assembling Pages"> Assembling Pages</a><ul>
  91             <li><a href="#readTemplate( $name, $skin ) ->"> readTemplate( $name, $skin ) -&gt; $text</a></li>
  92             <li><a href="#loadTemplate ( $name, $skin, $we"> loadTemplate ( $name, $skin, $web ) -&gt; $text</a></li>
  93             <li><a href="#expandTemplate( $def  ) -> $stri"> expandTemplate( $def ) -&gt; $string</a></li>
  94             <li><a href="#writeHeader( $query, $contentLen"> writeHeader( $query, $contentLength )</a></li>
  95             <li><a href="#redirect_CgiQuery( $query, $url,"> redirectCgiQuery( $query, $url, $passthru )</a></li>
  96             <li><a href="#add_ToHEAD( $id, $header )"> addToHEAD( $id, $header )</a></li>
  97             <li><a href="#expand_CommonVariables( $text, $"> expandCommonVariables( $text, $topic, $web ) -&gt; $text</a></li>
  98             <li><a href="#renderText( $text, $web ) -> $te"> renderText( $text, $web ) -&gt; $text</a></li>
  99             <li><a href="#internalLink( $pre, $web, $topic"> internalLink( $pre, $web, $topic, $label, $anchor, $createLink ) -&gt; $text</a></li>
 100           </ul>
 101         </li>
 102         <li><a href="#E-mail"> E-mail</a><ul>
 103             <li><a href="#sendEmail ( $text, $retries ) ->"> sendEmail ( $text, $retries ) -&gt; $error</a></li>
 104             <li><a href="#wiki_ToEmail( $wikiName ) -> $em"> wikiToEmail( $wikiName ) -&gt; $email</a></li>
 105           </ul>
 106         </li>
 107         <li><a href="#Creating New Topics"> Creating New Topics</a><ul>
 108             <li><a href="#expand_VariablesOnTopicCreation"> expandVariablesOnTopicCreation ( $text ) -&gt; $text</a></li>
 109           </ul>
 110         </li>
 111         <li><a href="#Special handlers"> Special handlers</a><ul>
 112             <li><a href="#register_TagHandler( $var, \fn,"> registerTagHandler( $var, \&amp;fn, $syntax )</a></li>
 113             <li><a href="#registerRESTHandler( $alias, \fn"> registerRESTHandler( $alias, \&amp;fn, )</a></li>
 114           </ul>
 115         </li>
 116         <li><a href="#Searching"> Searching</a><ul>
 117             <li><a href="#search_InWebContent($searchStrin"> searchInWebContent($searchString, $web, \@topics, \%options ) -&gt; \%map</a></li>
 118           </ul>
 119         </li>
 120         <li><a href="#Plugin-specific file handling"> Plugin-specific file handling</a><ul>
 121             <li><a href="#get_WorkArea( $pluginName ) -> $"> getWorkArea( $pluginName ) -&gt; $directorypath</a></li>
 122             <li><a href="#readFile( $filename ) -> $text"> readFile( $filename ) -&gt; $text</a></li>
 123             <li><a href="#saveFile( $filename, $text )"> saveFile( $filename, $text )</a></li>
 124           </ul>
 125         </li>
 126         <li><a href="#General Utilities"> General Utilities</a><ul>
 127             <li><a href="#get_RegularExpression( $name ) -"> getRegularExpression( $name ) -&gt; $expr</a></li>
 128             <li><a href="#normalize_WebTopicName($web, $to"> normalizeWebTopicName($web, $topic) -&gt; ($web, $topic)</a></li>
 129             <li><a href="#writeWarning( $text )"> writeWarning( $text )</a></li>
 130             <li><a href="#writeDebug( $text )"> writeDebug( $text )</a></li>
 131             <li><a href="#formatTime( $time, $format, $tim"> formatTime( $time, $format, $timezone ) -&gt; $text</a></li>
 132             <li><a href="#is_ValidWikiWord ( $text ) -> $b"> isValidWikiWord ( $text ) -&gt; $boolean</a></li>
 133             <li><a href="#extractParameters($attr ) -> %pa"> extractParameters($attr ) -&gt; %params</a></li>
 134             <li><a href="#extract_NameValuePair( $attr, $n"> extractNameValuePair( $attr, $name ) -&gt; $value</a></li>
 135           </ul>
 136         </li>
 137         <li><a href="#Deprecated functions"> Deprecated functions</a><ul>
 138             <li><a href="#get_ScriptUrlPath( ) -> $path"> getScriptUrlPath( ) -&gt; $path</a></li>
 139             <li><a href="#get_PublicWebList( ) -> @webs"> getPublicWebList( ) -&gt; @webs</a></li>
 140             <li><a href="#format_GmTime( $time, $format )"> formatGmTime( $time, $format ) -&gt; $text</a></li>
 141             <li><a href="#get_DataDir( ) -> $dir"> getDataDir( ) -&gt; $dir</a></li>
 142             <li><a href="#get_PubDir( ) -> $dir"> getPubDir( ) -&gt; $dir</a></li>
 143             <li><a href="#checkDependencies( $moduleName,"> checkDependencies( $moduleName, $dependenciesRef ) -&gt; $error</a></li>
 144           </ul>
 145         </li>
 146       </ul>
 147     </li>
 148   </ul>
 149 </div>
 150
 151 ## <a name="Environment"></a> Environment
 152
 153 ### <a name="getSkin( ) - $skin"></a> getSkin( ) -&gt; $skin
 154
 155 Get the skin path, set by the `SKIN` and `COVER` preferences variables or the `skin` and `cover` CGI parameters
 156
 157 Return: `$skin` Comma-separated list of skins, e.g. `'gnu,tartan'`. Empty string if none.
 158
 159 **Since:** TWiki::Plugins::VERSION 1.000 (29 Jul 2001)
 160
 161 ### <a name="get_UrlHost( ) - $host"></a> getUrlHost( ) -&gt; $host
 162
 163 Get protocol, domain and optional port of script URL
 164
 165 Return: `$host` URL host, e.g. `"http://example.com:80"`
 166
 167 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
 168
 169 ### <a name="get_ScriptUrl( $web, $topic, $sc"></a> getScriptUrl( $web, $topic, $script, ... ) -&gt; $url
 170
 171 Compose fully qualified URL
 172
 173 - `$web` - Web name, e.g. `'Main'`
 174 - `$topic` - Topic name, e.g. `'WebNotify'`
 175 - `$script` - Script name, e.g. `'view'`
 176 - `...` - an arbitrary number of name,value parameter pairs that will be url-encoded and added to the url. The special parameter name '#' is reserved for specifying an anchor. e.g. `getScriptUrl('x','y','view','#'=>'XXX',a=>1,b=>2)` will give `.../view/x/y?a=1&b=2#XXX`
 177
 178 Return: `$url` URL, e.g. `"http://example.com:80/cgi-bin/view.pl/Main/WebNotify"`
 179
 180 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
 181
 182 ### <a name="get_ViewUrl( $web, $topic ) - $u"></a> getViewUrl( $web, $topic ) -&gt; $url
 183
 184 Compose fully qualified view URL
 185
 186 - `$web` - Web name, e.g. `'Main'`. The current web is taken if empty
 187 - `$topic` - Topic name, e.g. `'WebNotify'`
 188
 189 Return: `$url` URL, e.g. `"http://example.com:80/cgi-bin/view.pl/Main/WebNotify"`
 190
 191 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
 192
 193 ### <a name="get_OopsUrl( $web, $topic, $temp"></a> getOopsUrl( $web, $topic, $template, $param1, $param2, $param3, $param4 ) -&gt; $url
 194
 195 Compose fully qualified 'oops' dialog URL
 196
 197 - `$web` - Web name, e.g. `'Main'`. The current web is taken if empty
 198 - `$topic` - Topic name, e.g. `'WebNotify'`
 199 - `$template` - Oops template name, e.g. `'oopsmistake'`. The 'oops' is optional; 'mistake' will translate to 'oopsmistake'.
 200 - `$param1` ... `$param4` - Parameter values for %PARAM1% ... %PARAMn% variables in template, optional
 201
 202 Return: `$url` URL, e.g. `"http://example.com:80/cgi-bin/oops.pl/ Main/WebNotify?template=oopslocked&param1=joe"`
 203
 204 This might be used like this:
 205
 206        my $url = TWiki::Func::getOopsUrl($web, $topic, 'oopsmistake', 'I made a boo-boo');
 207        TWiki::Func::redirectCgiQuery( undef, $url );
 208        return 0;
 209
 210 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
 211
 212 Since TWiki::Plugins::VERSION 1.1, the recommended approach is to throw an [[oops exception|Main/TWikiOopsExceptionDotPm]].
 213
 214        use Error qw( :try );
 215
 216        throw TWiki::OopsException($web, $topic, undef, 0, [ 'I made a boo-boo' ]);
 217
 218 and let TWiki handle the cleanup.
 219
 220 ### <a name="get_PubUrlPath( ) - $path"></a> getPubUrlPath( ) -&gt; $path
 221
 222 Get pub URL path
 223
 224 Return: `$path` URL path of pub directory, e.g. `"/pub"`
 225
 226 **Since:** TWiki::Plugins::VERSION 1.000 (14 Jul 2001)
 227
 228 ### <a name="get_CgiQuery( ) - $query"></a> getCgiQuery( ) -&gt; $query
 229
 230 Get CGI query object. Important: Plugins cannot assume that scripts run under CGI, Plugins must always test if the CGI query object is set
 231
 232 Return: `$query` CGI query object; or 0 if script is called as a shell script
 233
 234 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
 235
 236 ### <a name="get_SessionValue( $key ) - $valu"></a> getSessionValue( $key ) -&gt; $value
 237
 238 Get a session value from the client session module
 239
 240 - `$key` - Session key
 241
 242 Return: `$value` Value associated with key; empty string if not set
 243
 244 **Since:** TWiki::Plugins::VERSION 1.000 (27 Feb 200)
 245
 246 ### <a name="set_SessionValue( $key, $value )"></a> setSessionValue( $key, $value ) -&gt; $boolean
 247
 248 Set a session value.
 249
 250 - `$key` - Session key
 251 - `$value` - Value associated with key
 252
 253 Return: true if function succeeded
 254
 255 **Since:** TWiki::Plugins::VERSION 1.000 (17 Aug 2001)
 256
 257 ### <a name="clear_SessionValue( $key ) - $bo"></a> clearSessionValue( $key ) -&gt; $boolean
 258
 259 Clear a session value that was set using `setSessionValue`.
 260
 261 - `$key` - name of value stored in session to be cleared. Note that you **cannot** clear `AUTHUSER`.
 262
 263 Return: true if the session value was cleared
 264
 265 **Since:** TWiki::Plugins::VERSION 1.1
 266
 267 ### <a name="getContext() - \%hash"></a> getContext() -&gt; \\%hash
 268
 269 Get a hash of context identifiers representing the currently active context.
 270
 271 The context is a set of identifiers that are set during specific phases of TWiki processing. For example, each of the standard scripts in the 'bin' directory each has a context identifier - the view script has 'view', the edit script has 'edit' etc. So you can easily tell what 'type' of script your Plugin is being called within. The core context identifiers are listed in the [[TWikiTemplates]] topic. Please be careful not to overwrite any of these identifiers!
 272
 273 Context identifiers can be used to communicate between Plugins, and between Plugins and templates. For example, in [[FirstPlugin]].pm, you might write:
 274
 275     sub initPlugin {
 276        TWiki::Func::getContext()->{'MyID'} = 1;
 277        ...
 278
 279 This can be used in SecondPlugin.pm like this:
 280
 281     sub initPlugin {
 282        if( TWiki::Func::getContext()->{'MyID'} ) {
 283           ...
 284        }
 285        ...
 286
 287 or in a template, like this:
 288
 289     %TMPL:DEF{"ON"}% Not off %TMPL:END%
 290     %TMPL:DEF{"OFF"}% Not on %TMPL:END%
 291     %TMPL:P{context="MyID" then="ON" else="OFF"}%
 292
 293 or in a topic:
 294
 295     %IF{"context MyID" then="MyID is ON" else="MyID is OFF"}%
 296
 297 **_Note_**: **all** plugins have an **automatically generated** context identifier if they are installed and initialised. For example, if the [[FirstPlugin]] is working, the context ID 'FirstPlugin' will be set.
 298
 299 **Since:** TWiki::Plugins::VERSION 1.1
 300
 301 ## <a name="Preferences"></a> Preferences
 302
 303 ### <a name="get_PreferencesValue( $key, $web"></a> getPreferencesValue( $key, $web ) -&gt; $value
 304
 305 Get a preferences value from TWiki or from a Plugin
 306
 307 - `$key` - Preferences key
 308 - `$web` - Name of web, optional. Current web if not specified; does not apply to settings of Plugin topics
 309
 310 Return: `$value` Preferences value; empty string if not set
 311
 312 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
 313
 314 - Example for Plugin setting:
 315   - [[MyPlugin]] topic has: `* Set COLOR = red`
 316   - Use `"MYPLUGIN_COLOR"` for `$key`
 317   - `my $color = TWiki::Func::getPreferencesValue( "MYPLUGIN_COLOR" );`
 318
 319 - Example for preferences setting:
 320   - [[WebPreferences]] topic has: `* Set WEBBGCOLOR = #FFFFC0`
 321   - `my $webColor = TWiki::Func::getPreferencesValue( 'WEBBGCOLOR', 'Sandbox' );`
 322
 323 **NOTE:** As of TWiki4.1, if `$NO_PREFS_IN_TOPIC` is enabled in the plugin, then preferences set in the plugin topic will be ignored.
 324
 325 ### <a name="get_PluginPreferencesValue( $key"></a> getPluginPreferencesValue( $key ) -&gt; $value
 326
 327 Get a preferences value from your Plugin
 328
 329 - `$key` - Plugin Preferences key w/o PLUGINNAME\_ prefix.
 330
 331 Return: `$value` Preferences value; empty string if not set
 332
 333 **_Note_**: This function will will **only** work when called from the Plugin.pm file itself. it **will not work** if called from a sub-package (e.g. TWiki::Plugins::MyPlugin::MyModule)
 334
 335 **Since:** TWiki::Plugins::VERSION 1.021 (27 Mar 2004)
 336
 337 **NOTE:** As of TWiki4.1, if `$NO_PREFS_IN_TOPIC` is enabled in the plugin, then preferences set in the plugin topic will be ignored.
 338
 339 ### <a name="get_PreferencesFlag( $key, $web"></a><a name="get_PreferencesFlag( $key, $web "></a> getPreferencesFlag( $key, $web ) -&gt; $value
 340
 341 Get a preferences flag from TWiki or from a Plugin
 342
 343 - `$key` - Preferences key
 344 - `$web` - Name of web, optional. Current web if not specified; does not apply to settings of Plugin topics
 345
 346 Return: `$value` Preferences flag `'1'` (if set), or `"0"` (for preferences values `"off"`, `"no"` and `"0"`)
 347
 348 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
 349
 350 - Example for Plugin setting:
 351   - [[MyPlugin]] topic has: `* Set SHOWHELP = off`
 352   - Use `"MYPLUGIN_SHOWHELP"` for `$key`
 353   - `my $showHelp = TWiki::Func::getPreferencesFlag( "MYPLUGIN_SHOWHELP" );`
 354
 355 **NOTE:** As of TWiki4.1, if `$NO_PREFS_IN_TOPIC` is enabled in the plugin, then preferences set in the plugin topic will be ignored.
 356
 357 ### <a name="get_PluginPreferencesFlag( $key"></a><a name="get_PluginPreferencesFlag( $key "></a> getPluginPreferencesFlag( $key ) -&gt; $boolean
 358
 359 Get a preferences flag from your Plugin
 360
 361 - `$key` - Plugin Preferences key w/o PLUGINNAME\_ prefix.
 362
 363 Return: false for preferences values `"off"`, `"no"` and `"0"`, or values not set at all. True otherwise.
 364
 365 **_Note_**: This function will will **only** work when called from the Plugin.pm file itself. it **will not work** if called from a sub-package (e.g. TWiki::Plugins::MyPlugin::MyModule)
 366
 367 **Since:** TWiki::Plugins::VERSION 1.021 (27 Mar 2004)
 368
 369 **NOTE:** As of TWiki4.1, if `$NO_PREFS_IN_TOPIC` is enabled in the plugin, then preferences set in the plugin topic will be ignored.
 370
 371 ### <a name="get_WikiToolName( ) - $name"></a> getWikiToolName( ) -&gt; $name
 372
 373 Get toolname as defined in TWiki.cfg
 374
 375 Return: `$name` Name of tool, e.g. `'TWiki'`
 376
 377 **Since:** TWiki::Plugins::VERSION 1.000 (27 Feb 2001)
 378
 379 ### <a name="get_MainWebname( ) - $name"></a> getMainWebname( ) -&gt; $name
 380
 381 Get name of Main web as defined in TWiki.cfg
 382
 383 Return: `$name` Name, e.g. `'Main'`
 384
 385 **Since:** TWiki::Plugins::VERSION 1.000 (27 Feb 2001)
 386
 387 ### <a name="get_TwikiWebname( ) - $name"></a> getTwikiWebname( ) -&gt; $name
 388
 389 Get name of TWiki documentation web as defined in TWiki.cfg
 390
 391 Return: `$name` Name, e.g. `'TWiki'`
 392
 393 **Since:** TWiki::Plugins::VERSION 1.000 (27 Feb 2001)
 394
 395 ## <a name="User Handling and Access Control"></a> User Handling and Access Control
 396
 397 ### <a name="get_DefaultUserName( ) - $loginN"></a> getDefaultUserName( ) -&gt; $loginName
 398
 399 Get default user name as defined in the configuration as `DefaultUserLogin`
 400
 401 Return: `$loginName` Default user name, e.g. `'guest'`
 402
 403 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
 404
 405 ### <a name="get_WikiName( ) - $wikiName"></a> getWikiName( ) -&gt; $wikiName
 406
 407 Get Wiki name of logged in user
 408
 409 Return: `$wikiName` Wiki Name, e.g. `'JohnDoe'`
 410
 411 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
 412
 413 ### <a name="get_WikiUserName( ) - $wikiName"></a> getWikiUserName( ) -&gt; $wikiName
 414
 415 Get Wiki name of logged in user with web prefix
 416
 417 Return: `$wikiName` Wiki Name, e.g. `"Main.JohnDoe"`
 418
 419 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
 420
 421 ### <a name="wiki_ToUserName( $wikiName ) - $"></a> wikiToUserName( $wikiName ) -&gt; $loginName
 422
 423 Translate a Wiki name to a login name based on [[Main.TWikiUsers|Main/TWikiUsers]] topic
 424
 425 - `$wikiName` - Wiki name, e.g. `'Main.JohnDoe'` or `'JohnDoe'`
 426
 427 Return: `$loginName` Login name of user, e.g. `'jdoe'`
 428
 429 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
 430
 431 ### <a name="user_ToWikiName( $loginName, $do"></a> userToWikiName( $loginName, $dontAddWeb ) -&gt; $wikiName
 432
 433 Translate a login name to a Wiki name based on [[Main.TWikiUsers|Main/TWikiUsers]] topic
 434
 435 - `$loginName` - Login name, e.g. `'jdoe'`
 436 - `$dontAddWeb` - Do not add web prefix if `"1"`
 437
 438 Return: `$wikiName` Wiki name of user, e.g. `'Main.JohnDoe'` or `'JohnDoe'`
 439
 440 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
 441
 442 ### <a name="isGuest( ) - $boolean"></a> isGuest( ) -&gt; $boolean
 443
 444 Test if logged in user is a guest ([[TWikiGuest]])
 445
 446 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
 447
 448 ### <a name="permissionsSet( $web ) - $boolea"></a> permissionsSet( $web ) -&gt; $boolean
 449
 450 Test if any access restrictions are set for this web, ignoring settings on individual pages
 451
 452 - `$web` - Web name, required, e.g. `'Sandbox'`
 453
 454 **Since:** TWiki::Plugins::VERSION 1.000 (27 Feb 2001)
 455
 456 ### <a name="check_AccessPermission( $type, $"></a> checkAccessPermission( $type, $wikiName, $text, $topic, $web, $meta ) -&gt; $boolean
 457
 458 Check access permission for a topic based on the [[TWiki.TWikiAccessControl|TWiki/TWikiAccessControl]] rules
 459
 460 - `$type` - Access type, required, e.g. `'VIEW'`, `'CHANGE'`.
 461 - `$wikiName` - [[WikiName]] of remote user, required, e.g. `"PeterThoeny"`. If `$wikiName` is '', 0 or `undef` then access is **always permitted**.
 462 - `$text` - Topic text, optional. If 'perl false' (undef, 0 or ''), topic `$web.$topic` is consulted. `$text` may optionally contain embedded `%META:PREFERENCE` tags. Provide this parameter if:
 463   1. You are setting different access controls in the text to those defined in the stored topic,
 464   2. You already have the topic text in hand, and want to help TWiki avoid having to read it again,
 465   3. You are providing a `$meta` parameter.
 466 - `$topic` - Topic name, required, e.g. `'PrivateStuff'`
 467 - `$web` - Web name, required, e.g. `'Sandbox'`
 468 - `$meta` - Meta-data object, as returned by `readTopic`. Optional. If `undef`, but `$text` is defined, then access controls will be parsed from `$text`. If defined, then metadata embedded in `$text` will be ignored. This parameter is always ignored if `$text` is undefined. Settings in `$meta` override `Set` settings in $text.
 469
 470 A perl true result indicates that access is permitted.
 471
 472 **Note** the wierd parameter order is due to compatibility constraints with earlier TWiki releases.
 473
 474 **Tip** if you want, you can use this method to check your own access control types. For example, if you:
 475
 476 - Set ALLOWTOPICSPIN = [[IncyWincy]]
 477
 478 in `ThatWeb.ThisTopic`, then a call to `checkAccessPermissions('SPIN', 'IncyWincy', undef, 'ThisTopic', 'ThatWeb', undef)` will return `true`.
 479
 480 **Since:** TWiki::Plugins::VERSION 1.000 (27 Feb 2001)
 481
 482 ## <a name="Webs, Topics and Attachments"></a> Webs, Topics and Attachments
 483
 484 ### <a name="get_ListOfWebs( $filter ) - @web"></a> getListOfWebs( $filter ) -&gt; @webs
 485
 486 - `$filter` - spec of web types to recover
 487
 488 Gets a list of webs, filtered according to the spec in the $filter, which may include one of:
 489
 490 1. 'user' (for only user webs)
 491 2. 'template' (for only template webs i.e. those starting with "\_")
 492
 493 `$filter` may also contain the word 'public' which will further filter out webs that have NOSEARCHALL set on them. 'allowed' filters out webs the current user can't read.
 494
 495 For example, the deprecated getPublicWebList function can be duplicated as follows:
 496
 497        my @webs = TWiki::Func::getListOfWebs( "user,public" );
 498
 499 **Since:** TWiki::Plugins::VERSION 1.1
 500
 501 ### <a name="webExists( $web ) - $boolean"></a> webExists( $web ) -&gt; $boolean
 502
 503 Test if web exists
 504
 505 - `$web` - Web name, required, e.g. `'Sandbox'`
 506
 507 **Since:** TWiki::Plugins::VERSION 1.000 (14 Jul 2001)
 508
 509 ### <a name="createWeb( $newWeb, $baseWeb, $o"></a> createWeb( $newWeb, $baseWeb, $opts )
 510
 511 - `$newWeb` is the name of the new web.
 512 - `$baseWeb` is the name of an existing web (a template web). If the base web is a system web, all topics in it will be copied into the new web. If it is a normal web, only topics starting with 'Web' will be copied. If no base web is specified, an empty web (with no topics) will be created. If it is specified but does not exist, an error will be thrown.
 513 - `$opts` is a ref to a hash that contains settings to be modified in
 514
 515 the web preferences topic in the new web.
 516
 517     use Error qw( :try );
 518     use TWiki::AccessControlException;
 519
 520     try {
 521         TWiki::Func::createWeb( "Newweb" );
 522     } catch Error::Simple with {
 523         my $e = shift;
 524         # see documentation on Error::Simple
 525     } catch TWiki::AccessControlException with {
 526         my $e = shift;
 527         # see documentation on TWiki::AccessControlException
 528     } otherwise {
 529         ...
 530     };
 531
 532 **Since:** TWiki::Plugins::VERSION 1.1
 533
 534 ### <a name="moveWeb( $oldName, $newName )"></a> moveWeb( $oldName, $newName )
 535
 536 Move (rename) a web.
 537
 538     use Error qw( :try );
 539     use TWiki::AccessControlException;
 540
 541     try {
 542         TWiki::Func::moveWeb( "Oldweb", "Newweb" );
 543     } catch Error::Simple with {
 544         my $e = shift;
 545         # see documentation on Error::Simple
 546     } catch TWiki::AccessControlException with {
 547         my $e = shift;
 548         # see documentation on TWiki::AccessControlException
 549     } otherwise {
 550         ...
 551     };
 552
 553 To delete a web, move it to a subweb of `Trash`
 554
 555     TWiki::Func::moveWeb( "Deadweb", "Trash.Deadweb" );
 556
 557 **Since:** TWiki::Plugins::VERSION 1.1
 558
 559 ### <a name="get_TopicList( $web ) - @topics"></a> getTopicList( $web ) -&gt; @topics
 560
 561 Get list of all topics in a web
 562
 563 - `$web` - Web name, required, e.g. `'Sandbox'`
 564
 565 Return: `@topics` Topic list, e.g. `( 'WebChanges',  'WebHome', 'WebIndex', 'WebNotify' )`
 566
 567 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
 568
 569 ### <a name="topicExists( $web, $topic ) - $b"></a> topicExists( $web, $topic ) -&gt; $boolean
 570
 571 Test if topic exists
 572
 573 - `$web` - Web name, optional, e.g. `'Main'`.
 574 - `$topic` - Topic name, required, e.g. `'TokyoOffice'`, or `"Main.TokyoOffice"`
 575
 576 $web and $topic are parsed as described in the documentation for `normalizeWebTopicName`.
 577
 578 **Since:** TWiki::Plugins::VERSION 1.000 (14 Jul 2001)
 579
 580 ### <a name="check_TopicEditLock( $web, $topi"></a> checkTopicEditLock( $web, $topic, $script ) -&gt; ( $oopsUrl, $loginName, $unlockTime )
 581
 582 Check if a lease has been taken by some other user.
 583
 584 - `$web` Web name, e.g. `"Main"`, or empty
 585 - `$topic` Topic name, e.g. `"MyTopic"`, or `"Main.MyTopic"`
 586
 587 Return: `( $oopsUrl, $loginName, $unlockTime )` - The `$oopsUrl` for calling redirectCgiQuery(), user's `$loginName`, and estimated `$unlockTime` in minutes, or ( '', '', 0 ) if no lease exists.
 588
 589 - `$script` The script to invoke when continuing with the edit
 590
 591 **Since:** TWiki::Plugins::VERSION 1.010 (31 Dec 2002)
 592
 593 ### <a name="set_TopicEditLock( $web, $topic,"></a> setTopicEditLock( $web, $topic, $lock )
 594
 595 - `$web` Web name, e.g. `"Main"`, or empty
 596 - `$topic` Topic name, e.g. `"MyTopic"`, or `"Main.MyTopic"`
 597 - `$lock` 1 to lease the topic, 0 to clear the lease=
 598
 599 Takes out a "lease" on the topic. The lease doesn't prevent anyone from editing and changing the topic, but it does redirect them to a warning screen, so this provides some protection. The `edit` script always takes out a lease.
 600
 601 It is **impossible** to fully lock a topic. Concurrent changes will be merged.
 602
 603 **Since:** TWiki::Plugins::VERSION 1.010 (31 Dec 2002)
 604
 605 ### <a name="saveTopic( $web, $topic, $meta,"></a><a name="saveTopic( $web, $topic, $meta, "></a> saveTopic( $web, $topic, $meta, $text, $options ) -&gt; $error
 606
 607 - `$web` - web for the topic
 608 - `$topic` - topic name
 609 - `$meta` - reference to TWiki::Meta object
 610 - `$text` - text of the topic (without embedded meta-data!!!
 611 - `\%options` - ref to hash of save options `\%options` may include: <table border="1" cellpadding="0" cellspacing="0">
 612   <tr>
 613     <td><code>dontlog</code></td>
 614     <td> don't log this change in twiki log </td>
 615   </tr>
 616   <tr>
 617     <td><code>comment</code></td>
 618     <td> comment for save </td>
 619   </tr>
 620   <tr>
 621     <td><code>minor</code></td>
 622     <td> True if this is a minor change, and is not to be notified </td>
 623   </tr>
 624 </table>
 625
 626 Return: error message or undef.
 627
 628 **Since:** TWiki::Plugins::VERSION 1.000 (29 Jul 2001)
 629
 630 For example,
 631
 632     my( $meta, $text ) = TWiki::Func::readTopic( $web, $topic )
 633     $text =~ s/APPLE/ORANGE/g;
 634     TWiki::Func::saveTopic( $web, $topic, $meta, $text, { comment => 'refruited' } );
 635
 636 **_Note:_** Plugins handlers ( e.g. `beforeSaveHandler` ) will be called as appropriate.
 637
 638 ### <a name="save_TopicText( $web, $topic, $t"></a> saveTopicText( $web, $topic, $text, $ignorePermissions, $dontNotify ) -&gt; $oopsUrl
 639
 640 Save topic text, typically obtained by readTopicText(). Topic data usually includes meta data; the file attachment meta data is replaced by the meta data from the topic file if it exists.
 641
 642 - `$web` - Web name, e.g. `'Main'`, or empty
 643 - `$topic` - Topic name, e.g. `'MyTopic'`, or `"Main.MyTopic"`
 644 - `$text` - Topic text to save, assumed to include meta data
 645 - `$ignorePermissions` - Set to `"1"` if checkAccessPermission() is already performed and OK
 646 - `$dontNotify` - Set to `"1"` if not to notify users of the change
 647
 648 Return: `$oopsUrl` Empty string if OK; the `$oopsUrl` for calling redirectCgiQuery() in case of error
 649
 650 This method is a lot less efficient and much more dangerous than `saveTopic`.
 651
 652 **Since:** TWiki::Plugins::VERSION 1.010 (31 Dec 2002)
 653
 654     my $text = TWiki::Func::readTopicText( $web, $topic );
 655
 656     # check for oops URL in case of error:
 657     if( $text =~ /^http.*?\/oops/ ) {
 658         TWiki::Func::redirectCgiQuery( $query, $text );
 659         return;
 660     }
 661     # do topic text manipulation like:
 662     $text =~ s/old/new/g;
 663     # do meta data manipulation like:
 664     $text =~ s/(META\:FIELD.*?name\=\"TopicClassification\".*?value\=\")[^\"]*/$1BugResolved/;
 665     $oopsUrl = TWiki::Func::saveTopicText( $web, $topic, $text ); # save topic text
 666
 667 ### <a name="moveTopic( $web, $topic, $newWeb"></a> moveTopic( $web, $topic, $newWeb, $newTopic )
 668
 669 - `$web` source web - required
 670 - `$topic` source topic - required
 671 - `$newWeb` dest web
 672 - `$newTopic` dest topic
 673
 674 Renames the topic. Throws an exception if something went wrong. If $newWeb is undef, it defaults to $web. If $newTopic is undef, it defaults to $topic.
 675
 676 The destination topic must not already exist.
 677
 678 Rename a topic to the $TWiki::cfg\{TrashWebName\} to delete it.
 679
 680 **Since:** TWiki::Plugins::VERSION 1.1
 681
 682     use Error qw( :try );
 683
 684     try {
 685         moveTopic( "Work", "TokyoOffice", "Trash", "ClosedOffice" );
 686     } catch Error::Simple with {
 687         my $e = shift;
 688         # see documentation on Error::Simple
 689     } catch TWiki::AccessControlException with {
 690         my $e = shift;
 691         # see documentation on TWiki::AccessControlException
 692     } otherwise {
 693         ...
 694     };
 695
 696 ### <a name="get_RevisionInfo($web, $topic, $"></a> getRevisionInfo($web, $topic, $rev, $attachment ) -&gt; ( $date, $user, $rev, $comment )
 697
 698 Get revision info of a topic or attachment
 699
 700 - `$web` - Web name, optional, e.g. `'Main'`
 701 - `$topic` - Topic name, required, e.g. `'TokyoOffice'`
 702 - `$rev` - revsion number, or tag name (can be in the format 1.2, or just the minor number)
 703 - `$attachment` -attachment filename
 704
 705 Return: `( $date, $user, $rev, $comment )` List with: ( last update date, login name of last user, minor part of top revision number ), e.g. `( 1234561, 'phoeny', "5" )`
 706
 707 <table border="1" cellpadding="0" cellspacing="0">
 708   <tr>
 709     <td> $date </td>
 710     <td> in epochSec </td>
 711   </tr>
 712   <tr>
 713     <td> $user </td>
 714     <td> Wiki name of the author (<strong>not</strong> login name) </td>
 715   </tr>
 716   <tr>
 717     <td> $rev </td>
 718     <td> actual rev number </td>
 719   </tr>
 720   <tr>
 721     <td> $comment </td>
 722     <td> WHAT COMMENT? </td>
 723   </tr>
 724 </table>
 725
 726 NOTE: if you are trying to get revision info for a topic, use `$meta->getRevisionInfo` instead if you can - it is significantly more efficient, and returns a user object that contains other user information.
 727
 728 NOTE: prior versions of TWiki may under some circumstances have returned the login name of the user rather than the wiki name; the code documentation was totally unclear, and we have been unable to establish the intent. However the wikiname is obviously more useful, so that is what is returned.
 729
 730 **Since:** TWiki::Plugins::VERSION 1.000 (29 Jul 2001)
 731
 732 ### <a name="get_RevisionAtTime( $web, $topic"></a> getRevisionAtTime( $web, $topic, $time ) -&gt; $rev
 733
 734 Get the revision number of a topic at a specific time.
 735
 736 - `$web` - web for topic
 737 - `$topic` - topic
 738 - `$time` - time (in epoch secs) for the rev
 739
 740 Return: Single-digit revision number, or undef if it couldn't be determined (either because the topic isn't that old, or there was a problem)
 741
 742 **Since:** TWiki::Plugins::VERSION 1.1
 743
 744 ### <a name="readTopic( $web, $topic, $rev )"></a><a name="readTopic( $web, $topic, $rev ) "></a> readTopic( $web, $topic, $rev ) -&gt; ( $meta, $text )
 745
 746 Read topic text and meta data, regardless of access permissions.
 747
 748 - `$web` - Web name, required, e.g. `'Main'`
 749 - `$topic` - Topic name, required, e.g. `'TokyoOffice'`
 750 - `$rev` - revision to read (default latest)
 751
 752 Return: `( $meta, $text )` Meta data object and topic text
 753
 754 `$meta` is a perl 'object' of class `TWiki::Meta`. This class is fully documented in the source code documentation shipped with the release, or can be inspected in the `lib/TWiki/Meta.pm` file.
 755
 756 This method **ignores** topic access permissions. You should be careful to use `checkAccessPermissions` to ensure the current user has read access to the topic.
 757
 758 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
 759
 760 ### <a name="read_TopicText( $web, $topic, $r"></a> readTopicText( $web, $topic, $rev, $ignorePermissions ) -&gt; $text
 761
 762 Read topic text, including meta data
 763
 764 - `$web` - Web name, e.g. `'Main'`, or empty
 765 - `$topic` - Topic name, e.g. `'MyTopic'`, or `"Main.MyTopic"`
 766 - `$rev` - Topic revision to read, optional. Specify the minor part of the revision, e.g. `"5"`, not `"1.5"`; the top revision is returned if omitted or empty.
 767 - `$ignorePermissions` - Set to `"1"` if checkAccessPermission() is already performed and OK; an oops URL is returned if user has no permission
 768
 769 Return: `$text` Topic text with embedded meta data; an oops URL for calling redirectCgiQuery() is returned in case of an error
 770
 771 This method is more efficient than `readTopic`, but returns meta-data embedded in the text. Plugins authors must be very careful to avoid damaging meta-data. You are recommended to use readTopic instead, which is a lot safer..
 772
 773 **Since:** TWiki::Plugins::VERSION 1.010 (31 Dec 2002)
 774
 775 ### <a name="attachmentExists( $web, $topic,"></a><a name="attachmentExists( $web, $topic, "></a> attachmentExists( $web, $topic, $attachment ) -&gt; $boolean
 776
 777 Test if attachment exists
 778
 779 - `$web` - Web name, optional, e.g. `Main`.
 780 - `$topic` - Topic name, required, e.g. `TokyoOffice`, or `Main.TokyoOffice`
 781 - `$attachment` - attachment name, e.g.=logo.gif=
 782
 783 $web and $topic are parsed as described in the documentation for `normalizeWebTopicName`.
 784
 785 **Since:** TWiki::Plugins::VERSION 1.1
 786
 787 ### <a name="readAttachment( $web, $topic, $n"></a> readAttachment( $web, $topic, $name, $rev ) -&gt; $data
 788
 789 - `$web` - web for topic
 790 - `$topic` - topic
 791 - `$name` - attachment name
 792 - `$rev` - revision to read (default latest)
 793
 794 Read an attachment from the store for a topic, and return it as a string. The names of attachments on a topic can be recovered from the meta-data returned by `readTopic`. If the attachment does not exist, or cannot be read, undef will be returned. If the revision is not specified, the latest version will be returned.
 795
 796 View permission on the topic is required for the read to be successful. Access control violations are flagged by a TWiki::AccessControlException. Permissions are checked for the current user.
 797
 798     my( $meta, $text ) = TWiki::Func::readTopic( $web, $topic );
 799     my @attachments = $meta->find( 'FILEATTACHMENT' );
 800     foreach my $a ( @attachments ) {
 801        try {
 802            my $data = TWiki::Func::readAttachment( $web, $topic, $a->{name} );
 803            ...
 804        } catch TWiki::AccessControlException with {
 805        };
 806     }
 807
 808 **Since:** TWiki::Plugins::VERSION 1.1
 809
 810 ### <a name="saveAttachment( $web, $topic, $a"></a> saveAttachment( $web, $topic, $attachment, $opts )
 811
 812 - `$web` - web for topic
 813 - `$topic` - topic to atach to
 814 - `$attachment` - name of the attachment
 815 - `$opts` - Ref to hash of options
 816
 817 `$opts` may include:
 818
 819 <table border="1" cellpadding="0" cellspacing="0">
 820   <tr>
 821     <td><code>dontlog</code></td>
 822     <td> don't log this change in twiki log </td>
 823   </tr>
 824   <tr>
 825     <td><code>comment</code></td>
 826     <td> comment for save </td>
 827   </tr>
 828   <tr>
 829     <td><code>hide</code></td>
 830     <td> if the attachment is to be hidden in normal topic view </td>
 831   </tr>
 832   <tr>
 833     <td><code>stream</code></td>
 834     <td> Stream of file to upload </td>
 835   </tr>
 836   <tr>
 837     <td><code>file</code></td>
 838     <td> Name of a file to use for the attachment data. ignored if stream is set. Local file on the server. </td>
 839   </tr>
 840   <tr>
 841     <td><code>filepath</code></td>
 842     <td> Client path to file </td>
 843   </tr>
 844   <tr>
 845     <td><code>filesize</code></td>
 846     <td> Size of uploaded data </td>
 847   </tr>
 848   <tr>
 849     <td><code>filedate</code></td>
 850     <td> Date </td>
 851   </tr>
 852 </table>
 853
 854 Save an attachment to the store for a topic. On success, returns undef. If there is an error, an exception will be thrown.
 855
 856         try {
 857             TWiki::Func::saveAttachment( $web, $topic, 'image.gif',
 858                                          { file => 'image.gif',
 859                                            comment => 'Picture of Health',
 860                                            hide => 1 } );
 861        } catch Error::Simple with {
 862           # see documentation on Error
 863        } otherwise {
 864           ...
 865        };
 866
 867 **Since:** TWiki::Plugins::VERSION 1.1
 868
 869 ### <a name="moveAttachment( $web, $topic, $a"></a> moveAttachment( $web, $topic, $attachment, $newWeb, $newTopic, $newAttachment )
 870
 871 - `$web` source web - required
 872 - `$topic` source topic - required
 873 - `$attachment` source attachment - required
 874 - `$newWeb` dest web
 875 - `$newTopic` dest topic
 876 - `$newAttachment` dest attachment
 877
 878 Renames the topic. Throws an exception on error or access violation. If $newWeb is undef, it defaults to $web. If $newTopic is undef, it defaults to $topic. If $newAttachment is undef, it defaults to $attachment. If all of $newWeb, $newTopic and $newAttachment are undef, it is an error.
 879
 880 The destination topic must already exist, but the destination attachment must **not** exist.
 881
 882 Rename an attachment to $TWiki::cfg\{TrashWebName\}.TrashAttament to delete it.
 883
 884     use Error qw( :try );
 885
 886     try {
 887        # move attachment between topics
 888        moveAttachment( "Countries", "Germany", "AlsaceLorraine.dat",
 889                          "Countries", "France" );
 890        # Note destination attachment name is defaulted to the same as source
 891     } catch TWiki::AccessControlException with {
 892        my $e = shift;
 893        # see documentation on TWiki::AccessControlException
 894     } catch Error::Simple with {
 895        my $e = shift;
 896        # see documentation on Error::Simple
 897     };
 898
 899 **Since:** TWiki::Plugins::VERSION 1.1
 900
 901 ## <a name="Assembling Pages"></a> Assembling Pages
 902
 903 ### <a name="readTemplate( $name, $skin ) - $"></a> readTemplate( $name, $skin ) -&gt; $text
 904
 905 Read a template or skin. Embedded [[template directives|TWiki/TWikiTemplates]] get expanded
 906
 907 - `$name` - Template name, e.g. `'view'`
 908 - `$skin` - Comma-separated list of skin names, optional, e.g. `'print'`
 909
 910 Return: `$text` Template text
 911
 912 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
 913
 914 ### <a name="loadTemplate ( $name, $skin, $we"></a> loadTemplate ( $name, $skin, $web ) -&gt; $text
 915
 916 - `$name` - template file name
 917 - `$skin` - comma-separated list of skins to use (default: current skin)
 918 - `$web` - the web to look in for topics that contain templates (default: current web)
 919
 920 Return: expanded template text (what's left after removal of all %TMPL:DEF% statements)
 921
 922 **Since:** TWiki::Plugins::VERSION 1.1
 923
 924 Reads a template and extracts template definitions, adding them to the list of loaded templates, overwriting any previous definition.
 925
 926 How TWiki searches for templates is described in [[TWikiTemplates]].
 927
 928 If template text is found, extracts include statements and fully expands them.
 929
 930 ### <a name="expandTemplate( $def  ) - $strin"></a> expandTemplate( $def ) -&gt; $string
 931
 932 Do a , only expanding the template (not expanding any variables other than %TMPL)
 933
 934 - `$def` - template name
 935
 936 Return: the text of the expanded template
 937
 938 **Since:** TWiki::Plugins::VERSION 1.1
 939
 940 A template is defined using a %TMPL:DEF% statement in a template file. See the documentation on TWiki templates for more information.
 941
 942 ### <a name="writeHeader( $query, $contentLen"></a> writeHeader( $query, $contentLength )
 943
 944 Prints a basic content-type HTML header for text/html to standard out
 945
 946 - `$query` - CGI query object. If not given, the default CGI query will be used. In most cases you should _not_ pass this parameter.
 947 - `$contentLength` - Length of content
 948
 949 Return: none
 950
 951 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
 952
 953 ### <a name="redirect_CgiQuery( $query, $url,"></a> redirectCgiQuery( $query, $url, $passthru )
 954
 955 Redirect to URL
 956
 957 - `$query` - CGI query object. Ignored, only there for compatibility. The session CGI query object is used instead.
 958 - `$url` - URL to redirect to
 959 - `$passthru` - enable passthrough.
 960
 961 Return: none
 962
 963 Print output to STDOUT that will cause a 302 redirect to a new URL. Nothing more should be printed to STDOUT after this method has been called.
 964
 965 The `$passthru` parameter allows you to pass the parameters that were passed to the current query on to the target URL, as long as it is another URL on the same TWiki installation. If `$passthru` is set to a true value, then TWiki will save the current URL parameters, and then try to restore them on the other side of the redirect. Parameters are stored on the server in a cache file (see `{PassthroughDir} in =configure`).
 966
 967 Note that if `$passthru` is set, then any parameters in `$url` will be lost when the old parameters are restored. if you want to change any parameter values, you will need to do that in the current CGI query before redirecting e.g.
 968
 969     my $query = TWiki::Func::getCgiQuery();
 970     $query->param(-name => 'text', -value => 'Different text');
 971     TWiki::Func::redirectCgiQuery(
 972       undef, TWiki::Func::getScriptUrl($web, $topic, 'edit'), 1);
 973
 974 `$passthru` does nothing if `$url` does not point to a script in the current TWiki installation.
 975
 976 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
 977
 978 ### <a name="add_ToHEAD( $id, $header )"></a> addToHEAD( $id, $header )
 979
 980 Adds `$header` to the HTML header (the
 981
 982 tag). This is useful for Plugins that want to include some javascript custom css.
 983
 984 - `$id` - Unique ID to prevent the same HTML from being duplicated. Plugins should use a prefix to prevent name clashes (e.g EDITTABLEPLUGIN\_JSCALENDAR)
 985 - `$header` - the HTML to be added to the
 986
 987 section. The HTML must be valid in a HEAD tag - no checks are performed.
 988
 989 All TWiki variables present in `$header` will be expanded before being inserted into the ``
 990
 991 section.
 992
 993 Note that this is _not_ the same as the HTTP header, which is modified through the Plugins `modifyHeaderHandler`.
 994
 995 **Since:** TWiki::Plugins::VERSION 1.1
 996
 997 example:
 998
 999     TWiki::Func::addToHEAD('PATTERN_STYLE','<link id="twikiLayoutCss" rel="stylesheet" type="text/css" href="%PUBURL%/TWiki/PatternSkin/layout.css" media="all" />')
1000
1001 ### <a name="expand_CommonVariables( $text, $"></a> expandCommonVariables( $text, $topic, $web ) -&gt; $text
1002
1003 Expand all common `%VARIABLES%`
1004
1005 - `$text` - Text with variables to expand, e.g. `'Current user is %WIKIUSER%'`
1006 - `$topic` - Current topic name, e.g. `'WebNotify'`
1007 - `$web` - Web name, optional, e.g. `'Main'`. The current web is taken if missing
1008
1009 Return: `$text` Expanded text, e.g. `'Current user is TWikiGuest'`
1010
1011 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
1012
1013 See also: expandVariablesOnTopicCreation
1014
1015 ### <a name="renderText( $text, $web ) - $tex"></a> renderText( $text, $web ) -&gt; $text
1016
1017 Render text from TWiki markup into XHTML as defined in [[TWiki.TextFormattingRules|TWiki/TextFormattingRules]]
1018
1019 - `$text` - Text to render, e.g. `'*bold* text and =fixed font='`
1020 - `$web` - Web name, optional, e.g. `'Main'`. The current web is taken if missing
1021
1022 Return: `$text` XHTML text, e.g. `'<b>bold</b> and <code>fixed font</code>'`
1023
1024 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
1025
1026 ### <a name="internalLink( $pre, $web, $topic"></a> internalLink( $pre, $web, $topic, $label, $anchor, $createLink ) -&gt; $text
1027
1028 Render topic name and link label into an XHTML link. Normally you do not need to call this funtion, it is called internally by `renderText()`
1029
1030 - `$pre` - Text occuring before the TWiki link syntax, optional
1031 - `$web` - Web name, required, e.g. `'Main'`
1032 - `$topic` - Topic name to link to, required, e.g. `'WebNotify'`
1033 - `$label` - Link label, required. Usually the same as `$topic`, e.g. `'notify'`
1034 - `$anchor` - Anchor, optional, e.g. `'#Jump'`
1035 - `$createLink` - Set to `'1'` to add question linked mark after topic name if topic does not exist;<br /> set to `'0'` to suppress link for non-existing topics
1036
1037 Return: `$text` XHTML anchor, e.g. `'<a href='/cgi-bin/view/Main/WebNotify#Jump'>notify</a>'`
1038
1039 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
1040
1041 ## <a name="E-mail"></a> E-mail
1042
1043 ### <a name="sendEmail ( $text, $retries ) -"></a><a name="sendEmail ( $text, $retries ) - "></a> sendEmail ( $text, $retries ) -&gt; $error
1044
1045 - `$text` - text of the mail, including MIME headers
1046 - `$retries` - number of times to retry the send (default 1)
1047
1048 Send an e-mail specified as MIME format content. To specify MIME format mails, you create a string that contains a set of header lines that contain field definitions and a message body such as:
1049
1050     To: liz@windsor.gov.uk
1051     From: serf@hovel.net
1052     CC: george@whitehouse.gov
1053     Subject: Revolution
1054
1055     Dear Liz,
1056
1057     Please abolish the monarchy (with King George's permission, of course)
1058
1059     Thanks,
1060
1061     A. Peasant
1062
1063 Leave a blank line between the last header field and the message body.
1064
1065 **Since:** TWiki::Plugins::VERSION 1.1
1066
1067 ### <a name="wiki_ToEmail( $wikiName ) - $ema"></a> wikiToEmail( $wikiName ) -&gt; $email
1068
1069 - `$wikiName` - wiki name of the user
1070
1071 Get the e-mail address(es) of the named user. If the user has multiple e-mail addresses (for example, the user is a group), then the list will be comma-separated.
1072
1073 **Since:** TWiki::Plugins::VERSION 1.1
1074
1075 ## <a name="Creating New Topics"></a> Creating New Topics
1076
1077 ### <a name="expand_VariablesOnTopicCreation"></a><a name="expand_VariablesOnTopicCreation "></a> expandVariablesOnTopicCreation ( $text ) -&gt; $text
1078
1079 Expand the limited set of variables that are always expanded during topic creation
1080
1081 - `$text` - the text to process
1082
1083 Return: text with variables expanded
1084
1085 **Since:** TWiki::Plugins::VERSION 1.1
1086
1087 Expands only the variables expected in templates that must be statically expanded in new content.
1088
1089 The expanded variables are:
1090
1091 - `%DATE%` Signature-format date
1092 - `%SERVERTIME%` See [[TWikiVariables]]
1093 - `%GMTIME%` See [[TWikiVariables]]
1094 - `%USERNAME%` Base login name
1095 - `%WIKINAME%` Wiki name
1096 - `%WIKIUSERNAME%` Wiki name with prepended web
1097 - `%URLPARAM{...}%` - Parameters to the current CGI query
1098 - `%NOP%` No-op
1099
1100 See also: expandVariables
1101
1102 ## <a name="Special handlers"></a> Special handlers
1103
1104 Special handlers can be defined to make functions in plugins behave as if they were built-in to TWiki.
1105
1106 ### <a name="register_TagHandler( $var, \fn,"></a><a name="register_TagHandler( $var, \fn, "></a> registerTagHandler( $var, \\&amp;fn, $syntax )
1107
1108 Should only be called from initPlugin.
1109
1110 Register a function to handle a simple variable. Handles both %VAR% and %VAR\{...\}%. Registered variables are treated the same as TWiki internal variables, and are expanded at the same time. This is a _lot_ more efficient than using the `commonTagsHandler`.
1111
1112 - `$var` - The name of the variable, i.e. the 'MYVAR' part of %MYVAR%. The variable name **must** match /^[A-Z]\[A-Z0-9\_]\*$/ or it won't work.
1113 - `\&fn` - Reference to the handler function.
1114 - `$syntax` can be 'classic' (the default) or 'context-free'. 'classic' syntax is appropriate where you want the variable to support classic TWiki syntax i.e. to accept the standard `%MYVAR{ "unnamed" param1="value1" param2="value2" }%` syntax, as well as an unquoted default parameter, such as `%MYVAR{unquoted parameter}%`. If your variable will only use named parameters, you can use 'context-free' syntax, which supports a more relaxed syntax. For example, %MYVAR\{param1=value1, value 2, param3="value 3", param4='value 5"\}%
1115
1116 **Since:** TWiki::Plugins::VERSION 1.1
1117
1118 The variable handler function must be of the form:
1119
1120     sub handler(\%session, \%params, $topic, $web)
1121
1122 where:
1123
1124 - `\%session` - a reference to the TWiki session object (may be ignored)
1125 - `\%params` - a reference to a TWiki::Attrs object containing parameters. This can be used as a simple hash that maps parameter names to values, with \_DEFAULT being the name for the default parameter.
1126 - `$topic` - name of the topic in the query
1127 - `$web` - name of the web in the query
1128
1129 for example, to execute an arbitrary command on the server, you might do this:
1130
1131     sub initPlugin{
1132        TWiki::Func::registerTagHandler('EXEC', \&boo);
1133     }
1134
1135     sub boo {
1136         my( $session, $params, $topic, $web ) = @_;
1137         my $cmd = $params->{_DEFAULT};
1138
1139         return "NO COMMAND SPECIFIED" unless $cmd;
1140
1141         my $result = `$cmd 2>&1`;
1142         return $params->{silent} ? '' : $result;
1143     }
1144     }
1145
1146 would let you do this: `%EXEC{"ps -Af" silent="on"}%`
1147
1148 Registered tags differ from tags implemented using the old TWiki approach (text substitution in `commonTagsHandler`) in the following ways:
1149
1150 - registered tags are evaluated at the same time as system tags, such as %SERVERTIME. `commonTagsHandler` is only called later, when all system tags have already been expanded (though they are expanded _again_ after `commonTagsHandler` returns).
1151 - registered tag names can only contain alphanumerics and \_ (underscore)
1152 - registering a tag `FRED` defines both `%FRED{...}%` **and also** `%FRED%`.
1153 - registered tag handlers **cannot** return another tag as their only result (e.g. `return '%SERVERTIME%';`). It won't work.
1154
1155 ### <a name="registerRESTHandler( $alias, \fn"></a> registerRESTHandler( $alias, \\&amp;fn, )
1156
1157 Should only be called from initPlugin.
1158
1159 Adds a function to the dispatch table of the REST interface
1160
1161 - `$alias` - The name .
1162 - `\&fn` - Reference to the function.
1163
1164 **Since:** TWiki::Plugins::VERSION 1.1
1165
1166 The handler function must be of the form:
1167
1168     sub handler(\%session)
1169
1170 where:
1171
1172 - `\%session` - a reference to the TWiki session object (may be ignored)
1173
1174 From the REST interface, the name of the plugin must be used as the subject of the invokation.
1175
1176 Example
1177
1178 ----
1179
1180 The [[EmptyPlugin]] has the following call in the initPlugin handler:
1181
1182        TWiki::Func::registerRESTHandler('example', \&restExample);
1183
1184 This adds the `restExample` function to the REST dispatch table for the [[EmptyPlugin]] under the 'example' alias, and allows it to be invoked using the URL
1185
1186 `http://server:port/bin/rest/EmptyPlugin/example`
1187
1188 note that the URL
1189
1190 `http://server:port/bin/rest/EmptyPlugin/restExample`
1191
1192 (ie, with the name of the function instead of the alias) will not work.
1193
1194 ## <a name="Searching"></a> Searching
1195
1196 ### <a name="search_InWebContent($searchStrin"></a> searchInWebContent($searchString, $web, \\@topics, \\%options ) -&gt; \\%map
1197
1198 Search for a string in the content of a web. The search is over all content, including meta-data. Meta-data matches will be returned as formatted lines within the topic content (meta-data matches are returned as lines of the format %META:\\w+\{.\*\}%)
1199
1200 - `$searchString` - the search string, in egrep format
1201 - `$web` - The web to search in
1202 - `\@topics` - reference to a list of topics to search
1203 - `\%option` - reference to an options hash
1204
1205 The `\%options` hash may contain the following options:
1206
1207 - `type` - if `regex` will perform a egrep-syntax RE search (default '')
1208 - `casesensitive` - false to ignore case (defaulkt true)
1209 - `files_without_match` - true to return files only (default false). If `files_without_match` is specified, it will return on the first match in each topic (i.e. it will return only one match per topic, and will not return matching lines).
1210
1211 The return value is a reference to a hash which maps each matching topic name to a list of the lines in that topic that matched the search, as would be returned by 'grep'.
1212
1213 To iterate over the returned topics use:
1214
1215     my $result = TWiki::Func::searchInWebContent( "Slimy Toad", $web, \@topics,
1216        { casesensitive => 0, files_without_match => 0 } );
1217     foreach my $topic (keys %$result ) {
1218        foreach my $matching_line ( @{$result->{$topic}} ) {
1219           ...etc
1220
1221 **Since:** TWiki::Plugins::VERSION 1.1
1222
1223 ## <a name="Plugin-specific file handling"></a> Plugin-specific file handling
1224
1225 ### <a name="get_WorkArea( $pluginName ) - $d"></a> getWorkArea( $pluginName ) -&gt; $directorypath
1226
1227 Gets a private directory for Plugin use. The Plugin is entirely responsible for managing this directory; TWiki will not read from it, or write to it.
1228
1229 The directory is guaranteed to exist, and to be writable by the webserver user. By default it will **not** be web accessible.
1230
1231 The directory and it's contents are permanent, so Plugins must be careful to keep their areas tidy.
1232
1233 **Since:** TWiki::Plugins::VERSION 1.1 (Dec 2005)
1234
1235 ### <a name="readFile( $filename ) - $text"></a> readFile( $filename ) -&gt; $text
1236
1237 Read file, low level. Used for Plugin workarea.
1238
1239 - `$filename` - Full path name of file
1240
1241 Return: `$text` Content of file, empty if not found
1242
1243 **_NOTE:_** Use this function only for the Plugin workarea, **not** for topics and attachments. Use the appropriate functions to manipulate topics and attachments.
1244
1245 **Since:** TWiki::Plugins::VERSION 1.000 (07 Dec 2002)
1246
1247 ### <a name="saveFile( $filename, $text )"></a> saveFile( $filename, $text )
1248
1249 Save file, low level. Used for Plugin workarea.
1250
1251 - `$filename` - Full path name of file
1252 - `$text` - Text to save
1253
1254 Return: none
1255
1256 **_NOTE:_** Use this function only for the Plugin workarea, **not** for topics and attachments. Use the appropriate functions to manipulate topics and attachments.
1257
1258 **Since:** TWiki::Plugins::VERSION 1.000 (07 Dec 2002)
1259
1260 ## <a name="General Utilities"></a> General Utilities
1261
1262 ### <a name="get_RegularExpression( $name ) -"></a> getRegularExpression( $name ) -&gt; $expr
1263
1264 Retrieves a TWiki predefined regular expression or character class.
1265
1266 - `$name` - Name of the expression to retrieve. See notes below
1267
1268 Return: String or precompiled regular expression matching as described below.
1269
1270 **Since:** TWiki::Plugins::VERSION 1.020 (9 Feb 2004)
1271
1272 **_Note:_** TWiki internally precompiles several regular expressions to represent various string entities in an I18N-compatible manner. Plugins authors are encouraged to use these in matching where appropriate. The following are guaranteed to be present. Others may exist, but their use is unsupported and they may be removed in future TWiki versions.
1273
1274 In the table below, the expression marked type 'String' are intended for use within character classes (i.e. for use within square brackets inside a regular expression), for example:
1275
1276        my $upper = TWiki::Func::getRegularExpression('upperAlpha');
1277        my $alpha = TWiki::Func::getRegularExpression('mixedAlpha');
1278        my $capitalized = qr/[$upper][$alpha]+/;
1279
1280 Those expressions marked type 'RE' are precompiled regular expressions that can be used outside square brackets. For example:
1281
1282        my $webRE = TWiki::Func::getRegularExpression('webNameRegex');
1283        my $isWebName = ( $s =~ m/$webRE/ );
1284
1285 <table border="1" cellpadding="0" cellspacing="0">
1286   <tr>
1287     <th bgcolor="#99CCCC"><strong> Name </strong></th>
1288     <th bgcolor="#99CCCC"><strong> Matches </strong></th>
1289     <th bgcolor="#99CCCC"><strong> Type </strong></th>
1290   </tr>
1291   <tr>
1292     <td> upperAlpha </td>
1293     <td> Upper case characters </td>
1294     <td> String </td>
1295   </tr>
1296   <tr>
1297     <td> upperAlphaNum </td>
1298     <td> Upper case characters and digits </td>
1299     <td> String </td>
1300   </tr>
1301   <tr>
1302     <td> lowerAlpha </td>
1303     <td> Lower case characters </td>
1304     <td> String </td>
1305   </tr>
1306   <tr>
1307     <td> lowerAlphaNum </td>
1308     <td> Lower case characters and digits </td>
1309     <td> String </td>
1310   </tr>
1311   <tr>
1312     <td> numeric </td>
1313     <td> Digits </td>
1314     <td> String </td>
1315   </tr>
1316   <tr>
1317     <td> mixedAlpha </td>
1318     <td> Alphabetic characters </td>
1319     <td> String </td>
1320   </tr>
1321   <tr>
1322     <td> mixedAlphaNum </td>
1323     <td> Alphanumeric characters </td>
1324     <td> String </td>
1325   </tr>
1326   <tr>
1327     <td> wikiWordRegex </td>
1328     <td>[[Main/WikiWords]]</td>
1329     <td> RE </td>
1330   </tr>
1331   <tr>
1332     <td> webNameRegex </td>
1333     <td> User web names </td>
1334     <td> RE </td>
1335   </tr>
1336   <tr>
1337     <td> anchorRegex </td>
1338     <td> #AnchorNames </td>
1339     <td> RE </td>
1340   </tr>
1341   <tr>
1342     <td> abbrevRegex </td>
1343     <td> Abbreviations e.g. GOV, IRS </td>
1344     <td> RE </td>
1345   </tr>
1346   <tr>
1347     <td> emailAddrRegex </td>
1348     <td><a href="mailto:email@address.com">email@address.com</a></td>
1349     <td> RE </td>
1350   </tr>
1351   <tr>
1352     <td> tagNameRegex </td>
1353     <td> Standard variable names e.g. %THIS_BIT% (THIS_BIT only) </td>
1354     <td> RE </td>
1355   </tr>
1356 </table>
1357
1358 ### <a name="normalize_WebTopicName($web, $to"></a> normalizeWebTopicName($web, $topic) -&gt; ($web, $topic)
1359
1360 Parse a web and topic name, supplying defaults as appropriate.
1361
1362 - `$web` - Web name, identifying variable, or empty string
1363 - `$topic` - Topic name, may be a web.topic string, required.
1364
1365 Return: the parsed Web/Topic pair
1366
1367 **Since:** TWiki::Plugins::VERSION 1.1
1368
1369 <table border="1" cellpadding="0" cellspacing="0">
1370   <tr>
1371     <th bgcolor="#99CCCC"><strong> Input </strong></th>
1372     <th bgcolor="#99CCCC"><strong> Return </strong></th>
1373   </tr>
1374   <tr>
1375     <td><tt>( 'Web', 'Topic' ) </tt></td>
1376     <td><tt>( 'Web', 'Topic' ) </tt></td>
1377   </tr>
1378   <tr>
1379     <td><tt>( '', 'Topic' ) </tt></td>
1380     <td><tt>( 'Main', 'Topic' ) </tt></td>
1381   </tr>
1382   <tr>
1383     <td><tt>( '', '' ) </tt></td>
1384     <td><tt>( 'Main', 'WebHome' ) </tt></td>
1385   </tr>
1386   <tr>
1387     <td><tt>( '', 'Web/Topic' ) </tt></td>
1388     <td><tt>( 'Web', 'Topic' ) </tt></td>
1389   </tr>
1390   <tr>
1391     <td><tt>( '', 'Web/Subweb/Topic' ) </tt></td>
1392     <td><tt>( 'Web/Subweb', 'Topic' ) </tt></td>
1393   </tr>
1394   <tr>
1395     <td><tt>( '', 'Web.Topic' ) </tt></td>
1396     <td><tt>( 'Web', 'Topic' ) </tt></td>
1397   </tr>
1398   <tr>
1399     <td><tt>( '', 'Web.Subweb.Topic' ) </tt></td>
1400     <td><tt>( 'Web/Subweb', 'Topic' ) </tt></td>
1401   </tr>
1402   <tr>
1403     <td><tt>( 'Web1', 'Web2.Topic' )</tt></td>
1404     <td><tt>( 'Web2', 'Topic' ) </tt></td>
1405   </tr>
1406 </table>
1407
1408 Note that hierarchical web names ([[SubWeb]]) are only available if hierarchical webs are enabled in `configure`.
1409
1410 The symbols %USERSWEB%, %SYSTEMWEB%, %DOCWEB%, %MAINWEB% and %TWIKIWEB% can be used in the input to represent the web names set in $cfg\{UsersWebName\} and $cfg\{SystemWebName\}. For example:
1411
1412 <table border="1" cellpadding="0" cellspacing="0">
1413   <tr>
1414     <th bgcolor="#99CCCC"><strong> Input </strong></th>
1415     <th bgcolor="#99CCCC"><strong> Return </strong></th>
1416   </tr>
1417   <tr>
1418     <td><tt>( '%USERSWEB%', 'Topic' )</tt></td>
1419     <td><tt>( 'Main', 'Topic' ) </tt></td>
1420   </tr>
1421   <tr>
1422     <td><tt>( '%SYSTEMWEB%', 'Topic' )</tt></td>
1423     <td><tt>( 'TWiki', 'Topic' ) </tt></td>
1424   </tr>
1425   <tr>
1426     <td><tt>( '', '%DOCWEB%.Topic' )</tt></td>
1427     <td><tt>( 'TWiki', 'Topic' ) </tt></td>
1428   </tr>
1429 </table>
1430
1431 ### <a name="writeWarning( $text )"></a> writeWarning( $text )
1432
1433 Log Warning that may require admin intervention to data/warning.txt
1434
1435 - `$text` - Text to write; timestamp gets added
1436
1437 Return: none
1438
1439 **Since:** TWiki::Plugins::VERSION 1.020 (16 Feb 2004)
1440
1441 ### <a name="writeDebug( $text )"></a> writeDebug( $text )
1442
1443 Log debug message to data/debug.txt
1444
1445 - `$text` - Text to write; timestamp gets added
1446
1447 Return: none
1448
1449 **Since:** TWiki::Plugins::VERSION 1.020 (16 Feb 2004)
1450
1451 ### <a name="formatTime( $time, $format, $tim"></a> formatTime( $time, $format, $timezone ) -&gt; $text
1452
1453 Format the time in seconds into the desired time string
1454
1455 - `$time` - Time in epoc seconds
1456 - `$format` - Format type, optional. Default e.g. `'31 Dec 2002 - 19:30'`. Can be `'$iso'` (e.g. `'2002-12-31T19:30Z'`), `'$rcs'` (e.g. `'2001/12/31 23:59:59'`, `'$http'` for HTTP header format (e.g. `'Thu, 23 Jul 1998 07:21:56 GMT'`), or any string with tokens `'$seconds, $minutes, $hours, $day, $wday, $month, $mo, $year, $ye, $tz'` for seconds, minutes, hours, day of month, day of week, 3 letter month, 2 digit month, 4 digit year, 2 digit year, timezone string, respectively
1457 - `$timezone` - either not defined (uses the displaytime setting), 'gmtime', or 'servertime'
1458
1459 Return: `$text` Formatted time string
1460
1461 <table border="1" cellpadding="0" cellspacing="0">
1462   <tr>
1463     <td> Note: </td>
1464     <td> if you used the removed formatGmTime, add a third parameter 'gmtime' </td>
1465   </tr>
1466 </table>
1467
1468 **Since:** TWiki::Plugins::VERSION 1.020 (26 Feb 2004)
1469
1470 ### <a name="is_ValidWikiWord ( $text ) - $bo"></a> isValidWikiWord ( $text ) -&gt; $boolean
1471
1472 Check for a valid [[WikiWord]] or [[WikiName]]
1473
1474 - `$text` - Word to test
1475
1476 **Since:** TWiki::Plugins::VERSION 1.100 (Dec 2005)
1477
1478 ### <a name="extractParameters($attr ) - %par"></a> extractParameters($attr ) -&gt; %params
1479
1480 Extract all parameters from a variable string and returns a hash of parameters
1481
1482 - `$attr` - Attribute string
1483
1484 Return: `%params` Hash containing all parameters. The nameless parameter is stored in key `_DEFAULT`
1485
1486 **Since:** TWiki::Plugins::VERSION 1.025 (26 Aug 2004)
1487
1488 - Example:
1489   - Variable: `%TEST{ 'nameless' name1="val1" name2="val2" }%`
1490   - First extract text between `{...}` to get: `'nameless' name1="val1" name2="val2"`
1491   - Then call this on the text: <br />
1492 - params = TWiki::Func::extractParameters( $text );=
1493   - The `%params` hash contains now: <br />`_DEFAULT => 'nameless'`<br />`name1 => "val1"`<br />`name2 => "val2"`
1494
1495 ### <a name="extract_NameValuePair( $attr, $n"></a> extractNameValuePair( $attr, $name ) -&gt; $value
1496
1497 Extract a named or unnamed value from a variable parameter string - Note: | Function TWiki::Func::extractParameters is more efficient for extracting several parameters
1498
1499 - `$attr` - Attribute string
1500 - `$name` - Name, optional
1501
1502 Return: `$value` Extracted value
1503
1504 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
1505
1506 - Example:
1507   - Variable: `%TEST{ 'nameless' name1="val1" name2="val2" }%`
1508   - First extract text between `{...}` to get: `'nameless' name1="val1" name2="val2"`
1509   - Then call this on the text: <br />`my $noname = TWiki::Func::extractNameValuePair( $text );`<br />`my $val1  = TWiki::Func::extractNameValuePair( $text, "name1" );`<br />`my $val2  = TWiki::Func::extractNameValuePair( $text, "name2" );`
1510
1511 ## <a name="Deprecated functions"></a> Deprecated functions
1512
1513 From time-to-time, the TWiki developers will add new functions to the interface (either to [[TWikiFuncDotPm]], or new handlers). Sometimes these improvements mean that old functions have to be deprecated to keep the code manageable. When this happens, the deprecated functions will be supported in the interface for at least one more TWiki release, and probably longer, though this cannot be guaranteed.
1514
1515 Updated plugins may still need to define deprecated handlers for compatibility with old TWiki versions. In this case, the plugin package that defines old handlers can suppress the warnings in %FAILEDPLUGINS%.
1516
1517 This is done by defining a map from the handler name to the `TWiki::Plugins` version _in which the handler was first deprecated_. For example, if we need to define the `endRenderingHandler` for compatibility with `TWiki::Plugins` versions before 1.1, we would add this to the plugin:
1518
1519     package TWiki::Plugins::SinkPlugin;
1520     use vars qw( %TWikiCompatibility );
1521     $TWikiCompatibility{endRenderingHandler} = 1.1;
1522
1523 If the currently-running TWiki version is 1.1 _or later_, then the _handler will not be called_ and _the warning will not be issued_. TWiki with versions of `TWiki::Plugins` before 1.1 will still call the handler as required.
1524
1525 The following functions are retained for compatibility only. You should stop using them as soon as possible.
1526
1527 ### <a name="get_ScriptUrlPath( ) - $path"></a> getScriptUrlPath( ) -&gt; $path
1528
1529 Get script URL path
1530
1531 **DEPRECATED** since 1.1 - use `getScriptUrl` instead.
1532
1533 Return: `$path` URL path of TWiki scripts, e.g. `"/cgi-bin"`
1534
1535 **WARNING:** you are strongly recommended **not** to use this function, as the \{ScriptUrlPaths\} URL rewriting rules will not apply to urls generated using it.
1536
1537 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
1538
1539 ### <a name="get_PublicWebList( ) - @webs"></a> getPublicWebList( ) -&gt; @webs
1540
1541 **DEPRECATED** since 1.1 - use `getListOfWebs` instead.
1542
1543 Get list of all public webs, e.g. all webs that do not have the `NOSEARCHALL` flag set in the [[WebPreferences]]
1544
1545 Return: `@webs` List of all public webs, e.g. `( 'Main',  'Know', 'TWiki' )`
1546
1547 **Since:** TWiki::Plugins::VERSION 1.000 (07 Dec 2002)
1548
1549 ### <a name="format_GmTime( $time, $format )"></a><a name="format_GmTime( $time, $format ) "></a> formatGmTime( $time, $format ) -&gt; $text
1550
1551 **DEPRECATED** since 1.1 - use `formatTime` instead.
1552
1553 Format the time to GM time
1554
1555 - `$time` - Time in epoc seconds
1556 - `$format` - Format type, optional. Default e.g. `'31 Dec 2002 - 19:30'`, can be `'iso'` (e.g. `'2002-12-31T19:30Z'`), `'rcs'` (e.g. `'2001/12/31 23:59:59'`, `'http'` for HTTP header format (e.g. `'Thu, 23 Jul 1998 07:21:56 GMT'`)
1557
1558 Return: `$text` Formatted time string
1559
1560 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
1561
1562 ### <a name="get_DataDir( ) - $dir"></a> getDataDir( ) -&gt; $dir
1563
1564 **DEPRECATED** since 1.1 - use the "Webs, Topics and Attachments" functions to manipulate topics instead
1565
1566 Get data directory (topic file root)
1567
1568 Return: `$dir` Data directory, e.g. `'/twiki/data'`
1569
1570 This function violates store encapsulation and is therefore **deprecated**.
1571
1572 **Since:** TWiki::Plugins::VERSION 1.000 (07 Dec 2002)
1573
1574 ### <a name="get_PubDir( ) - $dir"></a> getPubDir( ) -&gt; $dir
1575
1576 **DEPRECATED** since 1.1 - use the "Webs, Topics and Attachments" functions to manipulateattachments instead
1577
1578 Get pub directory (file attachment root). Attachments are in `$dir/Web/TopicName`
1579
1580 Return: `$dir` Pub directory, e.g. `'/htdocs/twiki/pub'`
1581
1582 This function violates store encapsulation and is therefore **deprecated**.
1583
1584 Use `readAttachment` and `saveAttachment` instead.
1585
1586 **Since:** TWiki::Plugins::VERSION 1.000 (07 Dec 2002)
1587
1588 ### <a name="checkDependencies( $moduleName,"></a><a name="checkDependencies( $moduleName, "></a> checkDependencies( $moduleName, $dependenciesRef ) -&gt; $error
1589
1590 **DEPRECATED** since 1.1 - use TWiki:Plugins.BuildContrib and define DEPENDENCIES that can be statically evaluated at install time instead. It is a lot more efficient.
1591
1592 **Since:** TWiki::Plugins::VERSION 1.025 (01 Aug 2004)