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 ) -&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 ) -&gt; $boolean
 457
 458 Check access permission for a topic based on the [[TWiki.TWikiAccessControl|TWiki/TWikiAccessControl]] rules
 459
 460 - `$type` - Access type, e.g. `'VIEW'`, `'CHANGE'`, `'CREATE'`
 461 - `$wikiName` - [[WikiName]] of remote user, 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
 463 - `$topic` - Topic name, required, e.g. `'PrivateStuff'`
 464 - `$web` - Web name, required, e.g. `'Sandbox'`
 465
 466 A perl true result indicates that access is permitted.
 467
 468 **Since:** TWiki::Plugins::VERSION 1.000 (27 Feb 2001)
 469
 470 ## <a name="Webs, Topics and Attachments"></a> Webs, Topics and Attachments
 471
 472 ### <a name="get_ListOfWebs( $filter ) - @web"></a> getListOfWebs( $filter ) -&gt; @webs
 473
 474 - `$filter` - spec of web types to recover
 475
 476 Gets a list of webs, filtered according to the spec in the $filter, which may include one of:
 477
 478 1. 'user' (for only user webs)
 479 2. 'template' (for only template webs i.e. those starting with "\_")
 480
 481 `$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.
 482
 483 For example, the deprecated getPublicWebList function can be duplicated as follows:
 484
 485        my @webs = TWiki::Func::getListOfWebs( "user,public" );
 486
 487 **Since:** TWiki::Plugins::VERSION 1.1
 488
 489 ### <a name="webExists( $web ) - $boolean"></a> webExists( $web ) -&gt; $boolean
 490
 491 Test if web exists
 492
 493 - `$web` - Web name, required, e.g. `'Sandbox'`
 494
 495 **Since:** TWiki::Plugins::VERSION 1.000 (14 Jul 2001)
 496
 497 ### <a name="createWeb( $newWeb, $baseWeb, $o"></a> createWeb( $newWeb, $baseWeb, $opts )
 498
 499 - `$newWeb` is the name of the new web.
 500 - `$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.
 501 - `$opts` is a ref to a hash that contains settings to be modified in
 502
 503 the web preferences topic in the new web.
 504
 505     use Error qw( :try );
 506     use TWiki::AccessControlException;
 507
 508     try {
 509         TWiki::Func::createWeb( "Newweb" );
 510     } catch Error::Simple with {
 511         my $e = shift;
 512         # see documentation on Error::Simple
 513     } catch TWiki::AccessControlException with {
 514         my $e = shift;
 515         # see documentation on TWiki::AccessControlException
 516     } otherwise {
 517         ...
 518     };
 519
 520 **Since:** TWiki::Plugins::VERSION 1.1
 521
 522 ### <a name="moveWeb( $oldName, $newName )"></a> moveWeb( $oldName, $newName )
 523
 524 Move (rename) a web.
 525
 526     use Error qw( :try );
 527     use TWiki::AccessControlException;
 528
 529     try {
 530         TWiki::Func::moveWeb( "Oldweb", "Newweb" );
 531     } catch Error::Simple with {
 532         my $e = shift;
 533         # see documentation on Error::Simple
 534     } catch TWiki::AccessControlException with {
 535         my $e = shift;
 536         # see documentation on TWiki::AccessControlException
 537     } otherwise {
 538         ...
 539     };
 540
 541 To delete a web, move it to a subweb of `Trash`
 542
 543     TWiki::Func::moveWeb( "Deadweb", "Trash.Deadweb" );
 544
 545 **Since:** TWiki::Plugins::VERSION 1.1
 546
 547 ### <a name="get_TopicList( $web ) - @topics"></a> getTopicList( $web ) -&gt; @topics
 548
 549 Get list of all topics in a web
 550
 551 - `$web` - Web name, required, e.g. `'Sandbox'`
 552
 553 Return: `@topics` Topic list, e.g. `( 'WebChanges',  'WebHome', 'WebIndex', 'WebNotify' )`
 554
 555 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
 556
 557 ### <a name="topicExists( $web, $topic ) - $b"></a> topicExists( $web, $topic ) -&gt; $boolean
 558
 559 Test if topic exists
 560
 561 - `$web` - Web name, optional, e.g. `'Main'`.
 562 - `$topic` - Topic name, required, e.g. `'TokyoOffice'`, or `"Main.TokyoOffice"`
 563
 564 $web and $topic are parsed as described in the documentation for `normalizeWebTopicName`.
 565
 566 **Since:** TWiki::Plugins::VERSION 1.000 (14 Jul 2001)
 567
 568 ### <a name="check_TopicEditLock( $web, $topi"></a> checkTopicEditLock( $web, $topic, $script ) -&gt; ( $oopsUrl, $loginName, $unlockTime )
 569
 570 Check if a lease has been taken by some other user.
 571
 572 - `$web` Web name, e.g. `"Main"`, or empty
 573 - `$topic` Topic name, e.g. `"MyTopic"`, or `"Main.MyTopic"`
 574
 575 Return: `( $oopsUrl, $loginName, $unlockTime )` - The `$oopsUrl` for calling redirectCgiQuery(), user's `$loginName`, and estimated `$unlockTime` in minutes, or ( '', '', 0 ) if no lease exists.
 576
 577 - `$script` The script to invoke when continuing with the edit
 578
 579 **Since:** TWiki::Plugins::VERSION 1.010 (31 Dec 2002)
 580
 581 ### <a name="set_TopicEditLock( $web, $topic,"></a> setTopicEditLock( $web, $topic, $lock )
 582
 583 - `$web` Web name, e.g. `"Main"`, or empty
 584 - `$topic` Topic name, e.g. `"MyTopic"`, or `"Main.MyTopic"`
 585 - `$lock` 1 to lease the topic, 0 to clear the lease=
 586
 587 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.
 588
 589 It is **impossible** to fully lock a topic. Concurrent changes will be merged.
 590
 591 **Since:** TWiki::Plugins::VERSION 1.010 (31 Dec 2002)
 592
 593 ### <a name="saveTopic( $web, $topic, $meta,"></a><a name="saveTopic( $web, $topic, $meta, "></a> saveTopic( $web, $topic, $meta, $text, $options ) -&gt; $error
 594
 595 - `$web` - web for the topic
 596 - `$topic` - topic name
 597 - `$meta` - reference to TWiki::Meta object
 598 - `$text` - text of the topic (without embedded meta-data!!!
 599 - `\%options` - ref to hash of save options `\%options` may include: <table border="1" cellpadding="0" cellspacing="0">
 600   <tr>
 601     <td><code>dontlog</code></td>
 602     <td> don't log this change in twiki log </td>
 603   </tr>
 604   <tr>
 605     <td><code>comment</code></td>
 606     <td> comment for save </td>
 607   </tr>
 608   <tr>
 609     <td><code>minor</code></td>
 610     <td> True if this is a minor change, and is not to be notified </td>
 611   </tr>
 612 </table>
 613
 614 Return: error message or undef.
 615
 616 **Since:** TWiki::Plugins::VERSION 1.000 (29 Jul 2001)
 617
 618 For example,
 619
 620     my( $meta, $text ) = TWiki::Func::readTopic( $web, $topic )
 621     $text =~ s/APPLE/ORANGE/g;
 622     TWiki::Func::saveTopic( $web, $topic, $meta, $text, { comment => 'refruited' } );
 623
 624 **_Note:_** Plugins handlers ( e.g. `beforeSaveHandler` ) will be called as appropriate.
 625
 626 ### <a name="save_TopicText( $web, $topic, $t"></a> saveTopicText( $web, $topic, $text, $ignorePermissions, $dontNotify ) -&gt; $oopsUrl
 627
 628 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.
 629
 630 - `$web` - Web name, e.g. `'Main'`, or empty
 631 - `$topic` - Topic name, e.g. `'MyTopic'`, or `"Main.MyTopic"`
 632 - `$text` - Topic text to save, assumed to include meta data
 633 - `$ignorePermissions` - Set to `"1"` if checkAccessPermission() is already performed and OK
 634 - `$dontNotify` - Set to `"1"` if not to notify users of the change
 635
 636 Return: `$oopsUrl` Empty string if OK; the `$oopsUrl` for calling redirectCgiQuery() in case of error
 637
 638 This method is a lot less efficient and much more dangerous than `saveTopic`.
 639
 640 **Since:** TWiki::Plugins::VERSION 1.010 (31 Dec 2002)
 641
 642     my $text = TWiki::Func::readTopicText( $web, $topic );
 643
 644     # check for oops URL in case of error:
 645     if( $text =~ /^http.*?\/oops/ ) {
 646         TWiki::Func::redirectCgiQuery( $query, $text );
 647         return;
 648     }
 649     # do topic text manipulation like:
 650     $text =~ s/old/new/g;
 651     # do meta data manipulation like:
 652     $text =~ s/(META\:FIELD.*?name\=\"TopicClassification\".*?value\=\")[^\"]*/$1BugResolved/;
 653     $oopsUrl = TWiki::Func::saveTopicText( $web, $topic, $text ); # save topic text
 654
 655 ### <a name="moveTopic( $web, $topic, $newWeb"></a> moveTopic( $web, $topic, $newWeb, $newTopic )
 656
 657 - `$web` source web - required
 658 - `$topic` source topic - required
 659 - `$newWeb` dest web
 660 - `$newTopic` dest topic
 661
 662 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.
 663
 664 The destination topic must not already exist.
 665
 666 Rename a topic to the $TWiki::cfg\{TrashWebName\} to delete it.
 667
 668 **Since:** TWiki::Plugins::VERSION 1.1
 669
 670     use Error qw( :try );
 671
 672     try {
 673         moveTopic( "Work", "TokyoOffice", "Trash", "ClosedOffice" );
 674     } catch Error::Simple with {
 675         my $e = shift;
 676         # see documentation on Error::Simple
 677     } catch TWiki::AccessControlException with {
 678         my $e = shift;
 679         # see documentation on TWiki::AccessControlException
 680     } otherwise {
 681         ...
 682     };
 683
 684 ### <a name="get_RevisionInfo($web, $topic, $"></a> getRevisionInfo($web, $topic, $rev, $attachment ) -&gt; ( $date, $user, $rev, $comment )
 685
 686 Get revision info of a topic or attachment
 687
 688 - `$web` - Web name, optional, e.g. `'Main'`
 689 - `$topic` - Topic name, required, e.g. `'TokyoOffice'`
 690 - `$rev` - revsion number, or tag name (can be in the format 1.2, or just the minor number)
 691 - `$attachment` -attachment filename
 692
 693 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" )`
 694
 695 <table border="1" cellpadding="0" cellspacing="0">
 696   <tr>
 697     <td> $date </td>
 698     <td> in epochSec </td>
 699   </tr>
 700   <tr>
 701     <td> $user </td>
 702     <td> Wiki name of the author (<strong>not</strong> login name) </td>
 703   </tr>
 704   <tr>
 705     <td> $rev </td>
 706     <td> actual rev number </td>
 707   </tr>
 708   <tr>
 709     <td> $comment </td>
 710     <td> WHAT COMMENT? </td>
 711   </tr>
 712 </table>
 713
 714 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.
 715
 716 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.
 717
 718 **Since:** TWiki::Plugins::VERSION 1.000 (29 Jul 2001)
 719
 720 ### <a name="get_RevisionAtTime( $web, $topic"></a> getRevisionAtTime( $web, $topic, $time ) -&gt; $rev
 721
 722 Get the revision number of a topic at a specific time.
 723
 724 - `$web` - web for topic
 725 - `$topic` - topic
 726 - `$time` - time (in epoch secs) for the rev
 727
 728 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)
 729
 730 **Since:** TWiki::Plugins::VERSION 1.1
 731
 732 ### <a name="readTopic( $web, $topic, $rev )"></a><a name="readTopic( $web, $topic, $rev ) "></a> readTopic( $web, $topic, $rev ) -&gt; ( $meta, $text )
 733
 734 Read topic text and meta data, regardless of access permissions.
 735
 736 - `$web` - Web name, required, e.g. `'Main'`
 737 - `$topic` - Topic name, required, e.g. `'TokyoOffice'`
 738 - `$rev` - revision to read (default latest)
 739
 740 Return: `( $meta, $text )` Meta data object and topic text
 741
 742 `$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.
 743
 744 This method **ignores** topic access permissions. You should be careful to use `checkAccessPermissions` to ensure the current user has read access to the topic.
 745
 746 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
 747
 748 ### <a name="read_TopicText( $web, $topic, $r"></a> readTopicText( $web, $topic, $rev, $ignorePermissions ) -&gt; $text
 749
 750 Read topic text, including meta data
 751
 752 - `$web` - Web name, e.g. `'Main'`, or empty
 753 - `$topic` - Topic name, e.g. `'MyTopic'`, or `"Main.MyTopic"`
 754 - `$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.
 755 - `$ignorePermissions` - Set to `"1"` if checkAccessPermission() is already performed and OK; an oops URL is returned if user has no permission
 756
 757 Return: `$text` Topic text with embedded meta data; an oops URL for calling redirectCgiQuery() is returned in case of an error
 758
 759 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..
 760
 761 **Since:** TWiki::Plugins::VERSION 1.010 (31 Dec 2002)
 762
 763 ### <a name="attachmentExists( $web, $topic,"></a><a name="attachmentExists( $web, $topic, "></a> attachmentExists( $web, $topic, $attachment ) -&gt; $boolean
 764
 765 Test if attachment exists
 766
 767 - `$web` - Web name, optional, e.g. `Main`.
 768 - `$topic` - Topic name, required, e.g. `TokyoOffice`, or `Main.TokyoOffice`
 769 - `$attachment` - attachment name, e.g.=logo.gif=
 770
 771 $web and $topic are parsed as described in the documentation for `normalizeWebTopicName`.
 772
 773 **Since:** TWiki::Plugins::VERSION 1.1
 774
 775 ### <a name="readAttachment( $web, $topic, $n"></a> readAttachment( $web, $topic, $name, $rev ) -&gt; $data
 776
 777 - `$web` - web for topic
 778 - `$topic` - topic
 779 - `$name` - attachment name
 780 - `$rev` - revision to read (default latest)
 781
 782 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.
 783
 784 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.
 785
 786     my( $meta, $text ) = TWiki::Func::readTopic( $web, $topic );
 787     my @attachments = $meta->find( 'FILEATTACHMENT' );
 788     foreach my $a ( @attachments ) {
 789        try {
 790            my $data = TWiki::Func::readAttachment( $web, $topic, $a->{name} );
 791            ...
 792        } catch TWiki::AccessControlException with {
 793        };
 794     }
 795
 796 **Since:** TWiki::Plugins::VERSION 1.1
 797
 798 ### <a name="saveAttachment( $web, $topic, $a"></a> saveAttachment( $web, $topic, $attachment, $opts )
 799
 800 - `$web` - web for topic
 801 - `$topic` - topic to atach to
 802 - `$attachment` - name of the attachment
 803 - `$opts` - Ref to hash of options
 804
 805 `$opts` may include:
 806
 807 <table border="1" cellpadding="0" cellspacing="0">
 808   <tr>
 809     <td><code>dontlog</code></td>
 810     <td> don't log this change in twiki log </td>
 811   </tr>
 812   <tr>
 813     <td><code>comment</code></td>
 814     <td> comment for save </td>
 815   </tr>
 816   <tr>
 817     <td><code>hide</code></td>
 818     <td> if the attachment is to be hidden in normal topic view </td>
 819   </tr>
 820   <tr>
 821     <td><code>stream</code></td>
 822     <td> Stream of file to upload </td>
 823   </tr>
 824   <tr>
 825     <td><code>file</code></td>
 826     <td> Name of a file to use for the attachment data. ignored if stream is set. Local file on the server. </td>
 827   </tr>
 828   <tr>
 829     <td><code>filepath</code></td>
 830     <td> Client path to file </td>
 831   </tr>
 832   <tr>
 833     <td><code>filesize</code></td>
 834     <td> Size of uploaded data </td>
 835   </tr>
 836   <tr>
 837     <td><code>filedate</code></td>
 838     <td> Date </td>
 839   </tr>
 840 </table>
 841
 842 Save an attachment to the store for a topic. On success, returns undef. If there is an error, an exception will be thrown.
 843
 844         try {
 845             TWiki::Func::saveAttachment( $web, $topic, 'image.gif',
 846                                          { file => 'image.gif',
 847                                            comment => 'Picture of Health',
 848                                            hide => 1 } );
 849        } catch Error::Simple with {
 850           # see documentation on Error
 851        } otherwise {
 852           ...
 853        };
 854
 855 **Since:** TWiki::Plugins::VERSION 1.1
 856
 857 ### <a name="moveAttachment( $web, $topic, $a"></a> moveAttachment( $web, $topic, $attachment, $newWeb, $newTopic, $newAttachment )
 858
 859 - `$web` source web - required
 860 - `$topic` source topic - required
 861 - `$attachment` source attachment - required
 862 - `$newWeb` dest web
 863 - `$newTopic` dest topic
 864 - `$newAttachment` dest attachment
 865
 866 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.
 867
 868 The destination topic must already exist, but the destination attachment must **not** exist.
 869
 870 Rename an attachment to $TWiki::cfg\{TrashWebName\}.TrashAttament to delete it.
 871
 872     use Error qw( :try );
 873
 874     try {
 875        # move attachment between topics
 876        moveAttachment( "Countries", "Germany", "AlsaceLorraine.dat",
 877                          "Countries", "France" );
 878        # Note destination attachment name is defaulted to the same as source
 879     } catch TWiki::AccessControlException with {
 880        my $e = shift;
 881        # see documentation on TWiki::AccessControlException
 882     } catch Error::Simple with {
 883        my $e = shift;
 884        # see documentation on Error::Simple
 885     };
 886
 887 **Since:** TWiki::Plugins::VERSION 1.1
 888
 889 ## <a name="Assembling Pages"></a> Assembling Pages
 890
 891 ### <a name="readTemplate( $name, $skin ) - $"></a> readTemplate( $name, $skin ) -&gt; $text
 892
 893 Read a template or skin. Embedded [[template directives|TWiki/TWikiTemplates]] get expanded
 894
 895 - `$name` - Template name, e.g. `'view'`
 896 - `$skin` - Comma-separated list of skin names, optional, e.g. `'print'`
 897
 898 Return: `$text` Template text
 899
 900 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
 901
 902 ### <a name="loadTemplate ( $name, $skin, $we"></a> loadTemplate ( $name, $skin, $web ) -&gt; $text
 903
 904 - `$name` - template file name
 905 - `$skin` - comma-separated list of skins to use (default: current skin)
 906 - `$web` - the web to look in for topics that contain templates (default: current web)
 907
 908 Return: expanded template text (what's left after removal of all %TMPL:DEF% statements)
 909
 910 **Since:** TWiki::Plugins::VERSION 1.1
 911
 912 Reads a template and extracts template definitions, adding them to the list of loaded templates, overwriting any previous definition.
 913
 914 How TWiki searches for templates is described in [[TWikiTemplates]].
 915
 916 If template text is found, extracts include statements and fully expands them.
 917
 918 ### <a name="expandTemplate( $def  ) - $strin"></a> expandTemplate( $def ) -&gt; $string
 919
 920 Do a , only expanding the template (not expanding any variables other than %TMPL)
 921
 922 - `$def` - template name
 923
 924 Return: the text of the expanded template
 925
 926 **Since:** TWiki::Plugins::VERSION 1.1
 927
 928 A template is defined using a %TMPL:DEF% statement in a template file. See the documentation on TWiki templates for more information.
 929
 930 ### <a name="writeHeader( $query, $contentLen"></a> writeHeader( $query, $contentLength )
 931
 932 Prints a basic content-type HTML header for text/html to standard out
 933
 934 - `$query` - CGI query object. If not given, the default CGI query will be used. In most cases you should _not_ pass this parameter.
 935 - `$contentLength` - Length of content
 936
 937 Return: none
 938
 939 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
 940
 941 ### <a name="redirect_CgiQuery( $query, $url,"></a> redirectCgiQuery( $query, $url, $passthru )
 942
 943 Redirect to URL
 944
 945 - `$query` - CGI query object. Ignored, only there for compatibility. The session CGI query object is used instead.
 946 - `$url` - URL to redirect to
 947 - `$passthru` - enable passthrough.
 948
 949 Return: none
 950
 951 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.
 952
 953 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`).
 954
 955 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.
 956
 957     my $query = TWiki::Func::getCgiQuery();
 958     $query->param(-name => 'text', -value => 'Different text');
 959     TWiki::Func::redirectCgiQuery(
 960       undef, TWiki::Func::getScriptUrl($web, $topic, 'edit'), 1);
 961
 962 `$passthru` does nothing if `$url` does not point to a script in the current TWiki installation.
 963
 964 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
 965
 966 ### <a name="add_ToHEAD( $id, $header )"></a> addToHEAD( $id, $header )
 967
 968 Adds `$header` to the HTML header (the
 969
 970 tag). This is useful for Plugins that want to include some javascript custom css.
 971
 972 - `$id` - Unique ID to prevent the same HTML from being duplicated. Plugins should use a prefix to prevent name clashes (e.g EDITTABLEPLUGIN\_JSCALENDAR)
 973 - `$header` - the HTML to be added to the
 974
 975 section. The HTML must be valid in a HEAD tag - no checks are performed.
 976
 977 All TWiki variables present in `$header` will be expanded before being inserted into the ``
 978
 979 section.
 980
 981 Note that this is _not_ the same as the HTTP header, which is modified through the Plugins `modifyHeaderHandler`.
 982
 983 **Since:** TWiki::Plugins::VERSION 1.1
 984
 985 example:
 986
 987     TWiki::Func::addToHEAD('PATTERN_STYLE','<link id="twikiLayoutCss" rel="stylesheet" type="text/css" href="%PUBURL%/TWiki/PatternSkin/layout.css" media="all" />')
 988
 989 ### <a name="expand_CommonVariables( $text, $"></a> expandCommonVariables( $text, $topic, $web ) -&gt; $text
 990
 991 Expand all common `%VARIABLES%`
 992
 993 - `$text` - Text with variables to expand, e.g. `'Current user is %WIKIUSER%'`
 994 - `$topic` - Current topic name, e.g. `'WebNotify'`
 995 - `$web` - Web name, optional, e.g. `'Main'`. The current web is taken if missing
 996
 997 Return: `$text` Expanded text, e.g. `'Current user is TWikiGuest'`
 998
 999 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
1000
1001 See also: expandVariablesOnTopicCreation
1002
1003 ### <a name="renderText( $text, $web ) - $tex"></a> renderText( $text, $web ) -&gt; $text
1004
1005 Render text from TWiki markup into XHTML as defined in [[TWiki.TextFormattingRules|TWiki/TextFormattingRules]]
1006
1007 - `$text` - Text to render, e.g. `'*bold* text and =fixed font='`
1008 - `$web` - Web name, optional, e.g. `'Main'`. The current web is taken if missing
1009
1010 Return: `$text` XHTML text, e.g. `'<b>bold</b> and <code>fixed font</code>'`
1011
1012 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
1013
1014 ### <a name="internalLink( $pre, $web, $topic"></a> internalLink( $pre, $web, $topic, $label, $anchor, $createLink ) -&gt; $text
1015
1016 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()`
1017
1018 - `$pre` - Text occuring before the TWiki link syntax, optional
1019 - `$web` - Web name, required, e.g. `'Main'`
1020 - `$topic` - Topic name to link to, required, e.g. `'WebNotify'`
1021 - `$label` - Link label, required. Usually the same as `$topic`, e.g. `'notify'`
1022 - `$anchor` - Anchor, optional, e.g. `'#Jump'`
1023 - `$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
1024
1025 Return: `$text` XHTML anchor, e.g. `'<a href='/cgi-bin/view/Main/WebNotify#Jump'>notify</a>'`
1026
1027 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
1028
1029 ## <a name="E-mail"></a> E-mail
1030
1031 ### <a name="sendEmail ( $text, $retries ) -"></a><a name="sendEmail ( $text, $retries ) - "></a> sendEmail ( $text, $retries ) -&gt; $error
1032
1033 - `$text` - text of the mail, including MIME headers
1034 - `$retries` - number of times to retry the send (default 1)
1035
1036 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:
1037
1038     To: liz@windsor.gov.uk
1039     From: serf@hovel.net
1040     CC: george@whitehouse.gov
1041     Subject: Revolution
1042
1043     Dear Liz,
1044
1045     Please abolish the monarchy (with King George's permission, of course)
1046
1047     Thanks,
1048
1049     A. Peasant
1050
1051 Leave a blank line between the last header field and the message body.
1052
1053 **Since:** TWiki::Plugins::VERSION 1.1
1054
1055 ### <a name="wiki_ToEmail( $wikiName ) - $ema"></a> wikiToEmail( $wikiName ) -&gt; $email
1056
1057 - `$wikiName` - wiki name of the user
1058
1059 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.
1060
1061 **Since:** TWiki::Plugins::VERSION 1.1
1062
1063 ## <a name="Creating New Topics"></a> Creating New Topics
1064
1065 ### <a name="expand_VariablesOnTopicCreation"></a><a name="expand_VariablesOnTopicCreation "></a> expandVariablesOnTopicCreation ( $text ) -&gt; $text
1066
1067 Expand the limited set of variables that are always expanded during topic creation
1068
1069 - `$text` - the text to process
1070
1071 Return: text with variables expanded
1072
1073 **Since:** TWiki::Plugins::VERSION 1.1
1074
1075 Expands only the variables expected in templates that must be statically expanded in new content.
1076
1077 The expanded variables are:
1078
1079 - `%DATE%` Signature-format date
1080 - `%SERVERTIME%` See [[TWikiVariables]]
1081 - `%GMTIME%` See [[TWikiVariables]]
1082 - `%USERNAME%` Base login name
1083 - `%WIKINAME%` Wiki name
1084 - `%WIKIUSERNAME%` Wiki name with prepended web
1085 - `%URLPARAM{...}%` - Parameters to the current CGI query
1086 - `%NOP%` No-op
1087
1088 See also: expandVariables
1089
1090 ## <a name="Special handlers"></a> Special handlers
1091
1092 Special handlers can be defined to make functions in plugins behave as if they were built-in to TWiki.
1093
1094 ### <a name="register_TagHandler( $var, \fn,"></a><a name="register_TagHandler( $var, \fn, "></a> registerTagHandler( $var, \\&amp;fn, $syntax )
1095
1096 Should only be called from initPlugin.
1097
1098 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`.
1099
1100 - `$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.
1101 - `\&fn` - Reference to the handler function.
1102 - `$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"\}%
1103
1104 **Since:** TWiki::Plugins::VERSION 1.1
1105
1106 The variable handler function must be of the form:
1107
1108     sub handler(\%session, \%params, $topic, $web)
1109
1110 where:
1111
1112 - `\%session` - a reference to the TWiki session object (may be ignored)
1113 - `\%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.
1114 - `$topic` - name of the topic in the query
1115 - `$web` - name of the web in the query
1116
1117 for example, to execute an arbitrary command on the server, you might do this:
1118
1119     sub initPlugin{
1120        TWiki::Func::registerTagHandler('EXEC', \&boo);
1121     }
1122
1123     sub boo {
1124         my( $session, $params, $topic, $web ) = @_;
1125         my $cmd = $params->{_DEFAULT};
1126
1127         return "NO COMMAND SPECIFIED" unless $cmd;
1128
1129         my $result = `$cmd 2>&1`;
1130         return $params->{silent} ? '' : $result;
1131     }
1132     }
1133
1134 would let you do this: `%EXEC{"ps -Af" silent="on"}%`
1135
1136 Registered tags differ from tags implemented using the old TWiki approach (text substitution in `commonTagsHandler`) in the following ways:
1137
1138 - 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).
1139 - registered tag names can only contain alphanumerics and \_ (underscore)
1140 - registering a tag `FRED` defines both `%FRED{...}%` **and also** `%FRED%`.
1141 - registered tag handlers **cannot** return another tag as their only result (e.g. `return '%SERVERTIME%';`). It won't work.
1142
1143 ### <a name="registerRESTHandler( $alias, \fn"></a> registerRESTHandler( $alias, \\&amp;fn, )
1144
1145 Should only be called from initPlugin.
1146
1147 Adds a function to the dispatch table of the REST interface
1148
1149 - `$alias` - The name .
1150 - `\&fn` - Reference to the function.
1151
1152 **Since:** TWiki::Plugins::VERSION 1.1
1153
1154 The handler function must be of the form:
1155
1156     sub handler(\%session)
1157
1158 where:
1159
1160 - `\%session` - a reference to the TWiki session object (may be ignored)
1161
1162 From the REST interface, the name of the plugin must be used as the subject of the invokation.
1163
1164 Example
1165
1166 ----
1167
1168 The [[EmptyPlugin]] has the following call in the initPlugin handler:
1169
1170        TWiki::Func::registerRESTHandler('example', \&restExample);
1171
1172 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
1173
1174 `http://server:port/bin/rest/EmptyPlugin/example`
1175
1176 note that the URL
1177
1178 `http://server:port/bin/rest/EmptyPlugin/restExample`
1179
1180 (ie, with the name of the function instead of the alias) will not work.
1181
1182 ## <a name="Searching"></a> Searching
1183
1184 ### <a name="search_InWebContent($searchStrin"></a> searchInWebContent($searchString, $web, \\@topics, \\%options ) -&gt; \\%map
1185
1186 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+\{.\*\}%)
1187
1188 - `$searchString` - the search string, in egrep format
1189 - `$web` - The web to search in
1190 - `\@topics` - reference to a list of topics to search
1191 - `\%option` - reference to an options hash
1192
1193 The `\%options` hash may contain the following options:
1194
1195 - `type` - if `regex` will perform a egrep-syntax RE search (default '')
1196 - `casesensitive` - false to ignore case (defaulkt true)
1197 - `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).
1198
1199 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'.
1200
1201 To iterate over the returned topics use:
1202
1203     my $result = TWiki::Func::searchInWebContent( "Slimy Toad", $web, \@topics,
1204        { casesensitive => 0, files_without_match => 0 } );
1205     foreach my $topic (keys %$result ) {
1206        foreach my $matching_line ( @{$result->{$topic}} ) {
1207           ...etc
1208
1209 **Since:** TWiki::Plugins::VERSION 1.1
1210
1211 ## <a name="Plugin-specific file handling"></a> Plugin-specific file handling
1212
1213 ### <a name="get_WorkArea( $pluginName ) - $d"></a> getWorkArea( $pluginName ) -&gt; $directorypath
1214
1215 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.
1216
1217 The directory is guaranteed to exist, and to be writable by the webserver user. By default it will **not** be web accessible.
1218
1219 The directory and it's contents are permanent, so Plugins must be careful to keep their areas tidy.
1220
1221 **Since:** TWiki::Plugins::VERSION 1.1 (Dec 2005)
1222
1223 ### <a name="readFile( $filename ) - $text"></a> readFile( $filename ) -&gt; $text
1224
1225 Read file, low level. Used for Plugin workarea.
1226
1227 - `$filename` - Full path name of file
1228
1229 Return: `$text` Content of file, empty if not found
1230
1231 **_NOTE:_** Use this function only for the Plugin workarea, **not** for topics and attachments. Use the appropriate functions to manipulate topics and attachments.
1232
1233 **Since:** TWiki::Plugins::VERSION 1.000 (07 Dec 2002)
1234
1235 ### <a name="saveFile( $filename, $text )"></a> saveFile( $filename, $text )
1236
1237 Save file, low level. Used for Plugin workarea.
1238
1239 - `$filename` - Full path name of file
1240 - `$text` - Text to save
1241
1242 Return: none
1243
1244 **_NOTE:_** Use this function only for the Plugin workarea, **not** for topics and attachments. Use the appropriate functions to manipulate topics and attachments.
1245
1246 **Since:** TWiki::Plugins::VERSION 1.000 (07 Dec 2002)
1247
1248 ## <a name="General Utilities"></a> General Utilities
1249
1250 ### <a name="get_RegularExpression( $name ) -"></a> getRegularExpression( $name ) -&gt; $expr
1251
1252 Retrieves a TWiki predefined regular expression or character class.
1253
1254 - `$name` - Name of the expression to retrieve. See notes below
1255
1256 Return: String or precompiled regular expression matching as described below.
1257
1258 **Since:** TWiki::Plugins::VERSION 1.020 (9 Feb 2004)
1259
1260 **_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.
1261
1262 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:
1263
1264        my $upper = TWiki::Func::getRegularExpression('upperAlpha');
1265        my $alpha = TWiki::Func::getRegularExpression('mixedAlpha');
1266        my $capitalized = qr/[$upper][$alpha]+/;
1267
1268 Those expressions marked type 'RE' are precompiled regular expressions that can be used outside square brackets. For example:
1269
1270        my $webRE = TWiki::Func::getRegularExpression('webNameRegex');
1271        my $isWebName = ( $s =~ m/$webRE/ );
1272
1273 <table border="1" cellpadding="0" cellspacing="0">
1274   <tr>
1275     <th bgcolor="#99CCCC"><strong> Name </strong></th>
1276     <th bgcolor="#99CCCC"><strong> Matches </strong></th>
1277     <th bgcolor="#99CCCC"><strong> Type </strong></th>
1278   </tr>
1279   <tr>
1280     <td> upperAlpha </td>
1281     <td> Upper case characters </td>
1282     <td> String </td>
1283   </tr>
1284   <tr>
1285     <td> upperAlphaNum </td>
1286     <td> Upper case characters and digits </td>
1287     <td> String </td>
1288   </tr>
1289   <tr>
1290     <td> lowerAlpha </td>
1291     <td> Lower case characters </td>
1292     <td> String </td>
1293   </tr>
1294   <tr>
1295     <td> lowerAlphaNum </td>
1296     <td> Lower case characters and digits </td>
1297     <td> String </td>
1298   </tr>
1299   <tr>
1300     <td> numeric </td>
1301     <td> Digits </td>
1302     <td> String </td>
1303   </tr>
1304   <tr>
1305     <td> mixedAlpha </td>
1306     <td> Alphabetic characters </td>
1307     <td> String </td>
1308   </tr>
1309   <tr>
1310     <td> mixedAlphaNum </td>
1311     <td> Alphanumeric characters </td>
1312     <td> String </td>
1313   </tr>
1314   <tr>
1315     <td> wikiWordRegex </td>
1316     <td>[[Main/WikiWords]]</td>
1317     <td> RE </td>
1318   </tr>
1319   <tr>
1320     <td> webNameRegex </td>
1321     <td> User web names </td>
1322     <td> RE </td>
1323   </tr>
1324   <tr>
1325     <td> anchorRegex </td>
1326     <td> #AnchorNames </td>
1327     <td> RE </td>
1328   </tr>
1329   <tr>
1330     <td> abbrevRegex </td>
1331     <td> Abbreviations e.g. GOV, IRS </td>
1332     <td> RE </td>
1333   </tr>
1334   <tr>
1335     <td> emailAddrRegex </td>
1336     <td><a href="mailto:email@address.com">email@address.com</a></td>
1337     <td> RE </td>
1338   </tr>
1339   <tr>
1340     <td> tagNameRegex </td>
1341     <td> Standard variable names e.g. %THIS_BIT% (THIS_BIT only) </td>
1342     <td> RE </td>
1343   </tr>
1344 </table>
1345
1346 ### <a name="normalize_WebTopicName($web, $to"></a> normalizeWebTopicName($web, $topic) -&gt; ($web, $topic)
1347
1348 Parse a web and topic name, supplying defaults as appropriate.
1349
1350 - `$web` - Web name, identifying variable, or empty string
1351 - `$topic` - Topic name, may be a web.topic string, required.
1352
1353 Return: the parsed Web/Topic pair
1354
1355 **Since:** TWiki::Plugins::VERSION 1.1
1356
1357 <table border="1" cellpadding="0" cellspacing="0">
1358   <tr>
1359     <th bgcolor="#99CCCC"><strong> Input </strong></th>
1360     <th bgcolor="#99CCCC"><strong> Return </strong></th>
1361   </tr>
1362   <tr>
1363     <td><tt>( 'Web', 'Topic' ) </tt></td>
1364     <td><tt>( 'Web', 'Topic' ) </tt></td>
1365   </tr>
1366   <tr>
1367     <td><tt>( '', 'Topic' ) </tt></td>
1368     <td><tt>( 'Main', 'Topic' ) </tt></td>
1369   </tr>
1370   <tr>
1371     <td><tt>( '', '' ) </tt></td>
1372     <td><tt>( 'Main', 'WebHome' ) </tt></td>
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>( '', 'Web/Subweb/Topic' ) </tt></td>
1380     <td><tt>( 'Web/Subweb', 'Topic' ) </tt></td>
1381   </tr>
1382   <tr>
1383     <td><tt>( '', 'Web.Topic' ) </tt></td>
1384     <td><tt>( 'Web', 'Topic' ) </tt></td>
1385   </tr>
1386   <tr>
1387     <td><tt>( '', 'Web.Subweb.Topic' ) </tt></td>
1388     <td><tt>( 'Web/Subweb', 'Topic' ) </tt></td>
1389   </tr>
1390   <tr>
1391     <td><tt>( 'Web1', 'Web2.Topic' )</tt></td>
1392     <td><tt>( 'Web2', 'Topic' ) </tt></td>
1393   </tr>
1394 </table>
1395
1396 Note that hierarchical web names ([[SubWeb]]) are only available if hierarchical webs are enabled in `configure`.
1397
1398 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:
1399
1400 <table border="1" cellpadding="0" cellspacing="0">
1401   <tr>
1402     <th bgcolor="#99CCCC"><strong> Input </strong></th>
1403     <th bgcolor="#99CCCC"><strong> Return </strong></th>
1404   </tr>
1405   <tr>
1406     <td><tt>( '%USERSWEB%', 'Topic' )</tt></td>
1407     <td><tt>( 'Main', 'Topic' ) </tt></td>
1408   </tr>
1409   <tr>
1410     <td><tt>( '%SYSTEMWEB%', 'Topic' )</tt></td>
1411     <td><tt>( 'TWiki', 'Topic' ) </tt></td>
1412   </tr>
1413   <tr>
1414     <td><tt>( '', '%DOCWEB%.Topic' )</tt></td>
1415     <td><tt>( 'TWiki', 'Topic' ) </tt></td>
1416   </tr>
1417 </table>
1418
1419 ### <a name="writeWarning( $text )"></a> writeWarning( $text )
1420
1421 Log Warning that may require admin intervention to data/warning.txt
1422
1423 - `$text` - Text to write; timestamp gets added
1424
1425 Return: none
1426
1427 **Since:** TWiki::Plugins::VERSION 1.020 (16 Feb 2004)
1428
1429 ### <a name="writeDebug( $text )"></a> writeDebug( $text )
1430
1431 Log debug message to data/debug.txt
1432
1433 - `$text` - Text to write; timestamp gets added
1434
1435 Return: none
1436
1437 **Since:** TWiki::Plugins::VERSION 1.020 (16 Feb 2004)
1438
1439 ### <a name="formatTime( $time, $format, $tim"></a> formatTime( $time, $format, $timezone ) -&gt; $text
1440
1441 Format the time in seconds into the desired time string
1442
1443 - `$time` - Time in epoc seconds
1444 - `$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
1445 - `$timezone` - either not defined (uses the displaytime setting), 'gmtime', or 'servertime'
1446
1447 Return: `$text` Formatted time string
1448
1449 <table border="1" cellpadding="0" cellspacing="0">
1450   <tr>
1451     <td> Note: </td>
1452     <td> if you used the removed formatGmTime, add a third parameter 'gmtime' </td>
1453   </tr>
1454 </table>
1455
1456 **Since:** TWiki::Plugins::VERSION 1.020 (26 Feb 2004)
1457
1458 ### <a name="is_ValidWikiWord ( $text ) - $bo"></a> isValidWikiWord ( $text ) -&gt; $boolean
1459
1460 Check for a valid [[WikiWord]] or [[WikiName]]
1461
1462 - `$text` - Word to test
1463
1464 **Since:** TWiki::Plugins::VERSION 1.100 (Dec 2005)
1465
1466 ### <a name="extractParameters($attr ) - %par"></a> extractParameters($attr ) -&gt; %params
1467
1468 Extract all parameters from a variable string and returns a hash of parameters
1469
1470 - `$attr` - Attribute string
1471
1472 Return: `%params` Hash containing all parameters. The nameless parameter is stored in key `_DEFAULT`
1473
1474 **Since:** TWiki::Plugins::VERSION 1.025 (26 Aug 2004)
1475
1476 - Example:
1477   - Variable: `%TEST{ 'nameless' name1="val1" name2="val2" }%`
1478   - First extract text between `{...}` to get: `'nameless' name1="val1" name2="val2"`
1479   - Then call this on the text: <br />
1480 - params = TWiki::Func::extractParameters( $text );=
1481   - The `%params` hash contains now: <br />`_DEFAULT => 'nameless'`<br />`name1 => "val1"`<br />`name2 => "val2"`
1482
1483 ### <a name="extract_NameValuePair( $attr, $n"></a> extractNameValuePair( $attr, $name ) -&gt; $value
1484
1485 Extract a named or unnamed value from a variable parameter string - Note: | Function TWiki::Func::extractParameters is more efficient for extracting several parameters
1486
1487 - `$attr` - Attribute string
1488 - `$name` - Name, optional
1489
1490 Return: `$value` Extracted value
1491
1492 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
1493
1494 - Example:
1495   - Variable: `%TEST{ 'nameless' name1="val1" name2="val2" }%`
1496   - First extract text between `{...}` to get: `'nameless' name1="val1" name2="val2"`
1497   - 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" );`
1498
1499 ## <a name="Deprecated functions"></a> Deprecated functions
1500
1501 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.
1502
1503 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%.
1504
1505 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:
1506
1507     package TWiki::Plugins::SinkPlugin;
1508     use vars qw( %TWikiCompatibility );
1509     $TWikiCompatibility{endRenderingHandler} = 1.1;
1510
1511 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.
1512
1513 The following functions are retained for compatibility only. You should stop using them as soon as possible.
1514
1515 ### <a name="get_ScriptUrlPath( ) - $path"></a> getScriptUrlPath( ) -&gt; $path
1516
1517 Get script URL path
1518
1519 **DEPRECATED** since 1.1 - use `getScriptUrl` instead.
1520
1521 Return: `$path` URL path of TWiki scripts, e.g. `"/cgi-bin"`
1522
1523 **WARNING:** you are strongly recommended **not** to use this function, as the \{ScriptUrlPaths\} URL rewriting rules will not apply to urls generated using it.
1524
1525 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
1526
1527 ### <a name="get_PublicWebList( ) - @webs"></a> getPublicWebList( ) -&gt; @webs
1528
1529 **DEPRECATED** since 1.1 - use `getListOfWebs` instead.
1530
1531 Get list of all public webs, e.g. all webs that do not have the `NOSEARCHALL` flag set in the [[WebPreferences]]
1532
1533 Return: `@webs` List of all public webs, e.g. `( 'Main',  'Know', 'TWiki' )`
1534
1535 **Since:** TWiki::Plugins::VERSION 1.000 (07 Dec 2002)
1536
1537 ### <a name="format_GmTime( $time, $format )"></a><a name="format_GmTime( $time, $format ) "></a> formatGmTime( $time, $format ) -&gt; $text
1538
1539 **DEPRECATED** since 1.1 - use `formatTime` instead.
1540
1541 Format the time to GM time
1542
1543 - `$time` - Time in epoc seconds
1544 - `$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'`)
1545
1546 Return: `$text` Formatted time string
1547
1548 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
1549
1550 ### <a name="get_DataDir( ) - $dir"></a> getDataDir( ) -&gt; $dir
1551
1552 **DEPRECATED** since 1.1 - use the "Webs, Topics and Attachments" functions to manipulate topics instead
1553
1554 Get data directory (topic file root)
1555
1556 Return: `$dir` Data directory, e.g. `'/twiki/data'`
1557
1558 This function violates store encapsulation and is therefore **deprecated**.
1559
1560 **Since:** TWiki::Plugins::VERSION 1.000 (07 Dec 2002)
1561
1562 ### <a name="get_PubDir( ) - $dir"></a> getPubDir( ) -&gt; $dir
1563
1564 **DEPRECATED** since 1.1 - use the "Webs, Topics and Attachments" functions to manipulateattachments instead
1565
1566 Get pub directory (file attachment root). Attachments are in `$dir/Web/TopicName`
1567
1568 Return: `$dir` Pub directory, e.g. `'/htdocs/twiki/pub'`
1569
1570 This function violates store encapsulation and is therefore **deprecated**.
1571
1572 Use `readAttachment` and `saveAttachment` instead.
1573
1574 **Since:** TWiki::Plugins::VERSION 1.000 (07 Dec 2002)
1575
1576 ### <a name="checkDependencies( $moduleName,"></a><a name="checkDependencies( $moduleName, "></a> checkDependencies( $moduleName, $dependenciesRef ) -&gt; $error
1577
1578 **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.
1579
1580 **Since:** TWiki::Plugins::VERSION 1.025 (01 Aug 2004)