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( $wikiName ) ->"> wikiToUserName( $wikiName ) -&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="#wiki_NameToEmails( $wikiname ) -"> wikiNameToEmails( $wikiname ) -&gt; @emails</a></li>
  64             <li><a href="#isGuest( ) -> $boolean"> isGuest( ) -&gt; $boolean</a></li>
  65             <li><a href="#is_AnAdmin( $login ) -> $boolean"> isAnAdmin( $login ) -&gt; $boolean</a></li>
  66             <li><a href="#is_GroupMember( $group, $login )"> isGroupMember( $group, $login ) -&gt; $boolean</a></li>
  67             <li><a href="#eachUser() -> $iterator"> eachUser() -&gt; $iterator</a></li>
  68             <li><a href="#eachMembership($wikiname) -> $it"> eachMembership($wikiname) -&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, $wikiName, $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%.TWikiTemplates 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 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. Additionally, other usermappings will use other conventions - the [[JoomlauserMapping]] for example, has cUIDs like 'JoomlaeUserMapping\_1234'.
 479
 480 If $user is undefined Get the cUID of logged in user, and will generally be 'BaseUserMapping\_666'
 481
 482 - $user can be a cUID, login, wikiname or web.wikiname
 483
 484 Return: `$cUID` an internal unique and transportable escaped identifier for registered users (they can 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( $wikiName ) - $"></a> wikiToUserName( $wikiName ) -&gt; $loginName
 509
 510 Translate a Wiki name (or login name or cUID, if it can) to a login name.
 511
 512 - `$wikiName` - Wiki name, e.g. `'Main.JohnDoe'` or `'JohnDoe'`
 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'`
 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="wiki_NameToEmails( $wikiname ) -"></a> wikiNameToEmails( $wikiname ) -&gt; @emails
 545
 546 - `$wikiname` - wikiname of user to look up
 547
 548 Returns the registered email addresses of the named user. If $wikiname is undef, returns the registered email addresses for the logged-in user.
 549
 550 **Since:** TWiki::Plugins::VERSION 1.2
 551
 552 ### <a name="isGuest( ) - $boolean"></a> isGuest( ) -&gt; $boolean
 553
 554 Test if logged in user is a guest ([[TWikiGuest]])
 555
 556 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
 557
 558 ### <a name="is_AnAdmin( $login ) - $boolean"></a> isAnAdmin( $login ) -&gt; $boolean
 559
 560 Find out if the user is an admin or not. If the user is not given, the currently logged-in user is assumed.
 561
 562 - $login can be either a login, or a CUID
 563
 564 **Since:** TWiki::Plugins::VERSION 1.2
 565
 566 ### <a name="is_GroupMember( $group, $login )"></a> isGroupMember( $group, $login ) -&gt; $boolean
 567
 568 Find out if $login is in the named group. e.g.
 569
 570     if( TWiki::Func::isGroupMember( "HesperionXXGroup", "jordi" )) {
 571         ...
 572     }
 573
 574 If `$user` is `undef`, it defaults to the currently logged-in user.
 575
 576 - $login can be a login name, or a cUID, or [[WikiName]]
 577
 578 **Since:** TWiki::Plugins::VERSION 1.2
 579
 580 ### <a name="eachUser() - $iterator"></a> eachUser() -&gt; $iterator
 581
 582 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').
 583
 584 Use it as follows:
 585
 586         my $iterator = TWiki::Func::eachUser();
 587         while ($it->hasNext()) {
 588             my $user = $it->next();
 589             # $user is a wikiname
 590         }
 591
 592 **WARNING** on large sites, this could be a long list!
 593
 594 **Since:** TWiki::Plugins::VERSION 1.2
 595
 596 ### <a name="eachMembership($wikiname) - $ite"></a> eachMembership($wikiname) -&gt; $iterator
 597
 598 Get an iterator over the names of all groups that the user is a member of. If `$wikiname` is `undef`, defaults to the currently logged-in user.
 599
 600 **Since:** TWiki::Plugins::VERSION 1.2
 601
 602 ### <a name="eachGroup() - $iterator"></a> eachGroup() -&gt; $iterator
 603
 604 Get an iterator over all groups.
 605
 606 Use it as follows:
 607
 608         my $iterator = TWiki::Func::eachGroup();
 609         while ($it->hasNext()) {
 610             my $group = $it->next();
 611             # $group is a group name e.g. TWikiAdminGroup
 612         }
 613
 614 **WARNING** on large sites, this could be a long list!
 615
 616 **Since:** TWiki::Plugins::VERSION 1.2
 617
 618 ### <a name="isGroup( $group ) - $boolean"></a> isGroup( $group ) -&gt; $boolean
 619
 620 Checks if `$group` is the name of a group known to TWiki.
 621
 622 ### <a name="each_GroupMember($group) - $iter"></a> eachGroupMember($group) -&gt; $iterator
 623
 624 Get an iterator over all the members of the named group. Returns undef if $group is not a valid group.
 625
 626 Use it as follows:
 627
 628         my $iterator = TWiki::Func::eachGroupMember('RadioheadGroup');
 629         while ($it->hasNext()) {
 630             my $user = $it->next();
 631             # $user is a wiki name e.g. 'TomYorke', 'PhilSelway'
 632         }
 633
 634 **WARNING** on large sites, this could be a long list!
 635
 636 **Since:** TWiki::Plugins::VERSION 1.2
 637
 638 ### <a name="check_AccessPermission( $type, $"></a> checkAccessPermission( $type, $wikiName, $text, $topic, $web, $meta ) -&gt; $boolean
 639
 640 Check access permission for a topic based on the [[%SYSTEMWEB%.TWikiAccessControl|SYSTEMWEB/TWikiAccessControl]] rules
 641
 642 - `$type` - Access type, required, e.g. `'VIEW'`, `'CHANGE'`.
 643 - `$wikiName` - [[WikiName]] of remote user, required, e.g. `"PeterThoeny"`. If `$wikiName` is '', 0 or `undef` then access is **always permitted**.
 644 - `$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:
 645   1. You are setting different access controls in the text to those defined in the stored topic,
 646   2. You already have the topic text in hand, and want to help TWiki avoid having to read it again,
 647   3. You are providing a `$meta` parameter.
 648 - `$topic` - Topic name, required, e.g. `'PrivateStuff'`
 649 - `$web` - Web name, required, e.g. `'Sandbox'`
 650 - `$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.
 651
 652 A perl true result indicates that access is permitted.
 653
 654 **Note** the wierd parameter order is due to compatibility constraints with earlier TWiki releases.
 655
 656 **Tip** if you want, you can use this method to check your own access control types. For example, if you:
 657
 658 - Set ALLOWTOPICSPIN = [[IncyWincy]]
 659
 660 in `ThatWeb.ThisTopic`, then a call to `checkAccessPermissions('SPIN', 'IncyWincy', undef, 'ThisTopic', 'ThatWeb', undef)` will return `true`.
 661
 662 **Since:** TWiki::Plugins::VERSION 1.000 (27 Feb 2001)
 663
 664 ## <a name="Webs, Topics and Attachments"></a> Webs, Topics and Attachments
 665
 666 ### <a name="get_ListOfWebs( $filter ) - @web"></a> getListOfWebs( $filter ) -&gt; @webs
 667
 668 - `$filter` - spec of web types to recover
 669
 670 Gets a list of webs, filtered according to the spec in the $filter, which may include one of:
 671
 672 1. 'user' (for only user webs)
 673 2. 'template' (for only template webs i.e. those starting with "\_")
 674
 675 `$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.
 676
 677 For example, the deprecated getPublicWebList function can be duplicated as follows:
 678
 679        my @webs = TWiki::Func::getListOfWebs( "user,public" );
 680
 681 **Since:** TWiki::Plugins::VERSION 1.1
 682
 683 ### <a name="webExists( $web ) - $boolean"></a> webExists( $web ) -&gt; $boolean
 684
 685 Test if web exists
 686
 687 - `$web` - Web name, required, e.g. `'Sandbox'`
 688
 689 **Since:** TWiki::Plugins::VERSION 1.000 (14 Jul 2001)
 690
 691 ### <a name="createWeb( $newWeb, $baseWeb, $o"></a> createWeb( $newWeb, $baseWeb, $opts )
 692
 693 - `$newWeb` is the name of the new web.
 694 - `$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.
 695 - `$opts` is a ref to a hash that contains settings to be modified in
 696
 697 the web preferences topic in the new web.
 698
 699     use Error qw( :try );
 700     use TWiki::AccessControlException;
 701
 702     try {
 703         TWiki::Func::createWeb( "Newweb" );
 704     } catch Error::Simple with {
 705         my $e = shift;
 706         # see documentation on Error::Simple
 707     } catch TWiki::AccessControlException with {
 708         my $e = shift;
 709         # see documentation on TWiki::AccessControlException
 710     } otherwise {
 711         ...
 712     };
 713
 714 **Since:** TWiki::Plugins::VERSION 1.1
 715
 716 ### <a name="moveWeb( $oldName, $newName )"></a> moveWeb( $oldName, $newName )
 717
 718 Move (rename) a web.
 719
 720     use Error qw( :try );
 721     use TWiki::AccessControlException;
 722
 723     try {
 724         TWiki::Func::moveWeb( "Oldweb", "Newweb" );
 725     } catch Error::Simple with {
 726         my $e = shift;
 727         # see documentation on Error::Simple
 728     } catch TWiki::AccessControlException with {
 729         my $e = shift;
 730         # see documentation on TWiki::AccessControlException
 731     } otherwise {
 732         ...
 733     };
 734
 735 To delete a web, move it to a subweb of `Trash`
 736
 737     TWiki::Func::moveWeb( "Deadweb", "Trash.Deadweb" );
 738
 739 **Since:** TWiki::Plugins::VERSION 1.1
 740
 741 ### <a name="each_ChangeSince($web, $time) -"></a><a name="each_ChangeSince($web, $time) - "></a> eachChangeSince($web, $time) -&gt; $iterator
 742
 743 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.
 744
 745 Use it as follows:
 746
 747         my $iterator = TWiki::Func::eachChangeSince(
 748             $web, time() - 7 * 24 * 60 * 60); # the last 7 days
 749         while ($it->hasNext()) {
 750             my $change = $it->next();
 751             # $change is a perl hash that contains the following fields:
 752             # topic => topic name
 753             # user => wikiname - wikiname of user who made the change
 754             # time => time of the change
 755             # revision => revision number *after* the change
 756             # more => more info about the change (e.g. 'minor')
 757         }
 758
 759 ### <a name="get_TopicList( $web ) - @topics"></a> getTopicList( $web ) -&gt; @topics
 760
 761 Get list of all topics in a web
 762
 763 - `$web` - Web name, required, e.g. `'Sandbox'`
 764
 765 Return: `@topics` Topic list, e.g. `( 'WebChanges',  'WebHome', 'WebIndex', 'WebNotify' )`
 766
 767 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
 768
 769 ### <a name="topicExists( $web, $topic ) - $b"></a> topicExists( $web, $topic ) -&gt; $boolean
 770
 771 Test if topic exists
 772
 773 - `$web` - Web name, optional, e.g. `'Main'`.
 774 - `$topic` - Topic name, required, e.g. `'TokyoOffice'`, or `"Main.TokyoOffice"`
 775
 776 $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.
 777
 778 **Since:** TWiki::Plugins::VERSION 1.000 (14 Jul 2001)
 779
 780 ### <a name="check_TopicEditLock( $web, $topi"></a> checkTopicEditLock( $web, $topic, $script ) -&gt; ( $oopsUrl, $loginName, $unlockTime )
 781
 782 Check if a lease has been taken by some other user.
 783
 784 - `$web` Web name, e.g. `"Main"`, or empty
 785 - `$topic` Topic name, e.g. `"MyTopic"`, or `"Main.MyTopic"`
 786
 787 Return: `( $oopsUrl, $loginName, $unlockTime )` - The `$oopsUrl` for calling redirectCgiQuery(), user's `$loginName`, and estimated `$unlockTime` in minutes, or ( '', '', 0 ) if no lease exists.
 788
 789 - `$script` The script to invoke when continuing with the edit
 790
 791 **Since:** TWiki::Plugins::VERSION 1.010 (31 Dec 2002)
 792
 793 ### <a name="set_TopicEditLock( $web, $topic,"></a> setTopicEditLock( $web, $topic, $lock )
 794
 795 - `$web` Web name, e.g. `"Main"`, or empty
 796 - `$topic` Topic name, e.g. `"MyTopic"`, or `"Main.MyTopic"`
 797 - `$lock` 1 to lease the topic, 0 to clear an existing lease
 798
 799 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.
 800
 801 It is **impossible** to fully lock a topic. Concurrent changes will be merged.
 802
 803 **Since:** TWiki::Plugins::VERSION 1.010 (31 Dec 2002)
 804
 805 ### <a name="saveTopic( $web, $topic, $meta,"></a><a name="saveTopic( $web, $topic, $meta, "></a> saveTopic( $web, $topic, $meta, $text, $options ) -&gt; $error
 806
 807 - `$web` - web for the topic
 808 - `$topic` - topic name
 809 - `$meta` - reference to TWiki::Meta object
 810 - `$text` - text of the topic (without embedded meta-data!!!
 811 - `\%options` - ref to hash of save options `\%options` may include: <table border="1" cellpadding="0" cellspacing="0">
 812   <tr>
 813     <td><code>dontlog</code></td>
 814     <td> don't log this change in twiki log </td>
 815   </tr>
 816   <tr>
 817     <td><code>comment</code></td>
 818     <td> comment for save </td>
 819   </tr>
 820   <tr>
 821     <td><code>minor</code></td>
 822     <td> True if this is a minor change, and is not to be notified </td>
 823   </tr>
 824 </table>
 825
 826 Return: error message or undef.
 827
 828 **Since:** TWiki::Plugins::VERSION 1.000 (29 Jul 2001)
 829
 830 For example,
 831
 832     my( $meta, $text ) = TWiki::Func::readTopic( $web, $topic )
 833     $text =~ s/APPLE/ORANGE/g;
 834     TWiki::Func::saveTopic( $web, $topic, $meta, $text, { comment => 'refruited' } );
 835
 836 **_Note:_** Plugins handlers ( e.g. `beforeSaveHandler` ) will be called as appropriate.
 837
 838 ### <a name="save_TopicText( $web, $topic, $t"></a> saveTopicText( $web, $topic, $text, $ignorePermissions, $dontNotify ) -&gt; $oopsUrl
 839
 840 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.
 841
 842 - `$web` - Web name, e.g. `'Main'`, or empty
 843 - `$topic` - Topic name, e.g. `'MyTopic'`, or `"Main.MyTopic"`
 844 - `$text` - Topic text to save, assumed to include meta data
 845 - `$ignorePermissions` - Set to `"1"` if checkAccessPermission() is already performed and OK
 846 - `$dontNotify` - Set to `"1"` if not to notify users of the change
 847
 848 Return: `$oopsUrl` Empty string if OK; the `$oopsUrl` for calling redirectCgiQuery() in case of error
 849
 850 This method is a lot less efficient and much more dangerous than `saveTopic`.
 851
 852 **Since:** TWiki::Plugins::VERSION 1.010 (31 Dec 2002)
 853
 854     my $text = TWiki::Func::readTopicText( $web, $topic );
 855
 856     # check for oops URL in case of error:
 857     if( $text =~ /^http.*?\/oops/ ) {
 858         TWiki::Func::redirectCgiQuery( $query, $text );
 859         return;
 860     }
 861     # do topic text manipulation like:
 862     $text =~ s/old/new/g;
 863     # do meta data manipulation like:
 864     $text =~ s/(META\:FIELD.*?name\=\"TopicClassification\".*?value\=\")[^\"]*/$1BugResolved/;
 865     $oopsUrl = TWiki::Func::saveTopicText( $web, $topic, $text ); # save topic text
 866
 867 ### <a name="moveTopic( $web, $topic, $newWeb"></a> moveTopic( $web, $topic, $newWeb, $newTopic )
 868
 869 - `$web` source web - required
 870 - `$topic` source topic - required
 871 - `$newWeb` dest web
 872 - `$newTopic` dest topic
 873
 874 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.
 875
 876 The destination topic must not already exist.
 877
 878 Rename a topic to the $TWiki::cfg\{TrashWebName\} to delete it.
 879
 880 **Since:** TWiki::Plugins::VERSION 1.1
 881
 882     use Error qw( :try );
 883
 884     try {
 885         moveTopic( "Work", "TokyoOffice", "Trash", "ClosedOffice" );
 886     } catch Error::Simple with {
 887         my $e = shift;
 888         # see documentation on Error::Simple
 889     } catch TWiki::AccessControlException with {
 890         my $e = shift;
 891         # see documentation on TWiki::AccessControlException
 892     } otherwise {
 893         ...
 894     };
 895
 896 ### <a name="get_RevisionInfo($web, $topic, $"></a> getRevisionInfo($web, $topic, $rev, $attachment ) -&gt; ( $date, $user, $rev, $comment )
 897
 898 Get revision info of a topic or attachment
 899
 900 - `$web` - Web name, optional, e.g. `'Main'`
 901 - `$topic` - Topic name, required, e.g. `'TokyoOffice'`
 902 - `$rev` - revsion number, or tag name (can be in the format 1.2, or just the minor number)
 903 - `$attachment` -attachment filename
 904
 905 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" )`
 906
 907 <table border="1" cellpadding="0" cellspacing="0">
 908   <tr>
 909     <td> $date </td>
 910     <td> in epochSec </td>
 911   </tr>
 912   <tr>
 913     <td> $user </td>
 914     <td> Wiki name of the author (<strong>not</strong> login name) </td>
 915   </tr>
 916   <tr>
 917     <td> $rev </td>
 918     <td> actual rev number </td>
 919   </tr>
 920   <tr>
 921     <td> $comment </td>
 922     <td> WHAT COMMENT? </td>
 923   </tr>
 924 </table>
 925
 926 NOTE: if you are trying to get revision info for a topic, use `$meta->getRevisionInfo` instead if you can - it is significantly more efficient.
 927
 928 **Since:** TWiki::Plugins::VERSION 1.000 (29 Jul 2001)
 929
 930 ### <a name="get_RevisionAtTime( $web, $topic"></a> getRevisionAtTime( $web, $topic, $time ) -&gt; $rev
 931
 932 Get the revision number of a topic at a specific time.
 933
 934 - `$web` - web for topic
 935 - `$topic` - topic
 936 - `$time` - time (in epoch secs) for the rev
 937
 938 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)
 939
 940 **Since:** TWiki::Plugins::VERSION 1.1
 941
 942 ### <a name="readTopic( $web, $topic, $rev )"></a><a name="readTopic( $web, $topic, $rev ) "></a> readTopic( $web, $topic, $rev ) -&gt; ( $meta, $text )
 943
 944 Read topic text and meta data, regardless of access permissions.
 945
 946 - `$web` - Web name, required, e.g. `'Main'`
 947 - `$topic` - Topic name, required, e.g. `'TokyoOffice'`
 948 - `$rev` - revision to read (default latest)
 949
 950 Return: `( $meta, $text )` Meta data object and topic text
 951
 952 `$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.
 953
 954 This method **ignores** topic access permissions. You should be careful to use `checkAccessPermissions` to ensure the current user has read access to the topic.
 955
 956 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
 957
 958 ### <a name="read_TopicText( $web, $topic, $r"></a> readTopicText( $web, $topic, $rev, $ignorePermissions ) -&gt; $text
 959
 960 Read topic text, including meta data
 961
 962 - `$web` - Web name, e.g. `'Main'`, or empty
 963 - `$topic` - Topic name, e.g. `'MyTopic'`, or `"Main.MyTopic"`
 964 - `$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.
 965 - `$ignorePermissions` - Set to `"1"` if checkAccessPermission() is already performed and OK; an oops URL is returned if user has no permission
 966
 967 Return: `$text` Topic text with embedded meta data; an oops URL for calling redirectCgiQuery() is returned in case of an error
 968
 969 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.
 970
 971 **Since:** TWiki::Plugins::VERSION 1.010 (31 Dec 2002)
 972
 973 ### <a name="attachmentExists( $web, $topic,"></a><a name="attachmentExists( $web, $topic, "></a> attachmentExists( $web, $topic, $attachment ) -&gt; $boolean
 974
 975 Test if attachment exists
 976
 977 - `$web` - Web name, optional, e.g. `Main`.
 978 - `$topic` - Topic name, required, e.g. `TokyoOffice`, or `Main.TokyoOffice`
 979 - `$attachment` - attachment name, e.g.=logo.gif=
 980
 981 $web and $topic are parsed as described in the documentation for `normalizeWebTopicName`.
 982
 983 **Since:** TWiki::Plugins::VERSION 1.1
 984
 985 ### <a name="readAttachment( $web, $topic, $n"></a> readAttachment( $web, $topic, $name, $rev ) -&gt; $data
 986
 987 - `$web` - web for topic
 988 - `$topic` - topic
 989 - `$name` - attachment name
 990 - `$rev` - revision to read (default latest)
 991
 992 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.
 993
 994 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.
 995
 996     my( $meta, $text ) = TWiki::Func::readTopic( $web, $topic );
 997     my @attachments = $meta->find( 'FILEATTACHMENT' );
 998     foreach my $a ( @attachments ) {
 999        try {
1000            my $data = TWiki::Func::readAttachment( $web, $topic, $a->{name} );
1001            ...
1002        } catch TWiki::AccessControlException with {
1003        };
1004     }
1005
1006 **Since:** TWiki::Plugins::VERSION 1.1
1007
1008 ### <a name="saveAttachment( $web, $topic, $a"></a> saveAttachment( $web, $topic, $attachment, $opts )
1009
1010 - `$web` - web for topic
1011 - `$topic` - topic to atach to
1012 - `$attachment` - name of the attachment
1013 - `$opts` - Ref to hash of options
1014
1015 `$opts` may include:
1016
1017 <table border="1" cellpadding="0" cellspacing="0">
1018   <tr>
1019     <td><code>dontlog</code></td>
1020     <td> don't log this change in twiki log </td>
1021   </tr>
1022   <tr>
1023     <td><code>comment</code></td>
1024     <td> comment for save </td>
1025   </tr>
1026   <tr>
1027     <td><code>hide</code></td>
1028     <td> if the attachment is to be hidden in normal topic view </td>
1029   </tr>
1030   <tr>
1031     <td><code>stream</code></td>
1032     <td> Stream of file to upload </td>
1033   </tr>
1034   <tr>
1035     <td><code>file</code></td>
1036     <td> Name of a file to use for the attachment data. ignored if stream is set. Local file on the server. </td>
1037   </tr>
1038   <tr>
1039     <td><code>filepath</code></td>
1040     <td> Client path to file </td>
1041   </tr>
1042   <tr>
1043     <td><code>filesize</code></td>
1044     <td> Size of uploaded data </td>
1045   </tr>
1046   <tr>
1047     <td><code>filedate</code></td>
1048     <td> Date </td>
1049   </tr>
1050 </table>
1051
1052 Save an attachment to the store for a topic. On success, returns undef. If there is an error, an exception will be thrown.
1053
1054         try {
1055             TWiki::Func::saveAttachment( $web, $topic, 'image.gif',
1056                                          { file => 'image.gif',
1057                                            comment => 'Picture of Health',
1058                                            hide => 1 } );
1059        } catch Error::Simple with {
1060           # see documentation on Error
1061        } otherwise {
1062           ...
1063        };
1064
1065 **Since:** TWiki::Plugins::VERSION 1.1
1066
1067 ### <a name="moveAttachment( $web, $topic, $a"></a> moveAttachment( $web, $topic, $attachment, $newWeb, $newTopic, $newAttachment )
1068
1069 - `$web` source web - required
1070 - `$topic` source topic - required
1071 - `$attachment` source attachment - required
1072 - `$newWeb` dest web
1073 - `$newTopic` dest topic
1074 - `$newAttachment` dest attachment
1075
1076 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.
1077
1078 The destination topic must already exist, but the destination attachment must **not** exist.
1079
1080 Rename an attachment to $TWiki::cfg\{TrashWebName\}.TrashAttament to delete it.
1081
1082     use Error qw( :try );
1083
1084     try {
1085        # move attachment between topics
1086        moveAttachment( "Countries", "Germany", "AlsaceLorraine.dat",
1087                          "Countries", "France" );
1088        # Note destination attachment name is defaulted to the same as source
1089     } catch TWiki::AccessControlException with {
1090        my $e = shift;
1091        # see documentation on TWiki::AccessControlException
1092     } catch Error::Simple with {
1093        my $e = shift;
1094        # see documentation on Error::Simple
1095     };
1096
1097 **Since:** TWiki::Plugins::VERSION 1.1
1098
1099 ## <a name="Assembling Pages"></a> Assembling Pages
1100
1101 ### <a name="readTemplate( $name, $skin ) - $"></a> readTemplate( $name, $skin ) -&gt; $text
1102
1103 Read a template or skin. Embedded [[template directives|SYSTEMWEB/TWikiTemplates]] get expanded
1104
1105 - `$name` - Template name, e.g. `'view'`
1106 - `$skin` - Comma-separated list of skin names, optional, e.g. `'print'`
1107
1108 Return: `$text` Template text
1109
1110 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
1111
1112 ### <a name="loadTemplate ( $name, $skin, $we"></a> loadTemplate ( $name, $skin, $web ) -&gt; $text
1113
1114 - `$name` - template file name
1115 - `$skin` - comma-separated list of skins to use (default: current skin)
1116 - `$web` - the web to look in for topics that contain templates (default: current web)
1117
1118 Return: expanded template text (what's left after removal of all %TMPL:DEF% statements)
1119
1120 **Since:** TWiki::Plugins::VERSION 1.1
1121
1122 Reads a template and extracts template definitions, adding them to the list of loaded templates, overwriting any previous definition.
1123
1124 How TWiki searches for templates is described in [[TWikiTemplates]].
1125
1126 If template text is found, extracts include statements and fully expands them.
1127
1128 ### <a name="expandTemplate( $def  ) - $strin"></a> expandTemplate( $def ) -&gt; $string
1129
1130 Do a , only expanding the template (not expanding any variables other than %TMPL)
1131
1132 - `$def` - template name
1133
1134 Return: the text of the expanded template
1135
1136 **Since:** TWiki::Plugins::VERSION 1.1
1137
1138 A template is defined using a %TMPL:DEF% statement in a template file. See the documentation on TWiki templates for more information.
1139
1140 ### <a name="writeHeader( $query, $contentLen"></a> writeHeader( $query, $contentLength )
1141
1142 Prints a basic content-type HTML header for text/html to standard out
1143
1144 - `$query` - CGI query object. If not given, the default CGI query will be used (optional, in most cases you should _not_ pass this parameter)
1145 - `$contentLength` - Length of content (optional, in most cases you should _not_ pass this parameter)
1146
1147 Return: none
1148
1149 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
1150
1151 ### <a name="redirect_CgiQuery( $query, $url,"></a> redirectCgiQuery( $query, $url, $passthru )
1152
1153 Redirect to URL
1154
1155 - `$query` - CGI query object. Ignored, only there for compatibility. The session CGI query object is used instead.
1156 - `$url` - URL to redirect to
1157 - `$passthru` - enable passthrough.
1158
1159 Return: none
1160
1161 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.
1162
1163 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.
1164
1165 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.
1166
1167     my $query = TWiki::Func::getCgiQuery();
1168     $query->param(-name => 'text', -value => 'Different text');
1169     TWiki::Func::redirectCgiQuery(
1170       undef, TWiki::Func::getScriptUrl($web, $topic, 'edit'), 1);
1171
1172 `$passthru` does nothing if `$url` does not point to a script in the current TWiki installation.
1173
1174 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
1175
1176 ### <a name="add_ToHEAD( $id, $header )"></a> addToHEAD( $id, $header )
1177
1178 Adds `$header` to the HTML header (the
1179
1180 tag). This is useful for Plugins that want to include some javascript custom css.
1181
1182 - `$id` - Unique ID to prevent the same HTML from being duplicated. Plugins should use a prefix to prevent name clashes (e.g EDITTABLEPLUGIN\_JSCALENDAR)
1183 - `$header` - the HTML to be added to the
1184
1185 section. The HTML must be valid in a HEAD tag - no checks are performed.
1186
1187 All TWiki variables present in `$header` will be expanded before being inserted into the ``
1188
1189 section.
1190
1191 Note that this is _not_ the same as the HTTP header, which is modified through the Plugins `modifyHeaderHandler`.
1192
1193 **Since:** TWiki::Plugins::VERSION 1.1
1194
1195 example:
1196
1197     TWiki::Func::addToHEAD('PATTERN_STYLE','<link id="twikiLayoutCss" rel="stylesheet" type="text/css" href="%PUBURL%/TWiki/PatternSkin/layout.css" media="all" />')
1198
1199 ### <a name="expand_CommonVariables( $text, $"></a> expandCommonVariables( $text, $topic, $web, $meta ) -&gt; $text
1200
1201 Expand all common `%VARIABLES%`
1202
1203 - `$text` - Text with variables to expand, e.g. `'Current user is %WIKIUSER%'`
1204 - `$topic` - Current topic name, e.g. `'WebNotify'`
1205 - `$web` - Web name, optional, e.g. `'Main'`. The current web is taken if missing
1206 - `$meta` - topic meta-data to use while expanding (Since TWiki::Plugins::VERSION 1.2)
1207
1208 Return: `$text` Expanded text, e.g. `'Current user is TWikiGuest'`
1209
1210 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
1211
1212 See also: expandVariablesOnTopicCreation
1213
1214 ### <a name="renderText( $text, $web ) - $tex"></a> renderText( $text, $web ) -&gt; $text
1215
1216 Render text from TWiki markup into XHTML as defined in [[%SYSTEMWEB%.TextFormattingRules|SYSTEMWEB/TextFormattingRules]]
1217
1218 - `$text` - Text to render, e.g. `'*bold* text and =fixed font='`
1219 - `$web` - Web name, optional, e.g. `'Main'`. The current web is taken if missing
1220
1221 Return: `$text` XHTML text, e.g. `'<b>bold</b> and <code>fixed font</code>'`
1222
1223 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
1224
1225 ### <a name="internalLink( $pre, $web, $topic"></a> internalLink( $pre, $web, $topic, $label, $anchor, $createLink ) -&gt; $text
1226
1227 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()`
1228
1229 - `$pre` - Text occuring before the TWiki link syntax, optional
1230 - `$web` - Web name, required, e.g. `'Main'`
1231 - `$topic` - Topic name to link to, required, e.g. `'WebNotify'`
1232 - `$label` - Link label, required. Usually the same as `$topic`, e.g. `'notify'`
1233 - `$anchor` - Anchor, optional, e.g. `'#Jump'`
1234 - `$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
1235
1236 Return: `$text` XHTML anchor, e.g. `'<a href='/cgi-bin/view/Main/WebNotify#Jump'>notify</a>'`
1237
1238 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
1239
1240 ## <a name="E-mail"></a> E-mail
1241
1242 ### <a name="sendEmail ( $text, $retries ) -"></a><a name="sendEmail ( $text, $retries ) - "></a> sendEmail ( $text, $retries ) -&gt; $error
1243
1244 - `$text` - text of the mail, including MIME headers
1245 - `$retries` - number of times to retry the send (default 1)
1246
1247 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:
1248
1249     To: liz@windsor.gov.uk
1250     From: serf@hovel.net
1251     CC: george@whitehouse.gov
1252     Subject: Revolution
1253
1254     Dear Liz,
1255
1256     Please abolish the monarchy (with King George's permission, of course)
1257
1258     Thanks,
1259
1260     A. Peasant
1261
1262 Leave a blank line between the last header field and the message body.
1263
1264 **Since:** TWiki::Plugins::VERSION 1.1
1265
1266 ### <a name="wiki_ToEmail( $wikiName ) - $ema"></a> wikiToEmail( $wikiName ) -&gt; $email
1267
1268 - `$wikiName` - wiki name of the user
1269
1270 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.
1271
1272 **Since:** TWiki::Plugins::VERSION 1.1
1273
1274 ## <a name="Creating New Topics"></a> Creating New Topics
1275
1276 ### <a name="expand_VariablesOnTopicCreation"></a><a name="expand_VariablesOnTopicCreation "></a> expandVariablesOnTopicCreation ( $text ) -&gt; $text
1277
1278 Expand the limited set of variables that are always expanded during topic creation
1279
1280 - `$text` - the text to process
1281
1282 Return: text with variables expanded
1283
1284 **Since:** TWiki::Plugins::VERSION 1.1
1285
1286 Expands only the variables expected in templates that must be statically expanded in new content.
1287
1288 The expanded variables are:
1289
1290 - `%DATE%` Signature-format date
1291 - `%SERVERTIME%` See [[TWikiVariables]]
1292 - `%GMTIME%` See [[TWikiVariables]]
1293 - `%USERNAME%` Base login name
1294 - `%WIKINAME%` Wiki name
1295 - `%WIKIUSERNAME%` Wiki name with prepended web
1296 - `%URLPARAM{...}%` - Parameters to the current CGI query
1297 - `%NOP%` No-op
1298
1299 See also: expandVariables
1300
1301 ## <a name="Special handlers"></a> Special handlers
1302
1303 Special handlers can be defined to make functions in plugins behave as if they were built-in to TWiki.
1304
1305 ### <a name="register_TagHandler( $var, \fn,"></a><a name="register_TagHandler( $var, \fn, "></a> registerTagHandler( $var, \\&amp;fn, $syntax )
1306
1307 Should only be called from initPlugin.
1308
1309 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`.
1310
1311 - `$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.
1312 - `\&fn` - Reference to the handler function.
1313 - `$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"\}%
1314
1315 **Since:** TWiki::Plugins::VERSION 1.1
1316
1317 The variable handler function must be of the form:
1318
1319     sub handler(\%session, \%params, $topic, $web)
1320
1321 where:
1322
1323 - `\%session` - a reference to the TWiki session object (may be ignored)
1324 - `\%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.
1325 - `$topic` - name of the topic in the query
1326 - `$web` - name of the web in the query
1327
1328 for example, to execute an arbitrary command on the server, you might do this:
1329
1330     sub initPlugin{
1331        TWiki::Func::registerTagHandler('EXEC', \&boo);
1332     }
1333
1334     sub boo {
1335         my( $session, $params, $topic, $web ) = @_;
1336         my $cmd = $params->{_DEFAULT};
1337
1338         return "NO COMMAND SPECIFIED" unless $cmd;
1339
1340         my $result = `$cmd 2>&1`;
1341         return $params->{silent} ? '' : $result;
1342     }
1343     }
1344
1345 would let you do this: `%EXEC{"ps -Af" silent="on"}%`
1346
1347 Registered tags differ from tags implemented using the old TWiki approach (text substitution in `commonTagsHandler`) in the following ways:
1348
1349 - 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).
1350 - registered tag names can only contain alphanumerics and \_ (underscore)
1351 - registering a tag `FRED` defines both `%FRED{...}%` **and also** `%FRED%`.
1352 - registered tag handlers **cannot** return another tag as their only result (e.g. `return '%SERVERTIME%';`). It won't work.
1353
1354 ### <a name="registerRESTHandler( $alias, \fn"></a> registerRESTHandler( $alias, \\&amp;fn, )
1355
1356 Should only be called from initPlugin.
1357
1358 Adds a function to the dispatch table of the REST interface
1359
1360 - `$alias` - The name .
1361 - `\&fn` - Reference to the function.
1362
1363 **Since:** TWiki::Plugins::VERSION 1.1
1364
1365 The handler function must be of the form:
1366
1367     sub handler(\%session)
1368
1369 where:
1370
1371 - `\%session` - a reference to the TWiki session object (may be ignored)
1372
1373 From the REST interface, the name of the plugin must be used as the subject of the invokation.
1374
1375 Example
1376
1377 ----
1378
1379 The [[EmptyPlugin]] has the following call in the initPlugin handler:
1380
1381        TWiki::Func::registerRESTHandler('example', \&restExample);
1382
1383 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
1384
1385 `http://server:port/bin/rest/EmptyPlugin/example`
1386
1387 note that the URL
1388
1389 `http://server:port/bin/rest/EmptyPlugin/restExample`
1390
1391 (ie, with the name of the function instead of the alias) will not work.
1392
1393 ### <a name="decode_FormatTokens($str) - $une"></a> decodeFormatTokens($str) -&gt; $unencodedString
1394
1395 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
1396
1397 `%MYTAG{format="%WURBLE%"}%`
1398
1399 then %WURBLE would be expanded **before** %MYTAG is evaluated. To avoid this TWiki uses escapes in the format string. For example:
1400
1401 `%MYTAG{format="$percntWURBLE$percnt"}%`
1402
1403 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.
1404
1405 <table border="1" cellpadding="0" cellspacing="0">
1406   <tr>
1407     <th bgcolor="#99CCCC"><strong> Escape: </strong></th>
1408     <th bgcolor="#99CCCC"><strong> Expands To: </strong></th>
1409   </tr>
1410   <tr>
1411     <td><code>$n</code> or <code>$n()</code></td>
1412     <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>
1413   </tr>
1414   <tr>
1415     <td><code>$nop</code> or <code>$nop()</code></td>
1416     <td> Is a "no operation". </td>
1417   </tr>
1418   <tr>
1419     <td><code>$quot</code></td>
1420     <td> Double quote (<code>"</code>) </td>
1421   </tr>
1422   <tr>
1423     <td><code>$percnt</code></td>
1424     <td> Percent sign (<code>%</code>) </td>
1425   </tr>
1426   <tr>
1427     <td><code>$dollar</code></td>
1428     <td> Dollar sign (<code>$</code>) </td>
1429   </tr>
1430 </table>
1431
1432 Note thath $quot, $percnt and $dollar all work \*even if they are followed by alphanumeric characters\*. You have been warned!
1433
1434 **Since:** TWiki::Plugins::VERSION 1.2
1435
1436 ## <a name="Searching"></a> Searching
1437
1438 ### <a name="search_InWebContent($searchStrin"></a> searchInWebContent($searchString, $web, \\@topics, \\%options ) -&gt; \\%map
1439
1440 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+\{.\*\}%)
1441
1442 - `$searchString` - the search string, in egrep format
1443 - `$web` - The web to search in
1444 - `\@topics` - reference to a list of topics to search
1445 - `\%option` - reference to an options hash
1446
1447 The `\%options` hash may contain the following options:
1448
1449 - `type` - if `regex` will perform a egrep-syntax RE search (default '')
1450 - `casesensitive` - false to ignore case (defaulkt true)
1451 - `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).
1452
1453 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'.
1454
1455 To iterate over the returned topics use:
1456
1457     my $result = TWiki::Func::searchInWebContent( "Slimy Toad", $web, \@topics,
1458        { casesensitive => 0, files_without_match => 0 } );
1459     foreach my $topic (keys %$result ) {
1460        foreach my $matching_line ( @{$result->{$topic}} ) {
1461           ...etc
1462
1463 **Since:** TWiki::Plugins::VERSION 1.1
1464
1465 ## <a name="Plugin-specific file handling"></a> Plugin-specific file handling
1466
1467 ### <a name="get_WorkArea( $pluginName ) - $d"></a> getWorkArea( $pluginName ) -&gt; $directorypath
1468
1469 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.
1470
1471 The directory is guaranteed to exist, and to be writable by the webserver user. By default it will **not** be web accessible.
1472
1473 The directory and it's contents are permanent, so Plugins must be careful to keep their areas tidy.
1474
1475 **Since:** TWiki::Plugins::VERSION 1.1 (Dec 2005)
1476
1477 ### <a name="readFile( $filename ) - $text"></a> readFile( $filename ) -&gt; $text
1478
1479 Read file, low level. Used for Plugin workarea.
1480
1481 - `$filename` - Full path name of file
1482
1483 Return: `$text` Content of file, empty if not found
1484
1485 **_NOTE:_** Use this function only for the Plugin workarea, **not** for topics and attachments. Use the appropriate functions to manipulate topics and attachments.
1486
1487 **Since:** TWiki::Plugins::VERSION 1.000 (07 Dec 2002)
1488
1489 ### <a name="saveFile( $filename, $text )"></a> saveFile( $filename, $text )
1490
1491 Save file, low level. Used for Plugin workarea.
1492
1493 - `$filename` - Full path name of file
1494 - `$text` - Text to save
1495
1496 Return: none
1497
1498 **_NOTE:_** Use this function only for the Plugin workarea, **not** for topics and attachments. Use the appropriate functions to manipulate topics and attachments.
1499
1500 **Since:** TWiki::Plugins::VERSION 1.000 (07 Dec 2002)
1501
1502 ## <a name="General Utilities"></a> General Utilities
1503
1504 ### <a name="get_RegularExpression( $name ) -"></a> getRegularExpression( $name ) -&gt; $expr
1505
1506 Retrieves a TWiki predefined regular expression or character class.
1507
1508 - `$name` - Name of the expression to retrieve. See notes below
1509
1510 Return: String or precompiled regular expression matching as described below.
1511
1512 **Since:** TWiki::Plugins::VERSION 1.020 (9 Feb 2004)
1513
1514 **_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.
1515
1516 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:
1517
1518        my $upper = TWiki::Func::getRegularExpression('upperAlpha');
1519        my $alpha = TWiki::Func::getRegularExpression('mixedAlpha');
1520        my $capitalized = qr/[$upper][$alpha]+/;
1521
1522 Those expressions marked type 'RE' are precompiled regular expressions that can be used outside square brackets. For example:
1523
1524        my $webRE = TWiki::Func::getRegularExpression('webNameRegex');
1525        my $isWebName = ( $s =~ m/$webRE/ );
1526
1527 <table border="1" cellpadding="0" cellspacing="0">
1528   <tr>
1529     <th bgcolor="#99CCCC"><strong> Name </strong></th>
1530     <th bgcolor="#99CCCC"><strong> Matches </strong></th>
1531     <th bgcolor="#99CCCC"><strong> Type </strong></th>
1532   </tr>
1533   <tr>
1534     <td> upperAlpha </td>
1535     <td> Upper case characters </td>
1536     <td> String </td>
1537   </tr>
1538   <tr>
1539     <td> upperAlphaNum </td>
1540     <td> Upper case characters and digits </td>
1541     <td> String </td>
1542   </tr>
1543   <tr>
1544     <td> lowerAlpha </td>
1545     <td> Lower case characters </td>
1546     <td> String </td>
1547   </tr>
1548   <tr>
1549     <td> lowerAlphaNum </td>
1550     <td> Lower case characters and digits </td>
1551     <td> String </td>
1552   </tr>
1553   <tr>
1554     <td> numeric </td>
1555     <td> Digits </td>
1556     <td> String </td>
1557   </tr>
1558   <tr>
1559     <td> mixedAlpha </td>
1560     <td> Alphabetic characters </td>
1561     <td> String </td>
1562   </tr>
1563   <tr>
1564     <td> mixedAlphaNum </td>
1565     <td> Alphanumeric characters </td>
1566     <td> String </td>
1567   </tr>
1568   <tr>
1569     <td> wikiWordRegex </td>
1570     <td>[[Main/WikiWords]]</td>
1571     <td> RE </td>
1572   </tr>
1573   <tr>
1574     <td> webNameRegex </td>
1575     <td> User web names </td>
1576     <td> RE </td>
1577   </tr>
1578   <tr>
1579     <td> anchorRegex </td>
1580     <td> #AnchorNames </td>
1581     <td> RE </td>
1582   </tr>
1583   <tr>
1584     <td> abbrevRegex </td>
1585     <td> Abbreviations e.g. GOV, IRS </td>
1586     <td> RE </td>
1587   </tr>
1588   <tr>
1589     <td> emailAddrRegex </td>
1590     <td><a href="mailto:email@address.com">email@address.com</a></td>
1591     <td> RE </td>
1592   </tr>
1593   <tr>
1594     <td> tagNameRegex </td>
1595     <td> Standard variable names e.g. %THIS_BIT% (THIS_BIT only) </td>
1596     <td> RE </td>
1597   </tr>
1598 </table>
1599
1600 ### <a name="normalize_WebTopicName($web, $to"></a> normalizeWebTopicName($web, $topic) -&gt; ($web, $topic)
1601
1602 Parse a web and topic name, supplying defaults as appropriate.
1603
1604 - `$web` - Web name, identifying variable, or empty string
1605 - `$topic` - Topic name, may be a web.topic string, required.
1606
1607 Return: the parsed Web/Topic pair
1608
1609 **Since:** TWiki::Plugins::VERSION 1.1
1610
1611 <table border="1" cellpadding="0" cellspacing="0">
1612   <tr>
1613     <th bgcolor="#99CCCC"><strong> Input </strong></th>
1614     <th bgcolor="#99CCCC"><strong> Return </strong></th>
1615   </tr>
1616   <tr>
1617     <td><tt>( 'Web', 'Topic' ) </tt></td>
1618     <td><tt>( 'Web', 'Topic' ) </tt></td>
1619   </tr>
1620   <tr>
1621     <td><tt>( '', 'Topic' ) </tt></td>
1622     <td><tt>( 'Main', 'Topic' ) </tt></td>
1623   </tr>
1624   <tr>
1625     <td><tt>( '', '' ) </tt></td>
1626     <td><tt>( 'Main', 'WebHome' ) </tt></td>
1627   </tr>
1628   <tr>
1629     <td><tt>( '', 'Web/Topic' ) </tt></td>
1630     <td><tt>( 'Web', 'Topic' ) </tt></td>
1631   </tr>
1632   <tr>
1633     <td><tt>( '', 'Web/Subweb/Topic' ) </tt></td>
1634     <td><tt>( 'Web/Subweb', 'Topic' ) </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>( 'Web1', 'Web2.Topic' )</tt></td>
1646     <td><tt>( 'Web2', 'Topic' ) </tt></td>
1647   </tr>
1648 </table>
1649
1650 Note that hierarchical web names ([[SubWeb]]) are only available if hierarchical webs are enabled in `configure`.
1651
1652 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:
1653
1654 <table border="1" cellpadding="0" cellspacing="0">
1655   <tr>
1656     <th bgcolor="#99CCCC"><strong> Input </strong></th>
1657     <th bgcolor="#99CCCC"><strong> Return </strong></th>
1658   </tr>
1659   <tr>
1660     <td><tt>( '%USERSWEB%', 'Topic' )</tt></td>
1661     <td><tt>( 'Main', 'Topic' ) </tt></td>
1662   </tr>
1663   <tr>
1664     <td><tt>( '%SYSTEMWEB%', 'Topic' )</tt></td>
1665     <td><tt>( 'TWiki', 'Topic' ) </tt></td>
1666   </tr>
1667   <tr>
1668     <td><tt>( '', '%DOCWEB%.Topic' )</tt></td>
1669     <td><tt>( 'TWiki', 'Topic' ) </tt></td>
1670   </tr>
1671 </table>
1672
1673 ## <a name="StaticMethod &lt;strong&gt;sanitize_Attachmen"></a> [[StaticMethod]] \*sanitizeAttachmentName `($fname) -> ($fileName,$origName)`
1674
1675 Given a file namer, sanitise it according to the rules for transforming attachment names. Returns the sanitised name together with the basename before sanitisation.
1676
1677 Sanitation includes filtering illegal characters and mapping client file names to legal server names.
1678
1679 **Since:** TWiki::Plugins::VERSION 1.2
1680
1681 ### <a name="space_OutWikiWord( $word, $sep )"></a> spaceOutWikiWord( $word, $sep ) -&gt; $text
1682
1683 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.
1684
1685 **Since:** TWiki::Plugins::VERSION 1.2
1686
1687 ### <a name="writeWarning( $text )"></a> writeWarning( $text )
1688
1689 Log Warning that may require admin intervention to data/warning.txt
1690
1691 - `$text` - Text to write; timestamp gets added
1692
1693 Return: none
1694
1695 **Since:** TWiki::Plugins::VERSION 1.020 (16 Feb 2004)
1696
1697 ### <a name="writeDebug( $text )"></a> writeDebug( $text )
1698
1699 Log debug message to data/debug.txt
1700
1701 - `$text` - Text to write; timestamp gets added
1702
1703 Return: none
1704
1705 **Since:** TWiki::Plugins::VERSION 1.020 (16 Feb 2004)
1706
1707 ### <a name="formatTime( $time, $format, $tim"></a> formatTime( $time, $format, $timezone ) -&gt; $text
1708
1709 Format the time in seconds into the desired time string
1710
1711 - `$time` - Time in epoc seconds
1712 - `$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
1713 - `$timezone` - either not defined (uses the displaytime setting), 'gmtime', or 'servertime'
1714
1715 Return: `$text` Formatted time string
1716
1717 <table border="1" cellpadding="0" cellspacing="0">
1718   <tr>
1719     <td> Note: </td>
1720     <td> if you used the removed formatGmTime, add a third parameter 'gmtime' </td>
1721   </tr>
1722 </table>
1723
1724 **Since:** TWiki::Plugins::VERSION 1.020 (26 Feb 2004)
1725
1726 ### <a name="isTrue( $value, $default ) - $bo"></a> isTrue( $value, $default ) -&gt; $boolean
1727
1728 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.
1729
1730 If the value is undef, then `$default` is returned. If `$default` is not specified it is taken as 0.
1731
1732 **Since:** $TWiki::Plugins::VERSION 1.2
1733
1734 ### <a name="is_ValidWikiWord ( $text ) - $bo"></a> isValidWikiWord ( $text ) -&gt; $boolean
1735
1736 Check for a valid [[WikiWord]] or [[WikiName]]
1737
1738 - `$text` - Word to test
1739
1740 **Since:** TWiki::Plugins::VERSION 1.100 (Dec 2005)
1741
1742 ### <a name="extractParameters($attr ) - %par"></a> extractParameters($attr ) -&gt; %params
1743
1744 Extract all parameters from a variable string and returns a hash of parameters
1745
1746 - `$attr` - Attribute string
1747
1748 Return: `%params` Hash containing all parameters. The nameless parameter is stored in key `_DEFAULT`
1749
1750 **Since:** TWiki::Plugins::VERSION 1.025 (26 Aug 2004)
1751
1752 - Example:
1753   - Variable: `%TEST{ 'nameless' name1="val1" name2="val2" }%`
1754   - First extract text between `{...}` to get: `'nameless' name1="val1" name2="val2"`
1755   - Then call this on the text: <br />
1756 - params = TWiki::Func::extractParameters( $text );=
1757   - The `%params` hash contains now: <br />`_DEFAULT => 'nameless'`<br />`name1 => "val1"`<br />`name2 => "val2"`
1758
1759 ### <a name="extract_NameValuePair( $attr, $n"></a> extractNameValuePair( $attr, $name ) -&gt; $value
1760
1761 Extract a named or unnamed value from a variable parameter string - Note: | Function TWiki::Func::extractParameters is more efficient for extracting several parameters
1762
1763 - `$attr` - Attribute string
1764 - `$name` - Name, optional
1765
1766 Return: `$value` Extracted value
1767
1768 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
1769
1770 - Example:
1771   - Variable: `%TEST{ 'nameless' name1="val1" name2="val2" }%`
1772   - First extract text between `{...}` to get: `'nameless' name1="val1" name2="val2"`
1773   - 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" );`
1774
1775 ## <a name="Deprecated functions"></a> Deprecated functions
1776
1777 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.
1778
1779 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%.
1780
1781 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:
1782
1783     package TWiki::Plugins::SinkPlugin;
1784     use vars qw( %TWikiCompatibility );
1785     $TWikiCompatibility{endRenderingHandler} = 1.1;
1786
1787 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.
1788
1789 The following functions are retained for compatibility only. You should stop using them as soon as possible.
1790
1791 ### <a name="get_ScriptUrlPath( ) - $path"></a> getScriptUrlPath( ) -&gt; $path
1792
1793 Get script URL path
1794
1795 **DEPRECATED** since 1.1 - use `getScriptUrl` instead.
1796
1797 Return: `$path` URL path of TWiki scripts, e.g. `"/cgi-bin"`
1798
1799 **WARNING:** you are strongly recommended **not** to use this function, as the \{ScriptUrlPaths\} URL rewriting rules will not apply to urls generated using it.
1800
1801 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
1802
1803 ### <a name="get_OopsUrl( $web, $topic, $temp"></a> getOopsUrl( $web, $topic, $template, $param1, $param2, $param3, $param4 ) -&gt; $url
1804
1805 Compose fully qualified 'oops' dialog URL
1806
1807 - `$web` - Web name, e.g. `'Main'`. The current web is taken if empty
1808 - `$topic` - Topic name, e.g. `'WebNotify'`
1809 - `$template` - Oops template name, e.g. `'oopsmistake'`. The 'oops' is optional; 'mistake' will translate to 'oopsmistake'.
1810 - `$param1` ... `$param4` - Parameter values for %PARAM1% ... %PARAMn% variables in template, optional
1811
1812 Return: `$url` URL, e.g. `"http://example.com:80/cgi-bin/oops.pl/ Main/WebNotify?template=oopslocked&param1=joe"`
1813
1814 **DEPRECATED** since 1.1, the recommended approach is to throw an [[oops exception|Main/TWikiOopsExceptionDotPm]].
1815
1816        use Error qw( :try );
1817
1818        throw TWiki::OopsException(
1819           'toestuckerror',
1820           web => $web,
1821           topic => $topic,
1822           params => [ 'I got my toe stuck' ]);
1823
1824 (this example will use the `oopstoestuckerror` template.)
1825
1826 If this is not possible (e.g. in a REST handler that does not trap the exception) then you can use `getScriptUrl` instead:
1827
1828        my $url = TWiki::Func::getScriptUrl($web, $topic, 'oops',
1829                 template => 'oopstoestuckerror',
1830                 param1 => 'I got my toe stuck');
1831        TWiki::Func::redirectCgiQuery( undef, $url );
1832        return 0;
1833
1834 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
1835
1836 ### <a name="permissionsSet( $web ) - $boolea"></a> permissionsSet( $web ) -&gt; $boolean
1837
1838 Test if any access restrictions are set for this web, ignoring settings on individual pages
1839
1840 - `$web` - Web name, required, e.g. `'Sandbox'`
1841
1842 **Since:** TWiki::Plugins::VERSION 1.000 (27 Feb 2001)
1843
1844 **DEPRECATED** since 1.2 - use `getPreferencesValue` instead to determine what permissions are set on the web, for example:
1845
1846     foreach my $type qw( ALLOW DENY ) {
1847         foreach my $action qw( CHANGE VIEW ) {
1848             my $pref = $type . 'WEB' . $action;
1849             my $val = getPreferencesValue( $pref, $web ) || '';
1850             if( $val =~ /\S/ ) {
1851                 print "$pref is set to $val on $web\n";
1852             }
1853         }
1854     }
1855
1856 ### <a name="get_PublicWebList( ) - @webs"></a> getPublicWebList( ) -&gt; @webs
1857
1858 **DEPRECATED** since 1.1 - use `getListOfWebs` instead.
1859
1860 Get list of all public webs, e.g. all webs that do not have the `NOSEARCHALL` flag set in the [[WebPreferences]]
1861
1862 Return: `@webs` List of all public webs, e.g. `( 'Main',  'Know', 'TWiki' )`
1863
1864 **Since:** TWiki::Plugins::VERSION 1.000 (07 Dec 2002)
1865
1866 ### <a name="format_GmTime( $time, $format )"></a><a name="format_GmTime( $time, $format ) "></a> formatGmTime( $time, $format ) -&gt; $text
1867
1868 **DEPRECATED** since 1.1 - use `formatTime` instead.
1869
1870 Format the time to GM time
1871
1872 - `$time` - Time in epoc seconds
1873 - `$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'`)
1874
1875 Return: `$text` Formatted time string
1876
1877 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
1878
1879 ### <a name="get_DataDir( ) - $dir"></a> getDataDir( ) -&gt; $dir
1880
1881 **DEPRECATED** since 1.1 - use the "Webs, Topics and Attachments" functions to manipulate topics instead
1882
1883 Get data directory (topic file root)
1884
1885 Return: `$dir` Data directory, e.g. `'/twiki/data'`
1886
1887 This function violates store encapsulation and is therefore **deprecated**.
1888
1889 **Since:** TWiki::Plugins::VERSION 1.000 (07 Dec 2002)
1890
1891 ### <a name="get_PubDir( ) - $dir"></a> getPubDir( ) -&gt; $dir
1892
1893 **DEPRECATED** since 1.1 - use the "Webs, Topics and Attachments" functions to manipulateattachments instead
1894
1895 Get pub directory (file attachment root). Attachments are in `$dir/Web/TopicName`
1896
1897 Return: `$dir` Pub directory, e.g. `'/htdocs/twiki/pub'`
1898
1899 This function violates store encapsulation and is therefore **deprecated**.
1900
1901 Use `readAttachment` and `saveAttachment` instead.
1902
1903 **Since:** TWiki::Plugins::VERSION 1.000 (07 Dec 2002)
1904
1905 ### <a name="checkDependencies( $moduleName,"></a><a name="checkDependencies( $moduleName, "></a> checkDependencies( $moduleName, $dependenciesRef ) -&gt; $error
1906
1907 **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.
1908
1909 **Since:** TWiki::Plugins::VERSION 1.025 (01 Aug 2004)