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