data/TWiki/TWikiFuncDotPm.txt,v
changeset 0 414e01d06fd5
child 1 e2915a7cbdfa
     1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/data/TWiki/TWikiFuncDotPm.txt,v	Sat Jan 26 15:50:53 2008 +0100
     1.3 @@ -0,0 +1,2140 @@
     1.4 +head	1.7;
     1.5 +access;
     1.6 +symbols;
     1.7 +locks; strict;
     1.8 +comment	@# @;
     1.9 +
    1.10 +
    1.11 +1.7
    1.12 +date	2008.01.22.03.21.24;	author TWikiContributor;	state Exp;
    1.13 +branches;
    1.14 +next	1.6;
    1.15 +
    1.16 +1.6
    1.17 +date	2007.03.03.14.51.50;	author TWikiContributor;	state Exp;
    1.18 +branches;
    1.19 +next	1.5;
    1.20 +
    1.21 +1.5
    1.22 +date	2007.02.05.00.18.38;	author TWikiContributor;	state Exp;
    1.23 +branches;
    1.24 +next	1.4;
    1.25 +
    1.26 +1.4
    1.27 +date	2007.01.16.04.12.01;	author TWikiContributor;	state Exp;
    1.28 +branches;
    1.29 +next	1.3;
    1.30 +
    1.31 +1.3
    1.32 +date	2006.10.25.00.21.59;	author TWikiContributor;	state Exp;
    1.33 +branches;
    1.34 +next	1.2;
    1.35 +
    1.36 +1.2
    1.37 +date	2006.06.25.16.26.33;	author TWikiContributor;	state Exp;
    1.38 +branches;
    1.39 +next	1.1;
    1.40 +
    1.41 +1.1
    1.42 +date	2006.02.01.12.01.25;	author TWikiContributor;	state Exp;
    1.43 +branches;
    1.44 +next	;
    1.45 +
    1.46 +
    1.47 +desc
    1.48 +@new-topic
    1.49 +@
    1.50 +
    1.51 +
    1.52 +1.7
    1.53 +log
    1.54 +@buildrelease
    1.55 +@
    1.56 +text
    1.57 +@---+ Package =TWiki::Func=
    1.58 +
    1.59 +<!-- STARTINCLUDE required for huge TWikiDocumentation topic -->
    1.60 +%STARTINCLUDE%
    1.61 +
    1.62 +_Official list of stable TWiki functions for Plugin developers_
    1.63 +
    1.64 +This module defines official functions that [[%SYSTEMWEB%.TWikiPlugins][Plugins]]
    1.65 +can use to interact with the TWiki engine and content.
    1.66 +
    1.67 +Refer to TWiki.EmptyPlugin and lib/TWiki/Plugins/EmptyPlugin.pm for a template Plugin and documentation on how to write a Plugin.
    1.68 +
    1.69 +Plugins should *only* use functions published in this module. If you use
    1.70 +functions in other TWiki libraries you might create a security hole and
    1.71 +you will probably need to change your Plugin when you upgrade TWiki.
    1.72 +
    1.73 +Deprecated functions will still work in older code, though they should
    1.74 +_not_ be called in new Plugins and should be replaced in older Plugins
    1.75 +as soon as possible.
    1.76 +
    1.77 +The version of the TWiki::Func module is defined by the VERSION number of the
    1.78 +TWiki::Plugins module, currently %PLUGINVERSION%. This can be shown
    1.79 +by the =%<nop>PLUGINVERSION%= TWiki variable, and accessed in code using
    1.80 +=$TWiki::Plugins::VERSION=. The 'Since' field in the function
    1.81 +documentation refers to =$TWiki::Plugins::VERSION=.
    1.82 +
    1.83 +Notes on use of =$TWiki::Plugins::VERSION= (from 1.2 forwards):
    1.84 +   * If the *major* version (e.g. =1.=) is the same then any plugin coded
    1.85 +     to use any *earlier* revision of the =1.= API will still work. No
    1.86 +     function has been removed from the interface, nor has any API published
    1.87 +     in that version changed in such a way as to *require* plugins to be
    1.88 +     recoded.
    1.89 +   * If the *minor* version (e.g. 1.1) is incremented there may be changes
    1.90 +     in the API that may help improve the coding of some plugins - for
    1.91 +     example, new interfaces giving access to previously hidden core functions.
    1.92 +     In addition, *deprecation* of functions in the interface trigger a minor
    1.93 +     version increment. Note that deprecated functions are not _removed_, they
    1.94 +     are merely frozen, and plugin authors are recommended to stop using them.
    1.95 +   * Any additional digits in the version number relate to minor changes, such
    1.96 +     as the addition of parameters to the existing functions, or addition of
    1.97 +     utility functions that are unlikely to require significant changes to
    1.98 +     existing plugins.
    1.99 +   * =TWiki::Plugins::VERSION= also applies to the plugin handlers. The
   1.100 +     handlers are documented in the !EmptyPlugin, and that module indicates
   1.101 +     what version of =TWiki::Plugins::VERSION= it relates to.
   1.102 +A full history of the changes to this API can be found at the end of this
   1.103 +topic.
   1.104 +
   1.105 +
   1.106 +%TOC%
   1.107 +
   1.108 +---++ Environment
   1.109 +
   1.110 +
   1.111 +---+++ getSkin( ) -> $skin
   1.112 +
   1.113 +Get the skin path, set by the =SKIN= and =COVER= preferences variables or the =skin= and =cover= CGI parameters
   1.114 +
   1.115 +Return: =$skin= Comma-separated list of skins, e.g. ='gnu,tartan'=. Empty string if none.
   1.116 +
   1.117 +*Since:* TWiki::Plugins::VERSION 1.000 (29 Jul 2001)
   1.118 +
   1.119 +
   1.120 +---+++ getUrlHost( ) -> $host
   1.121 +
   1.122 +Get protocol, domain and optional port of script URL
   1.123 +
   1.124 +Return: =$host= URL host, e.g. ="http://example.com:80"=
   1.125 +
   1.126 +*Since:* TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
   1.127 +
   1.128 +
   1.129 +---+++ getScriptUrl( $web, $topic, $script, ... ) -> $url
   1.130 +
   1.131 +Compose fully qualified URL
   1.132 +   * =$web=    - Web name, e.g. ='Main'=
   1.133 +   * =$topic=  - Topic name, e.g. ='WebNotify'=
   1.134 +   * =$script= - Script name, e.g. ='view'=
   1.135 +   * =...= - 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. <tt>getScriptUrl('x','y','view','#'=>'XXX',a=>1,b=>2)</tt> will give <tt>.../view/x/y?a=1&b=2#XXX</tt>
   1.136 +
   1.137 +Return: =$url=       URL, e.g. ="http://example.com:80/cgi-bin/view.pl/Main/WebNotify"=
   1.138 +
   1.139 +*Since:* TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
   1.140 +
   1.141 +
   1.142 +---+++ getViewUrl( $web, $topic ) -> $url
   1.143 +
   1.144 +Compose fully qualified view URL
   1.145 +   * =$web=   - Web name, e.g. ='Main'=. The current web is taken if empty
   1.146 +   * =$topic= - Topic name, e.g. ='WebNotify'=
   1.147 +Return: =$url=      URL, e.g. ="http://example.com:80/cgi-bin/view.pl/Main/WebNotify"=
   1.148 +
   1.149 +*Since:* TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
   1.150 +
   1.151 +
   1.152 +---+++ getPubUrlPath( ) -> $path
   1.153 +
   1.154 +Get pub URL path
   1.155 +
   1.156 +Return: =$path= URL path of pub directory, e.g. ="/pub"=
   1.157 +
   1.158 +*Since:* TWiki::Plugins::VERSION 1.000 (14 Jul 2001)
   1.159 +
   1.160 +
   1.161 +---+++ getExternalResource( $url ) -> $response
   1.162 +
   1.163 +Get whatever is at the other end of a URL (using an HTTP GET request). Will
   1.164 +only work for encrypted protocols such as =https= if the =LWP= CPAN module is
   1.165 +installed.
   1.166 +
   1.167 +Note that the =$url= may have an optional user and password, as specified by
   1.168 +the relevant RFC. Any proxy set in =configure= is honoured.
   1.169 +
   1.170 +The =$response= is an object that is known to implement the following subset of
   1.171 +the methods of =LWP::Response=. It may in fact be an =LWP::Response= object,
   1.172 +but it may also not be if =LWP= is not available, so callers may only assume
   1.173 +the following subset of methods is available:
   1.174 +| =code()= |
   1.175 +| =message()= |
   1.176 +| =header($field)= |
   1.177 +| =content()= |
   1.178 +| =is_error()= |
   1.179 +| =is_redirect()= |
   1.180 +
   1.181 +Note that if LWP is *not* available, this function:
   1.182 +   1 can only really be trusted for HTTP/1.0 urls. If HTTP/1.1 or another
   1.183 +     protocol is required, you are *strongly* recommended to =require LWP=.
   1.184 +   1 Will not parse multipart content
   1.185 +
   1.186 +In the event of the server returning an error, then =is_error()= will return
   1.187 +true, =code()= will return a valid HTTP status code
   1.188 +as specified in RFC 2616 and RFC 2518, and =message()= will return the
   1.189 +message that was received from
   1.190 +the server. In the event of a client-side error (e.g. an unparseable URL)
   1.191 +then =is_error()= will return true and =message()= will return an explanatory
   1.192 +message. =code()= will return 400 (BAD REQUEST).
   1.193 +
   1.194 +Note: Callers can easily check the availability of other HTTP::Response methods
   1.195 +as follows:
   1.196 +
   1.197 +<verbatim>
   1.198 +my $response = TWiki::Func::getExternalResource($url);
   1.199 +if (!$response->is_error() && $response->isa('HTTP::Response')) {
   1.200 +    ... other methods of HTTP::Response may be called
   1.201 +} else {
   1.202 +    ... only the methods listed above may be called
   1.203 +}
   1.204 +</verbatim>
   1.205 +
   1.206 +*Since:* TWiki::Plugins::VERSION 1.2
   1.207 +
   1.208 +
   1.209 +---+++ getCgiQuery( ) -> $query
   1.210 +
   1.211 +Get CGI query object. Important: Plugins cannot assume that scripts run under CGI, Plugins must always test if the CGI query object is set
   1.212 +
   1.213 +Return: =$query= CGI query object; or 0 if script is called as a shell script
   1.214 +
   1.215 +*Since:* TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
   1.216 +
   1.217 +
   1.218 +---+++ getSessionKeys() -> @@keys
   1.219 +Get a list of all the names of session variables. The list is unsorted.
   1.220 +
   1.221 +Session keys are stored and retrieved using =setSessionValue= and
   1.222 +=getSessionValue=.
   1.223 +
   1.224 +*Since:* TWiki::Plugins::VERSION 1.2
   1.225 +
   1.226 +
   1.227 +---+++ getSessionValue( $key ) -> $value
   1.228 +
   1.229 +Get a session value from the client session module
   1.230 +   * =$key= - Session key
   1.231 +Return: =$value=  Value associated with key; empty string if not set
   1.232 +
   1.233 +*Since:* TWiki::Plugins::VERSION 1.000 (27 Feb 200)
   1.234 +
   1.235 +
   1.236 +---+++ setSessionValue( $key, $value ) -> $boolean
   1.237 +
   1.238 +Set a session value.
   1.239 +   * =$key=   - Session key
   1.240 +   * =$value= - Value associated with key
   1.241 +Return: true if function succeeded
   1.242 +
   1.243 +*Since:* TWiki::Plugins::VERSION 1.000 (17 Aug 2001)
   1.244 +
   1.245 +
   1.246 +---+++ clearSessionValue( $key ) -> $boolean
   1.247 +
   1.248 +Clear a session value that was set using =setSessionValue=.
   1.249 +   * =$key= - name of value stored in session to be cleared. Note that
   1.250 +   you *cannot* clear =AUTHUSER=.
   1.251 +Return: true if the session value was cleared
   1.252 +
   1.253 +*Since:* TWiki::Plugins::VERSION 1.1
   1.254 +
   1.255 +
   1.256 +---+++ getContext() -> \%hash
   1.257 +
   1.258 +Get a hash of context identifiers representing the currently active
   1.259 +context.
   1.260 +
   1.261 +The context is a set of identifiers that are set
   1.262 +during specific phases of TWiki processing. For example, each of
   1.263 +the standard scripts in the 'bin' directory each has a context
   1.264 +identifier - the view script has 'view', the edit script has 'edit'
   1.265 +etc. So you can easily tell what 'type' of script your Plugin is
   1.266 +being called within. The core context identifiers are listed
   1.267 +in the %SYSTEMWEB%.TWikiTemplates topic. Please be careful not to
   1.268 +overwrite any of these identifiers!
   1.269 +
   1.270 +Context identifiers can be used to communicate between Plugins, and between
   1.271 +Plugins and templates. For example, in FirstPlugin.pm, you might write:
   1.272 +<verbatim>
   1.273 +sub initPlugin {
   1.274 +   TWiki::Func::getContext()->{'MyID'} = 1;
   1.275 +   ...
   1.276 +</verbatim>
   1.277 +This can be used in !SecondPlugin.pm like this:
   1.278 +<verbatim>
   1.279 +sub initPlugin {
   1.280 +   if( TWiki::Func::getContext()->{'MyID'} ) {
   1.281 +      ...
   1.282 +   }
   1.283 +   ...
   1.284 +</verbatim>
   1.285 +or in a template, like this:
   1.286 +<verbatim>
   1.287 +%TMPL:DEF{"ON"}% Not off %TMPL:END%
   1.288 +%TMPL:DEF{"OFF"}% Not on %TMPL:END%
   1.289 +%TMPL:P{context="MyID" then="ON" else="OFF"}%
   1.290 +</verbatim>
   1.291 +or in a topic:
   1.292 +<verbatim>
   1.293 +%IF{"context MyID" then="MyID is ON" else="MyID is OFF"}%
   1.294 +</verbatim>
   1.295 +__Note__: *all* plugins have an *automatically generated* context identifier
   1.296 +if they are installed and initialised. For example, if the FirstPlugin is
   1.297 +working, the context ID 'FirstPlugin' will be set.
   1.298 +
   1.299 +*Since:* TWiki::Plugins::VERSION 1.1
   1.300 +
   1.301 +
   1.302 +---+++ pushTopicContext($web, $topic)
   1.303 +   * =$web= - new web
   1.304 +   * =$topic= - new topic
   1.305 +Change the TWiki context so it behaves as if it was processing =$web.$topic=
   1.306 +from now on. All the preferences will be reset to those of the new topic.
   1.307 +Note that if the new topic is not readable by the logged in user due to
   1.308 +access control considerations, there will *not* be an exception. It is the
   1.309 +duty of the caller to check access permissions before changing the topic.
   1.310 +
   1.311 +It is the duty of the caller to restore the original context by calling
   1.312 +=popTopicContext=.
   1.313 +
   1.314 +Note that this call does *not* re-initialise plugins, so if you have used
   1.315 +global variables to remember the web and topic in =initPlugin=, then those
   1.316 +values will be unchanged.
   1.317 +
   1.318 +*Since:* TWiki::Plugins::VERSION 1.2
   1.319 +
   1.320 +
   1.321 +---+++ popTopicContext()
   1.322 +
   1.323 +Returns the TWiki context to the state it was in before the
   1.324 +=pushTopicContext= was called.
   1.325 +
   1.326 +*Since:* TWiki::Plugins::VERSION 1.2
   1.327 +
   1.328 +
   1.329 +---++ Preferences
   1.330 +
   1.331 +
   1.332 +---+++ getPreferencesValue( $key, $web ) -> $value
   1.333 +
   1.334 +Get a preferences value from TWiki or from a Plugin
   1.335 +   * =$key= - Preferences key
   1.336 +   * =$web= - Name of web, optional. Current web if not specified; does not apply to settings of Plugin topics
   1.337 +Return: =$value=  Preferences value; empty string if not set
   1.338 +
   1.339 +*Since:* TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
   1.340 +
   1.341 +   * Example for Plugin setting:
   1.342 +      * MyPlugin topic has: =* Set COLOR = red=
   1.343 +      * Use ="MYPLUGIN_COLOR"= for =$key=
   1.344 +      * =my $color = TWiki::Func::getPreferencesValue( "MYPLUGIN_COLOR" );=
   1.345 +
   1.346 +   * Example for preferences setting:
   1.347 +      * WebPreferences topic has: =* Set WEBBGCOLOR = #FFFFC0=
   1.348 +      * =my $webColor = TWiki::Func::getPreferencesValue( 'WEBBGCOLOR', 'Sandbox' );=
   1.349 +
   1.350 +*NOTE:* As of TWiki4.1, if =$NO_PREFS_IN_TOPIC= is enabled in the plugin, then
   1.351 +preferences set in the plugin topic will be ignored.
   1.352 +
   1.353 +
   1.354 +---+++ getPluginPreferencesValue( $key ) -> $value
   1.355 +
   1.356 +Get a preferences value from your Plugin
   1.357 +   * =$key= - Plugin Preferences key w/o PLUGINNAME_ prefix.
   1.358 +Return: =$value=  Preferences value; empty string if not set
   1.359 +
   1.360 +__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)
   1.361 +
   1.362 +*Since:* TWiki::Plugins::VERSION 1.021 (27 Mar 2004)
   1.363 +
   1.364 +*NOTE:* As of TWiki4.1, if =$NO_PREFS_IN_TOPIC= is enabled in the plugin, then
   1.365 +preferences set in the plugin topic will be ignored.
   1.366 +
   1.367 +
   1.368 +---+++ getPreferencesFlag( $key, $web ) -> $value
   1.369 +
   1.370 +Get a preferences flag from TWiki or from a Plugin
   1.371 +   * =$key= - Preferences key
   1.372 +   * =$web= - Name of web, optional. Current web if not specified; does not apply to settings of Plugin topics
   1.373 +Return: =$value=  Preferences flag ='1'= (if set), or ="0"= (for preferences values ="off"=, ="no"= and ="0"=)
   1.374 +
   1.375 +*Since:* TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
   1.376 +
   1.377 +   * Example for Plugin setting:
   1.378 +      * MyPlugin topic has: =* Set SHOWHELP = off=
   1.379 +      * Use ="MYPLUGIN_SHOWHELP"= for =$key=
   1.380 +      * =my $showHelp = TWiki::Func::getPreferencesFlag( "MYPLUGIN_SHOWHELP" );=
   1.381 +
   1.382 +*NOTE:* As of TWiki4.1, if =$NO_PREFS_IN_TOPIC= is enabled in the plugin, then
   1.383 +preferences set in the plugin topic will be ignored.
   1.384 +
   1.385 +
   1.386 +---+++ getPluginPreferencesFlag( $key ) -> $boolean
   1.387 +
   1.388 +Get a preferences flag from your Plugin
   1.389 +   * =$key= - Plugin Preferences key w/o PLUGINNAME_ prefix.
   1.390 +Return: false for preferences values ="off"=, ="no"= and ="0"=, or values not set at all. True otherwise.
   1.391 +
   1.392 +__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)
   1.393 +
   1.394 +*Since:* TWiki::Plugins::VERSION 1.021 (27 Mar 2004)
   1.395 +
   1.396 +*NOTE:* As of TWiki4.1, if =$NO_PREFS_IN_TOPIC= is enabled in the plugin, then
   1.397 +preferences set in the plugin topic will be ignored.
   1.398 +
   1.399 +
   1.400 +---+++ setPreferencesValue($name, $val)
   1.401 +
   1.402 +Set the preferences value so that future calls to getPreferencesValue will
   1.403 +return this value, and =%$name%= will expand to the preference when used in
   1.404 +future variable expansions.
   1.405 +
   1.406 +The preference only persists for the rest of this request. Finalised
   1.407 +preferences cannot be redefined using this function.
   1.408 +
   1.409 +Returns 1 if the preference was defined, and 0 otherwise.
   1.410 +
   1.411 +
   1.412 +---+++ getWikiToolName( ) -> $name
   1.413 +
   1.414 +Get toolname as defined in TWiki.cfg
   1.415 +
   1.416 +Return: =$name= Name of tool, e.g. ='TWiki'=
   1.417 +
   1.418 +*Since:* TWiki::Plugins::VERSION 1.000 (27 Feb 2001)
   1.419 +
   1.420 +
   1.421 +---+++ getMainWebname( ) -> $name
   1.422 +
   1.423 +Get name of Main web as defined in TWiki.cfg
   1.424 +
   1.425 +Return: =$name= Name, e.g. ='Main'=
   1.426 +
   1.427 +*Since:* TWiki::Plugins::VERSION 1.000 (27 Feb 2001)
   1.428 +
   1.429 +
   1.430 +---+++ getTwikiWebname( ) -> $name
   1.431 +
   1.432 +Get name of TWiki documentation web as defined in TWiki.cfg
   1.433 +
   1.434 +Return: =$name= Name, e.g. ='TWiki'=
   1.435 +
   1.436 +*Since:* TWiki::Plugins::VERSION 1.000 (27 Feb 2001)
   1.437 +
   1.438 +
   1.439 +---++ User Handling and Access Control
   1.440 +---+++ getDefaultUserName( ) -> $loginName
   1.441 +Get default user name as defined in the configuration as =DefaultUserLogin=
   1.442 +
   1.443 +Return: =$loginName= Default user name, e.g. ='guest'=
   1.444 +
   1.445 +*Since:* TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
   1.446 +
   1.447 +
   1.448 +---+++ getCanonicalUserID( $user ) -> $cUID
   1.449 +Return the cUID of the specified user. A cUID is a unique identifier which
   1.450 +is assigned by TWiki for each user.
   1.451 +BEWARE: While the default TWikiUserMapping uses a cUID that looks like a user's
   1.452 +LoginName, some characters are modified to make them compatible with rcs.
   1.453 +Additionally, other usermappings will use other conventions - the JoomlauserMapping
   1.454 +for example, has cUIDs like 'JoomlaeUserMapping_1234'.
   1.455 + 
   1.456 +If $user is undefined Get the cUID of logged in user, and will generally be
   1.457 +'BaseUserMapping_666'
   1.458 + 
   1.459 +   * $user can be a cUID, login, wikiname or web.wikiname
   1.460 + 
   1.461 +Return: =$cUID= an internal unique and transportable escaped identifier for
   1.462 +registered users (they can be autogenerated for an authenticated but unregistered
   1.463 +user)
   1.464 + 
   1.465 +*Since:* TWiki::Plugins::VERSION 1.2
   1.466 +
   1.467 +
   1.468 +---+++ getWikiName( $user ) -> $wikiName
   1.469 +
   1.470 +return the WikiName of the specified user
   1.471 +if $user is undefined Get Wiki name of logged in user
   1.472 +
   1.473 +   * $user can be a cUID, login, wikiname or web.wikiname
   1.474 +
   1.475 +Return: =$wikiName= Wiki Name, e.g. ='JohnDoe'=
   1.476 +
   1.477 +*Since:* TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
   1.478 +
   1.479 + 
   1.480 +---+++ getWikiUserName( $user ) -> $wikiName
   1.481 +
   1.482 +return the userWeb.WikiName of the specified user
   1.483 +if $user is undefined Get Wiki name of logged in user
   1.484 + 
   1.485 +   * $user can be a cUID, login, wikiname or web.wikiname
   1.486 +
   1.487 +Return: =$wikiName= Wiki Name, e.g. ="Main.JohnDoe"=
   1.488 +
   1.489 +*Since:* TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
   1.490 +
   1.491 +
   1.492 +---+++ wikiToUserName( $wikiName ) -> $loginName
   1.493 +Translate a Wiki name (or login name or cUID, if it can) to a login name.
   1.494 +   * =$wikiName= - Wiki name, e.g. ='Main.JohnDoe'= or ='JohnDoe'=
   1.495 +Return: =$loginName=   Login name of user, e.g. ='jdoe'=, or undef if not
   1.496 +matched.
   1.497 +
   1.498 +Note that it is possible for several login names to map to the same wikiname.
   1.499 +This function will only return the *first* login name that maps to the
   1.500 +wikiname.
   1.501 +
   1.502 +returns undef if the WikiName is not found.
   1.503 +
   1.504 +*Since:* TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
   1.505 +
   1.506 +
   1.507 +---+++ userToWikiName( $loginName, $dontAddWeb ) -> $wikiName
   1.508 +Translate a login name to a Wiki name
   1.509 +   * =$loginName=  - Login name, e.g. ='jdoe'=
   1.510 +   * =$dontAddWeb= - Do not add web prefix if ="1"=
   1.511 +Return: =$wikiName=      Wiki name of user, e.g. ='Main.JohnDoe'= or ='JohnDoe'=
   1.512 +
   1.513 +userToWikiName will always return a name, if the user does not
   1.514 +exist in the mapping, the $loginName parameter is returned. (backward compatibility)
   1.515 +
   1.516 +*Since:* TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
   1.517 +
   1.518 +
   1.519 +---+++ emailToWikiNames( $email, $dontAddWeb ) -> @@wikiNames
   1.520 +   * =$email= - email address to look up
   1.521 +   * =$dontAddWeb= - Do not add web prefix if ="1"=
   1.522 +Find the wikinames of all users who have the given email address as their
   1.523 +registered address. Since several users could register with the same email
   1.524 +address, this returns a list of wikinames rather than a single wikiname.
   1.525 +
   1.526 +*Since:* TWiki::Plugins::VERSION 1.2
   1.527 +
   1.528 +
   1.529 +---+++ wikiNameToEmails( $wikiname ) -> @@emails
   1.530 +   * =$wikiname= - wikiname of user to look up
   1.531 +Returns the registered email addresses of the named user. If $wikiname is
   1.532 +undef, returns the registered email addresses for the logged-in user.
   1.533 +
   1.534 +*Since:* TWiki::Plugins::VERSION 1.2
   1.535 +
   1.536 +
   1.537 +---+++ isGuest( ) -> $boolean
   1.538 +
   1.539 +Test if logged in user is a guest (TWikiGuest)
   1.540 +
   1.541 +*Since:* TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
   1.542 +
   1.543 +
   1.544 +---+++ isAnAdmin( $login ) -> $boolean
   1.545 +
   1.546 +Find out if the user is an admin or not. If the user is not given,
   1.547 +the currently logged-in user is assumed.
   1.548 +   * $login can be either a login, or a CUID
   1.549 +
   1.550 +*Since:* TWiki::Plugins::VERSION 1.2
   1.551 +
   1.552 +
   1.553 +---+++ isGroupMember( $group, $login ) -> $boolean
   1.554 +
   1.555 +Find out if $login is in the named group. e.g.
   1.556 +<verbatim>
   1.557 +if( TWiki::Func::isGroupMember( "HesperionXXGroup", "jordi" )) {
   1.558 +    ...
   1.559 +}
   1.560 +</verbatim>
   1.561 +If =$user= is =undef=, it defaults to the currently logged-in user.
   1.562 +
   1.563 +   * $login can be a login name, or a cUID, or WikiName
   1.564 +
   1.565 +*Since:* TWiki::Plugins::VERSION 1.2
   1.566 +
   1.567 +
   1.568 +---+++ eachUser() -> $iterator
   1.569 +Get an iterator over the list of all the registered users *not* including
   1.570 +groups. The iterator will return each wiki name in turn (e.g. 'FredBloggs').
   1.571 +
   1.572 +Use it as follows:
   1.573 +<verbatim>
   1.574 +    my $iterator = TWiki::Func::eachUser();
   1.575 +    while ($it->hasNext()) {
   1.576 +        my $user = $it->next();
   1.577 +        # $user is a wikiname
   1.578 +    }
   1.579 +</verbatim>
   1.580 +
   1.581 +*WARNING* on large sites, this could be a long list!
   1.582 +
   1.583 +*Since:* TWiki::Plugins::VERSION 1.2
   1.584 +
   1.585 +
   1.586 +---+++ eachMembership($wikiname) -> $iterator
   1.587 +Get an iterator over the names of all groups that the user is a member of.
   1.588 +If =$wikiname= is =undef=, defaults to the currently logged-in user.
   1.589 +
   1.590 +*Since:* TWiki::Plugins::VERSION 1.2
   1.591 +
   1.592 +
   1.593 +---+++ eachGroup() -> $iterator
   1.594 +Get an iterator over all groups.
   1.595 +
   1.596 +Use it as follows:
   1.597 +<verbatim>
   1.598 +    my $iterator = TWiki::Func::eachGroup();
   1.599 +    while ($it->hasNext()) {
   1.600 +        my $group = $it->next();
   1.601 +        # $group is a group name e.g. TWikiAdminGroup
   1.602 +    }
   1.603 +</verbatim>
   1.604 +
   1.605 +*WARNING* on large sites, this could be a long list!
   1.606 +
   1.607 +*Since:* TWiki::Plugins::VERSION 1.2
   1.608 +
   1.609 +
   1.610 +---+++ isGroup( $group ) -> $boolean
   1.611 +
   1.612 +Checks if =$group= is the name of a group known to TWiki.
   1.613 +
   1.614 +
   1.615 +---+++ eachGroupMember($group) -> $iterator
   1.616 +Get an iterator over all the members of the named group. Returns undef if
   1.617 +$group is not a valid group.
   1.618 +
   1.619 +Use it as follows:
   1.620 +<verbatim>
   1.621 +    my $iterator = TWiki::Func::eachGroupMember('RadioheadGroup');
   1.622 +    while ($it->hasNext()) {
   1.623 +        my $user = $it->next();
   1.624 +        # $user is a wiki name e.g. 'TomYorke', 'PhilSelway'
   1.625 +    }
   1.626 +</verbatim>
   1.627 +
   1.628 +*WARNING* on large sites, this could be a long list!
   1.629 +
   1.630 +*Since:* TWiki::Plugins::VERSION 1.2
   1.631 +
   1.632 +
   1.633 +---+++ checkAccessPermission( $type, $wikiName, $text, $topic, $web, $meta ) -> $boolean
   1.634 +
   1.635 +Check access permission for a topic based on the
   1.636 +[[%SYSTEMWEB%.TWikiAccessControl]] rules
   1.637 +   * =$type=     - Access type, required, e.g. ='VIEW'=, ='CHANGE'=.
   1.638 +   * =$wikiName= - WikiName of remote user, required, e.g. ="PeterThoeny"=.
   1.639 +     If =$wikiName= is '', 0 or =undef= then access is *always permitted*.
   1.640 +   * =$text=     - Topic text, optional. If 'perl false' (undef, 0 or ''),
   1.641 +     topic =$web.$topic= is consulted. =$text= may optionally contain embedded
   1.642 +     =%META:PREFERENCE= tags. Provide this parameter if:
   1.643 +      1 You are setting different access controls in the text to those defined
   1.644 +      in the stored topic,
   1.645 +      1 You already have the topic text in hand, and want to help TWiki avoid
   1.646 +        having to read it again,
   1.647 +      1 You are providing a =$meta= parameter.
   1.648 +   * =$topic=    - Topic name, required, e.g. ='PrivateStuff'=
   1.649 +   * =$web=      - Web name, required, e.g. ='Sandbox'=
   1.650 +   * =$meta=     - Meta-data object, as returned by =readTopic=. Optional.
   1.651 +     If =undef=, but =$text= is defined, then access controls will be parsed
   1.652 +     from =$text=. If defined, then metadata embedded in =$text= will be
   1.653 +     ignored. This parameter is always ignored if =$text= is undefined.
   1.654 +     Settings in =$meta= override =Set= settings in $text.
   1.655 +A perl true result indicates that access is permitted.
   1.656 +
   1.657 +*Note* the wierd parameter order is due to compatibility constraints with
   1.658 +earlier TWiki releases.
   1.659 +
   1.660 +*Tip* if you want, you can use this method to check your own access control types. For example, if you:
   1.661 +   * Set ALLOWTOPICSPIN = IncyWincy
   1.662 +in =ThatWeb.ThisTopic=, then a call to =checkAccessPermissions('SPIN', 'IncyWincy', undef, 'ThisTopic', 'ThatWeb', undef)= will return =true=.
   1.663 +
   1.664 +*Since:* TWiki::Plugins::VERSION 1.000 (27 Feb 2001)
   1.665 +
   1.666 +
   1.667 +---++ Webs, Topics and Attachments
   1.668 +
   1.669 +
   1.670 +---+++ getListOfWebs( $filter ) -> @@webs
   1.671 +
   1.672 +   * =$filter= - spec of web types to recover
   1.673 +Gets a list of webs, filtered according to the spec in the $filter,
   1.674 +which may include one of:
   1.675 +   1 'user' (for only user webs)
   1.676 +   2 'template' (for only template webs i.e. those starting with "_")
   1.677 +=$filter= may also contain the word 'public' which will further filter
   1.678 +out webs that have NOSEARCHALL set on them.
   1.679 +'allowed' filters out webs the current user can't read.
   1.680 +
   1.681 +For example, the deprecated getPublicWebList function can be duplicated
   1.682 +as follows:
   1.683 +<verbatim>
   1.684 +   my @@webs = TWiki::Func::getListOfWebs( "user,public" );
   1.685 +</verbatim>
   1.686 +
   1.687 +*Since:* TWiki::Plugins::VERSION 1.1
   1.688 +
   1.689 +
   1.690 +---+++ webExists( $web ) -> $boolean
   1.691 +
   1.692 +Test if web exists
   1.693 +   * =$web= - Web name, required, e.g. ='Sandbox'=
   1.694 +
   1.695 +*Since:* TWiki::Plugins::VERSION 1.000 (14 Jul 2001)
   1.696 +
   1.697 +
   1.698 +---+++ createWeb( $newWeb, $baseWeb, $opts )
   1.699 +
   1.700 +   * =$newWeb= is the name of the new web.
   1.701 +   * =$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.
   1.702 +   * =$opts= is a ref to a hash that contains settings to be modified in
   1.703 +the web preferences topic in the new web.
   1.704 +
   1.705 +<verbatim>
   1.706 +use Error qw( :try );
   1.707 +use TWiki::AccessControlException;
   1.708 +
   1.709 +try {
   1.710 +    TWiki::Func::createWeb( "Newweb" );
   1.711 +} catch Error::Simple with {
   1.712 +    my $e = shift;
   1.713 +    # see documentation on Error::Simple
   1.714 +} catch TWiki::AccessControlException with {
   1.715 +    my $e = shift;
   1.716 +    # see documentation on TWiki::AccessControlException
   1.717 +} otherwise {
   1.718 +    ...
   1.719 +};
   1.720 +</verbatim>
   1.721 +
   1.722 +*Since:* TWiki::Plugins::VERSION 1.1
   1.723 +
   1.724 +
   1.725 +---+++ moveWeb( $oldName, $newName )
   1.726 +
   1.727 +Move (rename) a web.
   1.728 +
   1.729 +<verbatim>
   1.730 +use Error qw( :try );
   1.731 +use TWiki::AccessControlException;
   1.732 +
   1.733 +try {
   1.734 +    TWiki::Func::moveWeb( "Oldweb", "Newweb" );
   1.735 +} catch Error::Simple with {
   1.736 +    my $e = shift;
   1.737 +    # see documentation on Error::Simple
   1.738 +} catch TWiki::AccessControlException with {
   1.739 +    my $e = shift;
   1.740 +    # see documentation on TWiki::AccessControlException
   1.741 +} otherwise {
   1.742 +    ...
   1.743 +};
   1.744 +</verbatim>
   1.745 +
   1.746 +To delete a web, move it to a subweb of =Trash=
   1.747 +<verbatim>
   1.748 +TWiki::Func::moveWeb( "Deadweb", "Trash.Deadweb" );
   1.749 +</verbatim>
   1.750 +
   1.751 +*Since:* TWiki::Plugins::VERSION 1.1
   1.752 +
   1.753 +
   1.754 +---+++ eachChangeSince($web, $time) -> $iterator
   1.755 +
   1.756 +Get an iterator over the list of all the changes in the given web between
   1.757 +=$time= and now. $time is a time in seconds since 1st Jan 1970, and is not
   1.758 +guaranteed to return any changes that occurred before (now - 
   1.759 +{Store}{RememberChangesFor}). {Store}{RememberChangesFor}) is a
   1.760 +setting in =configure=. Changes are returned in *most-recent-first*
   1.761 +order.
   1.762 +
   1.763 +Use it as follows:
   1.764 +<verbatim>
   1.765 +    my $iterator = TWiki::Func::eachChangeSince(
   1.766 +        $web, time() - 7 * 24 * 60 * 60); # the last 7 days
   1.767 +    while ($it->hasNext()) {
   1.768 +        my $change = $it->next();
   1.769 +        # $change is a perl hash that contains the following fields:
   1.770 +        # topic => topic name
   1.771 +        # user => wikiname - wikiname of user who made the change
   1.772 +        # time => time of the change
   1.773 +        # revision => revision number *after* the change
   1.774 +        # more => more info about the change (e.g. 'minor')
   1.775 +    }
   1.776 +</verbatim>
   1.777 +
   1.778 +
   1.779 +---+++ getTopicList( $web ) -> @@topics
   1.780 +
   1.781 +Get list of all topics in a web
   1.782 +   * =$web= - Web name, required, e.g. ='Sandbox'=
   1.783 +Return: =@@topics= Topic list, e.g. =( 'WebChanges',  'WebHome', 'WebIndex', 'WebNotify' )=
   1.784 +
   1.785 +*Since:* TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
   1.786 +
   1.787 +
   1.788 +---+++ topicExists( $web, $topic ) -> $boolean
   1.789 +
   1.790 +Test if topic exists
   1.791 +   * =$web=   - Web name, optional, e.g. ='Main'=.
   1.792 +   * =$topic= - Topic name, required, e.g. ='TokyoOffice'=, or ="Main.TokyoOffice"=
   1.793 +
   1.794 +$web and $topic are parsed as described in the documentation for =normalizeWebTopicName=.
   1.795 +Specifically, the %USERSWEB% is used if $web is not specified and $topic has no web specifier.
   1.796 +To get an expected behaviour it is recommened to specify the current web for $web; don't leave it empty.
   1.797 +
   1.798 +*Since:* TWiki::Plugins::VERSION 1.000 (14 Jul 2001)
   1.799 +
   1.800 +
   1.801 +---+++ checkTopicEditLock( $web, $topic, $script ) -> ( $oopsUrl, $loginName, $unlockTime )
   1.802 +
   1.803 +Check if a lease has been taken by some other user.
   1.804 +   * =$web= Web name, e.g. ="Main"=, or empty
   1.805 +   * =$topic= Topic name, e.g. ="MyTopic"=, or ="Main.MyTopic"=
   1.806 +Return: =( $oopsUrl, $loginName, $unlockTime )= - The =$oopsUrl= for calling redirectCgiQuery(), user's =$loginName=, and estimated =$unlockTime= in minutes, or ( '', '', 0 ) if no lease exists.
   1.807 +   * =$script= The script to invoke when continuing with the edit
   1.808 +
   1.809 +*Since:* TWiki::Plugins::VERSION 1.010 (31 Dec 2002)
   1.810 +
   1.811 +
   1.812 +---+++ setTopicEditLock( $web, $topic, $lock )
   1.813 +
   1.814 +   * =$web= Web name, e.g. ="Main"=, or empty
   1.815 +   * =$topic= Topic name, e.g. ="MyTopic"=, or ="Main.MyTopic"=
   1.816 +   * =$lock= 1 to lease the topic, 0 to clear an existing lease
   1.817 +
   1.818 +Takes out a "lease" on the topic. The lease doesn't prevent
   1.819 +anyone from editing and changing the topic, but it does redirect them
   1.820 +to a warning screen, so this provides some protection. The =edit= script
   1.821 +always takes out a lease.
   1.822 +
   1.823 +It is *impossible* to fully lock a topic. Concurrent changes will be
   1.824 +merged.
   1.825 +
   1.826 +*Since:* TWiki::Plugins::VERSION 1.010 (31 Dec 2002)
   1.827 +
   1.828 +
   1.829 +---+++ saveTopic( $web, $topic, $meta, $text, $options ) -> $error
   1.830 +
   1.831 +   * =$web= - web for the topic
   1.832 +   * =$topic= - topic name
   1.833 +   * =$meta= - reference to TWiki::Meta object
   1.834 +   * =$text= - text of the topic (without embedded meta-data!!!
   1.835 +   * =\%options= - ref to hash of save options
   1.836 +     =\%options= may include:
   1.837 +     | =dontlog= | don't log this change in twiki log |
   1.838 +     | =comment= | comment for save |
   1.839 +     | =minor= | True if this is a minor change, and is not to be notified |
   1.840 +Return: error message or undef.
   1.841 +
   1.842 +*Since:* TWiki::Plugins::VERSION 1.000 (29 Jul 2001)
   1.843 +
   1.844 +For example,
   1.845 +<verbatim>
   1.846 +my( $meta, $text ) = TWiki::Func::readTopic( $web, $topic )
   1.847 +$text =~ s/APPLE/ORANGE/g;
   1.848 +TWiki::Func::saveTopic( $web, $topic, $meta, $text, { comment => 'refruited' } );
   1.849 +</verbatim>
   1.850 +
   1.851 +__Note:__ Plugins handlers ( e.g. =beforeSaveHandler= ) will be called as
   1.852 +appropriate.
   1.853 +
   1.854 +
   1.855 +---+++ saveTopicText( $web, $topic, $text, $ignorePermissions, $dontNotify ) -> $oopsUrl
   1.856 +
   1.857 +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.
   1.858 +   * =$web=                - Web name, e.g. ='Main'=, or empty
   1.859 +   * =$topic=              - Topic name, e.g. ='MyTopic'=, or ="Main.MyTopic"=
   1.860 +   * =$text=               - Topic text to save, assumed to include meta data
   1.861 +   * =$ignorePermissions=  - Set to ="1"= if checkAccessPermission() is already performed and OK
   1.862 +   * =$dontNotify=         - Set to ="1"= if not to notify users of the change
   1.863 +Return: =$oopsUrl=               Empty string if OK; the =$oopsUrl= for calling redirectCgiQuery() in case of error
   1.864 +
   1.865 +This method is a lot less efficient and much more dangerous than =saveTopic=.
   1.866 +
   1.867 +*Since:* TWiki::Plugins::VERSION 1.010 (31 Dec 2002)
   1.868 +
   1.869 +<verbatim>
   1.870 +my $text = TWiki::Func::readTopicText( $web, $topic );
   1.871 +
   1.872 +# check for oops URL in case of error:
   1.873 +if( $text =~ /^http.*?\/oops/ ) {
   1.874 +    TWiki::Func::redirectCgiQuery( $query, $text );
   1.875 +    return;
   1.876 +}
   1.877 +# do topic text manipulation like:
   1.878 +$text =~ s/old/new/g;
   1.879 +# do meta data manipulation like:
   1.880 +$text =~ s/(META\:FIELD.*?name\=\"TopicClassification\".*?value\=\")[^\"]*/$1BugResolved/;
   1.881 +$oopsUrl = TWiki::Func::saveTopicText( $web, $topic, $text ); # save topic text
   1.882 +</verbatim>
   1.883 +
   1.884 +
   1.885 +---+++ moveTopic( $web, $topic, $newWeb, $newTopic )
   1.886 +
   1.887 +   * =$web= source web - required
   1.888 +   * =$topic= source topic - required
   1.889 +   * =$newWeb= dest web
   1.890 +   * =$newTopic= dest topic
   1.891 +Renames the topic. Throws an exception if something went wrong.
   1.892 +If $newWeb is undef, it defaults to $web. If $newTopic is undef, it defaults
   1.893 +to $topic.
   1.894 +
   1.895 +The destination topic must not already exist.
   1.896 +
   1.897 +Rename a topic to the $TWiki::cfg{TrashWebName} to delete it.
   1.898 +
   1.899 +*Since:* TWiki::Plugins::VERSION 1.1
   1.900 +
   1.901 +<verbatim>
   1.902 +use Error qw( :try );
   1.903 +
   1.904 +try {
   1.905 +    moveTopic( "Work", "TokyoOffice", "Trash", "ClosedOffice" );
   1.906 +} catch Error::Simple with {
   1.907 +    my $e = shift;
   1.908 +    # see documentation on Error::Simple
   1.909 +} catch TWiki::AccessControlException with {
   1.910 +    my $e = shift;
   1.911 +    # see documentation on TWiki::AccessControlException
   1.912 +} otherwise {
   1.913 +    ...
   1.914 +};
   1.915 +</verbatim>
   1.916 +
   1.917 +
   1.918 +---+++ getRevisionInfo($web, $topic, $rev, $attachment ) -> ( $date, $user, $rev, $comment ) 
   1.919 +
   1.920 +Get revision info of a topic or attachment
   1.921 +   * =$web= - Web name, optional, e.g. ='Main'=
   1.922 +   * =$topic=   - Topic name, required, e.g. ='TokyoOffice'=
   1.923 +   * =$rev=     - revsion number, or tag name (can be in the format 1.2, or just the minor number)
   1.924 +   * =$attachment=                 -attachment filename
   1.925 +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" )=
   1.926 +| $date | in epochSec |
   1.927 +| $user | Wiki name of the author (*not* login name) |
   1.928 +| $rev | actual rev number |
   1.929 +| $comment | WHAT COMMENT? |
   1.930 +
   1.931 +NOTE: if you are trying to get revision info for a topic, use
   1.932 +=$meta->getRevisionInfo= instead if you can - it is significantly
   1.933 +more efficient.
   1.934 +
   1.935 +*Since:* TWiki::Plugins::VERSION 1.000 (29 Jul 2001)
   1.936 +
   1.937 +
   1.938 +---+++ getRevisionAtTime( $web, $topic, $time ) -> $rev
   1.939 +
   1.940 +Get the revision number of a topic at a specific time.
   1.941 +   * =$web= - web for topic
   1.942 +   * =$topic= - topic
   1.943 +   * =$time= - time (in epoch secs) for the rev
   1.944 +Return: Single-digit revision number, or undef if it couldn't be determined
   1.945 +(either because the topic isn't that old, or there was a problem)
   1.946 +
   1.947 +*Since:* TWiki::Plugins::VERSION 1.1
   1.948 +
   1.949 +
   1.950 +---+++ readTopic( $web, $topic, $rev ) -> ( $meta, $text )
   1.951 +
   1.952 +Read topic text and meta data, regardless of access permissions.
   1.953 +   * =$web= - Web name, required, e.g. ='Main'=
   1.954 +   * =$topic= - Topic name, required, e.g. ='TokyoOffice'=
   1.955 +   * =$rev= - revision to read (default latest)
   1.956 +Return: =( $meta, $text )= Meta data object and topic text
   1.957 +
   1.958 +=$meta= is a perl 'object' of class =TWiki::Meta=. This class is
   1.959 +fully documented in the source code documentation shipped with the
   1.960 +release, or can be inspected in the =lib/TWiki/Meta.pm= file.
   1.961 +
   1.962 +This method *ignores* topic access permissions. You should be careful to use =checkAccessPermissions= to ensure the current user has read access to the topic.
   1.963 +
   1.964 +*Since:* TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
   1.965 +
   1.966 +
   1.967 +---+++ readTopicText( $web, $topic, $rev, $ignorePermissions ) -> $text
   1.968 +
   1.969 +Read topic text, including meta data
   1.970 +   * =$web=                - Web name, e.g. ='Main'=, or empty
   1.971 +   * =$topic=              - Topic name, e.g. ='MyTopic'=, or ="Main.MyTopic"=
   1.972 +   * =$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.
   1.973 +   * =$ignorePermissions=  - Set to ="1"= if checkAccessPermission() is already performed and OK; an oops URL is returned if user has no permission
   1.974 +Return: =$text=                  Topic text with embedded meta data; an oops URL for calling redirectCgiQuery() is returned in case of an error
   1.975 +
   1.976 +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.
   1.977 +
   1.978 +*Since:* TWiki::Plugins::VERSION 1.010 (31 Dec 2002)
   1.979 +
   1.980 +
   1.981 +---+++ attachmentExists( $web, $topic, $attachment ) -> $boolean
   1.982 +
   1.983 +Test if attachment exists
   1.984 +   * =$web=   - Web name, optional, e.g. =Main=.
   1.985 +   * =$topic= - Topic name, required, e.g. =TokyoOffice=, or =Main.TokyoOffice=
   1.986 +   * =$attachment= - attachment name, e.g.=logo.gif=
   1.987 +$web and $topic are parsed as described in the documentation for =normalizeWebTopicName=.
   1.988 +
   1.989 +*Since:* TWiki::Plugins::VERSION 1.1
   1.990 +
   1.991 +
   1.992 +---+++ readAttachment( $web, $topic, $name, $rev ) -> $data
   1.993 +
   1.994 +   * =$web= - web for topic
   1.995 +   * =$topic= - topic
   1.996 +   * =$name= - attachment name
   1.997 +   * =$rev= - revision to read (default latest)
   1.998 +Read an attachment from the store for a topic, and return it as a string. The
   1.999 +names of attachments on a topic can be recovered from the meta-data returned
  1.1000 +by =readTopic=. If the attachment does not exist, or cannot be read, undef
  1.1001 +will be returned. If the revision is not specified, the latest version will
  1.1002 +be returned.
  1.1003 +
  1.1004 +View permission on the topic is required for the
  1.1005 +read to be successful.  Access control violations are flagged by a
  1.1006 +TWiki::AccessControlException. Permissions are checked for the current user.
  1.1007 +
  1.1008 +<verbatim>
  1.1009 +my( $meta, $text ) = TWiki::Func::readTopic( $web, $topic );
  1.1010 +my @@attachments = $meta->find( 'FILEATTACHMENT' );
  1.1011 +foreach my $a ( @@attachments ) {
  1.1012 +   try {
  1.1013 +       my $data = TWiki::Func::readAttachment( $web, $topic, $a->{name} );
  1.1014 +       ...
  1.1015 +   } catch TWiki::AccessControlException with {
  1.1016 +   };
  1.1017 +}
  1.1018 +</verbatim>
  1.1019 +
  1.1020 +*Since:* TWiki::Plugins::VERSION 1.1
  1.1021 +
  1.1022 +
  1.1023 +---+++ saveAttachment( $web, $topic, $attachment, $opts )
  1.1024 +
  1.1025 +   * =$web= - web for topic
  1.1026 +   * =$topic= - topic to atach to
  1.1027 +   * =$attachment= - name of the attachment
  1.1028 +   * =$opts= - Ref to hash of options
  1.1029 +=$opts= may include:
  1.1030 +| =dontlog= | don't log this change in twiki log |
  1.1031 +| =comment= | comment for save |
  1.1032 +| =hide= | if the attachment is to be hidden in normal topic view |
  1.1033 +| =stream= | Stream of file to upload |
  1.1034 +| =file= | Name of a file to use for the attachment data. ignored if stream is set. Local file on the server. |
  1.1035 +| =filepath= | Client path to file |
  1.1036 +| =filesize= | Size of uploaded data |
  1.1037 +| =filedate= | Date |
  1.1038 +
  1.1039 +Save an attachment to the store for a topic. On success, returns undef. If there is an error, an exception will be thrown.
  1.1040 +
  1.1041 +<verbatim>
  1.1042 +    try {
  1.1043 +        TWiki::Func::saveAttachment( $web, $topic, 'image.gif',
  1.1044 +                                     { file => 'image.gif',
  1.1045 +                                       comment => 'Picture of Health',
  1.1046 +                                       hide => 1 } );
  1.1047 +   } catch Error::Simple with {
  1.1048 +      # see documentation on Error
  1.1049 +   } otherwise {
  1.1050 +      ...
  1.1051 +   };
  1.1052 +</verbatim>
  1.1053 +
  1.1054 +*Since:* TWiki::Plugins::VERSION 1.1
  1.1055 +
  1.1056 +
  1.1057 +---+++ moveAttachment( $web, $topic, $attachment, $newWeb, $newTopic, $newAttachment )
  1.1058 +
  1.1059 +   * =$web= source web - required
  1.1060 +   * =$topic= source topic - required
  1.1061 +   * =$attachment= source attachment - required
  1.1062 +   * =$newWeb= dest web
  1.1063 +   * =$newTopic= dest topic
  1.1064 +   * =$newAttachment= dest attachment
  1.1065 +Renames the topic. Throws an exception on error or access violation.
  1.1066 +If $newWeb is undef, it defaults to $web. If $newTopic is undef, it defaults
  1.1067 +to $topic. If $newAttachment is undef, it defaults to $attachment. If all of $newWeb, $newTopic and $newAttachment are undef, it is an error.
  1.1068 +
  1.1069 +The destination topic must already exist, but the destination attachment must
  1.1070 +*not* exist.
  1.1071 +
  1.1072 +Rename an attachment to $TWiki::cfg{TrashWebName}.TrashAttament to delete it.
  1.1073 +
  1.1074 +<verbatim>
  1.1075 +use Error qw( :try );
  1.1076 +
  1.1077 +try {
  1.1078 +   # move attachment between topics
  1.1079 +   moveAttachment( "Countries", "Germany", "AlsaceLorraine.dat",
  1.1080 +                     "Countries", "France" );
  1.1081 +   # Note destination attachment name is defaulted to the same as source
  1.1082 +} catch TWiki::AccessControlException with {
  1.1083 +   my $e = shift;
  1.1084 +   # see documentation on TWiki::AccessControlException
  1.1085 +} catch Error::Simple with {
  1.1086 +   my $e = shift;
  1.1087 +   # see documentation on Error::Simple
  1.1088 +};
  1.1089 +</verbatim>
  1.1090 +
  1.1091 +*Since:* TWiki::Plugins::VERSION 1.1
  1.1092 +
  1.1093 +
  1.1094 +---++ Assembling Pages
  1.1095 +
  1.1096 +
  1.1097 +---+++ readTemplate( $name, $skin ) -> $text
  1.1098 +
  1.1099 +Read a template or skin. Embedded [[%SYSTEMWEB%.TWikiTemplates][template directives]] get expanded
  1.1100 +   * =$name= - Template name, e.g. ='view'=
  1.1101 +   * =$skin= - Comma-separated list of skin names, optional, e.g. ='print'=
  1.1102 +Return: =$text=    Template text
  1.1103 +
  1.1104 +*Since:* TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
  1.1105 +
  1.1106 +
  1.1107 +---+++ loadTemplate ( $name, $skin, $web ) -> $text
  1.1108 +
  1.1109 +   * =$name= - template file name
  1.1110 +   * =$skin= - comma-separated list of skins to use (default: current skin)
  1.1111 +   * =$web= - the web to look in for topics that contain templates (default: current web)
  1.1112 +Return: expanded template text (what's left after removal of all %TMPL:DEF% statements)
  1.1113 +
  1.1114 +*Since:* TWiki::Plugins::VERSION 1.1
  1.1115 +
  1.1116 +Reads a template and extracts template definitions, adding them to the
  1.1117 +list of loaded templates, overwriting any previous definition.
  1.1118 +
  1.1119 +How TWiki searches for templates is described in TWikiTemplates.
  1.1120 +
  1.1121 +If template text is found, extracts include statements and fully expands them.
  1.1122 +
  1.1123 +
  1.1124 +---+++ expandTemplate( $def  ) -> $string
  1.1125 +
  1.1126 +Do a %TMPL:P{$def}%, only expanding the template (not expanding any variables other than %TMPL)
  1.1127 +   * =$def= - template name
  1.1128 +Return: the text of the expanded template
  1.1129 +
  1.1130 +*Since:* TWiki::Plugins::VERSION 1.1
  1.1131 +
  1.1132 +A template is defined using a %TMPL:DEF% statement in a template
  1.1133 +file. See the documentation on TWiki templates for more information.
  1.1134 +
  1.1135 +
  1.1136 +---+++ writeHeader( $query, $contentLength )
  1.1137 +
  1.1138 +Prints a basic content-type HTML header for text/html to standard out
  1.1139 +   * =$query= - CGI query object. If not given, the default CGI query will be used (optional, in most cases you should _not_ pass this parameter)
  1.1140 +   * =$contentLength= - Length of content (optional, in most cases you should _not_ pass this parameter)
  1.1141 +Return:             none
  1.1142 +
  1.1143 +*Since:* TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
  1.1144 +
  1.1145 +
  1.1146 +---+++ redirectCgiQuery( $query, $url, $passthru )
  1.1147 +
  1.1148 +Redirect to URL
  1.1149 +   * =$query= - CGI query object. Ignored, only there for compatibility. The session CGI query object is used instead.
  1.1150 +   * =$url=   - URL to redirect to
  1.1151 +   * =$passthru= - enable passthrough.
  1.1152 +
  1.1153 +Return:             none
  1.1154 +
  1.1155 +Print output to STDOUT that will cause a 302 redirect to a new URL.
  1.1156 +Nothing more should be printed to STDOUT after this method has been called.
  1.1157 +
  1.1158 +The =$passthru= parameter allows you to pass the parameters that were passed
  1.1159 +to the current query on to the target URL, as long as it is another URL on the
  1.1160 +same TWiki installation. If =$passthru= is set to a true value, then TWiki
  1.1161 +will save the current URL parameters, and then try to restore them on the
  1.1162 +other side of the redirect. Parameters are stored on the server in a cache
  1.1163 +file.
  1.1164 +
  1.1165 +Note that if =$passthru= is set, then any parameters in =$url= will be lost
  1.1166 +when the old parameters are restored. if you want to change any parameter
  1.1167 +values, you will need to do that in the current CGI query before redirecting
  1.1168 +e.g.
  1.1169 +<verbatim>
  1.1170 +my $query = TWiki::Func::getCgiQuery();
  1.1171 +$query->param(-name => 'text', -value => 'Different text');
  1.1172 +TWiki::Func::redirectCgiQuery(
  1.1173 +  undef, TWiki::Func::getScriptUrl($web, $topic, 'edit'), 1);
  1.1174 +</verbatim>
  1.1175 +=$passthru= does nothing if =$url= does not point to a script in the current
  1.1176 +TWiki installation.
  1.1177 +
  1.1178 +*Since:* TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
  1.1179 +
  1.1180 +
  1.1181 +---+++ addToHEAD( $id, $header )
  1.1182 +
  1.1183 +Adds =$header= to the HTML header (the <head> tag).
  1.1184 +This is useful for Plugins that want to include some javascript custom css.
  1.1185 +   * =$id= - Unique ID to prevent the same HTML from being duplicated. Plugins should use a prefix to prevent name clashes (e.g EDITTABLEPLUGIN_JSCALENDAR)
  1.1186 +   * =$header= - the HTML to be added to the <head> section. The HTML must be valid in a HEAD tag - no checks are performed.
  1.1187 +
  1.1188 +All TWiki variables present in =$header= will be expanded before being inserted into the =<head>= section.
  1.1189 +
  1.1190 +Note that this is _not_ the same as the HTTP header, which is modified through the Plugins =modifyHeaderHandler=.
  1.1191 +
  1.1192 +*Since:* TWiki::Plugins::VERSION 1.1
  1.1193 +
  1.1194 +example:
  1.1195 +<verbatim>
  1.1196 +TWiki::Func::addToHEAD('PATTERN_STYLE','<link id="twikiLayoutCss" rel="stylesheet" type="text/css" href="%PUBURL%/TWiki/PatternSkin/layout.css" media="all" />')
  1.1197 +</verbatim>
  1.1198 +
  1.1199 +
  1.1200 +---+++ expandCommonVariables( $text, $topic, $web, $meta ) -> $text
  1.1201 +
  1.1202 +Expand all common =%<nop>VARIABLES%=
  1.1203 +   * =$text=  - Text with variables to expand, e.g. ='Current user is %<nop>WIKIUSER%'=
  1.1204 +   * =$topic= - Current topic name, e.g. ='WebNotify'=
  1.1205 +   * =$web=   - Web name, optional, e.g. ='Main'=. The current web is taken if missing
  1.1206 +   * =$meta=  - topic meta-data to use while expanding (Since TWiki::Plugins::VERSION 1.2)
  1.1207 +Return: =$text=     Expanded text, e.g. ='Current user is <nop>TWikiGuest'=
  1.1208 +
  1.1209 +*Since:* TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
  1.1210 +
  1.1211 +See also: expandVariablesOnTopicCreation
  1.1212 +
  1.1213 +
  1.1214 +---+++ renderText( $text, $web ) -> $text
  1.1215 +
  1.1216 +Render text from TWiki markup into XHTML as defined in [[%SYSTEMWEB%.TextFormattingRules]]
  1.1217 +   * =$text= - Text to render, e.g. ='*bold* text and =fixed font='=
  1.1218 +   * =$web=  - Web name, optional, e.g. ='Main'=. The current web is taken if missing
  1.1219 +Return: =$text=    XHTML text, e.g. ='&lt;b>bold&lt;/b> and &lt;code>fixed font&lt;/code>'=
  1.1220 +
  1.1221 +*Since:* TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
  1.1222 +
  1.1223 +
  1.1224 +---+++ internalLink( $pre, $web, $topic, $label, $anchor, $createLink ) -> $text
  1.1225 +
  1.1226 +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()=
  1.1227 +   * =$pre=        - Text occuring before the TWiki link syntax, optional
  1.1228 +   * =$web=        - Web name, required, e.g. ='Main'=
  1.1229 +   * =$topic=      - Topic name to link to, required, e.g. ='WebNotify'=
  1.1230 +   * =$label=      - Link label, required. Usually the same as =$topic=, e.g. ='notify'=
  1.1231 +   * =$anchor=     - Anchor, optional, e.g. ='#Jump'=
  1.1232 +   * =$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
  1.1233 +Return: =$text=          XHTML anchor, e.g. ='&lt;a href='/cgi-bin/view/Main/WebNotify#Jump'>notify&lt;/a>'=
  1.1234 +
  1.1235 +*Since:* TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
  1.1236 +
  1.1237 +
  1.1238 +---++ E-mail
  1.1239 +
  1.1240 +---+++ sendEmail ( $text, $retries ) -> $error
  1.1241 +
  1.1242 +   * =$text= - text of the mail, including MIME headers
  1.1243 +   * =$retries= - number of times to retry the send (default 1)
  1.1244 +Send an e-mail specified as MIME format content. To specify MIME
  1.1245 +format mails, you create a string that contains a set of header
  1.1246 +lines that contain field definitions and a message body such as:
  1.1247 +<verbatim>
  1.1248 +To: liz@@windsor.gov.uk
  1.1249 +From: serf@@hovel.net
  1.1250 +CC: george@@whitehouse.gov
  1.1251 +Subject: Revolution
  1.1252 +
  1.1253 +Dear Liz,
  1.1254 +
  1.1255 +Please abolish the monarchy (with King George's permission, of course)
  1.1256 +
  1.1257 +Thanks,
  1.1258 +
  1.1259 +A. Peasant
  1.1260 +</verbatim>
  1.1261 +Leave a blank line between the last header field and the message body.
  1.1262 +
  1.1263 +*Since:* TWiki::Plugins::VERSION 1.1
  1.1264 +
  1.1265 +
  1.1266 +---+++ wikiToEmail( $wikiName ) -> $email
  1.1267 +
  1.1268 +   * =$wikiName= - wiki name of the user
  1.1269 +Get the e-mail address(es) of the named user. If the user has multiple
  1.1270 +e-mail addresses (for example, the user is a group), then the list will
  1.1271 +be comma-separated.
  1.1272 +
  1.1273 +*Since:* TWiki::Plugins::VERSION 1.1
  1.1274 +
  1.1275 +
  1.1276 +---++ Creating New Topics
  1.1277 +
  1.1278 +
  1.1279 +---+++ expandVariablesOnTopicCreation ( $text ) -> $text
  1.1280 +
  1.1281 +Expand the limited set of variables that are always expanded during topic creation
  1.1282 +   * =$text= - the text to process
  1.1283 +Return: text with variables expanded
  1.1284 +
  1.1285 +*Since:* TWiki::Plugins::VERSION 1.1
  1.1286 +
  1.1287 +Expands only the variables expected in templates that must be statically
  1.1288 +expanded in new content.
  1.1289 +
  1.1290 +The expanded variables are:
  1.1291 +   * =%<nop>DATE%= Signature-format date
  1.1292 +   * =%<nop>SERVERTIME%= See TWikiVariables
  1.1293 +   * =%<nop>GMTIME%= See TWikiVariables
  1.1294 +   * =%<nop>USERNAME%= Base login name
  1.1295 +   * =%<nop>WIKINAME%= Wiki name
  1.1296 +   * =%<nop>WIKIUSERNAME%= Wiki name with prepended web
  1.1297 +   * =%<nop>URLPARAM{...}%= - Parameters to the current CGI query
  1.1298 +   * =%<nop>NOP%= No-op
  1.1299 +
  1.1300 +See also: expandVariables
  1.1301 +
  1.1302 +
  1.1303 +---++ Special handlers
  1.1304 +
  1.1305 +Special handlers can be defined to make functions in plugins behave as if they were built-in to TWiki.
  1.1306 +
  1.1307 +
  1.1308 +---+++ registerTagHandler( $var, \&fn, $syntax )
  1.1309 +
  1.1310 +Should only be called from initPlugin.
  1.1311 +
  1.1312 +Register a function to handle a simple variable. Handles both %<nop>VAR% and %<nop>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=.
  1.1313 +   * =$var= - The name of the variable, i.e. the 'MYVAR' part of %<nop>MYVAR%. The variable name *must* match /^[A-Z][A-Z0-9_]*$/ or it won't work.
  1.1314 +   * =\&fn= - Reference to the handler function.
  1.1315 +   * =$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 =%<nop>MYVAR{ "unnamed" param1="value1" param2="value2" }%= syntax, as well as an unquoted default parameter, such as =%<nop>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"}%
  1.1316 +
  1.1317 +*Since:* TWiki::Plugins::VERSION 1.1
  1.1318 +
  1.1319 +The variable handler function must be of the form:
  1.1320 +<verbatim>
  1.1321 +sub handler(\%session, \%params, $topic, $web)
  1.1322 +</verbatim>
  1.1323 +where:
  1.1324 +   * =\%session= - a reference to the TWiki session object (may be ignored)
  1.1325 +   * =\%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.
  1.1326 +   * =$topic= - name of the topic in the query
  1.1327 +   * =$web= - name of the web in the query
  1.1328 +for example, to execute an arbitrary command on the server, you might do this:
  1.1329 +<verbatim>
  1.1330 +sub initPlugin{
  1.1331 +   TWiki::Func::registerTagHandler('EXEC', \&boo);
  1.1332 +}
  1.1333 +
  1.1334 +sub boo {
  1.1335 +    my( $session, $params, $topic, $web ) = @@_;
  1.1336 +    my $cmd = $params->{_DEFAULT};
  1.1337 +
  1.1338 +    return "NO COMMAND SPECIFIED" unless $cmd;
  1.1339 +
  1.1340 +    my $result = `$cmd 2>&1`;
  1.1341 +    return $params->{silent} ? '' : $result;
  1.1342 +}
  1.1343 +}
  1.1344 +</verbatim>
  1.1345 +would let you do this:
  1.1346 +=%<nop>EXEC{"ps -Af" silent="on"}%=
  1.1347 +
  1.1348 +Registered tags differ from tags implemented using the old TWiki approach (text substitution in =commonTagsHandler=) in the following ways:
  1.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).
  1.1350 +   * registered tag names can only contain alphanumerics and _ (underscore)
  1.1351 +   * registering a tag =FRED= defines both =%<nop>FRED{...}%= *and also* =%FRED%=.
  1.1352 +   * registered tag handlers *cannot* return another tag as their only result (e.g. =return '%<nop>SERVERTIME%';=). It won't work.
  1.1353 +
  1.1354 +
  1.1355 +---+++ registerRESTHandler( $alias, \&fn, )
  1.1356 +
  1.1357 +Should only be called from initPlugin.
  1.1358 +
  1.1359 +Adds a function to the dispatch table of the REST interface 
  1.1360 +   * =$alias= - The name .
  1.1361 +   * =\&fn= - Reference to the function.
  1.1362 +
  1.1363 +*Since:* TWiki::Plugins::VERSION 1.1
  1.1364 +
  1.1365 +The handler function must be of the form:
  1.1366 +<verbatim>
  1.1367 +sub handler(\%session)
  1.1368 +</verbatim>
  1.1369 +where:
  1.1370 +   * =\%session= - a reference to the TWiki session object (may be ignored)
  1.1371 +
  1.1372 +From the REST interface, the name of the plugin must be used
  1.1373 +as the subject of the invokation.
  1.1374 +
  1.1375 +Example
  1.1376 +-------
  1.1377 +
  1.1378 +The EmptyPlugin has the following call in the initPlugin handler:
  1.1379 +<verbatim>
  1.1380 +   TWiki::Func::registerRESTHandler('example', \&restExample);
  1.1381 +</verbatim>
  1.1382 +
  1.1383 +This adds the =restExample= function to the REST dispatch table 
  1.1384 +for the EmptyPlugin under the 'example' alias, and allows it 
  1.1385 +to be invoked using the URL
  1.1386 +
  1.1387 +=http://server:port/bin/rest/EmptyPlugin/example=
  1.1388 +
  1.1389 +note that the URL
  1.1390 +
  1.1391 +=http://server:port/bin/rest/EmptyPlugin/restExample=
  1.1392 +
  1.1393 +(ie, with the name of the function instead of the alias) will not work.
  1.1394 +
  1.1395 +
  1.1396 +---+++ decodeFormatTokens($str) -> $unencodedString
  1.1397 +
  1.1398 +TWiki has an informal standard set of tokens used in =format=
  1.1399 +parameters that are used to block evaluation of paramater strings.
  1.1400 +For example, if you were to write
  1.1401 +
  1.1402 +=%<nop>MYTAG{format="%<nop>WURBLE%"}%=
  1.1403 +
  1.1404 +then %<nop>WURBLE would be expanded *before* %<NOP>MYTAG is evaluated. To avoid
  1.1405 +this TWiki uses escapes in the format string. For example:
  1.1406 +
  1.1407 +=%<nop>MYTAG{format="$percntWURBLE$percnt"}%=
  1.1408 +
  1.1409 +This lets you enter arbitrary strings into parameters without worrying that
  1.1410 +TWiki will expand them before your plugin gets a chance to deal with them
  1.1411 +properly. Once you have processed your tag, you will want to expand these
  1.1412 +tokens to their proper value. That's what this function does.
  1.1413 +
  1.1414 +| *Escape:* | *Expands To:* |
  1.1415 +| =$n= or =$n()= | New line. Use =$n()= if followed by alphanumeric character, e.g. write =Foo$n()Bar= instead of =Foo$nBar= |
  1.1416 +| =$nop= or =$nop()= | Is a "no operation". |
  1.1417 +| =$quot= | Double quote (="=) |
  1.1418 +| =$percnt= | Percent sign (=%=) |
  1.1419 +| =$dollar= | Dollar sign (=$=) |
  1.1420 +
  1.1421 +Note thath $quot, $percnt and $dollar all work *even if they are followed by
  1.1422 +alphanumeric characters*. You have been warned!
  1.1423 +
  1.1424 +*Since:* TWiki::Plugins::VERSION 1.2
  1.1425 +
  1.1426 +
  1.1427 +---++ Searching
  1.1428 +
  1.1429 +
  1.1430 +---+++ searchInWebContent($searchString, $web, \@@topics, \%options ) -> \%map
  1.1431 +
  1.1432 +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+{.*}%)
  1.1433 +   * =$searchString= - the search string, in egrep format
  1.1434 +   * =$web= - The web to search in
  1.1435 +   * =\@@topics= - reference to a list of topics to search
  1.1436 +   * =\%option= - reference to an options hash
  1.1437 +The =\%options= hash may contain the following options:
  1.1438 +   * =type= - if =regex= will perform a egrep-syntax RE search (default '')
  1.1439 +   * =casesensitive= - false to ignore case (defaulkt true)
  1.1440 +   * =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).
  1.1441 +
  1.1442 +The return value is a reference to a hash which maps each matching topic
  1.1443 +name to a list of the lines in that topic that matched the search,
  1.1444 +as would be returned by 'grep'.
  1.1445 +
  1.1446 +To iterate over the returned topics use:
  1.1447 +<verbatim>
  1.1448 +my $result = TWiki::Func::searchInWebContent( "Slimy Toad", $web, \@@topics,
  1.1449 +   { casesensitive => 0, files_without_match => 0 } );
  1.1450 +foreach my $topic (keys %$result ) {
  1.1451 +   foreach my $matching_line ( @@{$result->{$topic}} ) {
  1.1452 +      ...etc
  1.1453 +</verbatim>
  1.1454 +
  1.1455 +*Since:* TWiki::Plugins::VERSION 1.1
  1.1456 +
  1.1457 +
  1.1458 +---++ Plugin-specific file handling
  1.1459 +
  1.1460 +
  1.1461 +---+++ getWorkArea( $pluginName ) -> $directorypath
  1.1462 +
  1.1463 +Gets a private directory for Plugin use. The Plugin is entirely responsible
  1.1464 +for managing this directory; TWiki will not read from it, or write to it.
  1.1465 +
  1.1466 +The directory is guaranteed to exist, and to be writable by the webserver
  1.1467 +user. By default it will *not* be web accessible.
  1.1468 +
  1.1469 +The directory and it's contents are permanent, so Plugins must be careful
  1.1470 +to keep their areas tidy.
  1.1471 +
  1.1472 +*Since:* TWiki::Plugins::VERSION 1.1 (Dec 2005)
  1.1473 +
  1.1474 +
  1.1475 +---+++ readFile( $filename ) -> $text
  1.1476 +
  1.1477 +Read file, low level. Used for Plugin workarea.
  1.1478 +   * =$filename= - Full path name of file
  1.1479 +Return: =$text= Content of file, empty if not found
  1.1480 +
  1.1481 +__NOTE:__ Use this function only for the Plugin workarea, *not* for topics and attachments. Use the appropriate functions to manipulate topics and attachments.
  1.1482 +
  1.1483 +*Since:* TWiki::Plugins::VERSION 1.000 (07 Dec 2002)
  1.1484 +
  1.1485 +
  1.1486 +---+++ saveFile( $filename, $text )
  1.1487 +
  1.1488 +Save file, low level. Used for Plugin workarea.
  1.1489 +   * =$filename= - Full path name of file
  1.1490 +   * =$text=     - Text to save
  1.1491 +Return:                none
  1.1492 +
  1.1493 +__NOTE:__ Use this function only for the Plugin workarea, *not* for topics and attachments. Use the appropriate functions to manipulate topics and attachments.
  1.1494 +
  1.1495 +*Since:* TWiki::Plugins::VERSION 1.000 (07 Dec 2002)
  1.1496 +
  1.1497 +
  1.1498 +---++ General Utilities
  1.1499 +
  1.1500 +
  1.1501 +---+++ getRegularExpression( $name ) -> $expr
  1.1502 +
  1.1503 +Retrieves a TWiki predefined regular expression or character class.
  1.1504 +   * =$name= - Name of the expression to retrieve.  See notes below
  1.1505 +Return: String or precompiled regular expression matching as described below.
  1.1506 +
  1.1507 +*Since:* TWiki::Plugins::VERSION 1.020 (9 Feb 2004)
  1.1508 +
  1.1509 +__Note:__ TWiki internally precompiles several regular expressions to
  1.1510 +represent various string entities in an <nop>I18N-compatible manner. Plugins
  1.1511 +authors are encouraged to use these in matching where appropriate. The
  1.1512 +following are guaranteed to be present. Others may exist, but their use
  1.1513 +is unsupported and they may be removed in future TWiki versions.
  1.1514 +
  1.1515 +In the table below, the expression marked type 'String' are intended for
  1.1516 +use within character classes (i.e. for use within square brackets inside
  1.1517 +a regular expression), for example:
  1.1518 +<verbatim>
  1.1519 +   my $upper = TWiki::Func::getRegularExpression('upperAlpha');
  1.1520 +   my $alpha = TWiki::Func::getRegularExpression('mixedAlpha');
  1.1521 +   my $capitalized = qr/[$upper][$alpha]+/;
  1.1522 +</verbatim>
  1.1523 +Those expressions marked type 'RE' are precompiled regular expressions that can be used outside square brackets. For example:
  1.1524 +<verbatim>
  1.1525 +   my $webRE = TWiki::Func::getRegularExpression('webNameRegex');
  1.1526 +   my $isWebName = ( $s =~ m/$webRE/ );
  1.1527 +</verbatim>
  1.1528 +
  1.1529 +| *Name*         | *Matches*                        | *Type* |
  1.1530 +| upperAlpha     | Upper case characters            | String |
  1.1531 +| upperAlphaNum  | Upper case characters and digits | String |
  1.1532 +| lowerAlpha     | Lower case characters            | String |
  1.1533 +| lowerAlphaNum  | Lower case characters and digits | String |
  1.1534 +| numeric        | Digits                           | String |
  1.1535 +| mixedAlpha     | Alphabetic characters            | String |
  1.1536 +| mixedAlphaNum  | Alphanumeric characters          | String |
  1.1537 +| wikiWordRegex  | WikiWords                        | RE |
  1.1538 +| webNameRegex   | User web names                   | RE |
  1.1539 +| anchorRegex    | #AnchorNames                     | RE |
  1.1540 +| abbrevRegex    | Abbreviations e.g. GOV, IRS      | RE |
  1.1541 +| emailAddrRegex | email@@address.com                | RE |
  1.1542 +| tagNameRegex   | Standard variable names e.g. %<nop>THIS_BIT% (THIS_BIT only) | RE |
  1.1543 +
  1.1544 +
  1.1545 +---+++ normalizeWebTopicName($web, $topic) -> ($web, $topic)
  1.1546 +
  1.1547 +Parse a web and topic name, supplying defaults as appropriate.
  1.1548 +   * =$web= - Web name, identifying variable, or empty string
  1.1549 +   * =$topic= - Topic name, may be a web.topic string, required.
  1.1550 +Return: the parsed Web/Topic pair
  1.1551 +
  1.1552 +*Since:* TWiki::Plugins::VERSION 1.1
  1.1553 +
  1.1554 +| *Input*                               | *Return*  |
  1.1555 +| <tt>( 'Web', 'Topic' ) </tt>          | <tt>( 'Web', 'Topic' ) </tt>  |
  1.1556 +| <tt>( '', 'Topic' ) </tt>             | <tt>( 'Main', 'Topic' ) </tt>  |
  1.1557 +| <tt>( '', '' ) </tt>                  | <tt>( 'Main', 'WebHome' ) </tt>  |
  1.1558 +| <tt>( '', 'Web/Topic' ) </tt>         | <tt>( 'Web', 'Topic' ) </tt>  |
  1.1559 +| <tt>( '', 'Web/Subweb/Topic' ) </tt>  | <tt>( 'Web/Subweb', 'Topic' ) </tt>  |
  1.1560 +| <tt>( '', 'Web.Topic' ) </tt>         | <tt>( 'Web', 'Topic' ) </tt>  |
  1.1561 +| <tt>( '', 'Web.Subweb.Topic' ) </tt>  | <tt>( 'Web/Subweb', 'Topic' ) </tt>  |
  1.1562 +| <tt>( 'Web1', 'Web2.Topic' )</tt>     | <tt>( 'Web2', 'Topic' ) </tt>  |
  1.1563 +
  1.1564 +Note that hierarchical web names (Web.SubWeb) are only available if hierarchical webs are enabled in =configure=.
  1.1565 +
  1.1566 +The symbols %<nop>USERSWEB%, %<nop>SYSTEMWEB% and %<nop>DOCWEB% can be used in the input to represent the web names set in $cfg{UsersWebName} and $cfg{SystemWebName}. For example:
  1.1567 +| *Input*                               | *Return* |
  1.1568 +| <tt>( '%<nop>USERSWEB%', 'Topic' )</tt>     | <tt>( 'Main', 'Topic' ) </tt>  |
  1.1569 +| <tt>( '%<nop>SYSTEMWEB%', 'Topic' )</tt>    | <tt>( 'TWiki', 'Topic' ) </tt>  |
  1.1570 +| <tt>( '', '%<nop>DOCWEB%.Topic' )</tt>    | <tt>( 'TWiki', 'Topic' ) </tt>  |
  1.1571 +
  1.1572 +
  1.1573 +---++ StaticMethod *sanitizeAttachmentName* <tt>($fname) -> ($fileName,$origName)</tt>
  1.1574 +
  1.1575 +Given a file namer, sanitise it according to the rules for transforming
  1.1576 +attachment names. Returns
  1.1577 +the sanitised name together with the basename before sanitisation.
  1.1578 +
  1.1579 +Sanitation includes filtering illegal characters and mapping client
  1.1580 +file names to legal server names.
  1.1581 +
  1.1582 +*Since:* TWiki::Plugins::VERSION 1.2
  1.1583 +
  1.1584 +
  1.1585 +
  1.1586 +---+++ spaceOutWikiWord( $word, $sep ) -> $text
  1.1587 +
  1.1588 +Spaces out a wiki word by inserting a string (default: one space) between each word component.
  1.1589 +With parameter $sep any string may be used as separator between the word components; if $sep is undefined it defaults to a space.
  1.1590 +
  1.1591 +*Since:* TWiki::Plugins::VERSION 1.2
  1.1592 +
  1.1593 +
  1.1594 +---+++ writeWarning( $text )
  1.1595 +
  1.1596 +Log Warning that may require admin intervention to data/warning.txt
  1.1597 +   * =$text= - Text to write; timestamp gets added
  1.1598 +Return:            none
  1.1599 +
  1.1600 +*Since:* TWiki::Plugins::VERSION 1.020 (16 Feb 2004)
  1.1601 +
  1.1602 +
  1.1603 +---+++ writeDebug( $text )
  1.1604 +
  1.1605 +Log debug message to data/debug.txt
  1.1606 +   * =$text= - Text to write; timestamp gets added
  1.1607 +Return:            none
  1.1608 +
  1.1609 +*Since:* TWiki::Plugins::VERSION 1.020 (16 Feb 2004)
  1.1610 +
  1.1611 +
  1.1612 +---+++ formatTime( $time, $format, $timezone ) -> $text
  1.1613 +
  1.1614 +Format the time in seconds into the desired time string
  1.1615 +   * =$time=     - Time in epoc seconds
  1.1616 +   * =$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
  1.1617 +   * =$timezone= - either not defined (uses the displaytime setting), 'gmtime', or 'servertime'
  1.1618 +Return: =$text=        Formatted time string
  1.1619 +| Note:                  | if you used the removed formatGmTime, add a third parameter 'gmtime' |
  1.1620 +
  1.1621 +*Since:* TWiki::Plugins::VERSION 1.020 (26 Feb 2004)
  1.1622 +
  1.1623 +
  1.1624 +---+++ isTrue( $value, $default ) -> $boolean
  1.1625 +
  1.1626 +Returns 1 if =$value= is true, and 0 otherwise. "true" means set to
  1.1627 +something with a Perl true value, with the special cases that "off",
  1.1628 +"false" and "no" (case insensitive) are forced to false. Leading and
  1.1629 +trailing spaces in =$value= are ignored.
  1.1630 +
  1.1631 +If the value is undef, then =$default= is returned. If =$default= is
  1.1632 +not specified it is taken as 0.
  1.1633 +
  1.1634 +*Since:* $TWiki::Plugins::VERSION 1.2
  1.1635 +
  1.1636 +
  1.1637 +---+++ isValidWikiWord ( $text ) -> $boolean
  1.1638 +
  1.1639 +Check for a valid WikiWord or WikiName
  1.1640 +   * =$text= - Word to test
  1.1641 +
  1.1642 +*Since:* TWiki::Plugins::VERSION 1.100 (Dec 2005)
  1.1643 +
  1.1644 +
  1.1645 +---+++ extractParameters($attr ) -> %params
  1.1646 +
  1.1647 +Extract all parameters from a variable string and returns a hash of parameters
  1.1648 +   * =$attr= - Attribute string
  1.1649 +Return: =%params=  Hash containing all parameters. The nameless parameter is stored in key =_DEFAULT=
  1.1650 +
  1.1651 +*Since:* TWiki::Plugins::VERSION 1.025 (26 Aug 2004)
  1.1652 +
  1.1653 +   * Example:
  1.1654 +      * Variable: =%<nop>TEST{ 'nameless' name1="val1" name2="val2" }%=
  1.1655 +      * First extract text between ={...}= to get: ='nameless' name1="val1" name2="val2"=
  1.1656 +      * Then call this on the text: <br />
  1.1657 +   * params = TWiki::Func::extractParameters( $text );=
  1.1658 +      * The =%params= hash contains now: <br />
  1.1659 +        =_DEFAULT => 'nameless'= <br />
  1.1660 +        =name1 => "val1"= <br />
  1.1661 +        =name2 => "val2"=
  1.1662 +
  1.1663 +
  1.1664 +---+++ extractNameValuePair( $attr, $name ) -> $value
  1.1665 +
  1.1666 +Extract a named or unnamed value from a variable parameter string
  1.1667 +- Note:              | Function TWiki::Func::extractParameters is more efficient for extracting several parameters
  1.1668 +   * =$attr= - Attribute string
  1.1669 +   * =$name= - Name, optional
  1.1670 +Return: =$value=   Extracted value
  1.1671 +
  1.1672 +*Since:* TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
  1.1673 +
  1.1674 +   * Example:
  1.1675 +      * Variable: =%<nop>TEST{ 'nameless' name1="val1" name2="val2" }%=
  1.1676 +      * First extract text between ={...}= to get: ='nameless' name1="val1" name2="val2"=
  1.1677 +      * Then call this on the text: <br />
  1.1678 +        =my $noname = TWiki::Func::extractNameValuePair( $text );= <br />
  1.1679 +        =my $val1  = TWiki::Func::extractNameValuePair( $text, "name1" );= <br />
  1.1680 +        =my $val2  = TWiki::Func::extractNameValuePair( $text, "name2" );=
  1.1681 +
  1.1682 +
  1.1683 +---++ Deprecated functions
  1.1684 +
  1.1685 +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.
  1.1686 +
  1.1687 +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 %<nop>FAILEDPLUGINS%.
  1.1688 +
  1.1689 +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:
  1.1690 +<verbatim>
  1.1691 +package TWiki::Plugins::SinkPlugin;
  1.1692 +use vars qw( %TWikiCompatibility );
  1.1693 +$TWikiCompatibility{endRenderingHandler} = 1.1;
  1.1694 +</verbatim>
  1.1695 +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.
  1.1696 +
  1.1697 +The following functions are retained for compatibility only. You should
  1.1698 +stop using them as soon as possible.
  1.1699 +
  1.1700 +---+++ getScriptUrlPath( ) -> $path
  1.1701 +
  1.1702 +Get script URL path
  1.1703 +
  1.1704 +*DEPRECATED* since 1.1 - use =getScriptUrl= instead.
  1.1705 +
  1.1706 +Return: =$path= URL path of TWiki scripts, e.g. ="/cgi-bin"=
  1.1707 +
  1.1708 +*WARNING:* you are strongly recommended *not* to use this function, as the
  1.1709 +{ScriptUrlPaths} URL rewriting rules will not apply to urls generated
  1.1710 +using it.
  1.1711 +
  1.1712 +*Since:* TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
  1.1713 +
  1.1714 +
  1.1715 +---+++ getOopsUrl( $web, $topic, $template, $param1, $param2, $param3, $param4 ) -> $url
  1.1716 +
  1.1717 +Compose fully qualified 'oops' dialog URL
  1.1718 +   * =$web=                  - Web name, e.g. ='Main'=. The current web is taken if empty
  1.1719 +   * =$topic=                - Topic name, e.g. ='WebNotify'=
  1.1720 +   * =$template=             - Oops template name, e.g. ='oopsmistake'=. The 'oops' is optional; 'mistake' will translate to 'oopsmistake'.
  1.1721 +   * =$param1= ... =$param4= - Parameter values for %<nop>PARAM1% ... %<nop>PARAMn% variables in template, optional
  1.1722 +Return: =$url=                     URL, e.g. ="http://example.com:80/cgi-bin/oops.pl/ Main/WebNotify?template=oopslocked&amp;param1=joe"=
  1.1723 +
  1.1724 +*DEPRECATED* since 1.1, the recommended approach is to throw an [[TWikiOopsExceptionDotPm][oops exception]].
  1.1725 +<verbatim>
  1.1726 +   use Error qw( :try );
  1.1727 +
  1.1728 +   throw TWiki::OopsException(
  1.1729 +      'toestuckerror',
  1.1730 +      web => $web,
  1.1731 +      topic => $topic,
  1.1732 +      params => [ 'I got my toe stuck' ]);
  1.1733 +</verbatim>
  1.1734 +(this example will use the =oopstoestuckerror= template.)
  1.1735 +
  1.1736 +If this is not possible (e.g. in a REST handler that does not trap the exception)
  1.1737 +then you can use =getScriptUrl= instead:
  1.1738 +<verbatim>
  1.1739 +   my $url = TWiki::Func::getScriptUrl($web, $topic, 'oops',
  1.1740 +            template => 'oopstoestuckerror',
  1.1741 +            param1 => 'I got my toe stuck');
  1.1742 +   TWiki::Func::redirectCgiQuery( undef, $url );
  1.1743 +   return 0;
  1.1744 +</verbatim>
  1.1745 +
  1.1746 +*Since:* TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
  1.1747 +
  1.1748 +
  1.1749 +---+++ permissionsSet( $web ) -> $boolean
  1.1750 +
  1.1751 +Test if any access restrictions are set for this web, ignoring settings on
  1.1752 +individual pages
  1.1753 +   * =$web= - Web name, required, e.g. ='Sandbox'=
  1.1754 +
  1.1755 +*Since:* TWiki::Plugins::VERSION 1.000 (27 Feb 2001)
  1.1756 +
  1.1757 +*DEPRECATED* since 1.2 - use =getPreferencesValue= instead to determine
  1.1758 +what permissions are set on the web, for example:
  1.1759 +<verbatim>
  1.1760 +foreach my $type qw( ALLOW DENY ) {
  1.1761 +    foreach my $action qw( CHANGE VIEW ) {
  1.1762 +        my $pref = $type . 'WEB' . $action;
  1.1763 +        my $val = getPreferencesValue( $pref, $web ) || '';
  1.1764 +        if( $val =~ /\S/ ) {
  1.1765 +            print "$pref is set to $val on $web\n";
  1.1766 +        }
  1.1767 +    }
  1.1768 +}
  1.1769 +</verbatim>
  1.1770 +
  1.1771 +
  1.1772 +---+++ getPublicWebList( ) -> @@webs
  1.1773 +
  1.1774 +*DEPRECATED* since 1.1 - use =getListOfWebs= instead.
  1.1775 +
  1.1776 +Get list of all public webs, e.g. all webs that do not have the =NOSEARCHALL= flag set in the WebPreferences
  1.1777 +
  1.1778 +Return: =@@webs= List of all public webs, e.g. =( 'Main',  'Know', 'TWiki' )=
  1.1779 +
  1.1780 +*Since:* TWiki::Plugins::VERSION 1.000 (07 Dec 2002)
  1.1781 +
  1.1782 +
  1.1783 +---+++ formatGmTime( $time, $format ) -> $text
  1.1784 +
  1.1785 +*DEPRECATED* since 1.1 - use =formatTime= instead.
  1.1786 +
  1.1787 +Format the time to GM time
  1.1788 +   * =$time=   - Time in epoc seconds
  1.1789 +   * =$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'=)
  1.1790 +Return: =$text=      Formatted time string
  1.1791 +
  1.1792 +*Since:* TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
  1.1793 +
  1.1794 +
  1.1795 +---+++ getDataDir( ) -> $dir
  1.1796 +
  1.1797 +*DEPRECATED* since 1.1 - use the "Webs, Topics and Attachments" functions to manipulate topics instead
  1.1798 +
  1.1799 +Get data directory (topic file root)
  1.1800 +
  1.1801 +Return: =$dir= Data directory, e.g. ='/twiki/data'=
  1.1802 +
  1.1803 +This function violates store encapsulation and is therefore *deprecated*.
  1.1804 +
  1.1805 +*Since:* TWiki::Plugins::VERSION 1.000 (07 Dec 2002)
  1.1806 +
  1.1807 +
  1.1808 +---+++ getPubDir( ) -> $dir
  1.1809 +
  1.1810 +*DEPRECATED* since 1.1 - use the "Webs, Topics and Attachments" functions to manipulateattachments instead
  1.1811 +
  1.1812 +Get pub directory (file attachment root). Attachments are in =$dir/Web/TopicName=
  1.1813 +
  1.1814 +Return: =$dir= Pub directory, e.g. ='/htdocs/twiki/pub'=
  1.1815 +
  1.1816 +This function violates store encapsulation and is therefore *deprecated*.
  1.1817 +
  1.1818 +Use =readAttachment= and =saveAttachment= instead.
  1.1819 +
  1.1820 +*Since:* TWiki::Plugins::VERSION 1.000 (07 Dec 2002)
  1.1821 +
  1.1822 +
  1.1823 +---+++ checkDependencies( $moduleName, $dependenciesRef ) -> $error
  1.1824 +
  1.1825 +*DEPRECATED* since 1.1 - use TWiki:Plugins.BuildContrib and define DEPENDENCIES that can be statically
  1.1826 +evaluated at install time instead. It is a lot more efficient.
  1.1827 +
  1.1828 +*Since:* TWiki::Plugins::VERSION 1.025 (01 Aug 2004)
  1.1829 +
  1.1830 +@
  1.1831 +
  1.1832 +
  1.1833 +1.6
  1.1834 +log
  1.1835 +@buildrelease
  1.1836 +@
  1.1837 +text
  1.1838 +@d8 1
  1.1839 +a8 1
  1.1840 +This module defines official functions that [[%TWIKIWEB%.TWikiPlugins][Plugins]]
  1.1841 +d23 25
  1.1842 +a47 22
  1.1843 +by the =%<nop>PLUGINVERSION%= variable. The 'Since' field in the function
  1.1844 +documentation refers to the VERSION number and the date that the function
  1.1845 +was addded.
  1.1846 +
  1.1847 +__Note:__ Beware! These methods should only ever be called
  1.1848 +from the context of a TWiki Plugin. They require a Plugins SESSION context to be
  1.1849 +established before they are called, and will not work if simply called from
  1.1850 +another TWiki module. For example,
  1.1851 +<verbatim>
  1.1852 +use TWiki;
  1.1853 +print TWiki::Func::getSkin(),"\n";
  1.1854 +</verbatim>
  1.1855 +will fail with =Can't call method "getSkin" on an undefined value at TWiki/Func.pm line 83=.
  1.1856 +
  1.1857 +If you want to call the methods outside the context of a plugin, you can create a Plugins SESSION object. For example,
  1.1858 +the script:
  1.1859 +<verbatim>
  1.1860 +use TWiki:
  1.1861 +$TWiki::Plugins::SESSION = new TWiki();
  1.1862 +print TWiki::Func::getSkin(),"\n";
  1.1863 +</verbatim>
  1.1864 +will work happily.
  1.1865 +d79 1
  1.1866 +a79 1
  1.1867 +   * =...= - 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. <tt>getScriptUrl('x','y','view','#'=>'XXX',a=>1,b=>2)</tt> will give <tt>.../view/x/y?a=1&b=2#XXX</tt>
  1.1868 +d96 1
  1.1869 +a96 1
  1.1870 +---+++ getOopsUrl( $web, $topic, $template, $param1, $param2, $param3, $param4 ) -> $url
  1.1871 +d98 1
  1.1872 +a98 6
  1.1873 +Compose fully qualified 'oops' dialog URL
  1.1874 +   * =$web=                  - Web name, e.g. ='Main'=. The current web is taken if empty
  1.1875 +   * =$topic=                - Topic name, e.g. ='WebNotify'=
  1.1876 +   * =$template=             - Oops template name, e.g. ='oopsmistake'=. The 'oops' is optional; 'mistake' will translate to 'oopsmistake'.
  1.1877 +   * =$param1= ... =$param4= - Parameter values for %<nop>PARAM1% ... %<nop>PARAMn% variables in template, optional
  1.1878 +Return: =$url=                     URL, e.g. ="http://example.com:80/cgi-bin/oops.pl/ Main/WebNotify?template=oopslocked&amp;param1=joe"=
  1.1879 +d100 1
  1.1880 +a100 6
  1.1881 +This might be used like this:
  1.1882 +<verbatim>
  1.1883 +   my $url = TWiki::Func::getOopsUrl($web, $topic, 'oopsmistake', 'I made a boo-boo');
  1.1884 +   TWiki::Func::redirectCgiQuery( undef, $url );
  1.1885 +   return 0;
  1.1886 +</verbatim>
  1.1887 +d102 1
  1.1888 +a102 1
  1.1889 +*Since:* TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
  1.1890 +a103 3
  1.1891 +Since TWiki::Plugins::VERSION 1.1, the recommended approach is to throw an [[TWikiOopsExceptionDotPm][oops exception]].
  1.1892 +<verbatim>
  1.1893 +   use Error qw( :try );
  1.1894 +d105 1
  1.1895 +a105 3
  1.1896 +   throw TWiki::OopsException($web, $topic, undef, 0, [ 'I made a boo-boo' ]);
  1.1897 +</verbatim>
  1.1898 +and let TWiki handle the cleanup.
  1.1899 +d107 30
  1.1900 +d138 2
  1.1901 +a139 1
  1.1902 +---+++ getPubUrlPath( ) -> $path
  1.1903 +d141 8
  1.1904 +a148 1
  1.1905 +Get pub URL path
  1.1906 +d150 1
  1.1907 +a150 3
  1.1908 +Return: =$path= URL path of pub directory, e.g. ="/pub"=
  1.1909 +
  1.1910 +*Since:* TWiki::Plugins::VERSION 1.000 (14 Jul 2001)
  1.1911 +d162 9
  1.1912 +d211 1
  1.1913 +a211 1
  1.1914 +in the %TWIKIWEB%.TWikiTemplates topic. Please be careful not to
  1.1915 +d246 27
  1.1916 +d344 12
  1.1917 +a383 1
  1.1918 +
  1.1919 +a384 1
  1.1920 +
  1.1921 +d392 24
  1.1922 +a415 1
  1.1923 +---+++ getWikiName( ) -> $wikiName
  1.1924 +d417 1
  1.1925 +a417 1
  1.1926 +Get Wiki name of logged in user
  1.1927 +d423 2
  1.1928 +d426 4
  1.1929 +a429 3
  1.1930 +---+++ getWikiUserName( ) -> $wikiName
  1.1931 +
  1.1932 +Get Wiki name of logged in user with web prefix
  1.1933 +d437 4
  1.1934 +d442 5
  1.1935 +a446 3
  1.1936 +Translate a Wiki name to a login name based on [[%MAINWEB%.TWikiUsers]] topic
  1.1937 +   * =$wikiName= - Wiki name, e.g. ='Main.JohnDoe'= or ='JohnDoe'=
  1.1938 +Return: =$loginName=   Login name of user, e.g. ='jdoe'=
  1.1939 +d452 1
  1.1940 +a452 2
  1.1941 +
  1.1942 +Translate a login name to a Wiki name based on [[%MAINWEB%.TWikiUsers]] topic
  1.1943 +d457 3
  1.1944 +d463 18
  1.1945 +d488 83
  1.1946 +a570 1
  1.1947 +---+++ permissionsSet( $web ) -> $boolean
  1.1948 +d572 1
  1.1949 +a572 2
  1.1950 +Test if any access restrictions are set for this web, ignoring settings on individual pages
  1.1951 +   * =$web= - Web name, required, e.g. ='Sandbox'=
  1.1952 +d574 1
  1.1953 +a574 1
  1.1954 +*Since:* TWiki::Plugins::VERSION 1.000 (27 Feb 2001)
  1.1955 +d580 1
  1.1956 +a580 1
  1.1957 +[[%TWIKIWEB%.TWikiAccessControl]] rules
  1.1958 +d698 25
  1.1959 +d737 1
  1.1960 +d739 2
  1.1961 +d760 1
  1.1962 +a760 1
  1.1963 +   * =$lock= 1 to lease the topic, 0 to clear the lease=
  1.1964 +d877 1
  1.1965 +a877 7
  1.1966 +more efficient, and returns a user object that contains other user
  1.1967 +information.
  1.1968 +
  1.1969 +NOTE: prior versions of TWiki may under some circumstances have returned
  1.1970 +the login name of the user rather than the wiki name; the code documentation
  1.1971 +was totally unclear, and we have been unable to establish the intent.
  1.1972 +However the wikiname is obviously more useful, so that is what is returned.
  1.1973 +d920 1
  1.1974 +a920 1
  1.1975 +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..
  1.1976 +d1043 1
  1.1977 +a1043 1
  1.1978 +Read a template or skin. Embedded [[%TWIKIWEB%.TWikiTemplates][template directives]] get expanded
  1.1979 +d1083 2
  1.1980 +a1084 2
  1.1981 +   * =$query= - CGI query object. If not given, the default CGI query will be used. In most cases you should _not_ pass this parameter.
  1.1982 +   * =$contentLength= - Length of content
  1.1983 +d1107 1
  1.1984 +a1107 1
  1.1985 +file (see ={PassthroughDir} in =configure=).
  1.1986 +d1144 1
  1.1987 +a1144 1
  1.1988 +---+++ expandCommonVariables( $text, $topic, $web ) -> $text
  1.1989 +d1150 1
  1.1990 +d1160 1
  1.1991 +a1160 1
  1.1992 +Render text from TWiki markup into XHTML as defined in [[%TWIKIWEB%.TextFormattingRules]]
  1.1993 +d1338 32
  1.1994 +a1369 1
  1.1995 + 
  1.1996 +d1510 1
  1.1997 +a1510 1
  1.1998 +The symbols %<nop>USERSWEB%, %<nop>SYSTEMWEB%, %<nop>DOCWEB%, %<nop>MAINWEB% and %<nop>TWIKIWEB% can be used in the input to represent the web names set in $cfg{UsersWebName} and $cfg{SystemWebName}. For example:
  1.1999 +d1517 21
  1.2000 +d1568 13
  1.2001 +d1659 57
  1.2002 +@
  1.2003 +
  1.2004 +
  1.2005 +1.5
  1.2006 +log
  1.2007 +@buildrelease
  1.2008 +@
  1.2009 +text
  1.2010 +@d374 1
  1.2011 +a374 1
  1.2012 +---+++ checkAccessPermission( $type, $wikiName, $text, $topic, $web ) -> $boolean
  1.2013 +d376 13
  1.2014 +a388 4
  1.2015 +Check access permission for a topic based on the [[%TWIKIWEB%.TWikiAccessControl]] rules
  1.2016 +   * =$type=     - Access type, e.g. ='VIEW'=, ='CHANGE'=, ='CREATE'=
  1.2017 +   * =$wikiName= - WikiName of remote user, e.g. ="PeterThoeny"=. If =$wikiName= is '', 0 or undef then access is always *permitted*.
  1.2018 +   * =$text=     - Topic text, optional. If 'perl false' (undef, 0 or ''), topic =$web.$topic= is consulted
  1.2019 +d391 5
  1.2020 +d398 7
  1.2021 +@
  1.2022 +
  1.2023 +
  1.2024 +1.4
  1.2025 +log
  1.2026 +@buildrelease
  1.2027 +@
  1.2028 +text
  1.2029 +@d1176 1
  1.2030 +a1176 1
  1.2031 +represent various string entities in an I18N-compatible manner. Plugins
  1.2032 +@
  1.2033 +
  1.2034 +
  1.2035 +1.3
  1.2036 +log
  1.2037 +@buildrelease
  1.2038 +@
  1.2039 +text
  1.2040 +@d76 2
  1.2041 +d149 1
  1.2042 +a149 1
  1.2043 +Set a session value via the client session module
  1.2044 +d159 4
  1.2045 +a162 3
  1.2046 +Clear a session value via the client session module
  1.2047 +   * =$key=   - Session key
  1.2048 +Return: true if function succeeded
  1.2049 +d168 1
  1.2050 +d234 3
  1.2051 +d248 3
  1.2052 +d266 3
  1.2053 +d280 3
  1.2054 +d391 1
  1.2055 +d493 2
  1.2056 +a494 1
  1.2057 +---+++ checkTopicEditLock( $web, $topic ) -> ( $oopsUrl, $loginName, $unlockTime )
  1.2058 +d499 1
  1.2059 +d505 1
  1.2060 +d522 1
  1.2061 +d578 1
  1.2062 +d611 1
  1.2063 +d691 1
  1.2064 +d722 1
  1.2065 +d756 1
  1.2066 +d823 1
  1.2067 +d844 1
  1.2068 +a844 1
  1.2069 +---+++ redirectCgiQuery( $query, $url )
  1.2070 +d849 26
  1.2071 +a874 1
  1.2072 +Return:             none, never returns
  1.2073 +d880 1
  1.2074 +d938 1
  1.2075 +d964 1
  1.2076 +d977 1
  1.2077 +d1001 1
  1.2078 +d1006 1
  1.2079 +d1045 6
  1.2080 +d1053 1
  1.2081 +d1097 1
  1.2082 +d1216 1
  1.2083 +a1216 1
  1.2084 +Return: the parsed Web/Topic pai
  1.2085 +d1220 17
  1.2086 +a1236 10
  1.2087 +| *Input* | *Return* |
  1.2088 +| <tt>( 'Web',  'Topic' )     </tt> | <tt>( 'Web',  'Topic' ) </tt> |
  1.2089 +| <tt>( '',     'Topic' )     </tt> | <tt>( 'Main', 'Topic' ) </tt> |
  1.2090 +| <tt>( '',     '' )          </tt> | <tt>( 'Main', 'WebHome' ) </tt> |
  1.2091 +| <tt>( '',     'Web/Topic' ) </tt> | <tt>( 'Web',  'Topic' ) </tt> |
  1.2092 +| <tt>( '',     'Web.Topic' ) </tt> | <tt>( 'Web',  'Topic' ) </tt> |
  1.2093 +| <tt>( 'Web1', 'Web2.Topic' )</tt> | <tt>( 'Web2', 'Topic' ) </tt> |
  1.2094 +| <tt>( '%MAINWEB%', 'Topic' )</tt> | <tt>( 'Main', 'Topic' ) </tt> |
  1.2095 +| <tt>( '%TWIKIWEB%', 'Topic' )</tt> | <tt>( 'TWiki', 'Topic' ) </tt> |
  1.2096 +where =Main= and =TWiki= are the web names set in $cfg{UsersWebName} and $cfg{SystemWebName} respectively.
  1.2097 +d1372 1
  1.2098 +a1372 1
  1.2099 +*DEPRECATED* since 1.1 - use the [[#Functions_Content_Handling][content handling functions]] to manipulate topics instead
  1.2100 +d1385 1
  1.2101 +a1385 1
  1.2102 +*DEPRECATED* since 1.1 - use the [[#Functions_Content_Handling][content handling functions]] to manipulateattachments instead
  1.2103 +@
  1.2104 +
  1.2105 +
  1.2106 +1.2
  1.2107 +log
  1.2108 +@buildrelease
  1.2109 +@
  1.2110 +text
  1.2111 +@d362 2
  1.2112 +a363 2
  1.2113 +   * =$wikiName= - WikiName of remote user, i.e. ="Main.PeterThoeny"=
  1.2114 +   * =$text=     - Topic text, optional. If empty, topic =$web.$topic= is consulted
  1.2115 +d366 1
  1.2116 +@
  1.2117 +
  1.2118 +
  1.2119 +1.1
  1.2120 +log
  1.2121 +@buildrelease
  1.2122 +@
  1.2123 +text
  1.2124 +@a273 2
  1.2125 +Synonymous with TWiki::Func::getPreferencesValue('WIKITOOLNAME');
  1.2126 +
  1.2127 +a282 2
  1.2128 +Synonymous with TWiki::Func::getPreferencesValue('MAINWEB');
  1.2129 +
  1.2130 +a291 2
  1.2131 +Synonymous with TWiki::Func::getPreferencesValue('TWIKIWEB');
  1.2132 +
  1.2133 +d671 5
  1.2134 +a675 1
  1.2135 +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.
  1.2136 +d679 1
  1.2137 +a679 2
  1.2138 +TWiki::AccessControlException. Permissions are checked for the user
  1.2139 +passed in.
  1.2140 +d686 1
  1.2141 +a686 1
  1.2142 +       my $data = TWiki::Func::readAttachment( $meta, $a->{name} );
  1.2143 +@