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|SYSTEMWEB/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%` TWiki variable, and accessed in code using `$TWiki::Plugins::VERSION`. The 'Since' field in the function documentation refers to `$TWiki::Plugins::VERSION`.
  14
  15 Notes on use of `$TWiki::Plugins::VERSION` (from 1.2 forwards):
  16
  17 - If the **major** version (e.g. `1.`) is the same then any plugin coded to use any **earlier** revision of the `1.` API will still work. No function has been removed from the interface, nor has any API published in that version changed in such a way as to **require** plugins to be recoded.
  18 - If the **minor** version (e.g. 1.1) is incremented there may be changes in the API that may help improve the coding of some plugins - for example, new interfaces giving access to previously hidden core functions. In addition, **deprecation** of functions in the interface trigger a minor version increment. Note that deprecated functions are not _removed_, they are merely frozen, and plugin authors are recommended to stop using them.
  19 - Any additional digits in the version number relate to minor changes, such as the addition of parameters to the existing functions, or addition of utility functions that are unlikely to require significant changes to existing plugins.
  20 - `TWiki::Plugins::VERSION` also applies to the plugin handlers. The handlers are documented in the EmptyPlugin, and that module indicates what version of `TWiki::Plugins::VERSION` it relates to.
  21
  22 A full history of the changes to this API can be found at the end of this topic.
  23
  24 <div>
  25   <ul>
  26     <li><a href="#Package =TWiki::Func="> Package TWiki::Func</a><ul>
  27         <li><a href="#Environment"> Environment</a><ul>
  28             <li><a href="#getSkin( ) -> $skin"> getSkin( ) -&gt; $skin</a></li>
  29             <li><a href="#get_UrlHost( ) -> $host"> getUrlHost( ) -&gt; $host</a></li>
  30             <li><a href="#get_ScriptUrl( $web, $topic, $sc"> getScriptUrl( $web, $topic, $script, ... ) -&gt; $url</a></li>
  31             <li><a href="#get_ViewUrl( $web, $topic ) -> $"> getViewUrl( $web, $topic ) -&gt; $url</a></li>
  32             <li><a href="#get_PubUrlPath( ) -> $path"> getPubUrlPath( ) -&gt; $path</a></li>
  33             <li><a href="#get_ExternalResource( $url ) ->"> getExternalResource( $url ) -&gt; $response</a></li>
  34             <li><a href="#get_CgiQuery( ) -> $query"> getCgiQuery( ) -&gt; $query</a></li>
  35             <li><a href="#get_SessionKeys() -> @keys"> getSessionKeys() -&gt; @keys</a></li>
  36             <li><a href="#get_SessionValue( $key ) -> $val"> getSessionValue( $key ) -&gt; $value</a></li>
  37             <li><a href="#set_SessionValue( $key, $value )"> setSessionValue( $key, $value ) -&gt; $boolean</a></li>
  38             <li><a href="#clear_SessionValue( $key ) -> $b"> clearSessionValue( $key ) -&gt; $boolean</a></li>
  39             <li><a href="#getContext() -> \%hash"> getContext() -&gt; \%hash</a></li>
  40             <li><a href="#push_TopicContext($web, $topic)"> pushTopicContext($web, $topic)</a></li>
  41             <li><a href="#pop_TopicContext()"> popTopicContext()</a></li>
  42           </ul>
  43         </li>
  44         <li><a href="#Preferences"> Preferences</a><ul>
  45             <li><a href="#get_PreferencesValue( $key, $web"> getPreferencesValue( $key, $web ) -&gt; $value</a></li>
  46             <li><a href="#get_PluginPreferencesValue( $key"> getPluginPreferencesValue( $key ) -&gt; $value</a></li>
  47             <li><a href="#get_PreferencesFlag( $key, $web"> getPreferencesFlag( $key, $web ) -&gt; $value</a></li>
  48             <li><a href="#get_PluginPreferencesFlag( $key"> getPluginPreferencesFlag( $key ) -&gt; $boolean</a></li>
  49             <li><a href="#set_PreferencesValue($name, $val"> setPreferencesValue($name, $val)</a></li>
  50             <li><a href="#get_WikiToolName( ) -> $name"> getWikiToolName( ) -&gt; $name</a></li>
  51             <li><a href="#get_MainWebname( ) -> $name"> getMainWebname( ) -&gt; $name</a></li>
  52             <li><a href="#get_TwikiWebname( ) -> $name"> getTwikiWebname( ) -&gt; $name</a></li>
  53           </ul>
  54         </li>
  55         <li><a href="#User Handling and Access Control"> User Handling and Access Control</a><ul>
  56             <li><a href="#get_DefaultUserName( ) -> $login"> getDefaultUserName( ) -&gt; $loginName</a></li>
  57             <li><a href="#get_CanonicalUserID( $user ) ->"> getCanonicalUserID( $user ) -&gt; $cUID</a></li>
  58             <li><a href="#get_WikiName( $user ) -> $wikiNa"> getWikiName( $user ) -&gt; $wikiName</a></li>
  59             <li><a href="#get_WikiUserName( $user ) -> $wi"> getWikiUserName( $user ) -&gt; $wikiName</a></li>
  60             <li><a href="#wiki_ToUserName( $id ) -> $login"> wikiToUserName( $id ) -&gt; $loginName</a></li>
  61             <li><a href="#user_ToWikiName( $loginName, $do"> userToWikiName( $loginName, $dontAddWeb ) -&gt; $wikiName</a></li>
  62             <li><a href="#email_ToWikiNames( $email, $dont"> emailToWikiNames( $email, $dontAddWeb ) -&gt; @wikiNames</a></li>
  63             <li><a href="#wikiname_ToEmails( $user ) -> @e"> wikinameToEmails( $user ) -&gt; @emails</a></li>
  64             <li><a href="#isGuest( ) -> $boolean"> isGuest( ) -&gt; $boolean</a></li>
  65             <li><a href="#is_AnAdmin( $id ) -> $boolean"> isAnAdmin( $id ) -&gt; $boolean</a></li>
  66             <li><a href="#is_GroupMember( $group, $id ) ->"> isGroupMember( $group, $id ) -&gt; $boolean</a></li>
  67             <li><a href="#eachUser() -> $iterator"> eachUser() -&gt; $iterator</a></li>
  68             <li><a href="#eachMembership($id) -> $iterator"> eachMembership($id) -&gt; $iterator</a></li>
  69             <li><a href="#eachGroup() -> $iterator"> eachGroup() -&gt; $iterator</a></li>
  70             <li><a href="#isGroup( $group ) -> $boolean"> isGroup( $group ) -&gt; $boolean</a></li>
  71             <li><a href="#each_GroupMember($group) -> $ite"> eachGroupMember($group) -&gt; $iterator</a></li>
  72             <li><a href="#check_AccessPermission( $type, $"> checkAccessPermission( $type, $id, $text, $topic, $web, $meta ) -&gt; $boolean</a></li>
  73           </ul>
  74         </li>
  75         <li><a href="#Webs, Topics and Attachments"> Webs, Topics and Attachments</a><ul>
  76             <li><a href="#get_ListOfWebs( $filter ) -> @we"> getListOfWebs( $filter ) -&gt; @webs</a></li>
  77             <li><a href="#webExists( $web ) -> $boolean"> webExists( $web ) -&gt; $boolean</a></li>
  78             <li><a href="#createWeb( $newWeb, $baseWeb, $o"> createWeb( $newWeb, $baseWeb, $opts )</a></li>
  79             <li><a href="#moveWeb( $oldName, $newName )"> moveWeb( $oldName, $newName )</a></li>
  80             <li><a href="#each_ChangeSince($web, $time) ->"> eachChangeSince($web, $time) -&gt; $iterator</a></li>
  81             <li><a href="#get_TopicList( $web ) -> @topics"> getTopicList( $web ) -&gt; @topics</a></li>
  82             <li><a href="#topicExists( $web, $topic ) -> $"> topicExists( $web, $topic ) -&gt; $boolean</a></li>
  83             <li><a href="#check_TopicEditLock( $web, $topi"> checkTopicEditLock( $web, $topic, $script ) -&gt; ( $oopsUrl, $loginName, $unlockTime )</a></li>
  84             <li><a href="#set_TopicEditLock( $web, $topic,"> setTopicEditLock( $web, $topic, $lock )</a></li>
  85             <li><a href="#saveTopic( $web, $topic, $meta,"> saveTopic( $web, $topic, $meta, $text, $options ) -&gt; $error</a></li>
  86             <li><a href="#save_TopicText( $web, $topic, $t"> saveTopicText( $web, $topic, $text, $ignorePermissions, $dontNotify ) -&gt; $oopsUrl</a></li>
  87             <li><a href="#moveTopic( $web, $topic, $newWeb"> moveTopic( $web, $topic, $newWeb, $newTopic )</a></li>
  88             <li><a href="#get_RevisionInfo($web, $topic, $"> getRevisionInfo($web, $topic, $rev, $attachment ) -&gt; ( $date, $user, $rev, $comment ) </a></li>
  89             <li><a href="#get_RevisionAtTime( $web, $topic"> getRevisionAtTime( $web, $topic, $time ) -&gt; $rev</a></li>
  90             <li><a href="#readTopic( $web, $topic, $rev )"> readTopic( $web, $topic, $rev ) -&gt; ( $meta, $text )</a></li>
  91             <li><a href="#read_TopicText( $web, $topic, $r"> readTopicText( $web, $topic, $rev, $ignorePermissions ) -&gt; $text</a></li>
  92             <li><a href="#attachmentExists( $web, $topic,"> attachmentExists( $web, $topic, $attachment ) -&gt; $boolean</a></li>
  93             <li><a href="#readAttachment( $web, $topic, $n"> readAttachment( $web, $topic, $name, $rev ) -&gt; $data</a></li>
  94             <li><a href="#saveAttachment( $web, $topic, $a"> saveAttachment( $web, $topic, $attachment, $opts )</a></li>
  95             <li><a href="#moveAttachment( $web, $topic, $a"> moveAttachment( $web, $topic, $attachment, $newWeb, $newTopic, $newAttachment )</a></li>
  96           </ul>
  97         </li>
  98         <li><a href="#Assembling Pages"> Assembling Pages</a><ul>
  99             <li><a href="#readTemplate( $name, $skin ) ->"> readTemplate( $name, $skin ) -&gt; $text</a></li>
 100             <li><a href="#loadTemplate ( $name, $skin, $we"> loadTemplate ( $name, $skin, $web ) -&gt; $text</a></li>
 101             <li><a href="#expandTemplate( $def  ) -> $stri"> expandTemplate( $def ) -&gt; $string</a></li>
 102             <li><a href="#writeHeader( $query, $contentLen"> writeHeader( $query, $contentLength )</a></li>
 103             <li><a href="#redirect_CgiQuery( $query, $url,"> redirectCgiQuery( $query, $url, $passthru )</a></li>
 104             <li><a href="#add_ToHEAD( $id, $header )"> addToHEAD( $id, $header )</a></li>
 105             <li><a href="#expand_CommonVariables( $text, $"> expandCommonVariables( $text, $topic, $web, $meta ) -&gt; $text</a></li>
 106             <li><a href="#renderText( $text, $web ) -> $te"> renderText( $text, $web ) -&gt; $text</a></li>
 107             <li><a href="#internalLink( $pre, $web, $topic"> internalLink( $pre, $web, $topic, $label, $anchor, $createLink ) -&gt; $text</a></li>
 108           </ul>
 109         </li>
 110         <li><a href="#E-mail"> E-mail</a><ul>
 111             <li><a href="#sendEmail ( $text, $retries ) ->"> sendEmail ( $text, $retries ) -&gt; $error</a></li>
 112             <li><a href="#wiki_ToEmail( $wikiName ) -> $em"> wikiToEmail( $wikiName ) -&gt; $email</a></li>
 113           </ul>
 114         </li>
 115         <li><a href="#Creating New Topics"> Creating New Topics</a><ul>
 116             <li><a href="#expand_VariablesOnTopicCreation"> expandVariablesOnTopicCreation ( $text ) -&gt; $text</a></li>
 117           </ul>
 118         </li>
 119         <li><a href="#Special handlers"> Special handlers</a><ul>
 120             <li><a href="#register_TagHandler( $var, \fn,"> registerTagHandler( $var, \&amp;fn, $syntax )</a></li>
 121             <li><a href="#registerRESTHandler( $alias, \fn"> registerRESTHandler( $alias, \&amp;fn, )</a></li>
 122             <li><a href="#decode_FormatTokens($str) -> $un"> decodeFormatTokens($str) -&gt; $unencodedString</a></li>
 123           </ul>
 124         </li>
 125         <li><a href="#Searching"> Searching</a><ul>
 126             <li><a href="#search_InWebContent($searchStrin"> searchInWebContent($searchString, $web, \@topics, \%options ) -&gt; \%map</a></li>
 127           </ul>
 128         </li>
 129         <li><a href="#Plugin-specific file handling"> Plugin-specific file handling</a><ul>
 130             <li><a href="#get_WorkArea( $pluginName ) -> $"> getWorkArea( $pluginName ) -&gt; $directorypath</a></li>
 131             <li><a href="#readFile( $filename ) -> $text"> readFile( $filename ) -&gt; $text</a></li>
 132             <li><a href="#saveFile( $filename, $text )"> saveFile( $filename, $text )</a></li>
 133           </ul>
 134         </li>
 135         <li><a href="#General Utilities"> General Utilities</a><ul>
 136             <li><a href="#get_RegularExpression( $name ) -"> getRegularExpression( $name ) -&gt; $expr</a></li>
 137             <li><a href="#normalize_WebTopicName($web, $to"> normalizeWebTopicName($web, $topic) -&gt; ($web, $topic)</a></li>
 138           </ul>
 139         </li>
 140         <li><a href="#StaticMethod *sanitize_Attachmen"> StaticMethod sanitizeAttachmentName <tt>($fname) -&gt; ($fileName,$origName)</tt></a><ul>
 141             <li><a href="#space_OutWikiWord( $word, $sep )"> spaceOutWikiWord( $word, $sep ) -&gt; $text</a></li>
 142             <li><a href="#writeWarning( $text )"> writeWarning( $text )</a></li>
 143             <li><a href="#writeDebug( $text )"> writeDebug( $text )</a></li>
 144             <li><a href="#formatTime( $time, $format, $tim"> formatTime( $time, $format, $timezone ) -&gt; $text</a></li>
 145             <li><a href="#isTrue( $value, $default ) -> $b"> isTrue( $value, $default ) -&gt; $boolean</a></li>
 146             <li><a href="#is_ValidWikiWord ( $text ) -> $b"> isValidWikiWord ( $text ) -&gt; $boolean</a></li>
 147             <li><a href="#extractParameters($attr ) -> %pa"> extractParameters($attr ) -&gt; %params</a></li>
 148             <li><a href="#extract_NameValuePair( $attr, $n"> extractNameValuePair( $attr, $name ) -&gt; $value</a></li>
 149           </ul>
 150         </li>
 151         <li><a href="#Deprecated functions"> Deprecated functions</a><ul>
 152             <li><a href="#get_ScriptUrlPath( ) -> $path"> getScriptUrlPath( ) -&gt; $path</a></li>
 153             <li><a href="#get_OopsUrl( $web, $topic, $temp"> getOopsUrl( $web, $topic, $template, $param1, $param2, $param3, $param4 ) -&gt; $url</a></li>
 154             <li><a href="#permissionsSet( $web ) -> $boole"> permissionsSet( $web ) -&gt; $boolean</a></li>
 155             <li><a href="#get_PublicWebList( ) -> @webs"> getPublicWebList( ) -&gt; @webs</a></li>
 156             <li><a href="#format_GmTime( $time, $format )"> formatGmTime( $time, $format ) -&gt; $text</a></li>
 157             <li><a href="#get_DataDir( ) -> $dir"> getDataDir( ) -&gt; $dir</a></li>
 158             <li><a href="#get_PubDir( ) -> $dir"> getPubDir( ) -&gt; $dir</a></li>
 159             <li><a href="#checkDependencies( $moduleName,"> checkDependencies( $moduleName, $dependenciesRef ) -&gt; $error</a></li>
 160           </ul>
 161         </li>
 162       </ul>
 163     </li>
 164   </ul>
 165 </div>
 166
 167 ## <a name="Environment"></a> Environment
 168
 169 ### <a name="getSkin( ) - $skin"></a> getSkin( ) -&gt; $skin
 170
 171 Get the skin path, set by the `SKIN` and `COVER` preferences variables or the `skin` and `cover` CGI parameters
 172
 173 Return: `$skin` Comma-separated list of skins, e.g. `'gnu,tartan'`. Empty string if none.
 174
 175 **Since:** TWiki::Plugins::VERSION 1.000 (29 Jul 2001)
 176
 177 ### <a name="get_UrlHost( ) - $host"></a> getUrlHost( ) -&gt; $host
 178
 179 Get protocol, domain and optional port of script URL
 180
 181 Return: `$host` URL host, e.g. `"http://example.com:80"`
 182
 183 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
 184
 185 ### <a name="get_ScriptUrl( $web, $topic, $sc"></a> getScriptUrl( $web, $topic, $script, ... ) -&gt; $url
 186
 187 Compose fully qualified URL
 188
 189 - `$web` - Web name, e.g. `'Main'`
 190 - `$topic` - Topic name, e.g. `'WebNotify'`
 191 - `$script` - Script name, e.g. `'view'`
 192 - `...` - an arbitrary number of name=&gt;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`
 193
 194 Return: `$url` URL, e.g. `"http://example.com:80/cgi-bin/view.pl/Main/WebNotify"`
 195
 196 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
 197
 198 ### <a name="get_ViewUrl( $web, $topic ) - $u"></a> getViewUrl( $web, $topic ) -&gt; $url
 199
 200 Compose fully qualified view URL
 201
 202 - `$web` - Web name, e.g. `'Main'`. The current web is taken if empty
 203 - `$topic` - Topic name, e.g. `'WebNotify'`
 204
 205 Return: `$url` URL, e.g. `"http://example.com:80/cgi-bin/view.pl/Main/WebNotify"`
 206
 207 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
 208
 209 ### <a name="get_PubUrlPath( ) - $path"></a> getPubUrlPath( ) -&gt; $path
 210
 211 Get pub URL path
 212
 213 Return: `$path` URL path of pub directory, e.g. `"/pub"`
 214
 215 **Since:** TWiki::Plugins::VERSION 1.000 (14 Jul 2001)
 216
 217 ### <a name="get_ExternalResource( $url ) - $"></a> getExternalResource( $url ) -&gt; $response
 218
 219 Get whatever is at the other end of a URL (using an HTTP GET request). Will only work for encrypted protocols such as `https` if the `LWP` CPAN module is installed.
 220
 221 Note that the `$url` may have an optional user and password, as specified by the relevant RFC. Any proxy set in `configure` is honoured.
 222
 223 The `$response` is an object that is known to implement the following subset of the methods of `LWP::Response`. It may in fact be an `LWP::Response` object, but it may also not be if `LWP` is not available, so callers may only assume the following subset of methods is available:
 224
 225 <table border="1" cellpadding="0" cellspacing="0">
 226   <tr>
 227     <td><code>code()</code></td>
 228   </tr>
 229   <tr>
 230     <td><code>message()</code></td>
 231   </tr>
 232   <tr>
 233     <td><code>header($field)</code></td>
 234   </tr>
 235   <tr>
 236     <td><code>content()</code></td>
 237   </tr>
 238   <tr>
 239     <td><code>is_error()</code></td>
 240   </tr>
 241   <tr>
 242     <td><code>is_redirect()</code></td>
 243   </tr>
 244 </table>
 245
 246 Note that if LWP is **not** available, this function:
 247
 248 1. can only really be trusted for HTTP/1.0 urls. If HTTP/1.1 or another protocol is required, you are **strongly** recommended to `require LWP`.
 249 2. Will not parse multipart content
 250
 251 In the event of the server returning an error, then `is_error()` will return true, `code()` will return a valid HTTP status code as specified in RFC 2616 and RFC 2518, and `message()` will return the message that was received from the server. In the event of a client-side error (e.g. an unparseable URL) then `is_error()` will return true and `message()` will return an explanatory message. `code()` will return 400 (BAD REQUEST).
 252
 253 Note: Callers can easily check the availability of other HTTP::Response methods as follows:
 254
 255     my $response = TWiki::Func::getExternalResource($url);
 256     if (!$response->is_error() && $response->isa('HTTP::Response')) {
 257         ... other methods of HTTP::Response may be called
 258     } else {
 259         ... only the methods listed above may be called
 260     }
 261
 262 **Since:** TWiki::Plugins::VERSION 1.2
 263
 264 ### <a name="get_CgiQuery( ) - $query"></a> getCgiQuery( ) -&gt; $query
 265
 266 Get CGI query object. Important: Plugins cannot assume that scripts run under CGI, Plugins must always test if the CGI query object is set
 267
 268 Return: `$query` CGI query object; or 0 if script is called as a shell script
 269
 270 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
 271
 272 ### <a name="get_SessionKeys() - @keys"></a> getSessionKeys() -&gt; @keys
 273
 274 Get a list of all the names of session variables. The list is unsorted.
 275
 276 Session keys are stored and retrieved using `setSessionValue` and `getSessionValue`.
 277
 278 **Since:** TWiki::Plugins::VERSION 1.2
 279
 280 ### <a name="get_SessionValue( $key ) - $valu"></a> getSessionValue( $key ) -&gt; $value
 281
 282 Get a session value from the client session module
 283
 284 - `$key` - Session key
 285
 286 Return: `$value` Value associated with key; empty string if not set
 287
 288 **Since:** TWiki::Plugins::VERSION 1.000 (27 Feb 200)
 289
 290 ### <a name="set_SessionValue( $key, $value )"></a> setSessionValue( $key, $value ) -&gt; $boolean
 291
 292 Set a session value.
 293
 294 - `$key` - Session key
 295 - `$value` - Value associated with key
 296
 297 Return: true if function succeeded
 298
 299 **Since:** TWiki::Plugins::VERSION 1.000 (17 Aug 2001)
 300
 301 ### <a name="clear_SessionValue( $key ) - $bo"></a> clearSessionValue( $key ) -&gt; $boolean
 302
 303 Clear a session value that was set using `setSessionValue`.
 304
 305 - `$key` - name of value stored in session to be cleared. Note that you **cannot** clear `AUTHUSER`.
 306
 307 Return: true if the session value was cleared
 308
 309 **Since:** TWiki::Plugins::VERSION 1.1
 310
 311 ### <a name="getContext() - \%hash"></a> getContext() -&gt; \\%hash
 312
 313 Get a hash of context identifiers representing the currently active context.
 314
 315 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 %SYSTEMWEB%.IfStatements topic. Please be careful not to overwrite any of these identifiers!
 316
 317 Context identifiers can be used to communicate between Plugins, and between Plugins and templates. For example, in [[FirstPlugin]].pm, you might write:
 318
 319     sub initPlugin {
 320        TWiki::Func::getContext()->{'MyID'} = 1;
 321        ...
 322
 323 This can be used in SecondPlugin.pm like this:
 324
 325     sub initPlugin {
 326        if( TWiki::Func::getContext()->{'MyID'} ) {
 327           ...
 328        }
 329        ...
 330
 331 or in a template, like this:
 332
 333     %TMPL:DEF{"ON"}% Not off %TMPL:END%
 334     %TMPL:DEF{"OFF"}% Not on %TMPL:END%
 335     %TMPL:P{context="MyID" then="ON" else="OFF"}%
 336
 337 or in a topic:
 338
 339     %IF{"context MyID" then="MyID is ON" else="MyID is OFF"}%
 340
 341 **_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.
 342
 343 **Since:** TWiki::Plugins::VERSION 1.1
 344
 345 ### <a name="push_TopicContext($web, $topic)"></a> pushTopicContext($web, $topic)
 346
 347 - `$web` - new web
 348 - `$topic` - new topic
 349
 350 Change the TWiki context so it behaves as if it was processing `$web.$topic` from now on. All the preferences will be reset to those of the new topic. Note that if the new topic is not readable by the logged in user due to access control considerations, there will **not** be an exception. It is the duty of the caller to check access permissions before changing the topic.
 351
 352 It is the duty of the caller to restore the original context by calling `popTopicContext`.
 353
 354 Note that this call does **not** re-initialise plugins, so if you have used global variables to remember the web and topic in `initPlugin`, then those values will be unchanged.
 355
 356 **Since:** TWiki::Plugins::VERSION 1.2
 357
 358 ### <a name="pop_TopicContext()"></a> popTopicContext()
 359
 360 Returns the TWiki context to the state it was in before the `pushTopicContext` was called.
 361
 362 **Since:** TWiki::Plugins::VERSION 1.2
 363
 364 ## <a name="Preferences"></a> Preferences
 365
 366 ### <a name="get_PreferencesValue( $key, $web"></a> getPreferencesValue( $key, $web ) -&gt; $value
 367
 368 Get a preferences value from TWiki or from a Plugin
 369
 370 - `$key` - Preferences key
 371 - `$web` - Name of web, optional. Current web if not specified; does not apply to settings of Plugin topics
 372
 373 Return: `$value` Preferences value; empty string if not set
 374
 375 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
 376
 377 - Example for Plugin setting:
 378   - [[MyPlugin]] topic has: `* Set COLOR = red`
 379   - Use `"MYPLUGIN_COLOR"` for `$key`
 380   - `my $color = TWiki::Func::getPreferencesValue( "MYPLUGIN_COLOR" );`
 381
 382 - Example for preferences setting:
 383   - [[WebPreferences]] topic has: `* Set WEBBGCOLOR = #FFFFC0`
 384   - `my $webColor = TWiki::Func::getPreferencesValue( 'WEBBGCOLOR', 'Sandbox' );`
 385
 386 **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.
 387
 388 ### <a name="get_PluginPreferencesValue( $key"></a> getPluginPreferencesValue( $key ) -&gt; $value
 389
 390 Get a preferences value from your Plugin
 391
 392 - `$key` - Plugin Preferences key w/o PLUGINNAME\_ prefix.
 393
 394 Return: `$value` Preferences value; empty string if not set
 395
 396 **_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)
 397
 398 **Since:** TWiki::Plugins::VERSION 1.021 (27 Mar 2004)
 399
 400 **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.
 401
 402 ### <a name="get_PreferencesFlag( $key, $web"></a><a name="get_PreferencesFlag( $key, $web "></a> getPreferencesFlag( $key, $web ) -&gt; $value
 403
 404 Get a preferences flag from TWiki or from a Plugin
 405
 406 - `$key` - Preferences key
 407 - `$web` - Name of web, optional. Current web if not specified; does not apply to settings of Plugin topics
 408
 409 Return: `$value` Preferences flag `'1'` (if set), or `"0"` (for preferences values `"off"`, `"no"` and `"0"`)
 410
 411 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
 412
 413 - Example for Plugin setting:
 414   - [[MyPlugin]] topic has: `* Set SHOWHELP = off`
 415   - Use `"MYPLUGIN_SHOWHELP"` for `$key`
 416   - `my $showHelp = TWiki::Func::getPreferencesFlag( "MYPLUGIN_SHOWHELP" );`
 417
 418 **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.
 419
 420 ### <a name="get_PluginPreferencesFlag( $key"></a><a name="get_PluginPreferencesFlag( $key "></a> getPluginPreferencesFlag( $key ) -&gt; $boolean
 421
 422 Get a preferences flag from your Plugin
 423
 424 - `$key` - Plugin Preferences key w/o PLUGINNAME\_ prefix.
 425
 426 Return: false for preferences values `"off"`, `"no"` and `"0"`, or values not set at all. True otherwise.
 427
 428 **_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)
 429
 430 **Since:** TWiki::Plugins::VERSION 1.021 (27 Mar 2004)
 431
 432 **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.
 433
 434 ### <a name="set_PreferencesValue($name, $val"></a> setPreferencesValue($name, $val)
 435
 436 Set the preferences value so that future calls to getPreferencesValue will return this value, and `%$name%` will expand to the preference when used in future variable expansions.
 437
 438 The preference only persists for the rest of this request. Finalised preferences cannot be redefined using this function.
 439
 440 Returns 1 if the preference was defined, and 0 otherwise.
 441
 442 ### <a name="get_WikiToolName( ) - $name"></a> getWikiToolName( ) -&gt; $name
 443
 444 Get toolname as defined in TWiki.cfg
 445
 446 Return: `$name` Name of tool, e.g. `'TWiki'`
 447
 448 **Since:** TWiki::Plugins::VERSION 1.000 (27 Feb 2001)
 449
 450 ### <a name="get_MainWebname( ) - $name"></a> getMainWebname( ) -&gt; $name
 451
 452 Get name of Main web as defined in TWiki.cfg
 453
 454 Return: `$name` Name, e.g. `'Main'`
 455
 456 **Since:** TWiki::Plugins::VERSION 1.000 (27 Feb 2001)
 457
 458 ### <a name="get_TwikiWebname( ) - $name"></a> getTwikiWebname( ) -&gt; $name
 459
 460 Get name of TWiki documentation web as defined in TWiki.cfg
 461
 462 Return: `$name` Name, e.g. `'TWiki'`
 463
 464 **Since:** TWiki::Plugins::VERSION 1.000 (27 Feb 2001)
 465
 466 ## <a name="User Handling and Access Control"></a> User Handling and Access Control
 467
 468 ### <a name="get_DefaultUserName( ) - $loginN"></a> getDefaultUserName( ) -&gt; $loginName
 469
 470 Get default user name as defined in the configuration as `DefaultUserLogin`
 471
 472 Return: `$loginName` Default user name, e.g. `'guest'`
 473
 474 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
 475
 476 ### <a name="get_CanonicalUserID( $user ) - $"></a> getCanonicalUserID( $user ) -&gt; $cUID
 477
 478 - `$user` can be a login, wikiname or web.wikiname
 479
 480 Return the cUID of the specified user. A cUID is a unique identifier which is assigned by TWiki for each user. BEWARE: While the default [[TWikiUserMapping]] uses a cUID that looks like a user's [[LoginName]], some characters are modified to make them compatible with rcs. Other usermappings may use other conventions - the JoomlaUserMapping for example, has cUIDs like 'JoomlaeUserMapping\_1234'.
 481
 482 If $user is undefined, it assumes the currently logged-in user.
 483
 484 Return: `$cUID`, an internal unique and portable escaped identifier for registered users. This may be autogenerated for an authenticated but unregistered user.
 485
 486 **Since:** TWiki::Plugins::VERSION 1.2
 487
 488 ### <a name="get_WikiName( $user ) - $wikiNam"></a> getWikiName( $user ) -&gt; $wikiName
 489
 490 return the [[WikiName]] of the specified user if $user is undefined Get Wiki name of logged in user
 491
 492 - $user can be a cUID, login, wikiname or web.wikiname
 493
 494 Return: `$wikiName` Wiki Name, e.g. `'JohnDoe'`
 495
 496 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
 497
 498 ### <a name="get_WikiUserName( $user ) - $wik"></a> getWikiUserName( $user ) -&gt; $wikiName
 499
 500 return the userWeb.WikiName of the specified user if $user is undefined Get Wiki name of logged in user
 501
 502 - $user can be a cUID, login, wikiname or web.wikiname
 503
 504 Return: `$wikiName` Wiki Name, e.g. `"Main.JohnDoe"`
 505
 506 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
 507
 508 ### <a name="wiki_ToUserName( $id ) - $loginN"></a> wikiToUserName( $id ) -&gt; $loginName
 509
 510 Translate a Wiki name to a login name.
 511
 512 - `$id` - Wiki name, e.g. `'Main.JohnDoe'` or `'JohnDoe'`. Since TWiki 4.2.1, $id may also be a login name. This will normally be transparent, but should be borne in mind if you have login names that are also legal wiki names.
 513
 514 Return: `$loginName` Login name of user, e.g. `'jdoe'`, or undef if not matched.
 515
 516 Note that it is possible for several login names to map to the same wikiname. This function will only return the **first** login name that maps to the wikiname.
 517
 518 returns undef if the [[WikiName]] is not found.
 519
 520 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
 521
 522 ### <a name="user_ToWikiName( $loginName, $do"></a> userToWikiName( $loginName, $dontAddWeb ) -&gt; $wikiName
 523
 524 Translate a login name to a Wiki name
 525
 526 - `$loginName` - Login name, e.g. `'jdoe'`. Since TWiki 4.2.1 this may also be a wiki name. This will normally be transparent, but may be relevant if you have login names that are also valid wiki names.
 527 - `$dontAddWeb` - Do not add web prefix if `"1"`
 528
 529 Return: `$wikiName` Wiki name of user, e.g. `'Main.JohnDoe'` or `'JohnDoe'`
 530
 531 userToWikiName will always return a name. If the user does not exist in the mapping, the $loginName parameter is returned. (backward compatibility)
 532
 533 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
 534
 535 ### <a name="email_ToWikiNames( $email, $dont"></a> emailToWikiNames( $email, $dontAddWeb ) -&gt; @wikiNames
 536
 537 - `$email` - email address to look up
 538 - `$dontAddWeb` - Do not add web prefix if `"1"`
 539
 540 Find the wikinames of all users who have the given email address as their registered address. Since several users could register with the same email address, this returns a list of wikinames rather than a single wikiname.
 541
 542 **Since:** TWiki::Plugins::VERSION 1.2
 543
 544 ### <a name="wikiname_ToEmails( $user ) - @em"></a> wikinameToEmails( $user ) -&gt; @emails
 545
 546 - `$user` - wikiname of user to look up
 547
 548 Returns the registered email addresses of the named user. If $user is undef, returns the registered email addresses for the logged-in user.
 549
 550 Since TWiki 4.2.1, $user may also be a login name, or the name of a group.
 551
 552 **Since:** TWiki::Plugins::VERSION 1.2
 553
 554 ### <a name="isGuest( ) - $boolean"></a> isGuest( ) -&gt; $boolean
 555
 556 Test if logged in user is a guest ([[TWikiGuest]])
 557
 558 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
 559
 560 ### <a name="is_AnAdmin( $id ) - $boolean"></a> isAnAdmin( $id ) -&gt; $boolean
 561
 562 Find out if the user is an admin or not. If the user is not given, the currently logged-in user is assumed.
 563
 564 - $id can be either a login name or a [[WikiName]]
 565
 566 **Since:** TWiki::Plugins::VERSION 1.2
 567
 568 ### <a name="is_GroupMember( $group, $id ) -"></a><a name="is_GroupMember( $group, $id ) - "></a> isGroupMember( $group, $id ) -&gt; $boolean
 569
 570 Find out if $id is in the named group. e.g.
 571
 572     if( TWiki::Func::isGroupMember( "HesperionXXGroup", "jordi" )) {
 573         ...
 574     }
 575
 576 If `$user` is `undef`, it defaults to the currently logged-in user.
 577
 578 - $id can be a login name or a [[WikiName]]
 579
 580 **Since:** TWiki::Plugins::VERSION 1.2
 581
 582 ### <a name="eachUser() - $iterator"></a> eachUser() -&gt; $iterator
 583
 584 Get an iterator over the list of all the registered users **not** including groups. The iterator will return each wiki name in turn (e.g. 'FredBloggs').
 585
 586 Use it as follows:
 587
 588         my $iterator = TWiki::Func::eachUser();
 589         while ($it->hasNext()) {
 590             my $user = $it->next();
 591             # $user is a wikiname
 592         }
 593
 594 **WARNING** on large sites, this could be a long list!
 595
 596 **Since:** TWiki::Plugins::VERSION 1.2
 597
 598 ### <a name="eachMembership($id) - $iterator"></a> eachMembership($id) -&gt; $iterator
 599
 600 - `$id` - [[WikiName]] or login name of the user. If `$id` is `undef`, defaults to the currently logged-in user.
 601
 602 Get an iterator over the names of all groups that the user is a member of.
 603
 604 **Since:** TWiki::Plugins::VERSION 1.2
 605
 606 ### <a name="eachGroup() - $iterator"></a> eachGroup() -&gt; $iterator
 607
 608 Get an iterator over all groups.
 609
 610 Use it as follows:
 611
 612         my $iterator = TWiki::Func::eachGroup();
 613         while ($it->hasNext()) {
 614             my $group = $it->next();
 615             # $group is a group name e.g. TWikiAdminGroup
 616         }
 617
 618 **WARNING** on large sites, this could be a long list!
 619
 620 **Since:** TWiki::Plugins::VERSION 1.2
 621
 622 ### <a name="isGroup( $group ) - $boolean"></a> isGroup( $group ) -&gt; $boolean
 623
 624 Checks if `$group` is the name of a group known to TWiki.
 625
 626 ### <a name="each_GroupMember($group) - $iter"></a> eachGroupMember($group) -&gt; $iterator
 627
 628 Get an iterator over all the members of the named group. Returns undef if $group is not a valid group.
 629
 630 Use it as follows:
 631
 632         my $iterator = TWiki::Func::eachGroupMember('RadioheadGroup');
 633         while ($it->hasNext()) {
 634             my $user = $it->next();
 635             # $user is a wiki name e.g. 'TomYorke', 'PhilSelway'
 636         }
 637
 638 **WARNING** on large sites, this could be a long list!
 639
 640 **Since:** TWiki::Plugins::VERSION 1.2
 641
 642 ### <a name="check_AccessPermission( $type, $"></a> checkAccessPermission( $type, $id, $text, $topic, $web, $meta ) -&gt; $boolean
 643
 644 Check access permission for a topic based on the [[%SYSTEMWEB%.TWikiAccessControl|SYSTEMWEB/TWikiAccessControl]] rules
 645
 646 - `$type` - Access type, required, e.g. `'VIEW'`, `'CHANGE'`.
 647 - `$id` - [[WikiName]] of remote user, required, e.g. `"PeterThoeny"`. From TWiki 4.2.1, $id may also be a login name. If `$id` is '', 0 or `undef` then access is **always permitted**.
 648 - `$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:
 649   1. You are setting different access controls in the text to those defined in the stored topic,
 650   2. You already have the topic text in hand, and want to help TWiki avoid having to read it again,
 651   3. You are providing a `$meta` parameter.
 652 - `$topic` - Topic name, required, e.g. `'PrivateStuff'`
 653 - `$web` - Web name, required, e.g. `'Sandbox'`
 654 - `$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.
 655
 656 A perl true result indicates that access is permitted.
 657
 658 **Note** the weird parameter order is due to compatibility constraints with earlier TWiki releases.
 659
 660 **Tip** if you want, you can use this method to check your own access control types. For example, if you:
 661
 662 - Set ALLOWTOPICSPIN = [[IncyWincy]]
 663
 664 in `ThatWeb.ThisTopic`, then a call to `checkAccessPermissions('SPIN', 'IncyWincy', undef, 'ThisTopic', 'ThatWeb', undef)` will return `true`.
 665
 666 **Since:** TWiki::Plugins::VERSION 1.000 (27 Feb 2001)
 667
 668 ## <a name="Webs, Topics and Attachments"></a> Webs, Topics and Attachments
 669
 670 ### <a name="get_ListOfWebs( $filter ) - @web"></a> getListOfWebs( $filter ) -&gt; @webs
 671
 672 - `$filter` - spec of web types to recover
 673
 674 Gets a list of webs, filtered according to the spec in the $filter, which may include one of:
 675
 676 1. 'user' (for only user webs)
 677 2. 'template' (for only template webs i.e. those starting with "\_")
 678
 679 `$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.
 680
 681 For example, the deprecated getPublicWebList function can be duplicated as follows:
 682
 683        my @webs = TWiki::Func::getListOfWebs( "user,public" );
 684
 685 **Since:** TWiki::Plugins::VERSION 1.1
 686
 687 ### <a name="webExists( $web ) - $boolean"></a> webExists( $web ) -&gt; $boolean
 688
 689 Test if web exists
 690
 691 - `$web` - Web name, required, e.g. `'Sandbox'`
 692
 693 **Since:** TWiki::Plugins::VERSION 1.000 (14 Jul 2001)
 694
 695 ### <a name="createWeb( $newWeb, $baseWeb, $o"></a> createWeb( $newWeb, $baseWeb, $opts )
 696
 697 - `$newWeb` is the name of the new web.
 698 - `$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.
 699 - `$opts` is a ref to a hash that contains settings to be modified in
 700
 701 the web preferences topic in the new web.
 702
 703     use Error qw( :try );
 704     use TWiki::AccessControlException;
 705
 706     try {
 707         TWiki::Func::createWeb( "Newweb" );
 708     } catch Error::Simple with {
 709         my $e = shift;
 710         # see documentation on Error::Simple
 711     } catch TWiki::AccessControlException with {
 712         my $e = shift;
 713         # see documentation on TWiki::AccessControlException
 714     } otherwise {
 715         ...
 716     };
 717
 718 **Since:** TWiki::Plugins::VERSION 1.1
 719
 720 ### <a name="moveWeb( $oldName, $newName )"></a> moveWeb( $oldName, $newName )
 721
 722 Move (rename) a web.
 723
 724     use Error qw( :try );
 725     use TWiki::AccessControlException;
 726
 727     try {
 728         TWiki::Func::moveWeb( "Oldweb", "Newweb" );
 729     } catch Error::Simple with {
 730         my $e = shift;
 731         # see documentation on Error::Simple
 732     } catch TWiki::AccessControlException with {
 733         my $e = shift;
 734         # see documentation on TWiki::AccessControlException
 735     } otherwise {
 736         ...
 737     };
 738
 739 To delete a web, move it to a subweb of `Trash`
 740
 741     TWiki::Func::moveWeb( "Deadweb", "Trash.Deadweb" );
 742
 743 **Since:** TWiki::Plugins::VERSION 1.1
 744
 745 ### <a name="each_ChangeSince($web, $time) -"></a><a name="each_ChangeSince($web, $time) - "></a> eachChangeSince($web, $time) -&gt; $iterator
 746
 747 Get an iterator over the list of all the changes in the given web between `$time` and now. $time is a time in seconds since 1st Jan 1970, and is not guaranteed to return any changes that occurred before (now - \{Store\}\{RememberChangesFor\}). \{Store\}\{RememberChangesFor\}) is a setting in `configure`. Changes are returned in **most-recent-first** order.
 748
 749 Use it as follows:
 750
 751         my $iterator = TWiki::Func::eachChangeSince(
 752             $web, time() - 7 * 24 * 60 * 60); # the last 7 days
 753         while ($iterator->hasNext()) {
 754             my $change = $iterator->next();
 755             # $change is a perl hash that contains the following fields:
 756             # topic => topic name
 757             # user => wikiname - wikiname of user who made the change
 758             # time => time of the change
 759             # revision => revision number *after* the change
 760             # more => more info about the change (e.g. 'minor')
 761         }
 762
 763 ### <a name="get_TopicList( $web ) - @topics"></a> getTopicList( $web ) -&gt; @topics
 764
 765 Get list of all topics in a web
 766
 767 - `$web` - Web name, required, e.g. `'Sandbox'`
 768
 769 Return: `@topics` Topic list, e.g. `( 'WebChanges',  'WebHome', 'WebIndex', 'WebNotify' )`
 770
 771 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
 772
 773 ### <a name="topicExists( $web, $topic ) - $b"></a> topicExists( $web, $topic ) -&gt; $boolean
 774
 775 Test if topic exists
 776
 777 - `$web` - Web name, optional, e.g. `'Main'`.
 778 - `$topic` - Topic name, required, e.g. `'TokyoOffice'`, or `"Main.TokyoOffice"`
 779
 780 $web and $topic are parsed as described in the documentation for `normalizeWebTopicName`. Specifically, the %USERSWEB% is used if $web is not specified and $topic has no web specifier. To get an expected behaviour it is recommened to specify the current web for $web; don't leave it empty.
 781
 782 **Since:** TWiki::Plugins::VERSION 1.000 (14 Jul 2001)
 783
 784 ### <a name="check_TopicEditLock( $web, $topi"></a> checkTopicEditLock( $web, $topic, $script ) -&gt; ( $oopsUrl, $loginName, $unlockTime )
 785
 786 Check if a lease has been taken by some other user.
 787
 788 - `$web` Web name, e.g. `"Main"`, or empty
 789 - `$topic` Topic name, e.g. `"MyTopic"`, or `"Main.MyTopic"`
 790
 791 Return: `( $oopsUrl, $loginName, $unlockTime )` - The `$oopsUrl` for calling redirectCgiQuery(), user's `$loginName`, and estimated `$unlockTime` in minutes, or ( '', '', 0 ) if no lease exists.
 792
 793 - `$script` The script to invoke when continuing with the edit
 794
 795 **Since:** TWiki::Plugins::VERSION 1.010 (31 Dec 2002)
 796
 797 ### <a name="set_TopicEditLock( $web, $topic,"></a> setTopicEditLock( $web, $topic, $lock )
 798
 799 - `$web` Web name, e.g. `"Main"`, or empty
 800 - `$topic` Topic name, e.g. `"MyTopic"`, or `"Main.MyTopic"`
 801 - `$lock` 1 to lease the topic, 0 to clear an existing lease
 802
 803 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.
 804
 805 It is **impossible** to fully lock a topic. Concurrent changes will be merged.
 806
 807 **Since:** TWiki::Plugins::VERSION 1.010 (31 Dec 2002)
 808
 809 ### <a name="saveTopic( $web, $topic, $meta,"></a><a name="saveTopic( $web, $topic, $meta, "></a> saveTopic( $web, $topic, $meta, $text, $options ) -&gt; $error
 810
 811 - `$web` - web for the topic
 812 - `$topic` - topic name
 813 - `$meta` - reference to TWiki::Meta object
 814 - `$text` - text of the topic (without embedded meta-data!!!
 815 - `\%options` - ref to hash of save options `\%options` may include: <table border="1" cellpadding="0" cellspacing="0">
 816   <tr>
 817     <td><code>dontlog</code></td>
 818     <td> don't log this change in twiki log </td>
 819   </tr>
 820   <tr>
 821     <td><code>forcenewrevision</code></td>
 822     <td> force the save to increment the revision counter </td>
 823   </tr>
 824   <tr>
 825     <td><code>minor</code></td>
 826     <td> True if this is a minor change, and is not to be notified </td>
 827   </tr>
 828 </table>
 829
 830 Return: error message or undef.
 831
 832 **Since:** TWiki::Plugins::VERSION 1.000 (29 Jul 2001)
 833
 834 For example,
 835
 836     my( $meta, $text ) = TWiki::Func::readTopic( $web, $topic )
 837     $text =~ s/APPLE/ORANGE/g;
 838     TWiki::Func::saveTopic( $web, $topic, $meta, $text, { forcenewrevision => 1 } );
 839
 840 **_Note:_** Plugins handlers ( e.g. `beforeSaveHandler` ) will be called as appropriate.
 841
 842 ### <a name="save_TopicText( $web, $topic, $t"></a> saveTopicText( $web, $topic, $text, $ignorePermissions, $dontNotify ) -&gt; $oopsUrl
 843
 844 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.
 845
 846 - `$web` - Web name, e.g. `'Main'`, or empty
 847 - `$topic` - Topic name, e.g. `'MyTopic'`, or `"Main.MyTopic"`
 848 - `$text` - Topic text to save, assumed to include meta data
 849 - `$ignorePermissions` - Set to `"1"` if checkAccessPermission() is already performed and OK
 850 - `$dontNotify` - Set to `"1"` if not to notify users of the change
 851
 852 Return: `$oopsUrl` Empty string if OK; the `$oopsUrl` for calling redirectCgiQuery() in case of error
 853
 854 This method is a lot less efficient and much more dangerous than `saveTopic`.
 855
 856 **Since:** TWiki::Plugins::VERSION 1.010 (31 Dec 2002)
 857
 858     my $text = TWiki::Func::readTopicText( $web, $topic );
 859
 860     # check for oops URL in case of error:
 861     if( $text =~ /^http.*?\/oops/ ) {
 862         TWiki::Func::redirectCgiQuery( $query, $text );
 863         return;
 864     }
 865     # do topic text manipulation like:
 866     $text =~ s/old/new/g;
 867     # do meta data manipulation like:
 868     $text =~ s/(META\:FIELD.*?name\=\"TopicClassification\".*?value\=\")[^\"]*/$1BugResolved/;
 869     $oopsUrl = TWiki::Func::saveTopicText( $web, $topic, $text ); # save topic text
 870
 871 ### <a name="moveTopic( $web, $topic, $newWeb"></a> moveTopic( $web, $topic, $newWeb, $newTopic )
 872
 873 - `$web` source web - required
 874 - `$topic` source topic - required
 875 - `$newWeb` dest web
 876 - `$newTopic` dest topic
 877
 878 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.
 879
 880 The destination topic must not already exist.
 881
 882 Rename a topic to the $TWiki::cfg\{TrashWebName\} to delete it.
 883
 884 **Since:** TWiki::Plugins::VERSION 1.1
 885
 886     use Error qw( :try );
 887
 888     try {
 889         moveTopic( "Work", "TokyoOffice", "Trash", "ClosedOffice" );
 890     } catch Error::Simple with {
 891         my $e = shift;
 892         # see documentation on Error::Simple
 893     } catch TWiki::AccessControlException with {
 894         my $e = shift;
 895         # see documentation on TWiki::AccessControlException
 896     } otherwise {
 897         ...
 898     };
 899
 900 ### <a name="get_RevisionInfo($web, $topic, $"></a> getRevisionInfo($web, $topic, $rev, $attachment ) -&gt; ( $date, $user, $rev, $comment )
 901
 902 Get revision info of a topic or attachment
 903
 904 - `$web` - Web name, optional, e.g. `'Main'`
 905 - `$topic` - Topic name, required, e.g. `'TokyoOffice'`
 906 - `$rev` - revsion number, or tag name (can be in the format 1.2, or just the minor number)
 907 - `$attachment` -attachment filename
 908
 909 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" )`
 910
 911 <table border="1" cellpadding="0" cellspacing="0">
 912   <tr>
 913     <td> $date </td>
 914     <td> in epochSec </td>
 915   </tr>
 916   <tr>
 917     <td> $user </td>
 918     <td> Wiki name of the author (<strong>not</strong> login name) </td>
 919   </tr>
 920   <tr>
 921     <td> $rev </td>
 922     <td> actual rev number </td>
 923   </tr>
 924   <tr>
 925     <td> $comment </td>
 926     <td> WHAT COMMENT? </td>
 927   </tr>
 928 </table>
 929
 930 NOTE: if you are trying to get revision info for a topic, use `$meta->getRevisionInfo` instead if you can - it is significantly more efficient.
 931
 932 **Since:** TWiki::Plugins::VERSION 1.000 (29 Jul 2001)
 933
 934 ### <a name="get_RevisionAtTime( $web, $topic"></a> getRevisionAtTime( $web, $topic, $time ) -&gt; $rev
 935
 936 Get the revision number of a topic at a specific time.
 937
 938 - `$web` - web for topic
 939 - `$topic` - topic
 940 - `$time` - time (in epoch secs) for the rev
 941
 942 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)
 943
 944 **Since:** TWiki::Plugins::VERSION 1.1
 945
 946 ### <a name="readTopic( $web, $topic, $rev )"></a><a name="readTopic( $web, $topic, $rev ) "></a> readTopic( $web, $topic, $rev ) -&gt; ( $meta, $text )
 947
 948 Read topic text and meta data, regardless of access permissions.
 949
 950 - `$web` - Web name, required, e.g. `'Main'`
 951 - `$topic` - Topic name, required, e.g. `'TokyoOffice'`
 952 - `$rev` - revision to read (default latest)
 953
 954 Return: `( $meta, $text )` Meta data object and topic text
 955
 956 `$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.
 957
 958 This method **ignores** topic access permissions. You should be careful to use `checkAccessPermissions` to ensure the current user has read access to the topic.
 959
 960 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
 961
 962 ### <a name="read_TopicText( $web, $topic, $r"></a> readTopicText( $web, $topic, $rev, $ignorePermissions ) -&gt; $text
 963
 964 Read topic text, including meta data
 965
 966 - `$web` - Web name, e.g. `'Main'`, or empty
 967 - `$topic` - Topic name, e.g. `'MyTopic'`, or `"Main.MyTopic"`
 968 - `$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.
 969 - `$ignorePermissions` - Set to `"1"` if checkAccessPermission() is already performed and OK; an oops URL is returned if user has no permission
 970
 971 Return: `$text` Topic text with embedded meta data; an oops URL for calling redirectCgiQuery() is returned in case of an error
 972
 973 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.
 974
 975 **Since:** TWiki::Plugins::VERSION 1.010 (31 Dec 2002)
 976
 977 ### <a name="attachmentExists( $web, $topic,"></a><a name="attachmentExists( $web, $topic, "></a> attachmentExists( $web, $topic, $attachment ) -&gt; $boolean
 978
 979 Test if attachment exists
 980
 981 - `$web` - Web name, optional, e.g. `Main`.
 982 - `$topic` - Topic name, required, e.g. `TokyoOffice`, or `Main.TokyoOffice`
 983 - `$attachment` - attachment name, e.g.=logo.gif=
 984
 985 $web and $topic are parsed as described in the documentation for `normalizeWebTopicName`.
 986
 987 **Since:** TWiki::Plugins::VERSION 1.1
 988
 989 ### <a name="readAttachment( $web, $topic, $n"></a> readAttachment( $web, $topic, $name, $rev ) -&gt; $data
 990
 991 - `$web` - web for topic
 992 - `$topic` - topic
 993 - `$name` - attachment name
 994 - `$rev` - revision to read (default latest)
 995
 996 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.
 997
 998 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.
 999
1000     my( $meta, $text ) = TWiki::Func::readTopic( $web, $topic );
1001     my @attachments = $meta->find( 'FILEATTACHMENT' );
1002     foreach my $a ( @attachments ) {
1003        try {
1004            my $data = TWiki::Func::readAttachment( $web, $topic, $a->{name} );
1005            ...
1006        } catch TWiki::AccessControlException with {
1007        };
1008     }
1009
1010 **Since:** TWiki::Plugins::VERSION 1.1
1011
1012 ### <a name="saveAttachment( $web, $topic, $a"></a> saveAttachment( $web, $topic, $attachment, $opts )
1013
1014 - `$web` - web for topic
1015 - `$topic` - topic to atach to
1016 - `$attachment` - name of the attachment
1017 - `$opts` - Ref to hash of options
1018
1019 `$opts` may include:
1020
1021 <table border="1" cellpadding="0" cellspacing="0">
1022   <tr>
1023     <td><code>dontlog</code></td>
1024     <td> don't log this change in twiki log </td>
1025   </tr>
1026   <tr>
1027     <td><code>comment</code></td>
1028     <td> comment for save </td>
1029   </tr>
1030   <tr>
1031     <td><code>hide</code></td>
1032     <td> if the attachment is to be hidden in normal topic view </td>
1033   </tr>
1034   <tr>
1035     <td><code>stream</code></td>
1036     <td> Stream of file to upload </td>
1037   </tr>
1038   <tr>
1039     <td><code>file</code></td>
1040     <td> Name of a file to use for the attachment data. ignored if stream is set. Local file on the server. </td>
1041   </tr>
1042   <tr>
1043     <td><code>filepath</code></td>
1044     <td> Client path to file </td>
1045   </tr>
1046   <tr>
1047     <td><code>filesize</code></td>
1048     <td> Size of uploaded data </td>
1049   </tr>
1050   <tr>
1051     <td><code>filedate</code></td>
1052     <td> Date </td>
1053   </tr>
1054 </table>
1055
1056 Save an attachment to the store for a topic. On success, returns undef. If there is an error, an exception will be thrown.
1057
1058         try {
1059             TWiki::Func::saveAttachment( $web, $topic, 'image.gif',
1060                                          { file => 'image.gif',
1061                                            comment => 'Picture of Health',
1062                                            hide => 1 } );
1063        } catch Error::Simple with {
1064           # see documentation on Error
1065        } otherwise {
1066           ...
1067        };
1068
1069 **Since:** TWiki::Plugins::VERSION 1.1
1070
1071 ### <a name="moveAttachment( $web, $topic, $a"></a> moveAttachment( $web, $topic, $attachment, $newWeb, $newTopic, $newAttachment )
1072
1073 - `$web` source web - required
1074 - `$topic` source topic - required
1075 - `$attachment` source attachment - required
1076 - `$newWeb` dest web
1077 - `$newTopic` dest topic
1078 - `$newAttachment` dest attachment
1079
1080 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.
1081
1082 The destination topic must already exist, but the destination attachment must **not** exist.
1083
1084 Rename an attachment to $TWiki::cfg\{TrashWebName\}.TrashAttament to delete it.
1085
1086     use Error qw( :try );
1087
1088     try {
1089        # move attachment between topics
1090        moveAttachment( "Countries", "Germany", "AlsaceLorraine.dat",
1091                          "Countries", "France" );
1092        # Note destination attachment name is defaulted to the same as source
1093     } catch TWiki::AccessControlException with {
1094        my $e = shift;
1095        # see documentation on TWiki::AccessControlException
1096     } catch Error::Simple with {
1097        my $e = shift;
1098        # see documentation on Error::Simple
1099     };
1100
1101 **Since:** TWiki::Plugins::VERSION 1.1
1102
1103 ## <a name="Assembling Pages"></a> Assembling Pages
1104
1105 ### <a name="readTemplate( $name, $skin ) - $"></a> readTemplate( $name, $skin ) -&gt; $text
1106
1107 Read a template or skin. Embedded [[template directives|SYSTEMWEB/TWikiTemplates]] get expanded
1108
1109 - `$name` - Template name, e.g. `'view'`
1110 - `$skin` - Comma-separated list of skin names, optional, e.g. `'print'`
1111
1112 Return: `$text` Template text
1113
1114 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
1115
1116 ### <a name="loadTemplate ( $name, $skin, $we"></a> loadTemplate ( $name, $skin, $web ) -&gt; $text
1117
1118 - `$name` - template file name
1119 - `$skin` - comma-separated list of skins to use (default: current skin)
1120 - `$web` - the web to look in for topics that contain templates (default: current web)
1121
1122 Return: expanded template text (what's left after removal of all %TMPL:DEF% statements)
1123
1124 **Since:** TWiki::Plugins::VERSION 1.1
1125
1126 Reads a template and extracts template definitions, adding them to the list of loaded templates, overwriting any previous definition.
1127
1128 How TWiki searches for templates is described in [[TWikiTemplates]].
1129
1130 If template text is found, extracts include statements and fully expands them.
1131
1132 ### <a name="expandTemplate( $def  ) - $strin"></a> expandTemplate( $def ) -&gt; $string
1133
1134 Do a , only expanding the template (not expanding any variables other than %TMPL)
1135
1136 - `$def` - template name
1137
1138 Return: the text of the expanded template
1139
1140 **Since:** TWiki::Plugins::VERSION 1.1
1141
1142 A template is defined using a %TMPL:DEF% statement in a template file. See the documentation on TWiki templates for more information.
1143
1144 ### <a name="writeHeader( $query, $contentLen"></a> writeHeader( $query, $contentLength )
1145
1146 Prints a basic content-type HTML header for text/html to standard out
1147
1148 - `$query` - CGI query object. If not given, the default CGI query will be used (optional, in most cases you should _not_ pass this parameter)
1149 - `$contentLength` - Length of content (optional, in most cases you should _not_ pass this parameter)
1150
1151 Return: none
1152
1153 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
1154
1155 ### <a name="redirect_CgiQuery( $query, $url,"></a> redirectCgiQuery( $query, $url, $passthru )
1156
1157 Redirect to URL
1158
1159 - `$query` - CGI query object. Ignored, only there for compatibility. The session CGI query object is used instead.
1160 - `$url` - URL to redirect to
1161 - `$passthru` - enable passthrough.
1162
1163 Return: none
1164
1165 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.
1166
1167 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.
1168
1169 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.
1170
1171     my $query = TWiki::Func::getCgiQuery();
1172     $query->param(-name => 'text', -value => 'Different text');
1173     TWiki::Func::redirectCgiQuery(
1174       undef, TWiki::Func::getScriptUrl($web, $topic, 'edit'), 1);
1175
1176 `$passthru` does nothing if `$url` does not point to a script in the current TWiki installation.
1177
1178 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
1179
1180 ### <a name="add_ToHEAD( $id, $header )"></a> addToHEAD( $id, $header )
1181
1182 Adds `$header` to the HTML header (the
1183
1184 tag). This is useful for Plugins that want to include some javascript custom css.
1185
1186 - `$id` - Unique ID to prevent the same HTML from being duplicated. Plugins should use a prefix to prevent name clashes (e.g EDITTABLEPLUGIN\_JSCALENDAR)
1187 - `$header` - the HTML to be added to the
1188
1189 section. The HTML must be valid in a HEAD tag - no checks are performed.
1190
1191 All TWiki variables present in `$header` will be expanded before being inserted into the ``
1192
1193 section.
1194
1195 Note that this is _not_ the same as the HTTP header, which is modified through the Plugins `modifyHeaderHandler`.
1196
1197 **Since:** TWiki::Plugins::VERSION 1.1
1198
1199 example:
1200
1201     TWiki::Func::addToHEAD('PATTERN_STYLE','<link id="twikiLayoutCss" rel="stylesheet" type="text/css" href="%PUBURL%/TWiki/PatternSkin/layout.css" media="all" />')
1202
1203 ### <a name="expand_CommonVariables( $text, $"></a> expandCommonVariables( $text, $topic, $web, $meta ) -&gt; $text
1204
1205 Expand all common `%VARIABLES%`
1206
1207 - `$text` - Text with variables to expand, e.g. `'Current user is %WIKIUSER%'`
1208 - `$topic` - Current topic name, e.g. `'WebNotify'`
1209 - `$web` - Web name, optional, e.g. `'Main'`. The current web is taken if missing
1210 - `$meta` - topic meta-data to use while expanding (Since TWiki::Plugins::VERSION 1.2)
1211
1212 Return: `$text` Expanded text, e.g. `'Current user is TWikiGuest'`
1213
1214 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
1215
1216 See also: expandVariablesOnTopicCreation
1217
1218 ### <a name="renderText( $text, $web ) - $tex"></a> renderText( $text, $web ) -&gt; $text
1219
1220 Render text from TWiki markup into XHTML as defined in [[%SYSTEMWEB%.TextFormattingRules|SYSTEMWEB/TextFormattingRules]]
1221
1222 - `$text` - Text to render, e.g. `'*bold* text and =fixed font='`
1223 - `$web` - Web name, optional, e.g. `'Main'`. The current web is taken if missing
1224
1225 Return: `$text` XHTML text, e.g. `'<b>bold</b> and <code>fixed font</code>'`
1226
1227 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
1228
1229 ### <a name="internalLink( $pre, $web, $topic"></a> internalLink( $pre, $web, $topic, $label, $anchor, $createLink ) -&gt; $text
1230
1231 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()`
1232
1233 - `$pre` - Text occuring before the TWiki link syntax, optional
1234 - `$web` - Web name, required, e.g. `'Main'`
1235 - `$topic` - Topic name to link to, required, e.g. `'WebNotify'`
1236 - `$label` - Link label, required. Usually the same as `$topic`, e.g. `'notify'`
1237 - `$anchor` - Anchor, optional, e.g. `'#Jump'`
1238 - `$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
1239
1240 Return: `$text` XHTML anchor, e.g. `'<a href='/cgi-bin/view/Main/WebNotify#Jump'>notify</a>'`
1241
1242 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
1243
1244 ## <a name="E-mail"></a> E-mail
1245
1246 ### <a name="sendEmail ( $text, $retries ) -"></a><a name="sendEmail ( $text, $retries ) - "></a> sendEmail ( $text, $retries ) -&gt; $error
1247
1248 - `$text` - text of the mail, including MIME headers
1249 - `$retries` - number of times to retry the send (default 1)
1250
1251 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:
1252
1253     To: liz@windsor.gov.uk
1254     From: serf@hovel.net
1255     CC: george@whitehouse.gov
1256     Subject: Revolution
1257
1258     Dear Liz,
1259
1260     Please abolish the monarchy (with King George's permission, of course)
1261
1262     Thanks,
1263
1264     A. Peasant
1265
1266 Leave a blank line between the last header field and the message body.
1267
1268 **Since:** TWiki::Plugins::VERSION 1.1
1269
1270 ### <a name="wiki_ToEmail( $wikiName ) - $ema"></a> wikiToEmail( $wikiName ) -&gt; $email
1271
1272 - `$wikiname` - wiki name of the user
1273
1274 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.
1275
1276 **Since:** TWiki::Plugins::VERSION 1.1
1277
1278 **Deprecated** in favour of wikinameToEmails, because this function only returns a single email address, where a user may in fact have several.
1279
1280 Since TWiki 4.2.1, $wikiName may also be a login name.
1281
1282 ## <a name="Creating New Topics"></a> Creating New Topics
1283
1284 ### <a name="expand_VariablesOnTopicCreation"></a><a name="expand_VariablesOnTopicCreation "></a> expandVariablesOnTopicCreation ( $text ) -&gt; $text
1285
1286 Expand the limited set of variables that are always expanded during topic creation
1287
1288 - `$text` - the text to process
1289
1290 Return: text with variables expanded
1291
1292 **Since:** TWiki::Plugins::VERSION 1.1
1293
1294 Expands only the variables expected in templates that must be statically expanded in new content.
1295
1296 The expanded variables are:
1297
1298 - `%DATE%` Signature-format date
1299 - `%SERVERTIME%` See [[TWikiVariables]]
1300 - `%GMTIME%` See [[TWikiVariables]]
1301 - `%USERNAME%` Base login name
1302 - `%WIKINAME%` Wiki name
1303 - `%WIKIUSERNAME%` Wiki name with prepended web
1304 - `%URLPARAM{...}%` - Parameters to the current CGI query
1305 - `%NOP%` No-op
1306
1307 See also: expandVariables
1308
1309 ## <a name="Special handlers"></a> Special handlers
1310
1311 Special handlers can be defined to make functions in plugins behave as if they were built-in to TWiki.
1312
1313 ### <a name="register_TagHandler( $var, \fn,"></a><a name="register_TagHandler( $var, \fn, "></a> registerTagHandler( $var, \\&amp;fn, $syntax )
1314
1315 Should only be called from initPlugin.
1316
1317 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`.
1318
1319 - `$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.
1320 - `\&fn` - Reference to the handler function.
1321 - `$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"\}%
1322
1323 **Since:** TWiki::Plugins::VERSION 1.1
1324
1325 The variable handler function must be of the form:
1326
1327     sub handler(\%session, \%params, $topic, $web)
1328
1329 where:
1330
1331 - `\%session` - a reference to the TWiki session object (may be ignored)
1332 - `\%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.
1333 - `$topic` - name of the topic in the query
1334 - `$web` - name of the web in the query
1335
1336 for example, to execute an arbitrary command on the server, you might do this:
1337
1338     sub initPlugin{
1339        TWiki::Func::registerTagHandler('EXEC', \&boo);
1340     }
1341
1342     sub boo {
1343         my( $session, $params, $topic, $web ) = @_;
1344         my $cmd = $params->{_DEFAULT};
1345
1346         return "NO COMMAND SPECIFIED" unless $cmd;
1347
1348         my $result = `$cmd 2>&1`;
1349         return $params->{silent} ? '' : $result;
1350     }
1351     }
1352
1353 would let you do this: `%EXEC{"ps -Af" silent="on"}%`
1354
1355 Registered tags differ from tags implemented using the old TWiki approach (text substitution in `commonTagsHandler`) in the following ways:
1356
1357 - 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).
1358 - registered tag names can only contain alphanumerics and \_ (underscore)
1359 - registering a tag `FRED` defines both `%FRED{...}%` **and also** `%FRED%`.
1360 - registered tag handlers **cannot** return another tag as their only result (e.g. `return '%SERVERTIME%';`). It won't work.
1361
1362 ### <a name="registerRESTHandler( $alias, \fn"></a> registerRESTHandler( $alias, \\&amp;fn, )
1363
1364 Should only be called from initPlugin.
1365
1366 Adds a function to the dispatch table of the REST interface
1367
1368 - `$alias` - The name .
1369 - `\&fn` - Reference to the function.
1370
1371 **Since:** TWiki::Plugins::VERSION 1.1
1372
1373 The handler function must be of the form:
1374
1375     sub handler(\%session)
1376
1377 where:
1378
1379 - `\%session` - a reference to the TWiki session object (may be ignored)
1380
1381 From the REST interface, the name of the plugin must be used as the subject of the invokation.
1382
1383 Example
1384
1385 ----
1386
1387 The [[EmptyPlugin]] has the following call in the initPlugin handler:
1388
1389        TWiki::Func::registerRESTHandler('example', \&restExample);
1390
1391 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
1392
1393 `http://server:port/bin/rest/EmptyPlugin/example`
1394
1395 note that the URL
1396
1397 `http://server:port/bin/rest/EmptyPlugin/restExample`
1398
1399 (ie, with the name of the function instead of the alias) will not work.
1400
1401 ### <a name="decode_FormatTokens($str) - $une"></a> decodeFormatTokens($str) -&gt; $unencodedString
1402
1403 TWiki has an informal standard set of tokens used in `format` parameters that are used to block evaluation of paramater strings. For example, if you were to write
1404
1405 `%MYTAG{format="%WURBLE%"}%`
1406
1407 then %WURBLE would be expanded **before** %MYTAG is evaluated. To avoid this TWiki uses escapes in the format string. For example:
1408
1409 `%MYTAG{format="$percntWURBLE$percnt"}%`
1410
1411 This lets you enter arbitrary strings into parameters without worrying that TWiki will expand them before your plugin gets a chance to deal with them properly. Once you have processed your tag, you will want to expand these tokens to their proper value. That's what this function does.
1412
1413 <table border="1" cellpadding="0" cellspacing="0">
1414   <tr>
1415     <th bgcolor="#99CCCC"><strong> Escape: </strong></th>
1416     <th bgcolor="#99CCCC"><strong> Expands To: </strong></th>
1417   </tr>
1418   <tr>
1419     <td><code>$n</code> or <code>$n()</code></td>
1420     <td> New line. Use <code>$n()</code> if followed by alphanumeric character, e.g. write <code>Foo$n()Bar</code> instead of <code>Foo$nBar</code></td>
1421   </tr>
1422   <tr>
1423     <td><code>$nop</code> or <code>$nop()</code></td>
1424     <td> Is a "no operation". </td>
1425   </tr>
1426   <tr>
1427     <td><code>$quot</code></td>
1428     <td> Double quote (<code>"</code>) </td>
1429   </tr>
1430   <tr>
1431     <td><code>$percnt</code></td>
1432     <td> Percent sign (<code>%</code>) </td>
1433   </tr>
1434   <tr>
1435     <td><code>$dollar</code></td>
1436     <td> Dollar sign (<code>$</code>) </td>
1437   </tr>
1438 </table>
1439
1440 Note thath $quot, $percnt and $dollar all work \*even if they are followed by alphanumeric characters\*. You have been warned!
1441
1442 **Since:** TWiki::Plugins::VERSION 1.2
1443
1444 ## <a name="Searching"></a> Searching
1445
1446 ### <a name="search_InWebContent($searchStrin"></a> searchInWebContent($searchString, $web, \\@topics, \\%options ) -&gt; \\%map
1447
1448 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+\{.\*\}%)
1449
1450 - `$searchString` - the search string, in egrep format
1451 - `$web` - The web to search in
1452 - `\@topics` - reference to a list of topics to search
1453 - `\%option` - reference to an options hash
1454
1455 The `\%options` hash may contain the following options:
1456
1457 - `type` - if `regex` will perform a egrep-syntax RE search (default '')
1458 - `casesensitive` - false to ignore case (defaulkt true)
1459 - `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).
1460
1461 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'.
1462
1463 To iterate over the returned topics use:
1464
1465     my $result = TWiki::Func::searchInWebContent( "Slimy Toad", $web, \@topics,
1466        { casesensitive => 0, files_without_match => 0 } );
1467     foreach my $topic (keys %$result ) {
1468        foreach my $matching_line ( @{$result->{$topic}} ) {
1469           ...etc
1470
1471 **Since:** TWiki::Plugins::VERSION 1.1
1472
1473 ## <a name="Plugin-specific file handling"></a> Plugin-specific file handling
1474
1475 ### <a name="get_WorkArea( $pluginName ) - $d"></a> getWorkArea( $pluginName ) -&gt; $directorypath
1476
1477 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.
1478
1479 The directory is guaranteed to exist, and to be writable by the webserver user. By default it will **not** be web accessible.
1480
1481 The directory and it's contents are permanent, so Plugins must be careful to keep their areas tidy.
1482
1483 **Since:** TWiki::Plugins::VERSION 1.1 (Dec 2005)
1484
1485 ### <a name="readFile( $filename ) - $text"></a> readFile( $filename ) -&gt; $text
1486
1487 Read file, low level. Used for Plugin workarea.
1488
1489 - `$filename` - Full path name of file
1490
1491 Return: `$text` Content of file, empty if not found
1492
1493 **_NOTE:_** Use this function only for the Plugin workarea, **not** for topics and attachments. Use the appropriate functions to manipulate topics and attachments.
1494
1495 **Since:** TWiki::Plugins::VERSION 1.000 (07 Dec 2002)
1496
1497 ### <a name="saveFile( $filename, $text )"></a> saveFile( $filename, $text )
1498
1499 Save file, low level. Used for Plugin workarea.
1500
1501 - `$filename` - Full path name of file
1502 - `$text` - Text to save
1503
1504 Return: none
1505
1506 **_NOTE:_** Use this function only for the Plugin workarea, **not** for topics and attachments. Use the appropriate functions to manipulate topics and attachments.
1507
1508 **Since:** TWiki::Plugins::VERSION 1.000 (07 Dec 2002)
1509
1510 ## <a name="General Utilities"></a> General Utilities
1511
1512 ### <a name="get_RegularExpression( $name ) -"></a> getRegularExpression( $name ) -&gt; $expr
1513
1514 Retrieves a TWiki predefined regular expression or character class.
1515
1516 - `$name` - Name of the expression to retrieve. See notes below
1517
1518 Return: String or precompiled regular expression matching as described below.
1519
1520 **Since:** TWiki::Plugins::VERSION 1.020 (9 Feb 2004)
1521
1522 **_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.
1523
1524 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:
1525
1526        my $upper = TWiki::Func::getRegularExpression('upperAlpha');
1527        my $alpha = TWiki::Func::getRegularExpression('mixedAlpha');
1528        my $capitalized = qr/[$upper][$alpha]+/;
1529
1530 Those expressions marked type 'RE' are precompiled regular expressions that can be used outside square brackets. For example:
1531
1532        my $webRE = TWiki::Func::getRegularExpression('webNameRegex');
1533        my $isWebName = ( $s =~ m/$webRE/ );
1534
1535 <table border="1" cellpadding="0" cellspacing="0">
1536   <tr>
1537     <th bgcolor="#99CCCC"><strong> Name </strong></th>
1538     <th bgcolor="#99CCCC"><strong> Matches </strong></th>
1539     <th bgcolor="#99CCCC"><strong> Type </strong></th>
1540   </tr>
1541   <tr>
1542     <td> upperAlpha </td>
1543     <td> Upper case characters </td>
1544     <td> String </td>
1545   </tr>
1546   <tr>
1547     <td> upperAlphaNum </td>
1548     <td> Upper case characters and digits </td>
1549     <td> String </td>
1550   </tr>
1551   <tr>
1552     <td> lowerAlpha </td>
1553     <td> Lower case characters </td>
1554     <td> String </td>
1555   </tr>
1556   <tr>
1557     <td> lowerAlphaNum </td>
1558     <td> Lower case characters and digits </td>
1559     <td> String </td>
1560   </tr>
1561   <tr>
1562     <td> numeric </td>
1563     <td> Digits </td>
1564     <td> String </td>
1565   </tr>
1566   <tr>
1567     <td> mixedAlpha </td>
1568     <td> Alphabetic characters </td>
1569     <td> String </td>
1570   </tr>
1571   <tr>
1572     <td> mixedAlphaNum </td>
1573     <td> Alphanumeric characters </td>
1574     <td> String </td>
1575   </tr>
1576   <tr>
1577     <td> wikiWordRegex </td>
1578     <td>[[Main/WikiWords]]</td>
1579     <td> RE </td>
1580   </tr>
1581   <tr>
1582     <td> webNameRegex </td>
1583     <td> User web names </td>
1584     <td> RE </td>
1585   </tr>
1586   <tr>
1587     <td> anchorRegex </td>
1588     <td> #AnchorNames </td>
1589     <td> RE </td>
1590   </tr>
1591   <tr>
1592     <td> abbrevRegex </td>
1593     <td> Abbreviations e.g. GOV, IRS </td>
1594     <td> RE </td>
1595   </tr>
1596   <tr>
1597     <td> emailAddrRegex </td>
1598     <td><a href="mailto:email@address.com">email@address.com</a></td>
1599     <td> RE </td>
1600   </tr>
1601   <tr>
1602     <td> tagNameRegex </td>
1603     <td> Standard variable names e.g. %THIS_BIT% (THIS_BIT only) </td>
1604     <td> RE </td>
1605   </tr>
1606 </table>
1607
1608 ### <a name="normalize_WebTopicName($web, $to"></a> normalizeWebTopicName($web, $topic) -&gt; ($web, $topic)
1609
1610 Parse a web and topic name, supplying defaults as appropriate.
1611
1612 - `$web` - Web name, identifying variable, or empty string
1613 - `$topic` - Topic name, may be a web.topic string, required.
1614
1615 Return: the parsed Web/Topic pair
1616
1617 **Since:** TWiki::Plugins::VERSION 1.1
1618
1619 <table border="1" cellpadding="0" cellspacing="0">
1620   <tr>
1621     <th bgcolor="#99CCCC"><strong> Input </strong></th>
1622     <th bgcolor="#99CCCC"><strong> Return </strong></th>
1623   </tr>
1624   <tr>
1625     <td><tt>( 'Web', 'Topic' ) </tt></td>
1626     <td><tt>( 'Web', 'Topic' ) </tt></td>
1627   </tr>
1628   <tr>
1629     <td><tt>( '', 'Topic' ) </tt></td>
1630     <td><tt>( 'Main', 'Topic' ) </tt></td>
1631   </tr>
1632   <tr>
1633     <td><tt>( '', '' ) </tt></td>
1634     <td><tt>( 'Main', 'WebHome' ) </tt></td>
1635   </tr>
1636   <tr>
1637     <td><tt>( '', 'Web/Topic' ) </tt></td>
1638     <td><tt>( 'Web', 'Topic' ) </tt></td>
1639   </tr>
1640   <tr>
1641     <td><tt>( '', 'Web/Subweb/Topic' ) </tt></td>
1642     <td><tt>( 'Web/Subweb', 'Topic' ) </tt></td>
1643   </tr>
1644   <tr>
1645     <td><tt>( '', 'Web.Topic' ) </tt></td>
1646     <td><tt>( 'Web', 'Topic' ) </tt></td>
1647   </tr>
1648   <tr>
1649     <td><tt>( '', 'Web.Subweb.Topic' ) </tt></td>
1650     <td><tt>( 'Web/Subweb', 'Topic' ) </tt></td>
1651   </tr>
1652   <tr>
1653     <td><tt>( 'Web1', 'Web2.Topic' )</tt></td>
1654     <td><tt>( 'Web2', 'Topic' ) </tt></td>
1655   </tr>
1656 </table>
1657
1658 Note that hierarchical web names ([[SubWeb]]) are only available if hierarchical webs are enabled in `configure`.
1659
1660 The symbols %USERSWEB%, %SYSTEMWEB% and %DOCWEB% can be used in the input to represent the web names set in $cfg\{UsersWebName\} and $cfg\{SystemWebName\}. For example:
1661
1662 <table border="1" cellpadding="0" cellspacing="0">
1663   <tr>
1664     <th bgcolor="#99CCCC"><strong> Input </strong></th>
1665     <th bgcolor="#99CCCC"><strong> Return </strong></th>
1666   </tr>
1667   <tr>
1668     <td><tt>( '%USERSWEB%', 'Topic' )</tt></td>
1669     <td><tt>( 'Main', 'Topic' ) </tt></td>
1670   </tr>
1671   <tr>
1672     <td><tt>( '%SYSTEMWEB%', 'Topic' )</tt></td>
1673     <td><tt>( 'TWiki', 'Topic' ) </tt></td>
1674   </tr>
1675   <tr>
1676     <td><tt>( '', '%DOCWEB%.Topic' )</tt></td>
1677     <td><tt>( 'TWiki', 'Topic' ) </tt></td>
1678   </tr>
1679 </table>
1680
1681 ## <a name="StaticMethod &lt;strong&gt;sanitize_Attachmen"></a> [[StaticMethod]] \*sanitizeAttachmentName `($fname) -> ($fileName,$origName)`
1682
1683 Given a file namer, sanitise it according to the rules for transforming attachment names. Returns the sanitised name together with the basename before sanitisation.
1684
1685 Sanitation includes filtering illegal characters and mapping client file names to legal server names.
1686
1687 **Since:** TWiki::Plugins::VERSION 1.2
1688
1689 ### <a name="space_OutWikiWord( $word, $sep )"></a> spaceOutWikiWord( $word, $sep ) -&gt; $text
1690
1691 Spaces out a wiki word by inserting a string (default: one space) between each word component. With parameter $sep any string may be used as separator between the word components; if $sep is undefined it defaults to a space.
1692
1693 **Since:** TWiki::Plugins::VERSION 1.2
1694
1695 ### <a name="writeWarning( $text )"></a> writeWarning( $text )
1696
1697 Log Warning that may require admin intervention to data/warning.txt
1698
1699 - `$text` - Text to write; timestamp gets added
1700
1701 Return: none
1702
1703 **Since:** TWiki::Plugins::VERSION 1.020 (16 Feb 2004)
1704
1705 ### <a name="writeDebug( $text )"></a> writeDebug( $text )
1706
1707 Log debug message to data/debug.txt
1708
1709 - `$text` - Text to write; timestamp gets added
1710
1711 Return: none
1712
1713 **Since:** TWiki::Plugins::VERSION 1.020 (16 Feb 2004)
1714
1715 ### <a name="formatTime( $time, $format, $tim"></a> formatTime( $time, $format, $timezone ) -&gt; $text
1716
1717 Format the time in seconds into the desired time string
1718
1719 - `$time` - Time in epoc seconds
1720 - `$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
1721 - `$timezone` - either not defined (uses the displaytime setting), 'gmtime', or 'servertime'
1722
1723 Return: `$text` Formatted time string
1724
1725 <table border="1" cellpadding="0" cellspacing="0">
1726   <tr>
1727     <td> Note: </td>
1728     <td> if you used the removed formatGmTime, add a third parameter 'gmtime' </td>
1729   </tr>
1730 </table>
1731
1732 **Since:** TWiki::Plugins::VERSION 1.020 (26 Feb 2004)
1733
1734 ### <a name="isTrue( $value, $default ) - $bo"></a> isTrue( $value, $default ) -&gt; $boolean
1735
1736 Returns 1 if `$value` is true, and 0 otherwise. "true" means set to something with a Perl true value, with the special cases that "off", "false" and "no" (case insensitive) are forced to false. Leading and trailing spaces in `$value` are ignored.
1737
1738 If the value is undef, then `$default` is returned. If `$default` is not specified it is taken as 0.
1739
1740 **Since:** $TWiki::Plugins::VERSION 1.2
1741
1742 ### <a name="is_ValidWikiWord ( $text ) - $bo"></a> isValidWikiWord ( $text ) -&gt; $boolean
1743
1744 Check for a valid [[WikiWord]] or [[WikiName]]
1745
1746 - `$text` - Word to test
1747
1748 **Since:** TWiki::Plugins::VERSION 1.100 (Dec 2005)
1749
1750 ### <a name="extractParameters($attr ) - %par"></a> extractParameters($attr ) -&gt; %params
1751
1752 Extract all parameters from a variable string and returns a hash of parameters
1753
1754 - `$attr` - Attribute string
1755
1756 Return: `%params` Hash containing all parameters. The nameless parameter is stored in key `_DEFAULT`
1757
1758 **Since:** TWiki::Plugins::VERSION 1.025 (26 Aug 2004)
1759
1760 - Example:
1761   - Variable: `%TEST{ 'nameless' name1="val1" name2="val2" }%`
1762   - First extract text between `{...}` to get: `'nameless' name1="val1" name2="val2"`
1763   - Then call this on the text: <br />
1764 - params = TWiki::Func::extractParameters( $text );=
1765   - The `%params` hash contains now: <br />`_DEFAULT => 'nameless'`<br />`name1 => "val1"`<br />`name2 => "val2"`
1766
1767 ### <a name="extract_NameValuePair( $attr, $n"></a> extractNameValuePair( $attr, $name ) -&gt; $value
1768
1769 Extract a named or unnamed value from a variable parameter string - Note: | Function TWiki::Func::extractParameters is more efficient for extracting several parameters
1770
1771 - `$attr` - Attribute string
1772 - `$name` - Name, optional
1773
1774 Return: `$value` Extracted value
1775
1776 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
1777
1778 - Example:
1779   - Variable: `%TEST{ 'nameless' name1="val1" name2="val2" }%`
1780   - First extract text between `{...}` to get: `'nameless' name1="val1" name2="val2"`
1781   - 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" );`
1782
1783 ## <a name="Deprecated functions"></a> Deprecated functions
1784
1785 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.
1786
1787 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%.
1788
1789 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:
1790
1791     package TWiki::Plugins::SinkPlugin;
1792     use vars qw( %TWikiCompatibility );
1793     $TWikiCompatibility{endRenderingHandler} = 1.1;
1794
1795 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.
1796
1797 The following functions are retained for compatibility only. You should stop using them as soon as possible.
1798
1799 ### <a name="get_ScriptUrlPath( ) - $path"></a> getScriptUrlPath( ) -&gt; $path
1800
1801 Get script URL path
1802
1803 **DEPRECATED** since 1.1 - use `getScriptUrl` instead.
1804
1805 Return: `$path` URL path of TWiki scripts, e.g. `"/cgi-bin"`
1806
1807 **WARNING:** you are strongly recommended **not** to use this function, as the \{ScriptUrlPaths\} URL rewriting rules will not apply to urls generated using it.
1808
1809 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
1810
1811 ### <a name="get_OopsUrl( $web, $topic, $temp"></a> getOopsUrl( $web, $topic, $template, $param1, $param2, $param3, $param4 ) -&gt; $url
1812
1813 Compose fully qualified 'oops' dialog URL
1814
1815 - `$web` - Web name, e.g. `'Main'`. The current web is taken if empty
1816 - `$topic` - Topic name, e.g. `'WebNotify'`
1817 - `$template` - Oops template name, e.g. `'oopsmistake'`. The 'oops' is optional; 'mistake' will translate to 'oopsmistake'.
1818 - `$param1` ... `$param4` - Parameter values for %PARAM1% ... %PARAMn% variables in template, optional
1819
1820 Return: `$url` URL, e.g. `"http://example.com:80/cgi-bin/oops.pl/ Main/WebNotify?template=oopslocked&param1=joe"`
1821
1822 **DEPRECATED** since 1.1, the recommended approach is to throw an [[oops exception|Main/TWikiOopsExceptionDotPm]].
1823
1824        use Error qw( :try );
1825
1826        throw TWiki::OopsException(
1827           'toestuckerror',
1828           web => $web,
1829           topic => $topic,
1830           params => [ 'I got my toe stuck' ]);
1831
1832 (this example will use the `oopstoestuckerror` template.)
1833
1834 If this is not possible (e.g. in a REST handler that does not trap the exception) then you can use `getScriptUrl` instead:
1835
1836        my $url = TWiki::Func::getScriptUrl($web, $topic, 'oops',
1837                 template => 'oopstoestuckerror',
1838                 param1 => 'I got my toe stuck');
1839        TWiki::Func::redirectCgiQuery( undef, $url );
1840        return 0;
1841
1842 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
1843
1844 ### <a name="permissionsSet( $web ) - $boolea"></a> permissionsSet( $web ) -&gt; $boolean
1845
1846 Test if any access restrictions are set for this web, ignoring settings on individual pages
1847
1848 - `$web` - Web name, required, e.g. `'Sandbox'`
1849
1850 **Since:** TWiki::Plugins::VERSION 1.000 (27 Feb 2001)
1851
1852 **DEPRECATED** since 1.2 - use `getPreferencesValue` instead to determine what permissions are set on the web, for example:
1853
1854     foreach my $type qw( ALLOW DENY ) {
1855         foreach my $action qw( CHANGE VIEW ) {
1856             my $pref = $type . 'WEB' . $action;
1857             my $val = getPreferencesValue( $pref, $web ) || '';
1858             if( $val =~ /\S/ ) {
1859                 print "$pref is set to $val on $web\n";
1860             }
1861         }
1862     }
1863
1864 ### <a name="get_PublicWebList( ) - @webs"></a> getPublicWebList( ) -&gt; @webs
1865
1866 **DEPRECATED** since 1.1 - use `getListOfWebs` instead.
1867
1868 Get list of all public webs, e.g. all webs that do not have the `NOSEARCHALL` flag set in the [[WebPreferences]]
1869
1870 Return: `@webs` List of all public webs, e.g. `( 'Main',  'Know', 'TWiki' )`
1871
1872 **Since:** TWiki::Plugins::VERSION 1.000 (07 Dec 2002)
1873
1874 ### <a name="format_GmTime( $time, $format )"></a><a name="format_GmTime( $time, $format ) "></a> formatGmTime( $time, $format ) -&gt; $text
1875
1876 **DEPRECATED** since 1.1 - use `formatTime` instead.
1877
1878 Format the time to GM time
1879
1880 - `$time` - Time in epoc seconds
1881 - `$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'`)
1882
1883 Return: `$text` Formatted time string
1884
1885 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
1886
1887 ### <a name="get_DataDir( ) - $dir"></a> getDataDir( ) -&gt; $dir
1888
1889 **DEPRECATED** since 1.1 - use the "Webs, Topics and Attachments" functions to manipulate topics instead
1890
1891 Get data directory (topic file root)
1892
1893 Return: `$dir` Data directory, e.g. `'/twiki/data'`
1894
1895 This function violates store encapsulation and is therefore **deprecated**.
1896
1897 **Since:** TWiki::Plugins::VERSION 1.000 (07 Dec 2002)
1898
1899 ### <a name="get_PubDir( ) - $dir"></a> getPubDir( ) -&gt; $dir
1900
1901 **DEPRECATED** since 1.1 - use the "Webs, Topics and Attachments" functions to manipulateattachments instead
1902
1903 Get pub directory (file attachment root). Attachments are in `$dir/Web/TopicName`
1904
1905 Return: `$dir` Pub directory, e.g. `'/htdocs/twiki/pub'`
1906
1907 This function violates store encapsulation and is therefore **deprecated**.
1908
1909 Use `readAttachment` and `saveAttachment` instead.
1910
1911 **Since:** TWiki::Plugins::VERSION 1.000 (07 Dec 2002)
1912
1913 ### <a name="checkDependencies( $moduleName,"></a><a name="checkDependencies( $moduleName, "></a> checkDependencies( $moduleName, $dependenciesRef ) -&gt; $error
1914
1915 **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.
1916
1917 **Since:** TWiki::Plugins::VERSION 1.025 (01 Aug 2004)