1 # <a name="Package <code>TWiki::Func="></a> Package =TWiki::Func
3 _Official list of stable TWiki functions for Plugin developers_
5 This module defines official functions that [[Plugins|SYSTEMWEB/TWikiPlugins]] can use to interact with the TWiki engine and content.
7 Refer to [[EmptyPlugin]] and lib/TWiki/Plugins/EmptyPlugin.pm for a template Plugin and documentation on how to write a Plugin.
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.
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.
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`.
15 Notes on use of `$TWiki::Plugins::VERSION` (from 1.2 forwards):
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.
22 A full history of the changes to this API can be found at the end of this topic.
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( ) -> $skin</a></li>
29 <li><a href="#get_UrlHost( ) -> $host"> getUrlHost( ) -> $host</a></li>
30 <li><a href="#get_ScriptUrl( $web, $topic, $sc"> getScriptUrl( $web, $topic, $script, ... ) -> $url</a></li>
31 <li><a href="#get_ViewUrl( $web, $topic ) -> $"> getViewUrl( $web, $topic ) -> $url</a></li>
32 <li><a href="#get_PubUrlPath( ) -> $path"> getPubUrlPath( ) -> $path</a></li>
33 <li><a href="#get_ExternalResource( $url ) ->"> getExternalResource( $url ) -> $response</a></li>
34 <li><a href="#get_CgiQuery( ) -> $query"> getCgiQuery( ) -> $query</a></li>
35 <li><a href="#get_SessionKeys() -> @keys"> getSessionKeys() -> @keys</a></li>
36 <li><a href="#get_SessionValue( $key ) -> $val"> getSessionValue( $key ) -> $value</a></li>
37 <li><a href="#set_SessionValue( $key, $value )"> setSessionValue( $key, $value ) -> $boolean</a></li>
38 <li><a href="#clear_SessionValue( $key ) -> $b"> clearSessionValue( $key ) -> $boolean</a></li>
39 <li><a href="#getContext() -> \%hash"> getContext() -> \%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>
44 <li><a href="#Preferences"> Preferences</a><ul>
45 <li><a href="#get_PreferencesValue( $key, $web"> getPreferencesValue( $key, $web ) -> $value</a></li>
46 <li><a href="#get_PluginPreferencesValue( $key"> getPluginPreferencesValue( $key ) -> $value</a></li>
47 <li><a href="#get_PreferencesFlag( $key, $web"> getPreferencesFlag( $key, $web ) -> $value</a></li>
48 <li><a href="#get_PluginPreferencesFlag( $key"> getPluginPreferencesFlag( $key ) -> $boolean</a></li>
49 <li><a href="#set_PreferencesValue($name, $val"> setPreferencesValue($name, $val)</a></li>
50 <li><a href="#get_WikiToolName( ) -> $name"> getWikiToolName( ) -> $name</a></li>
51 <li><a href="#get_MainWebname( ) -> $name"> getMainWebname( ) -> $name</a></li>
52 <li><a href="#get_TwikiWebname( ) -> $name"> getTwikiWebname( ) -> $name</a></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( ) -> $loginName</a></li>
57 <li><a href="#get_CanonicalUserID( $user ) ->"> getCanonicalUserID( $user ) -> $cUID</a></li>
58 <li><a href="#get_WikiName( $user ) -> $wikiNa"> getWikiName( $user ) -> $wikiName</a></li>
59 <li><a href="#get_WikiUserName( $user ) -> $wi"> getWikiUserName( $user ) -> $wikiName</a></li>
60 <li><a href="#wiki_ToUserName( $wikiName ) ->"> wikiToUserName( $wikiName ) -> $loginName</a></li>
61 <li><a href="#user_ToWikiName( $loginName, $do"> userToWikiName( $loginName, $dontAddWeb ) -> $wikiName</a></li>
62 <li><a href="#email_ToWikiNames( $email, $dont"> emailToWikiNames( $email, $dontAddWeb ) -> @wikiNames</a></li>
63 <li><a href="#wiki_NameToEmails( $wikiname ) -"> wikiNameToEmails( $wikiname ) -> @emails</a></li>
64 <li><a href="#isGuest( ) -> $boolean"> isGuest( ) -> $boolean</a></li>
65 <li><a href="#is_AnAdmin( $login ) -> $boolean"> isAnAdmin( $login ) -> $boolean</a></li>
66 <li><a href="#is_GroupMember( $group, $login )"> isGroupMember( $group, $login ) -> $boolean</a></li>
67 <li><a href="#eachUser() -> $iterator"> eachUser() -> $iterator</a></li>
68 <li><a href="#eachMembership($wikiname) -> $it"> eachMembership($wikiname) -> $iterator</a></li>
69 <li><a href="#eachGroup() -> $iterator"> eachGroup() -> $iterator</a></li>
70 <li><a href="#isGroup( $group ) -> $boolean"> isGroup( $group ) -> $boolean</a></li>
71 <li><a href="#each_GroupMember($group) -> $ite"> eachGroupMember($group) -> $iterator</a></li>
72 <li><a href="#check_AccessPermission( $type, $"> checkAccessPermission( $type, $wikiName, $text, $topic, $web, $meta ) -> $boolean</a></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 ) -> @webs</a></li>
77 <li><a href="#webExists( $web ) -> $boolean"> webExists( $web ) -> $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) -> $iterator</a></li>
81 <li><a href="#get_TopicList( $web ) -> @topics"> getTopicList( $web ) -> @topics</a></li>
82 <li><a href="#topicExists( $web, $topic ) -> $"> topicExists( $web, $topic ) -> $boolean</a></li>
83 <li><a href="#check_TopicEditLock( $web, $topi"> checkTopicEditLock( $web, $topic, $script ) -> ( $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 ) -> $error</a></li>
86 <li><a href="#save_TopicText( $web, $topic, $t"> saveTopicText( $web, $topic, $text, $ignorePermissions, $dontNotify ) -> $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 ) -> ( $date, $user, $rev, $comment ) </a></li>
89 <li><a href="#get_RevisionAtTime( $web, $topic"> getRevisionAtTime( $web, $topic, $time ) -> $rev</a></li>
90 <li><a href="#readTopic( $web, $topic, $rev )"> readTopic( $web, $topic, $rev ) -> ( $meta, $text )</a></li>
91 <li><a href="#read_TopicText( $web, $topic, $r"> readTopicText( $web, $topic, $rev, $ignorePermissions ) -> $text</a></li>
92 <li><a href="#attachmentExists( $web, $topic,"> attachmentExists( $web, $topic, $attachment ) -> $boolean</a></li>
93 <li><a href="#readAttachment( $web, $topic, $n"> readAttachment( $web, $topic, $name, $rev ) -> $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>
98 <li><a href="#Assembling Pages"> Assembling Pages</a><ul>
99 <li><a href="#readTemplate( $name, $skin ) ->"> readTemplate( $name, $skin ) -> $text</a></li>
100 <li><a href="#loadTemplate ( $name, $skin, $we"> loadTemplate ( $name, $skin, $web ) -> $text</a></li>
101 <li><a href="#expandTemplate( $def ) -> $stri"> expandTemplate( $def ) -> $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 ) -> $text</a></li>
106 <li><a href="#renderText( $text, $web ) -> $te"> renderText( $text, $web ) -> $text</a></li>
107 <li><a href="#internalLink( $pre, $web, $topic"> internalLink( $pre, $web, $topic, $label, $anchor, $createLink ) -> $text</a></li>
110 <li><a href="#E-mail"> E-mail</a><ul>
111 <li><a href="#sendEmail ( $text, $retries ) ->"> sendEmail ( $text, $retries ) -> $error</a></li>
112 <li><a href="#wiki_ToEmail( $wikiName ) -> $em"> wikiToEmail( $wikiName ) -> $email</a></li>
115 <li><a href="#Creating New Topics"> Creating New Topics</a><ul>
116 <li><a href="#expand_VariablesOnTopicCreation"> expandVariablesOnTopicCreation ( $text ) -> $text</a></li>
119 <li><a href="#Special handlers"> Special handlers</a><ul>
120 <li><a href="#register_TagHandler( $var, \fn,"> registerTagHandler( $var, \&fn, $syntax )</a></li>
121 <li><a href="#registerRESTHandler( $alias, \fn"> registerRESTHandler( $alias, \&fn, )</a></li>
122 <li><a href="#decode_FormatTokens($str) -> $un"> decodeFormatTokens($str) -> $unencodedString</a></li>
125 <li><a href="#Searching"> Searching</a><ul>
126 <li><a href="#search_InWebContent($searchStrin"> searchInWebContent($searchString, $web, \@topics, \%options ) -> \%map</a></li>
129 <li><a href="#Plugin-specific file handling"> Plugin-specific file handling</a><ul>
130 <li><a href="#get_WorkArea( $pluginName ) -> $"> getWorkArea( $pluginName ) -> $directorypath</a></li>
131 <li><a href="#readFile( $filename ) -> $text"> readFile( $filename ) -> $text</a></li>
132 <li><a href="#saveFile( $filename, $text )"> saveFile( $filename, $text )</a></li>
135 <li><a href="#General Utilities"> General Utilities</a><ul>
136 <li><a href="#get_RegularExpression( $name ) -"> getRegularExpression( $name ) -> $expr</a></li>
137 <li><a href="#normalize_WebTopicName($web, $to"> normalizeWebTopicName($web, $topic) -> ($web, $topic)</a></li>
140 <li><a href="#StaticMethod *sanitize_Attachmen"> StaticMethod sanitizeAttachmentName <tt>($fname) -> ($fileName,$origName)</tt></a><ul>
141 <li><a href="#space_OutWikiWord( $word, $sep )"> spaceOutWikiWord( $word, $sep ) -> $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 ) -> $text</a></li>
145 <li><a href="#isTrue( $value, $default ) -> $b"> isTrue( $value, $default ) -> $boolean</a></li>
146 <li><a href="#is_ValidWikiWord ( $text ) -> $b"> isValidWikiWord ( $text ) -> $boolean</a></li>
147 <li><a href="#extractParameters($attr ) -> %pa"> extractParameters($attr ) -> %params</a></li>
148 <li><a href="#extract_NameValuePair( $attr, $n"> extractNameValuePair( $attr, $name ) -> $value</a></li>
151 <li><a href="#Deprecated functions"> Deprecated functions</a><ul>
152 <li><a href="#get_ScriptUrlPath( ) -> $path"> getScriptUrlPath( ) -> $path</a></li>
153 <li><a href="#get_OopsUrl( $web, $topic, $temp"> getOopsUrl( $web, $topic, $template, $param1, $param2, $param3, $param4 ) -> $url</a></li>
154 <li><a href="#permissionsSet( $web ) -> $boole"> permissionsSet( $web ) -> $boolean</a></li>
155 <li><a href="#get_PublicWebList( ) -> @webs"> getPublicWebList( ) -> @webs</a></li>
156 <li><a href="#format_GmTime( $time, $format )"> formatGmTime( $time, $format ) -> $text</a></li>
157 <li><a href="#get_DataDir( ) -> $dir"> getDataDir( ) -> $dir</a></li>
158 <li><a href="#get_PubDir( ) -> $dir"> getPubDir( ) -> $dir</a></li>
159 <li><a href="#checkDependencies( $moduleName,"> checkDependencies( $moduleName, $dependenciesRef ) -> $error</a></li>
167 ## <a name="Environment"></a> Environment
169 ### <a name="getSkin( ) - $skin"></a> getSkin( ) -> $skin
171 Get the skin path, set by the `SKIN` and `COVER` preferences variables or the `skin` and `cover` CGI parameters
173 Return: `$skin` Comma-separated list of skins, e.g. `'gnu,tartan'`. Empty string if none.
175 **Since:** TWiki::Plugins::VERSION 1.000 (29 Jul 2001)
177 ### <a name="get_UrlHost( ) - $host"></a> getUrlHost( ) -> $host
179 Get protocol, domain and optional port of script URL
181 Return: `$host` URL host, e.g. `"http://example.com:80"`
183 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
185 ### <a name="get_ScriptUrl( $web, $topic, $sc"></a> getScriptUrl( $web, $topic, $script, ... ) -> $url
187 Compose fully qualified URL
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=>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`
194 Return: `$url` URL, e.g. `"http://example.com:80/cgi-bin/view.pl/Main/WebNotify"`
196 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
198 ### <a name="get_ViewUrl( $web, $topic ) - $u"></a> getViewUrl( $web, $topic ) -> $url
200 Compose fully qualified view URL
202 - `$web` - Web name, e.g. `'Main'`. The current web is taken if empty
203 - `$topic` - Topic name, e.g. `'WebNotify'`
205 Return: `$url` URL, e.g. `"http://example.com:80/cgi-bin/view.pl/Main/WebNotify"`
207 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
209 ### <a name="get_PubUrlPath( ) - $path"></a> getPubUrlPath( ) -> $path
213 Return: `$path` URL path of pub directory, e.g. `"/pub"`
215 **Since:** TWiki::Plugins::VERSION 1.000 (14 Jul 2001)
217 ### <a name="get_ExternalResource( $url ) - $"></a> getExternalResource( $url ) -> $response
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.
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.
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:
225 <table border="1" cellpadding="0" cellspacing="0">
227 <td><code>code()</code></td>
230 <td><code>message()</code></td>
233 <td><code>header($field)</code></td>
236 <td><code>content()</code></td>
239 <td><code>is_error()</code></td>
242 <td><code>is_redirect()</code></td>
246 Note that if LWP is **not** available, this function:
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
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).
253 Note: Callers can easily check the availability of other HTTP::Response methods as follows:
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
259 ... only the methods listed above may be called
262 **Since:** TWiki::Plugins::VERSION 1.2
264 ### <a name="get_CgiQuery( ) - $query"></a> getCgiQuery( ) -> $query
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
268 Return: `$query` CGI query object; or 0 if script is called as a shell script
270 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
272 ### <a name="get_SessionKeys() - @keys"></a> getSessionKeys() -> @keys
274 Get a list of all the names of session variables. The list is unsorted.
276 Session keys are stored and retrieved using `setSessionValue` and `getSessionValue`.
278 **Since:** TWiki::Plugins::VERSION 1.2
280 ### <a name="get_SessionValue( $key ) - $valu"></a> getSessionValue( $key ) -> $value
282 Get a session value from the client session module
284 - `$key` - Session key
286 Return: `$value` Value associated with key; empty string if not set
288 **Since:** TWiki::Plugins::VERSION 1.000 (27 Feb 200)
290 ### <a name="set_SessionValue( $key, $value )"></a> setSessionValue( $key, $value ) -> $boolean
294 - `$key` - Session key
295 - `$value` - Value associated with key
297 Return: true if function succeeded
299 **Since:** TWiki::Plugins::VERSION 1.000 (17 Aug 2001)
301 ### <a name="clear_SessionValue( $key ) - $bo"></a> clearSessionValue( $key ) -> $boolean
303 Clear a session value that was set using `setSessionValue`.
305 - `$key` - name of value stored in session to be cleared. Note that you **cannot** clear `AUTHUSER`.
307 Return: true if the session value was cleared
309 **Since:** TWiki::Plugins::VERSION 1.1
311 ### <a name="getContext() - \%hash"></a> getContext() -> \\%hash
313 Get a hash of context identifiers representing the currently active context.
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!
317 Context identifiers can be used to communicate between Plugins, and between Plugins and templates. For example, in [[FirstPlugin]].pm, you might write:
320 TWiki::Func::getContext()->{'MyID'} = 1;
323 This can be used in SecondPlugin.pm like this:
326 if( TWiki::Func::getContext()->{'MyID'} ) {
331 or in a template, like this:
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"}%
339 %IF{"context MyID" then="MyID is ON" else="MyID is OFF"}%
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.
343 **Since:** TWiki::Plugins::VERSION 1.1
345 ### <a name="push_TopicContext($web, $topic)"></a> pushTopicContext($web, $topic)
348 - `$topic` - new topic
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.
352 It is the duty of the caller to restore the original context by calling `popTopicContext`.
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.
356 **Since:** TWiki::Plugins::VERSION 1.2
358 ### <a name="pop_TopicContext()"></a> popTopicContext()
360 Returns the TWiki context to the state it was in before the `pushTopicContext` was called.
362 **Since:** TWiki::Plugins::VERSION 1.2
364 ## <a name="Preferences"></a> Preferences
366 ### <a name="get_PreferencesValue( $key, $web"></a> getPreferencesValue( $key, $web ) -> $value
368 Get a preferences value from TWiki or from a Plugin
370 - `$key` - Preferences key
371 - `$web` - Name of web, optional. Current web if not specified; does not apply to settings of Plugin topics
373 Return: `$value` Preferences value; empty string if not set
375 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
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" );`
382 - Example for preferences setting:
383 - [[WebPreferences]] topic has: `* Set WEBBGCOLOR = #FFFFC0`
384 - `my $webColor = TWiki::Func::getPreferencesValue( 'WEBBGCOLOR', 'Sandbox' );`
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.
388 ### <a name="get_PluginPreferencesValue( $key"></a> getPluginPreferencesValue( $key ) -> $value
390 Get a preferences value from your Plugin
392 - `$key` - Plugin Preferences key w/o PLUGINNAME\_ prefix.
394 Return: `$value` Preferences value; empty string if not set
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)
398 **Since:** TWiki::Plugins::VERSION 1.021 (27 Mar 2004)
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.
402 ### <a name="get_PreferencesFlag( $key, $web"></a><a name="get_PreferencesFlag( $key, $web "></a> getPreferencesFlag( $key, $web ) -> $value
404 Get a preferences flag from TWiki or from a Plugin
406 - `$key` - Preferences key
407 - `$web` - Name of web, optional. Current web if not specified; does not apply to settings of Plugin topics
409 Return: `$value` Preferences flag `'1'` (if set), or `"0"` (for preferences values `"off"`, `"no"` and `"0"`)
411 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
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" );`
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.
420 ### <a name="get_PluginPreferencesFlag( $key"></a><a name="get_PluginPreferencesFlag( $key "></a> getPluginPreferencesFlag( $key ) -> $boolean
422 Get a preferences flag from your Plugin
424 - `$key` - Plugin Preferences key w/o PLUGINNAME\_ prefix.
426 Return: false for preferences values `"off"`, `"no"` and `"0"`, or values not set at all. True otherwise.
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)
430 **Since:** TWiki::Plugins::VERSION 1.021 (27 Mar 2004)
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.
434 ### <a name="set_PreferencesValue($name, $val"></a> setPreferencesValue($name, $val)
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.
438 The preference only persists for the rest of this request. Finalised preferences cannot be redefined using this function.
440 Returns 1 if the preference was defined, and 0 otherwise.
442 ### <a name="get_WikiToolName( ) - $name"></a> getWikiToolName( ) -> $name
444 Get toolname as defined in TWiki.cfg
446 Return: `$name` Name of tool, e.g. `'TWiki'`
448 **Since:** TWiki::Plugins::VERSION 1.000 (27 Feb 2001)
450 ### <a name="get_MainWebname( ) - $name"></a> getMainWebname( ) -> $name
452 Get name of Main web as defined in TWiki.cfg
454 Return: `$name` Name, e.g. `'Main'`
456 **Since:** TWiki::Plugins::VERSION 1.000 (27 Feb 2001)
458 ### <a name="get_TwikiWebname( ) - $name"></a> getTwikiWebname( ) -> $name
460 Get name of TWiki documentation web as defined in TWiki.cfg
462 Return: `$name` Name, e.g. `'TWiki'`
464 **Since:** TWiki::Plugins::VERSION 1.000 (27 Feb 2001)
466 ## <a name="User Handling and Access Control"></a> User Handling and Access Control
468 ### <a name="get_DefaultUserName( ) - $loginN"></a> getDefaultUserName( ) -> $loginName
470 Get default user name as defined in the configuration as `DefaultUserLogin`
472 Return: `$loginName` Default user name, e.g. `'guest'`
474 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
476 ### <a name="get_CanonicalUserID( $user ) - $"></a> getCanonicalUserID( $user ) -> $cUID
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'.
480 If $user is undefined Get the cUID of logged in user, and will generally be 'BaseUserMapping\_666'
482 - $user can be a cUID, login, wikiname or web.wikiname
484 Return: `$cUID` an internal unique and transportable escaped identifier for registered users (they can be autogenerated for an authenticated but unregistered user)
486 **Since:** TWiki::Plugins::VERSION 1.2
488 ### <a name="get_WikiName( $user ) - $wikiNam"></a> getWikiName( $user ) -> $wikiName
490 return the [[WikiName]] of the specified user if $user is undefined Get Wiki name of logged in user
492 - $user can be a cUID, login, wikiname or web.wikiname
494 Return: `$wikiName` Wiki Name, e.g. `'JohnDoe'`
496 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
498 ### <a name="get_WikiUserName( $user ) - $wik"></a> getWikiUserName( $user ) -> $wikiName
500 return the userWeb.WikiName of the specified user if $user is undefined Get Wiki name of logged in user
502 - $user can be a cUID, login, wikiname or web.wikiname
504 Return: `$wikiName` Wiki Name, e.g. `"Main.JohnDoe"`
506 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
508 ### <a name="wiki_ToUserName( $wikiName ) - $"></a> wikiToUserName( $wikiName ) -> $loginName
510 Translate a Wiki name (or login name or cUID, if it can) to a login name.
512 - `$wikiName` - Wiki name, e.g. `'Main.JohnDoe'` or `'JohnDoe'`
514 Return: `$loginName` Login name of user, e.g. `'jdoe'`, or undef if not matched.
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.
518 returns undef if the [[WikiName]] is not found.
520 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
522 ### <a name="user_ToWikiName( $loginName, $do"></a> userToWikiName( $loginName, $dontAddWeb ) -> $wikiName
524 Translate a login name to a Wiki name
526 - `$loginName` - Login name, e.g. `'jdoe'`
527 - `$dontAddWeb` - Do not add web prefix if `"1"`
529 Return: `$wikiName` Wiki name of user, e.g. `'Main.JohnDoe'` or `'JohnDoe'`
531 userToWikiName will always return a name, if the user does not exist in the mapping, the $loginName parameter is returned. (backward compatibility)
533 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
535 ### <a name="email_ToWikiNames( $email, $dont"></a> emailToWikiNames( $email, $dontAddWeb ) -> @wikiNames
537 - `$email` - email address to look up
538 - `$dontAddWeb` - Do not add web prefix if `"1"`
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.
542 **Since:** TWiki::Plugins::VERSION 1.2
544 ### <a name="wiki_NameToEmails( $wikiname ) -"></a> wikiNameToEmails( $wikiname ) -> @emails
546 - `$wikiname` - wikiname of user to look up
548 Returns the registered email addresses of the named user. If $wikiname is undef, returns the registered email addresses for the logged-in user.
550 **Since:** TWiki::Plugins::VERSION 1.2
552 ### <a name="isGuest( ) - $boolean"></a> isGuest( ) -> $boolean
554 Test if logged in user is a guest ([[TWikiGuest]])
556 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
558 ### <a name="is_AnAdmin( $login ) - $boolean"></a> isAnAdmin( $login ) -> $boolean
560 Find out if the user is an admin or not. If the user is not given, the currently logged-in user is assumed.
562 - $login can be either a login, or a CUID
564 **Since:** TWiki::Plugins::VERSION 1.2
566 ### <a name="is_GroupMember( $group, $login )"></a> isGroupMember( $group, $login ) -> $boolean
568 Find out if $login is in the named group. e.g.
570 if( TWiki::Func::isGroupMember( "HesperionXXGroup", "jordi" )) {
574 If `$user` is `undef`, it defaults to the currently logged-in user.
576 - $login can be a login name, or a cUID, or [[WikiName]]
578 **Since:** TWiki::Plugins::VERSION 1.2
580 ### <a name="eachUser() - $iterator"></a> eachUser() -> $iterator
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').
586 my $iterator = TWiki::Func::eachUser();
587 while ($it->hasNext()) {
588 my $user = $it->next();
589 # $user is a wikiname
592 **WARNING** on large sites, this could be a long list!
594 **Since:** TWiki::Plugins::VERSION 1.2
596 ### <a name="eachMembership($wikiname) - $ite"></a> eachMembership($wikiname) -> $iterator
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.
600 **Since:** TWiki::Plugins::VERSION 1.2
602 ### <a name="eachGroup() - $iterator"></a> eachGroup() -> $iterator
604 Get an iterator over all groups.
608 my $iterator = TWiki::Func::eachGroup();
609 while ($it->hasNext()) {
610 my $group = $it->next();
611 # $group is a group name e.g. TWikiAdminGroup
614 **WARNING** on large sites, this could be a long list!
616 **Since:** TWiki::Plugins::VERSION 1.2
618 ### <a name="isGroup( $group ) - $boolean"></a> isGroup( $group ) -> $boolean
620 Checks if `$group` is the name of a group known to TWiki.
622 ### <a name="each_GroupMember($group) - $iter"></a> eachGroupMember($group) -> $iterator
624 Get an iterator over all the members of the named group. Returns undef if $group is not a valid group.
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'
634 **WARNING** on large sites, this could be a long list!
636 **Since:** TWiki::Plugins::VERSION 1.2
638 ### <a name="check_AccessPermission( $type, $"></a> checkAccessPermission( $type, $wikiName, $text, $topic, $web, $meta ) -> $boolean
640 Check access permission for a topic based on the [[%SYSTEMWEB%.TWikiAccessControl|SYSTEMWEB/TWikiAccessControl]] rules
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.
652 A perl true result indicates that access is permitted.
654 **Note** the wierd parameter order is due to compatibility constraints with earlier TWiki releases.
656 **Tip** if you want, you can use this method to check your own access control types. For example, if you:
658 - Set ALLOWTOPICSPIN = [[IncyWincy]]
660 in `ThatWeb.ThisTopic`, then a call to `checkAccessPermissions('SPIN', 'IncyWincy', undef, 'ThisTopic', 'ThatWeb', undef)` will return `true`.
662 **Since:** TWiki::Plugins::VERSION 1.000 (27 Feb 2001)
664 ## <a name="Webs, Topics and Attachments"></a> Webs, Topics and Attachments
666 ### <a name="get_ListOfWebs( $filter ) - @web"></a> getListOfWebs( $filter ) -> @webs
668 - `$filter` - spec of web types to recover
670 Gets a list of webs, filtered according to the spec in the $filter, which may include one of:
672 1. 'user' (for only user webs)
673 2. 'template' (for only template webs i.e. those starting with "\_")
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.
677 For example, the deprecated getPublicWebList function can be duplicated as follows:
679 my @webs = TWiki::Func::getListOfWebs( "user,public" );
681 **Since:** TWiki::Plugins::VERSION 1.1
683 ### <a name="webExists( $web ) - $boolean"></a> webExists( $web ) -> $boolean
687 - `$web` - Web name, required, e.g. `'Sandbox'`
689 **Since:** TWiki::Plugins::VERSION 1.000 (14 Jul 2001)
691 ### <a name="createWeb( $newWeb, $baseWeb, $o"></a> createWeb( $newWeb, $baseWeb, $opts )
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
697 the web preferences topic in the new web.
699 use Error qw( :try );
700 use TWiki::AccessControlException;
703 TWiki::Func::createWeb( "Newweb" );
704 } catch Error::Simple with {
706 # see documentation on Error::Simple
707 } catch TWiki::AccessControlException with {
709 # see documentation on TWiki::AccessControlException
714 **Since:** TWiki::Plugins::VERSION 1.1
716 ### <a name="moveWeb( $oldName, $newName )"></a> moveWeb( $oldName, $newName )
720 use Error qw( :try );
721 use TWiki::AccessControlException;
724 TWiki::Func::moveWeb( "Oldweb", "Newweb" );
725 } catch Error::Simple with {
727 # see documentation on Error::Simple
728 } catch TWiki::AccessControlException with {
730 # see documentation on TWiki::AccessControlException
735 To delete a web, move it to a subweb of `Trash`
737 TWiki::Func::moveWeb( "Deadweb", "Trash.Deadweb" );
739 **Since:** TWiki::Plugins::VERSION 1.1
741 ### <a name="each_ChangeSince($web, $time) -"></a><a name="each_ChangeSince($web, $time) - "></a> eachChangeSince($web, $time) -> $iterator
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.
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')
759 ### <a name="get_TopicList( $web ) - @topics"></a> getTopicList( $web ) -> @topics
761 Get list of all topics in a web
763 - `$web` - Web name, required, e.g. `'Sandbox'`
765 Return: `@topics` Topic list, e.g. `( 'WebChanges', 'WebHome', 'WebIndex', 'WebNotify' )`
767 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
769 ### <a name="topicExists( $web, $topic ) - $b"></a> topicExists( $web, $topic ) -> $boolean
773 - `$web` - Web name, optional, e.g. `'Main'`.
774 - `$topic` - Topic name, required, e.g. `'TokyoOffice'`, or `"Main.TokyoOffice"`
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.
778 **Since:** TWiki::Plugins::VERSION 1.000 (14 Jul 2001)
780 ### <a name="check_TopicEditLock( $web, $topi"></a> checkTopicEditLock( $web, $topic, $script ) -> ( $oopsUrl, $loginName, $unlockTime )
782 Check if a lease has been taken by some other user.
784 - `$web` Web name, e.g. `"Main"`, or empty
785 - `$topic` Topic name, e.g. `"MyTopic"`, or `"Main.MyTopic"`
787 Return: `( $oopsUrl, $loginName, $unlockTime )` - The `$oopsUrl` for calling redirectCgiQuery(), user's `$loginName`, and estimated `$unlockTime` in minutes, or ( '', '', 0 ) if no lease exists.
789 - `$script` The script to invoke when continuing with the edit
791 **Since:** TWiki::Plugins::VERSION 1.010 (31 Dec 2002)
793 ### <a name="set_TopicEditLock( $web, $topic,"></a> setTopicEditLock( $web, $topic, $lock )
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
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.
801 It is **impossible** to fully lock a topic. Concurrent changes will be merged.
803 **Since:** TWiki::Plugins::VERSION 1.010 (31 Dec 2002)
805 ### <a name="saveTopic( $web, $topic, $meta,"></a><a name="saveTopic( $web, $topic, $meta, "></a> saveTopic( $web, $topic, $meta, $text, $options ) -> $error
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">
813 <td><code>dontlog</code></td>
814 <td> don't log this change in twiki log </td>
817 <td><code>comment</code></td>
818 <td> comment for save </td>
821 <td><code>minor</code></td>
822 <td> True if this is a minor change, and is not to be notified </td>
826 Return: error message or undef.
828 **Since:** TWiki::Plugins::VERSION 1.000 (29 Jul 2001)
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' } );
836 **_Note:_** Plugins handlers ( e.g. `beforeSaveHandler` ) will be called as appropriate.
838 ### <a name="save_TopicText( $web, $topic, $t"></a> saveTopicText( $web, $topic, $text, $ignorePermissions, $dontNotify ) -> $oopsUrl
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.
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
848 Return: `$oopsUrl` Empty string if OK; the `$oopsUrl` for calling redirectCgiQuery() in case of error
850 This method is a lot less efficient and much more dangerous than `saveTopic`.
852 **Since:** TWiki::Plugins::VERSION 1.010 (31 Dec 2002)
854 my $text = TWiki::Func::readTopicText( $web, $topic );
856 # check for oops URL in case of error:
857 if( $text =~ /^http.*?\/oops/ ) {
858 TWiki::Func::redirectCgiQuery( $query, $text );
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
867 ### <a name="moveTopic( $web, $topic, $newWeb"></a> moveTopic( $web, $topic, $newWeb, $newTopic )
869 - `$web` source web - required
870 - `$topic` source topic - required
872 - `$newTopic` dest topic
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.
876 The destination topic must not already exist.
878 Rename a topic to the $TWiki::cfg\{TrashWebName\} to delete it.
880 **Since:** TWiki::Plugins::VERSION 1.1
882 use Error qw( :try );
885 moveTopic( "Work", "TokyoOffice", "Trash", "ClosedOffice" );
886 } catch Error::Simple with {
888 # see documentation on Error::Simple
889 } catch TWiki::AccessControlException with {
891 # see documentation on TWiki::AccessControlException
896 ### <a name="get_RevisionInfo($web, $topic, $"></a> getRevisionInfo($web, $topic, $rev, $attachment ) -> ( $date, $user, $rev, $comment )
898 Get revision info of a topic or attachment
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
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" )`
907 <table border="1" cellpadding="0" cellspacing="0">
910 <td> in epochSec </td>
914 <td> Wiki name of the author (<strong>not</strong> login name) </td>
918 <td> actual rev number </td>
922 <td> WHAT COMMENT? </td>
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.
928 **Since:** TWiki::Plugins::VERSION 1.000 (29 Jul 2001)
930 ### <a name="get_RevisionAtTime( $web, $topic"></a> getRevisionAtTime( $web, $topic, $time ) -> $rev
932 Get the revision number of a topic at a specific time.
934 - `$web` - web for topic
936 - `$time` - time (in epoch secs) for the rev
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)
940 **Since:** TWiki::Plugins::VERSION 1.1
942 ### <a name="readTopic( $web, $topic, $rev )"></a><a name="readTopic( $web, $topic, $rev ) "></a> readTopic( $web, $topic, $rev ) -> ( $meta, $text )
944 Read topic text and meta data, regardless of access permissions.
946 - `$web` - Web name, required, e.g. `'Main'`
947 - `$topic` - Topic name, required, e.g. `'TokyoOffice'`
948 - `$rev` - revision to read (default latest)
950 Return: `( $meta, $text )` Meta data object and topic text
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.
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.
956 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
958 ### <a name="read_TopicText( $web, $topic, $r"></a> readTopicText( $web, $topic, $rev, $ignorePermissions ) -> $text
960 Read topic text, including meta data
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
967 Return: `$text` Topic text with embedded meta data; an oops URL for calling redirectCgiQuery() is returned in case of an error
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.
971 **Since:** TWiki::Plugins::VERSION 1.010 (31 Dec 2002)
973 ### <a name="attachmentExists( $web, $topic,"></a><a name="attachmentExists( $web, $topic, "></a> attachmentExists( $web, $topic, $attachment ) -> $boolean
975 Test if attachment exists
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=
981 $web and $topic are parsed as described in the documentation for `normalizeWebTopicName`.
983 **Since:** TWiki::Plugins::VERSION 1.1
985 ### <a name="readAttachment( $web, $topic, $n"></a> readAttachment( $web, $topic, $name, $rev ) -> $data
987 - `$web` - web for topic
989 - `$name` - attachment name
990 - `$rev` - revision to read (default latest)
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.
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.
996 my( $meta, $text ) = TWiki::Func::readTopic( $web, $topic );
997 my @attachments = $meta->find( 'FILEATTACHMENT' );
998 foreach my $a ( @attachments ) {
1000 my $data = TWiki::Func::readAttachment( $web, $topic, $a->{name} );
1002 } catch TWiki::AccessControlException with {
1006 **Since:** TWiki::Plugins::VERSION 1.1
1008 ### <a name="saveAttachment( $web, $topic, $a"></a> saveAttachment( $web, $topic, $attachment, $opts )
1010 - `$web` - web for topic
1011 - `$topic` - topic to atach to
1012 - `$attachment` - name of the attachment
1013 - `$opts` - Ref to hash of options
1015 `$opts` may include:
1017 <table border="1" cellpadding="0" cellspacing="0">
1019 <td><code>dontlog</code></td>
1020 <td> don't log this change in twiki log </td>
1023 <td><code>comment</code></td>
1024 <td> comment for save </td>
1027 <td><code>hide</code></td>
1028 <td> if the attachment is to be hidden in normal topic view </td>
1031 <td><code>stream</code></td>
1032 <td> Stream of file to upload </td>
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>
1039 <td><code>filepath</code></td>
1040 <td> Client path to file </td>
1043 <td><code>filesize</code></td>
1044 <td> Size of uploaded data </td>
1047 <td><code>filedate</code></td>
1052 Save an attachment to the store for a topic. On success, returns undef. If there is an error, an exception will be thrown.
1055 TWiki::Func::saveAttachment( $web, $topic, 'image.gif',
1056 { file => 'image.gif',
1057 comment => 'Picture of Health',
1059 } catch Error::Simple with {
1060 # see documentation on Error
1065 **Since:** TWiki::Plugins::VERSION 1.1
1067 ### <a name="moveAttachment( $web, $topic, $a"></a> moveAttachment( $web, $topic, $attachment, $newWeb, $newTopic, $newAttachment )
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
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.
1078 The destination topic must already exist, but the destination attachment must **not** exist.
1080 Rename an attachment to $TWiki::cfg\{TrashWebName\}.TrashAttament to delete it.
1082 use Error qw( :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 {
1091 # see documentation on TWiki::AccessControlException
1092 } catch Error::Simple with {
1094 # see documentation on Error::Simple
1097 **Since:** TWiki::Plugins::VERSION 1.1
1099 ## <a name="Assembling Pages"></a> Assembling Pages
1101 ### <a name="readTemplate( $name, $skin ) - $"></a> readTemplate( $name, $skin ) -> $text
1103 Read a template or skin. Embedded [[template directives|SYSTEMWEB/TWikiTemplates]] get expanded
1105 - `$name` - Template name, e.g. `'view'`
1106 - `$skin` - Comma-separated list of skin names, optional, e.g. `'print'`
1108 Return: `$text` Template text
1110 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
1112 ### <a name="loadTemplate ( $name, $skin, $we"></a> loadTemplate ( $name, $skin, $web ) -> $text
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)
1118 Return: expanded template text (what's left after removal of all %TMPL:DEF% statements)
1120 **Since:** TWiki::Plugins::VERSION 1.1
1122 Reads a template and extracts template definitions, adding them to the list of loaded templates, overwriting any previous definition.
1124 How TWiki searches for templates is described in [[TWikiTemplates]].
1126 If template text is found, extracts include statements and fully expands them.
1128 ### <a name="expandTemplate( $def ) - $strin"></a> expandTemplate( $def ) -> $string
1130 Do a , only expanding the template (not expanding any variables other than %TMPL)
1132 - `$def` - template name
1134 Return: the text of the expanded template
1136 **Since:** TWiki::Plugins::VERSION 1.1
1138 A template is defined using a %TMPL:DEF% statement in a template file. See the documentation on TWiki templates for more information.
1140 ### <a name="writeHeader( $query, $contentLen"></a> writeHeader( $query, $contentLength )
1142 Prints a basic content-type HTML header for text/html to standard out
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)
1149 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
1151 ### <a name="redirect_CgiQuery( $query, $url,"></a> redirectCgiQuery( $query, $url, $passthru )
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.
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.
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.
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.
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);
1172 `$passthru` does nothing if `$url` does not point to a script in the current TWiki installation.
1174 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
1176 ### <a name="add_ToHEAD( $id, $header )"></a> addToHEAD( $id, $header )
1178 Adds `$header` to the HTML header (the
1180 tag). This is useful for Plugins that want to include some javascript custom css.
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
1185 section. The HTML must be valid in a HEAD tag - no checks are performed.
1187 All TWiki variables present in `$header` will be expanded before being inserted into the ``
1191 Note that this is _not_ the same as the HTTP header, which is modified through the Plugins `modifyHeaderHandler`.
1193 **Since:** TWiki::Plugins::VERSION 1.1
1197 TWiki::Func::addToHEAD('PATTERN_STYLE','<link id="twikiLayoutCss" rel="stylesheet" type="text/css" href="%PUBURL%/TWiki/PatternSkin/layout.css" media="all" />')
1199 ### <a name="expand_CommonVariables( $text, $"></a> expandCommonVariables( $text, $topic, $web, $meta ) -> $text
1201 Expand all common `%VARIABLES%`
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)
1208 Return: `$text` Expanded text, e.g. `'Current user is TWikiGuest'`
1210 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
1212 See also: expandVariablesOnTopicCreation
1214 ### <a name="renderText( $text, $web ) - $tex"></a> renderText( $text, $web ) -> $text
1216 Render text from TWiki markup into XHTML as defined in [[%SYSTEMWEB%.TextFormattingRules|SYSTEMWEB/TextFormattingRules]]
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
1221 Return: `$text` XHTML text, e.g. `'<b>bold</b> and <code>fixed font</code>'`
1223 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
1225 ### <a name="internalLink( $pre, $web, $topic"></a> internalLink( $pre, $web, $topic, $label, $anchor, $createLink ) -> $text
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()`
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
1236 Return: `$text` XHTML anchor, e.g. `'<a href='/cgi-bin/view/Main/WebNotify#Jump'>notify</a>'`
1238 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
1240 ## <a name="E-mail"></a> E-mail
1242 ### <a name="sendEmail ( $text, $retries ) -"></a><a name="sendEmail ( $text, $retries ) - "></a> sendEmail ( $text, $retries ) -> $error
1244 - `$text` - text of the mail, including MIME headers
1245 - `$retries` - number of times to retry the send (default 1)
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:
1249 To: liz@windsor.gov.uk
1250 From: serf@hovel.net
1251 CC: george@whitehouse.gov
1256 Please abolish the monarchy (with King George's permission, of course)
1262 Leave a blank line between the last header field and the message body.
1264 **Since:** TWiki::Plugins::VERSION 1.1
1266 ### <a name="wiki_ToEmail( $wikiName ) - $ema"></a> wikiToEmail( $wikiName ) -> $email
1268 - `$wikiName` - wiki name of the user
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.
1272 **Since:** TWiki::Plugins::VERSION 1.1
1274 ## <a name="Creating New Topics"></a> Creating New Topics
1276 ### <a name="expand_VariablesOnTopicCreation"></a><a name="expand_VariablesOnTopicCreation "></a> expandVariablesOnTopicCreation ( $text ) -> $text
1278 Expand the limited set of variables that are always expanded during topic creation
1280 - `$text` - the text to process
1282 Return: text with variables expanded
1284 **Since:** TWiki::Plugins::VERSION 1.1
1286 Expands only the variables expected in templates that must be statically expanded in new content.
1288 The expanded variables are:
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
1299 See also: expandVariables
1301 ## <a name="Special handlers"></a> Special handlers
1303 Special handlers can be defined to make functions in plugins behave as if they were built-in to TWiki.
1305 ### <a name="register_TagHandler( $var, \fn,"></a><a name="register_TagHandler( $var, \fn, "></a> registerTagHandler( $var, \\&fn, $syntax )
1307 Should only be called from initPlugin.
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`.
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"\}%
1315 **Since:** TWiki::Plugins::VERSION 1.1
1317 The variable handler function must be of the form:
1319 sub handler(\%session, \%params, $topic, $web)
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
1328 for example, to execute an arbitrary command on the server, you might do this:
1331 TWiki::Func::registerTagHandler('EXEC', \&boo);
1335 my( $session, $params, $topic, $web ) = @_;
1336 my $cmd = $params->{_DEFAULT};
1338 return "NO COMMAND SPECIFIED" unless $cmd;
1340 my $result = `$cmd 2>&1`;
1341 return $params->{silent} ? '' : $result;
1345 would let you do this: `%EXEC{"ps -Af" silent="on"}%`
1347 Registered tags differ from tags implemented using the old TWiki approach (text substitution in `commonTagsHandler`) in the following ways:
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.
1354 ### <a name="registerRESTHandler( $alias, \fn"></a> registerRESTHandler( $alias, \\&fn, )
1356 Should only be called from initPlugin.
1358 Adds a function to the dispatch table of the REST interface
1360 - `$alias` - The name .
1361 - `\&fn` - Reference to the function.
1363 **Since:** TWiki::Plugins::VERSION 1.1
1365 The handler function must be of the form:
1367 sub handler(\%session)
1371 - `\%session` - a reference to the TWiki session object (may be ignored)
1373 From the REST interface, the name of the plugin must be used as the subject of the invokation.
1379 The [[EmptyPlugin]] has the following call in the initPlugin handler:
1381 TWiki::Func::registerRESTHandler('example', \&restExample);
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
1385 `http://server:port/bin/rest/EmptyPlugin/example`
1389 `http://server:port/bin/rest/EmptyPlugin/restExample`
1391 (ie, with the name of the function instead of the alias) will not work.
1393 ### <a name="decode_FormatTokens($str) - $une"></a> decodeFormatTokens($str) -> $unencodedString
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
1397 `%MYTAG{format="%WURBLE%"}%`
1399 then %WURBLE would be expanded **before** %MYTAG is evaluated. To avoid this TWiki uses escapes in the format string. For example:
1401 `%MYTAG{format="$percntWURBLE$percnt"}%`
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.
1405 <table border="1" cellpadding="0" cellspacing="0">
1407 <th bgcolor="#99CCCC"><strong> Escape: </strong></th>
1408 <th bgcolor="#99CCCC"><strong> Expands To: </strong></th>
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>
1415 <td><code>$nop</code> or <code>$nop()</code></td>
1416 <td> Is a "no operation". </td>
1419 <td><code>$quot</code></td>
1420 <td> Double quote (<code>"</code>) </td>
1423 <td><code>$percnt</code></td>
1424 <td> Percent sign (<code>%</code>) </td>
1427 <td><code>$dollar</code></td>
1428 <td> Dollar sign (<code>$</code>) </td>
1432 Note thath $quot, $percnt and $dollar all work \*even if they are followed by alphanumeric characters\*. You have been warned!
1434 **Since:** TWiki::Plugins::VERSION 1.2
1436 ## <a name="Searching"></a> Searching
1438 ### <a name="search_InWebContent($searchStrin"></a> searchInWebContent($searchString, $web, \\@topics, \\%options ) -> \\%map
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+\{.\*\}%)
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
1447 The `\%options` hash may contain the following options:
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).
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'.
1455 To iterate over the returned topics use:
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}} ) {
1463 **Since:** TWiki::Plugins::VERSION 1.1
1465 ## <a name="Plugin-specific file handling"></a> Plugin-specific file handling
1467 ### <a name="get_WorkArea( $pluginName ) - $d"></a> getWorkArea( $pluginName ) -> $directorypath
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.
1471 The directory is guaranteed to exist, and to be writable by the webserver user. By default it will **not** be web accessible.
1473 The directory and it's contents are permanent, so Plugins must be careful to keep their areas tidy.
1475 **Since:** TWiki::Plugins::VERSION 1.1 (Dec 2005)
1477 ### <a name="readFile( $filename ) - $text"></a> readFile( $filename ) -> $text
1479 Read file, low level. Used for Plugin workarea.
1481 - `$filename` - Full path name of file
1483 Return: `$text` Content of file, empty if not found
1485 **_NOTE:_** Use this function only for the Plugin workarea, **not** for topics and attachments. Use the appropriate functions to manipulate topics and attachments.
1487 **Since:** TWiki::Plugins::VERSION 1.000 (07 Dec 2002)
1489 ### <a name="saveFile( $filename, $text )"></a> saveFile( $filename, $text )
1491 Save file, low level. Used for Plugin workarea.
1493 - `$filename` - Full path name of file
1494 - `$text` - Text to save
1498 **_NOTE:_** Use this function only for the Plugin workarea, **not** for topics and attachments. Use the appropriate functions to manipulate topics and attachments.
1500 **Since:** TWiki::Plugins::VERSION 1.000 (07 Dec 2002)
1502 ## <a name="General Utilities"></a> General Utilities
1504 ### <a name="get_RegularExpression( $name ) -"></a> getRegularExpression( $name ) -> $expr
1506 Retrieves a TWiki predefined regular expression or character class.
1508 - `$name` - Name of the expression to retrieve. See notes below
1510 Return: String or precompiled regular expression matching as described below.
1512 **Since:** TWiki::Plugins::VERSION 1.020 (9 Feb 2004)
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.
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:
1518 my $upper = TWiki::Func::getRegularExpression('upperAlpha');
1519 my $alpha = TWiki::Func::getRegularExpression('mixedAlpha');
1520 my $capitalized = qr/[$upper][$alpha]+/;
1522 Those expressions marked type 'RE' are precompiled regular expressions that can be used outside square brackets. For example:
1524 my $webRE = TWiki::Func::getRegularExpression('webNameRegex');
1525 my $isWebName = ( $s =~ m/$webRE/ );
1527 <table border="1" cellpadding="0" cellspacing="0">
1529 <th bgcolor="#99CCCC"><strong> Name </strong></th>
1530 <th bgcolor="#99CCCC"><strong> Matches </strong></th>
1531 <th bgcolor="#99CCCC"><strong> Type </strong></th>
1534 <td> upperAlpha </td>
1535 <td> Upper case characters </td>
1539 <td> upperAlphaNum </td>
1540 <td> Upper case characters and digits </td>
1544 <td> lowerAlpha </td>
1545 <td> Lower case characters </td>
1549 <td> lowerAlphaNum </td>
1550 <td> Lower case characters and digits </td>
1559 <td> mixedAlpha </td>
1560 <td> Alphabetic characters </td>
1564 <td> mixedAlphaNum </td>
1565 <td> Alphanumeric characters </td>
1569 <td> wikiWordRegex </td>
1570 <td>[[Main/WikiWords]]</td>
1574 <td> webNameRegex </td>
1575 <td> User web names </td>
1579 <td> anchorRegex </td>
1580 <td> #AnchorNames </td>
1584 <td> abbrevRegex </td>
1585 <td> Abbreviations e.g. GOV, IRS </td>
1589 <td> emailAddrRegex </td>
1590 <td><a href="mailto:email@address.com">email@address.com</a></td>
1594 <td> tagNameRegex </td>
1595 <td> Standard variable names e.g. %THIS_BIT% (THIS_BIT only) </td>
1600 ### <a name="normalize_WebTopicName($web, $to"></a> normalizeWebTopicName($web, $topic) -> ($web, $topic)
1602 Parse a web and topic name, supplying defaults as appropriate.
1604 - `$web` - Web name, identifying variable, or empty string
1605 - `$topic` - Topic name, may be a web.topic string, required.
1607 Return: the parsed Web/Topic pair
1609 **Since:** TWiki::Plugins::VERSION 1.1
1611 <table border="1" cellpadding="0" cellspacing="0">
1613 <th bgcolor="#99CCCC"><strong> Input </strong></th>
1614 <th bgcolor="#99CCCC"><strong> Return </strong></th>
1617 <td><tt>( 'Web', 'Topic' ) </tt></td>
1618 <td><tt>( 'Web', 'Topic' ) </tt></td>
1621 <td><tt>( '', 'Topic' ) </tt></td>
1622 <td><tt>( 'Main', 'Topic' ) </tt></td>
1625 <td><tt>( '', '' ) </tt></td>
1626 <td><tt>( 'Main', 'WebHome' ) </tt></td>
1629 <td><tt>( '', 'Web/Topic' ) </tt></td>
1630 <td><tt>( 'Web', 'Topic' ) </tt></td>
1633 <td><tt>( '', 'Web/Subweb/Topic' ) </tt></td>
1634 <td><tt>( 'Web/Subweb', 'Topic' ) </tt></td>
1637 <td><tt>( '', 'Web.Topic' ) </tt></td>
1638 <td><tt>( 'Web', 'Topic' ) </tt></td>
1641 <td><tt>( '', 'Web.Subweb.Topic' ) </tt></td>
1642 <td><tt>( 'Web/Subweb', 'Topic' ) </tt></td>
1645 <td><tt>( 'Web1', 'Web2.Topic' )</tt></td>
1646 <td><tt>( 'Web2', 'Topic' ) </tt></td>
1650 Note that hierarchical web names ([[SubWeb]]) are only available if hierarchical webs are enabled in `configure`.
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:
1654 <table border="1" cellpadding="0" cellspacing="0">
1656 <th bgcolor="#99CCCC"><strong> Input </strong></th>
1657 <th bgcolor="#99CCCC"><strong> Return </strong></th>
1660 <td><tt>( '%USERSWEB%', 'Topic' )</tt></td>
1661 <td><tt>( 'Main', 'Topic' ) </tt></td>
1664 <td><tt>( '%SYSTEMWEB%', 'Topic' )</tt></td>
1665 <td><tt>( 'TWiki', 'Topic' ) </tt></td>
1668 <td><tt>( '', '%DOCWEB%.Topic' )</tt></td>
1669 <td><tt>( 'TWiki', 'Topic' ) </tt></td>
1673 ## <a name="StaticMethod <strong>sanitize_Attachmen"></a> [[StaticMethod]] \*sanitizeAttachmentName `($fname) -> ($fileName,$origName)`
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.
1677 Sanitation includes filtering illegal characters and mapping client file names to legal server names.
1679 **Since:** TWiki::Plugins::VERSION 1.2
1681 ### <a name="space_OutWikiWord( $word, $sep )"></a> spaceOutWikiWord( $word, $sep ) -> $text
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.
1685 **Since:** TWiki::Plugins::VERSION 1.2
1687 ### <a name="writeWarning( $text )"></a> writeWarning( $text )
1689 Log Warning that may require admin intervention to data/warning.txt
1691 - `$text` - Text to write; timestamp gets added
1695 **Since:** TWiki::Plugins::VERSION 1.020 (16 Feb 2004)
1697 ### <a name="writeDebug( $text )"></a> writeDebug( $text )
1699 Log debug message to data/debug.txt
1701 - `$text` - Text to write; timestamp gets added
1705 **Since:** TWiki::Plugins::VERSION 1.020 (16 Feb 2004)
1707 ### <a name="formatTime( $time, $format, $tim"></a> formatTime( $time, $format, $timezone ) -> $text
1709 Format the time in seconds into the desired time string
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'
1715 Return: `$text` Formatted time string
1717 <table border="1" cellpadding="0" cellspacing="0">
1720 <td> if you used the removed formatGmTime, add a third parameter 'gmtime' </td>
1724 **Since:** TWiki::Plugins::VERSION 1.020 (26 Feb 2004)
1726 ### <a name="isTrue( $value, $default ) - $bo"></a> isTrue( $value, $default ) -> $boolean
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.
1730 If the value is undef, then `$default` is returned. If `$default` is not specified it is taken as 0.
1732 **Since:** $TWiki::Plugins::VERSION 1.2
1734 ### <a name="is_ValidWikiWord ( $text ) - $bo"></a> isValidWikiWord ( $text ) -> $boolean
1736 Check for a valid [[WikiWord]] or [[WikiName]]
1738 - `$text` - Word to test
1740 **Since:** TWiki::Plugins::VERSION 1.100 (Dec 2005)
1742 ### <a name="extractParameters($attr ) - %par"></a> extractParameters($attr ) -> %params
1744 Extract all parameters from a variable string and returns a hash of parameters
1746 - `$attr` - Attribute string
1748 Return: `%params` Hash containing all parameters. The nameless parameter is stored in key `_DEFAULT`
1750 **Since:** TWiki::Plugins::VERSION 1.025 (26 Aug 2004)
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"`
1759 ### <a name="extract_NameValuePair( $attr, $n"></a> extractNameValuePair( $attr, $name ) -> $value
1761 Extract a named or unnamed value from a variable parameter string - Note: | Function TWiki::Func::extractParameters is more efficient for extracting several parameters
1763 - `$attr` - Attribute string
1764 - `$name` - Name, optional
1766 Return: `$value` Extracted value
1768 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
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" );`
1775 ## <a name="Deprecated functions"></a> Deprecated functions
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.
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%.
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:
1783 package TWiki::Plugins::SinkPlugin;
1784 use vars qw( %TWikiCompatibility );
1785 $TWikiCompatibility{endRenderingHandler} = 1.1;
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.
1789 The following functions are retained for compatibility only. You should stop using them as soon as possible.
1791 ### <a name="get_ScriptUrlPath( ) - $path"></a> getScriptUrlPath( ) -> $path
1795 **DEPRECATED** since 1.1 - use `getScriptUrl` instead.
1797 Return: `$path` URL path of TWiki scripts, e.g. `"/cgi-bin"`
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.
1801 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
1803 ### <a name="get_OopsUrl( $web, $topic, $temp"></a> getOopsUrl( $web, $topic, $template, $param1, $param2, $param3, $param4 ) -> $url
1805 Compose fully qualified 'oops' dialog URL
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
1812 Return: `$url` URL, e.g. `"http://example.com:80/cgi-bin/oops.pl/ Main/WebNotify?template=oopslocked¶m1=joe"`
1814 **DEPRECATED** since 1.1, the recommended approach is to throw an [[oops exception|Main/TWikiOopsExceptionDotPm]].
1816 use Error qw( :try );
1818 throw TWiki::OopsException(
1822 params => [ 'I got my toe stuck' ]);
1824 (this example will use the `oopstoestuckerror` template.)
1826 If this is not possible (e.g. in a REST handler that does not trap the exception) then you can use `getScriptUrl` instead:
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 );
1834 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
1836 ### <a name="permissionsSet( $web ) - $boolea"></a> permissionsSet( $web ) -> $boolean
1838 Test if any access restrictions are set for this web, ignoring settings on individual pages
1840 - `$web` - Web name, required, e.g. `'Sandbox'`
1842 **Since:** TWiki::Plugins::VERSION 1.000 (27 Feb 2001)
1844 **DEPRECATED** since 1.2 - use `getPreferencesValue` instead to determine what permissions are set on the web, for example:
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";
1856 ### <a name="get_PublicWebList( ) - @webs"></a> getPublicWebList( ) -> @webs
1858 **DEPRECATED** since 1.1 - use `getListOfWebs` instead.
1860 Get list of all public webs, e.g. all webs that do not have the `NOSEARCHALL` flag set in the [[WebPreferences]]
1862 Return: `@webs` List of all public webs, e.g. `( 'Main', 'Know', 'TWiki' )`
1864 **Since:** TWiki::Plugins::VERSION 1.000 (07 Dec 2002)
1866 ### <a name="format_GmTime( $time, $format )"></a><a name="format_GmTime( $time, $format ) "></a> formatGmTime( $time, $format ) -> $text
1868 **DEPRECATED** since 1.1 - use `formatTime` instead.
1870 Format the time to GM time
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'`)
1875 Return: `$text` Formatted time string
1877 **Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
1879 ### <a name="get_DataDir( ) - $dir"></a> getDataDir( ) -> $dir
1881 **DEPRECATED** since 1.1 - use the "Webs, Topics and Attachments" functions to manipulate topics instead
1883 Get data directory (topic file root)
1885 Return: `$dir` Data directory, e.g. `'/twiki/data'`
1887 This function violates store encapsulation and is therefore **deprecated**.
1889 **Since:** TWiki::Plugins::VERSION 1.000 (07 Dec 2002)
1891 ### <a name="get_PubDir( ) - $dir"></a> getPubDir( ) -> $dir
1893 **DEPRECATED** since 1.1 - use the "Webs, Topics and Attachments" functions to manipulateattachments instead
1895 Get pub directory (file attachment root). Attachments are in `$dir/Web/TopicName`
1897 Return: `$dir` Pub directory, e.g. `'/htdocs/twiki/pub'`
1899 This function violates store encapsulation and is therefore **deprecated**.
1901 Use `readAttachment` and `saveAttachment` instead.
1903 **Since:** TWiki::Plugins::VERSION 1.000 (07 Dec 2002)
1905 ### <a name="checkDependencies( $moduleName,"></a><a name="checkDependencies( $moduleName, "></a> checkDependencies( $moduleName, $dependenciesRef ) -> $error
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.
1909 **Since:** TWiki::Plugins::VERSION 1.025 (01 Aug 2004)