TWiki/TWikiDotPm.mdwn

   1 # <a name="Package &lt;code&gt;TWiki="></a> Package =TWiki
   2
   3 TWiki operates by creating a singleton object (known as the Session object) that acts as a point of reference for all the different modules in the system. This package is the class for this singleton, and also contains the vast bulk of the basic constants and the per- site configuration mechanisms.
   4
   5 Global variables are avoided wherever possible to avoid problems with CGI accelerators such as mod\_perl.
   6
   7 ## <a name="Public Data members"></a> Public Data members
   8
   9 - `cgiQuery` Pointer to the CGI::
  10 - `context` Hash of context ids
  11 - moved: `loginManager` TWiki::LoginManager singleton (moved to TWiki::Users)
  12 - `plugins` TWiki::Plugins singleton
  13 - `prefs` TWiki::Prefs singleton
  14 - `remoteUser` Login ID when using [[ApacheLogin]]. Maintained for compatibility only, do not use.
  15 - `requestedWebName` Name of web found in URL path or `web` URL parameter
  16 - `sandbox` TWiki::Sandbox singleton
  17 - `scriptUrlPath` URL path to the current script. May be dynamically extracted from the URL path if \{GetScriptUrlFromCgi\}. Only required to support \{GetScriptUrlFromCgi\} and not consistently used. Avoid.
  18 - `security` TWiki::Access singleton
  19 - `SESSION_TAGS` Hash of TWiki variables whose value is specific to the current CGI request.
  20 - `store` TWiki::Store singleton
  21 - `topicName` Name of topic found in URL path or `topic` URL parameter
  22 - `urlHost` Host part of the URL (including the protocol) determined during intialisation and defaulting to \{DefaultUrlHost\}
  23 - `user` Unique user ID of logged-in user
  24 - `users` TWiki::Users singleton
  25 - `webName` Name of web found in URL path, or `web` URL parameter, or \{UsersWebName\}
  26
  27 <div>
  28   <ul>
  29     <li><a href="#Package =TWiki="> Package TWiki</a><ul>
  30         <li><a href="#Public Data members"> Public Data members</a></li>
  31         <li><a href="#StaticMethod <strong>get_TWikiLibDir</strong> ("> StaticMethod getTWikiLibDir <tt>() -&gt; $path</tt></a></li>
  32         <li><a href="#StaticMethod *_UTF82SiteCharSet*"> StaticMethod UTF82SiteCharSet <tt>($utf8) -&gt; $ascii</tt></a></li>
  33         <li><a href="#ObjectMethod *write_CompletePage"> ObjectMethod writeCompletePage <tt>($text,$pageType,$contentType)</tt></a></li>
  34         <li><a href="#ObjectMethod *generateHTTPHeader"> ObjectMethod generateHTTPHeaders <tt>($query,$pageType,$contentType,$contentLength) -&gt; $header</tt></a></li>
  35         <li><a href="#StaticMethod <strong>is_RedirectSafe</strong> ("> StaticMethod isRedirectSafe <tt>($redirect)=&gt;$ok</tt></a></li>
  36         <li><a href="#ObjectMethod <strong>redirect</strong> ($url,$p"> ObjectMethod redirect <tt>($url,$passthrough,$action_redirectto)</tt></a></li>
  37         <li><a href="#ObjectMethod <strong>cacheQuery</strong> () ->"> ObjectMethod cacheQuery <tt>() -&gt; $queryString</tt></a></li>
  38         <li><a href="#StaticMethod *is_ValidWikiWord*"> StaticMethod isValidWikiWord <tt>($name) -&gt; $boolean</tt></a></li>
  39         <li><a href="#StaticMethod *is_ValidTopicName*"> StaticMethod isValidTopicName <tt>($name) -&gt; $boolean</tt></a></li>
  40         <li><a href="#StaticMethod <strong>is_ValidAbbrev</strong> ($"> StaticMethod isValidAbbrev <tt>($name) -&gt; $boolean</tt></a></li>
  41         <li><a href="#StaticMethod <strong>is_ValidWebName</strong> ("> StaticMethod isValidWebName <tt>($name,$system) -&gt; $boolean</tt></a></li>
  42         <li><a href="#ObjectMethod *read_OnlyMirrorWeb"> ObjectMethod readOnlyMirrorWeb <tt>($theWeb) -&gt; ($mirrorSiteName,$mirrorViewURL,$mirrorLink,$mirrorNote)</tt></a></li>
  43         <li><a href="#ObjectMethod <strong>getSkin</strong> () -> $st"> ObjectMethod getSkin <tt>() -&gt; $string</tt></a></li>
  44         <li><a href="#ObjectMethod <strong>get_ScriptUrl</strong> ($a"> ObjectMethod getScriptUrl <tt>($absolute,$script,$web,$topic,...) -&gt; $scriptURL</tt></a></li>
  45         <li><a href="#ObjectMethod <strong>get_PubUrl</strong> ($abso"> ObjectMethod getPubUrl <tt>($absolute,$web,$topic,$attachment) -&gt; $url</tt></a></li>
  46         <li><a href="#ObjectMethod <strong>get_IconUrl</strong> ($abs"> ObjectMethod getIconUrl <tt>($absolute,$iconName) -&gt; $iconURL</tt></a></li>
  47         <li><a href="#ObjectMethod *map_ToIconFileName"> ObjectMethod mapToIconFileName <tt>($fileName,$default) -&gt; $fileName</tt></a></li>
  48         <li><a href="#ObjectMethod *normalize_WebTopic"> ObjectMethod normalizeWebTopicName <tt>($theWeb,$theTopic) -&gt; ($theWeb,$theTopic)</tt></a></li>
  49         <li><a href="#ClassMethod <strong>new</strong> ($loginName,$q"> ClassMethod new <tt>($loginName,$query,\%initialContext)</tt></a></li>
  50         <li><a href="#ObjectMethod <strong>renderer</strong> ()"> ObjectMethod renderer <tt>()</tt></a></li>
  51         <li><a href="#ObjectMethod <strong>attach</strong> ()"> ObjectMethod attach <tt>()</tt></a></li>
  52         <li><a href="#ObjectMethod <strong>templates</strong> ()"> ObjectMethod templates <tt>()</tt></a></li>
  53         <li><a href="#ObjectMethod <strong>i18n</strong> ()"> ObjectMethod i18n <tt>()</tt></a></li>
  54         <li><a href="#ObjectMethod <strong>search</strong> ()"> ObjectMethod search <tt>()</tt></a></li>
  55         <li><a href="#ObjectMethod <strong>security</strong> ()"> ObjectMethod security <tt>()</tt></a></li>
  56         <li><a href="#ObjectMethod <strong>net</strong> ()"> ObjectMethod net <tt>()</tt></a></li>
  57         <li><a href="#ObjectMethod <strong>finish</strong> ()"> ObjectMethod finish <tt>()</tt></a></li>
  58         <li><a href="#ObjectMethod <strong>writeLog</strong> ($action"> ObjectMethod writeLog <tt>($action,$webTopic,$extra,$user)</tt></a></li>
  59         <li><a href="#ObjectMethod <strong>writeWarning</strong> ($te"> ObjectMethod writeWarning <tt>($text)</tt></a></li>
  60         <li><a href="#ObjectMethod <strong>writeDebug</strong> ($text"> ObjectMethod writeDebug <tt>($text)</tt></a></li>
  61         <li><a href="#StaticMethod *apply_PatternToInc"> StaticMethod applyPatternToIncludedText <tt>($text,$pattern) -&gt; $text</tt></a></li>
  62         <li><a href="#ObjectMethod <strong>inlineAlert</strong> ($tem"> ObjectMethod inlineAlert <tt>($template,$def,...) -&gt; $string</tt></a></li>
  63         <li><a href="#StaticMethod <strong>parseSections</strong> ($t"> StaticMethod parseSections <tt>($text) -&gt; ($string,$sectionlistref)</tt></a></li>
  64         <li><a href="#ObjectMethod *expand_VariablesOn"> ObjectMethod expandVariablesOnTopicCreation <tt>($text,$user,$web,$topic) -&gt; $text</tt></a></li>
  65         <li><a href="#StaticMethod <strong>entityEncode</strong> ($te"> StaticMethod entityEncode <tt>($text,$extras) -&gt; $encodedText</tt></a></li>
  66         <li><a href="#StaticMethod <strong>entityDecode</strong> ($en"> StaticMethod entityDecode <tt>($encodedText) -&gt; $text</tt></a></li>
  67         <li><a href="#StaticMethod *url_EncodeAttachme"> StaticMethod urlEncodeAttachment <tt>($text)</tt></a></li>
  68         <li><a href="#StaticMethod <strong>urlEncode</strong> ($strin"> StaticMethod urlEncode <tt>($string) -&gt; encodedstring</tt></a></li>
  69         <li><a href="#StaticMethod <strong>urlDecode</strong> ($strin"> StaticMethod urlDecode <tt>($string) -&gt; decodedstring</tt></a></li>
  70         <li><a href="#StaticMethod <strong>isTrue</strong> ($value,$d"> StaticMethod isTrue <tt>($value,$default) -&gt; $boolean</tt></a></li>
  71         <li><a href="#StaticMethod *space_OutWikiWord*"> StaticMethod spaceOutWikiWord <tt>($word,$sep) -&gt; $string</tt></a></li>
  72         <li><a href="#ObjectMethod <strong>expand_AllTags</strong> (\"> ObjectMethod expandAllTags <tt>(\$text,$topic,$web,$meta)</tt></a></li>
  73         <li><a href="#ObjectMethod <strong>enterContext</strong> ($id"> ObjectMethod enterContext <tt>($id,$val)</tt></a></li>
  74         <li><a href="#ObjectMethod <strong>leaveContext</strong> ($id"> ObjectMethod leaveContext <tt>($id)</tt></a></li>
  75         <li><a href="#ObjectMethod <strong>inContext</strong> ($id)"> ObjectMethod inContext <tt>($id)</tt></a></li>
  76         <li><a href="#StaticMethod *register_TagHandle"> StaticMethod registerTagHandler <tt>($tag,$fnref)</tt></a></li>
  77         <li><a href="#StaticMethod *registerRESTHandle"> StaticMethod registerRESTHandler <tt>($subject,$verb,\&amp;fn)</tt></a></li>
  78         <li><a href="#StaticMethod <strong>restDispatch</strong> ($su"> StaticMethod restDispatch <tt>($subject,$verb)=&gt;\&amp;fn</tt></a></li>
  79         <li><a href="#ObjectMethod *handle_CommonTags*"> ObjectMethod handleCommonTags <tt>($text,$web,$topic,$meta) -&gt; $text</tt></a></li>
  80         <li><a href="#ObjectMethod <strong>add_ToHEAD</strong> ($id,$"> ObjectMethod addToHEAD <tt>($id,$html)</tt></a></li>
  81         <li><a href="#StaticMethod <strong>initialize</strong> ($path"> StaticMethod initialize <tt>($pathInfo,$remoteUser,$topic,$url,$query) -&gt; ($topicName,$webName,$scriptUrlPath,$userName,$dataDir)</tt></a></li>
  82         <li><a href="#StaticMethod <strong>readFile</strong> ($filena"> StaticMethod readFile <tt>($filename) -&gt; $text</tt></a></li>
  83         <li><a href="#StaticMethod *expand_StandardEsc"> StaticMethod expandStandardEscapes <tt>($str) -&gt; $unescapedStr</tt></a></li>
  84       </ul>
  85     </li>
  86   </ul>
  87 </div>
  88
  89 ## <a name="StaticMethod &lt;strong&gt;get_TWikiLibDir&lt;/strong&gt; ("></a> [[StaticMethod]] **getTWikiLibDir** `() -> $path`
  90
  91 Returns the full path of the directory containing TWiki.pm
  92
  93 ## <a name="StaticMethod &lt;strong&gt;_UTF82SiteCharSet*"></a> [[StaticMethod]] \*UTF82SiteCharSet `($utf8) -> $ascii`
  94
  95 Auto-detect UTF-8 vs. site charset in string, and convert UTF-8 into site charset.
  96
  97 ## <a name="ObjectMethod &lt;strong&gt;write_CompletePage"></a> [[ObjectMethod]] \*writeCompletePage `($text,$pageType,$contentType)`
  98
  99 Write a complete HTML page with basic header to the browser.
 100
 101 - `$text` is the text of the page body (&lt;html&gt; to &lt;/html&gt; if it's HTML)
 102 - `$pageType` - May be "edit", which will cause headers to be generated that force caching for 24 hours, to prevent [[BackFromPreviewLosesText]] bug, which caused data loss with IE5 and IE6.
 103 - `$contentType` - page content type | text/html
 104
 105 This method removes noautolink and nop tags before outputting the page unless $contentType is text/plain.
 106
 107 ## <a name="ObjectMethod &lt;strong&gt;generateHTTPHeader"></a> [[ObjectMethod]] \*generateHTTPHeaders `($query,$pageType,$contentType,$contentLength) -> $header`
 108
 109 All parameters are optional.
 110
 111 - `$query` CGI query object | Session CGI query (there is no good reason to set this)
 112 - `$pageType` - May be "edit", which will cause headers to be generated that force caching for 24 hours, to prevent [[BackFromPreviewLosesText]] bug, which caused data loss with IE5 and IE6.
 113 - `$contentType` - page content type | text/html
 114 - `$contentLength` - content-length | no content-length will be set if this is undefined, as required by HTTP1.1
 115
 116 Implements the post-Dec2001 release plugin API, which requires the writeHeaderHandler in plugin to return a string of HTTP headers, CR/LF delimited. Filters any illegal headers. Plugin headers will override core settings.
 117
 118 Does **not** add a `Content-length` header.
 119
 120 ## <a name="StaticMethod &lt;strong&gt;is_RedirectSafe&lt;/strong&gt; ("></a> [[StaticMethod]] **isRedirectSafe** `($redirect)=>$ok`
 121
 122 tests if the $redirect is an external URL, returning false if [[AllowRedirectUrl]] is denied
 123
 124 ## <a name="ObjectMethod &lt;strong&gt;redirect&lt;/strong&gt; ($url,$p"></a> [[ObjectMethod]] **redirect** `($url,$passthrough,$action_redirectto)`
 125
 126 - $url - url or twikitopic to redirect to
 127 - $passthrough - (optional) parameter to **\*FILLMEIN\***
 128 - $action\_redirectto - (optional) redirect to where ?redirectto= points to (if it's valid)
 129
 130 Redirects the request to `$url`, **unless**
 131
 132 1. It is overridden by a plugin declaring a `redirectCgiQueryHandler`.
 133 2. `$session->{cgiQuery}` is `undef` or
 134 3. $query-&gt;param('noredirect') is set to a true value.
 135
 136 Thus a redirect is only generated when in a CGI context.
 137
 138 Normally this method will ignore parameters to the current query. Sometimes, for example when redirecting to a login page during authentication (and then again from the login page to the original requested URL), you want to make sure all parameters are passed on, and for this $passthrough should be set to true. In this case it will pass all parameters that were passed to the current query on to the redirect target. If the request\_method for the current query was GET, then all parameters will be passed by encoding them in the URL (after ?). If the request\_method was POST, then there is a risk the URL would be too big for the receiver, so it caches the form data and passes over a cache reference in the redirect GET.
 139
 140 NOTE: Passthrough is only meaningful if the redirect target is on the same server.
 141
 142 ## <a name="ObjectMethod &lt;strong&gt;cacheQuery&lt;/strong&gt; () - $"></a> [[ObjectMethod]] **cacheQuery** `() -> $queryString`
 143
 144 Caches the current query in the params cache, and returns a rewritten query string for the cache to be picked up again on the other side of a redirect.
 145
 146 We can't encode post params into a redirect, because they may exceed the size of the GET request. So we cache the params, and reload them when the redirect target is reached.
 147
 148 ## <a name="StaticMethod &lt;strong&gt;is_ValidWikiWord*"></a><a name="StaticMethod *is_ValidWikiWord&lt;/strong&gt; "></a> [[StaticMethod]] **isValidWikiWord** `($name) -> $boolean`
 149
 150 Check for a valid [[WikiWord]] or [[WikiName]]
 151
 152 ## <a name="StaticMethod &lt;strong&gt;is_ValidTopicName*"></a> [[StaticMethod]] \*isValidTopicName `($name) -> $boolean`
 153
 154 Check for a valid topic name
 155
 156 ## <a name="StaticMethod &lt;strong&gt;is_ValidAbbrev&lt;/strong&gt; ($"></a> [[StaticMethod]] **isValidAbbrev** `($name) -> $boolean`
 157
 158 Check for a valid ABBREV (acronym)
 159
 160 ## <a name="StaticMethod &lt;strong&gt;is_ValidWebName&lt;/strong&gt; ("></a> [[StaticMethod]] **isValidWebName** `($name,$system) -> $boolean`
 161
 162 STATIC Check for a valid web name. If $system is true, then system web names are considered valid (names starting with \_) otherwise only user web names are valid
 163
 164 If $TWiki::cfg\{EnableHierarchicalWebs\} is off, it will also return false when a nested web name is passed to it.
 165
 166 ## <a name="ObjectMethod &lt;strong&gt;read_OnlyMirrorWeb"></a> [[ObjectMethod]] \*readOnlyMirrorWeb `($theWeb) -> ($mirrorSiteName,$mirrorViewURL,$mirrorLink,$mirrorNote)`
 167
 168 If this is a mirrored web, return information about the mirror. The info is returned in a quadruple:
 169
 170 <table border="1" cellpadding="0" cellspacing="0">
 171   <tr>
 172     <td> site name </td>
 173     <td> URL </td>
 174     <td> link </td>
 175     <td> note </td>
 176   </tr>
 177 </table>
 178
 179 ## <a name="ObjectMethod &lt;strong&gt;getSkin&lt;/strong&gt; () - $str"></a> [[ObjectMethod]] **getSkin** `() -> $string`
 180
 181 Get the currently requested skin path
 182
 183 ## <a name="ObjectMethod &lt;strong&gt;get_ScriptUrl&lt;/strong&gt; ($a"></a> [[ObjectMethod]] **getScriptUrl** `($absolute,$script,$web,$topic,...) -> $scriptURL`
 184
 185 Returns the URL to a TWiki script, providing the web and topic as "path info" parameters. The result looks something like this: "http://host/twiki/bin/$script/$web/$topic".
 186
 187 - `...` - an arbitrary number of name,value parameter pairs that will be url-encoded and added to the url. The special parameter name '#' is reserved for specifying an anchor. e.g. `getScriptUrl('x','y','view','#'=>'XXX',a=>1,b=>2)` will give `.../view/x/y?a=1&b=2#XXX`
 188
 189 If $absolute is set, generates an absolute URL. $absolute is advisory only; TWiki can decide to generate absolute URLs (for example when run from the command-line) even when relative URLs have been requested.
 190
 191 The default script url is taken from \{ScriptUrlPath\}, unless there is an exception defined for the given script in \{ScriptUrlPaths\}. Both \{ScriptUrlPath\} and \{ScriptUrlPaths\} may be absolute or relative URIs. If they are absolute, then they will always generate absolute URLs. if they are relative, then they will be converted to absolute when required (e.g. when running from the command line, or when generating rss). If $script is not given, absolute URLs will always be generated.
 192
 193 If either the web or the topic is defined, will generate a full url (including web and topic). Otherwise will generate only up to the script name. An undefined web will default to the main web name.
 194
 195 ## <a name="ObjectMethod &lt;strong&gt;get_PubUrl&lt;/strong&gt; ($abso"></a> [[ObjectMethod]] **getPubUrl** `($absolute,$web,$topic,$attachment) -> $url`
 196
 197 Composes a pub url. If $absolute is set, returns an absolute URL. If $absolute is set, generates an absolute URL. $absolute is advisory only; TWiki can decide to generate absolute URLs (for example when run from the command-line) even when relative URLs have been requested.
 198
 199 $web, $topic and $attachment are optional. A partial URL path will be generated if one or all is not given.
 200
 201 ## <a name="ObjectMethod &lt;strong&gt;get_IconUrl&lt;/strong&gt; ($abs"></a> [[ObjectMethod]] **getIconUrl** `($absolute,$iconName) -> $iconURL`
 202
 203 Map an icon name to a URL path.
 204
 205 ## <a name="ObjectMethod &lt;strong&gt;map_ToIconFileName"></a> [[ObjectMethod]] \*mapToIconFileName `($fileName,$default) -> $fileName`
 206
 207 Maps from a filename (or just the extension) to the name of the file that contains the image for that file type.
 208
 209 ## <a name="ObjectMethod &lt;strong&gt;normalize_WebTopic"></a> [[ObjectMethod]] \*normalizeWebTopicName `($theWeb,$theTopic) -> ($theWeb,$theTopic)`
 210
 211 Normalize a Web.TopicName
 212
 213 See [[TWikiFuncDotPm]] for a full specification of the expansion (not duplicated here)
 214
 215 **WARNING** if there is no web specification (in the web or topic parameters) the web defaults to $TWiki::cfg\{UsersWebName\}. If there is no topic specification, or the topic is '0', the topic defaults to the web home topic name.
 216
 217 ## <a name="ClassMethod &lt;strong&gt;new&lt;/strong&gt; ($loginName,$q"></a> [[ClassMethod]] **new** `($loginName,$query,\%initialContext)`
 218
 219 Constructs a new TWiki object. Parameters are taken from the query object.
 220
 221 - `$loginName` is the login username (**not** the wikiname) of the user you want to be logged-in if none is available from a session or browser. Used mainly for side scripts and debugging.
 222 - `$query` the CGI query (may be undef, in which case an empty query is used)
 223 - `\%initialContext` - reference to a hash containing context name=value pairs to be pre-installed in the context hash
 224
 225 ## <a name="ObjectMethod &lt;strong&gt;renderer&lt;/strong&gt; ()"></a> [[ObjectMethod]] **renderer** `()`
 226
 227 Get a reference to the renderer object. Done lazily because not everyone needs the renderer.
 228
 229 ## <a name="ObjectMethod &lt;strong&gt;attach&lt;/strong&gt; ()"></a> [[ObjectMethod]] **attach** `()`
 230
 231 Get a reference to the attach object. Done lazily because not everyone needs the attach.
 232
 233 ## <a name="ObjectMethod &lt;strong&gt;templates&lt;/strong&gt; ()"></a> [[ObjectMethod]] **templates** `()`
 234
 235 Get a reference to the templates object. Done lazily because not everyone needs the templates.
 236
 237 ## <a name="ObjectMethod &lt;strong&gt;i18n&lt;/strong&gt; ()"></a> [[ObjectMethod]] **i18n** `()`
 238
 239 Get a reference to the i18n object. Done lazily because not everyone needs the i18ner.
 240
 241 ## <a name="ObjectMethod &lt;strong&gt;search&lt;/strong&gt; ()"></a> [[ObjectMethod]] **search** `()`
 242
 243 Get a reference to the search object. Done lazily because not everyone needs the searcher.
 244
 245 ## <a name="ObjectMethod &lt;strong&gt;security&lt;/strong&gt; ()"></a> [[ObjectMethod]] **security** `()`
 246
 247 Get a reference to the security object. Done lazily because not everyone needs the security.
 248
 249 ## <a name="ObjectMethod &lt;strong&gt;net&lt;/strong&gt; ()"></a> [[ObjectMethod]] **net** `()`
 250
 251 Get a reference to the net object. Done lazily because not everyone needs the net.
 252
 253 ## <a name="ObjectMethod &lt;strong&gt;finish&lt;/strong&gt; ()"></a> [[ObjectMethod]] **finish** `()`
 254
 255 Break circular references.
 256
 257 ## <a name="ObjectMethod &lt;strong&gt;writeLog&lt;/strong&gt; ($action"></a> [[ObjectMethod]] **writeLog** `($action,$webTopic,$extra,$user)`
 258
 259 - `$action` - what happened, e.g. view, save, rename
 260 - `$wbTopic` - what it happened to
 261 - `$extra` - extra info, such as minor flag
 262 - `$user` - user who did the saving (user id)
 263
 264 Write the log for an event to the logfile
 265
 266 ## <a name="ObjectMethod &lt;strong&gt;writeWarning&lt;/strong&gt; ($te"></a> [[ObjectMethod]] **writeWarning** `($text)`
 267
 268 Prints date, time, and contents $text to $TWiki::cfg\{WarningFileName\}, typically 'warnings.txt'. Use for warnings and errors that may require admin intervention. Use this for defensive programming warnings (e.g. assertions).
 269
 270 ## <a name="ObjectMethod &lt;strong&gt;writeDebug&lt;/strong&gt; ($text"></a> [[ObjectMethod]] **writeDebug** `($text)`
 271
 272 Prints date, time, and contents of $text to $TWiki::cfg\{DebugFileName\}, typically 'debug.txt'. Use for debugging messages.
 273
 274 ## <a name="StaticMethod &lt;strong&gt;apply_PatternToInc"></a> [[StaticMethod]] \*applyPatternToIncludedText `($text,$pattern) -> $text`
 275
 276 Apply a pattern on included text to extract a subset
 277
 278 ## <a name="ObjectMethod &lt;strong&gt;inlineAlert&lt;/strong&gt; ($tem"></a> [[ObjectMethod]] **inlineAlert** `($template,$def,...) -> $string`
 279
 280 Format an error for inline inclusion in rendered output. The message string is obtained from the template 'oops'.$template, and the DEF $def is selected. The parameters (...) are used to populate %PARAM1%..%PARAMn%
 281
 282 ## <a name="StaticMethod &lt;strong&gt;parseSections&lt;/strong&gt; ($t"></a> [[StaticMethod]] **parseSections** `($text) -> ($string,$sectionlistref)`
 283
 284 Generic parser for sections within a topic. Sections are delimited by STARTSECTION and ENDSECTION, which may be nested, overlapped or otherwise abused. The parser builds an array of sections, which is ordered by the order of the STARTSECTION within the topic. It also removes all the SECTION tags from the text, and returns the text and the array of sections.
 285
 286 Each section is a `TWiki::Attrs` object, which contains the attributes \{type, name, start, end\} where start and end are character offsets in the string **after all section tags have been removed**. All sections are required to be uniquely named; if a section is unnamed, it will be given a generated name. Sections may overlap or nest.
 287
 288 See test/unit/Fn\_SECTION.pm for detailed testcases that round out the spec.
 289
 290 ## <a name="ObjectMethod &lt;strong&gt;expand_VariablesOn"></a> [[ObjectMethod]] \*expandVariablesOnTopicCreation `($text,$user,$web,$topic) -> $text`
 291
 292 - `$text` - text to expand
 293 - `$user` - This is the user expanded in e.g. %USERNAME. Optional, defaults to logged-in user.
 294
 295 Expand limited set of variables during topic creation. These are variables expected in templates that must be statically expanded in new content.
 296
 297 - `$web` - name of web
 298 - `$topic` - name of topic
 299
 300 # SMELL: no plugin handler
 301
 302 ## <a name="StaticMethod &lt;strong&gt;entityEncode&lt;/strong&gt; ($te"></a> [[StaticMethod]] **entityEncode** `($text,$extras) -> $encodedText`
 303
 304 Escape special characters to HTML numeric entities. This is **not** a generic encoding, it is tuned specifically for use in TWiki.
 305
 306 HTML4.0 spec: "Certain characters in HTML are reserved for use as markup and must be escaped to appear literally. The "&lt;" character may be represented with an _entity_, **&amp;lt;**. Similarly, "&gt;" is escaped as **&amp;gt;**, and "&amp;" is escaped as **&amp;amp;**. If an attribute value contains a double quotation mark and is delimited by double quotation marks, then the quote should be escaped as **&amp;quot;**.
 307
 308 Other entities exist for special characters that cannot easily be entered with some keyboards..."
 309
 310 This method encodes HTML special and any non-printable ascii characters (except for \\n and \\r) using numeric entities.
 311
 312 FURTHER this method also encodes characters that are special in TWiki meta-language.
 313
 314 $extras is an optional param that may be used to include **additional** characters in the set of encoded characters. It should be a string containing the additional chars.
 315
 316 ## <a name="StaticMethod &lt;strong&gt;entityDecode&lt;/strong&gt; ($en"></a> [[StaticMethod]] **entityDecode** `($encodedText) -> $text`
 317
 318 Decodes all numeric entities (e.g. &amp;#123;). _Does not_ decode named entities such as &amp;amp; (use HTML::Entities for that)
 319
 320 ## <a name="StaticMethod &lt;strong&gt;url_EncodeAttachme"></a> [[StaticMethod]] \*urlEncodeAttachment `($text)`
 321
 322 For attachments, URL-encode specially to 'freeze' any characters &gt;127 in the site charset (e.g. ISO-8859-1 or KOI8-R), by doing URL encoding into native charset ($siteCharset) - used when generating attachment URLs, to enable the web server to serve attachments, including images, directly.
 323
 324 This encoding is required to handle the cases of:
 325
 326 - browsers that generate UTF-8 URLs automatically from site charset URLs - now quite common - web servers that directly serve attachments, using the site charset for filenames, and cannot convert UTF-8 URLs into site charset filenames
 327
 328 The aim is to prevent the browser from converting a site charset URL in the web page to a UTF-8 URL, which is the default. Hence we 'freeze' the URL into the site character set through URL encoding.
 329
 330 In two cases, no URL encoding is needed: For EBCDIC mainframes, we assume that site charset URLs will be translated (outbound and inbound) by the web server to/from an EBCDIC character set. For sites running in UTF-8, there's no need for TWiki to do anything since all URLs and attachment filenames are already in UTF-8.
 331
 332 ## <a name="StaticMethod &lt;strong&gt;urlEncode&lt;/strong&gt; ($strin"></a> [[StaticMethod]] **urlEncode** `($string) -> encodedstring`
 333
 334 Encode by converting characters that are illegal in URLs to their %NN equivalents. This method is used for encoding strings that must be embedded _verbatim_ in URLs; it cannot be applied to URLs themselves, as it escapes reserved characters such as = and ?.
 335
 336 RFC 1738, Dec. '94:
 337
 338         ...Only alphanumerics [0-9a-zA-Z], the special
 339         characters $-_.+!*'(), and reserved characters used for their
 340         reserved purposes may be used unencoded within a URL.
 341
 342 Reserved characters are $&amp;+,/:;=?@ - these are _also_ encoded by this method.
 343
 344 This URL-encoding handles all character encodings including ISO-8859-\*, KOI8-R, EUC-\* and UTF-8.
 345
 346 This may not handle EBCDIC properly, as it generates an EBCDIC URL-encoded URL, but mainframe web servers seem to translate this outbound before it hits browser - see CGI::Util::escape for another approach.
 347
 348 ## <a name="StaticMethod &lt;strong&gt;urlDecode&lt;/strong&gt; ($strin"></a> [[StaticMethod]] **urlDecode** `($string) -> decodedstring`
 349
 350 Reverses the encoding done in urlEncode.
 351
 352 ## <a name="StaticMethod &lt;strong&gt;isTrue&lt;/strong&gt; ($value,$d"></a> [[StaticMethod]] **isTrue** `($value,$default) -> $boolean`
 353
 354 Returns 1 if `$value` is true, and 0 otherwise. "true" means set to something with a Perl true value, with the special cases that "off", "false" and "no" (case insensitive) are forced to false. Leading and trailing spaces in `$value` are ignored.
 355
 356 If the value is undef, then `$default` is returned. If `$default` is not specified it is taken as 0.
 357
 358 ## <a name="StaticMethod &lt;strong&gt;space_OutWikiWord*"></a> [[StaticMethod]] \*spaceOutWikiWord `($word,$sep) -> $string`
 359
 360 Spaces out a wiki word by inserting a string (default: one space) between each word component. With parameter $sep any string may be used as separator between the word components; if $sep is undefined it defaults to a space.
 361
 362 ## <a name="ObjectMethod &lt;strong&gt;expand_AllTags&lt;/strong&gt; (\"></a> [[ObjectMethod]] **expandAllTags** `(\$text,$topic,$web,$meta)`
 363
 364 Expands variables by replacing the variables with their values. Some example variables: %TOPIC%, %SCRIPTURL%, %WIKINAME%, etc. $web and $incs are passed in for recursive include expansion. They can safely be undef. The rules for tag expansion are:
 365
 366 1. Tags are expanded left to right, in the order they are encountered.
 367 2. Tags are recursively expanded as soon as they are encountered - the algorithm is inherently single-pass
 368 3. A tag is not "encountered" until the matching \}% has been seen, by which time all tags in parameters will have been expanded
 369 4. Tag expansions that create new tags recursively are limited to a set number of hierarchical levels of expansion
 370
 371 ## <a name="ObjectMethod &lt;strong&gt;enterContext&lt;/strong&gt; ($id"></a> [[ObjectMethod]] **enterContext** `($id,$val)`
 372
 373 Add the context id $id into the set of active contexts. The $val can be anything you like, but should always evaluate to boolean TRUE.
 374
 375 An example of the use of contexts is in the use of tag expansion. The commonTagsHandler in plugins is called every time tags need to be expanded, and the context of that expansion is signalled by the expanding module using a context id. So the forms module adds the context id "form" before invoking common tags expansion.
 376
 377 Contexts are not just useful for tag expansion; they are also relevant when rendering.
 378
 379 Contexts are intended for use mainly by plugins. Core modules can use $session-&gt;inContext( $id ) to determine if a context is active.
 380
 381 ## <a name="ObjectMethod &lt;strong&gt;leaveContext&lt;/strong&gt; ($id"></a> [[ObjectMethod]] **leaveContext** `($id)`
 382
 383 Remove the context id $id from the set of active contexts. (see `enterContext` for more information on contexts)
 384
 385 ## <a name="ObjectMethod &lt;strong&gt;inContext&lt;/strong&gt; ($id)"></a> [[ObjectMethod]] **inContext** `($id)`
 386
 387 Return the value for the given context id (see `enterContext` for more information on contexts)
 388
 389 ## <a name="StaticMethod &lt;strong&gt;register_TagHandle"></a> [[StaticMethod]] \*registerTagHandler `($tag,$fnref)`
 390
 391 STATIC Add a tag handler to the function tag handlers.
 392
 393 - `$tag` name of the tag e.g. MYTAG
 394 - `$fnref` Function to execute. Will be passed ($session, \\%params, $web, $topic )
 395
 396 ## <a name="StaticMethod &lt;strong&gt;registerRESTHandle"></a> [[StaticMethod]] \*registerRESTHandler `($subject,$verb,\&fn)`
 397
 398 Adds a function to the dispatch table of the REST interface for a given subject. See [[TWikiScripts#rest]] for more info.
 399
 400 - `$subject` - The subject under which the function will be registered.
 401 - `$verb` - The verb under which the function will be registered.
 402 - `\&fn` - Reference to the function.
 403
 404 The handler function must be of the form:
 405
 406     sub handler(\%session,$subject,$verb) -> $text
 407
 408 where:
 409
 410 - `\%session` - a reference to the TWiki session object (may be ignored)
 411 - `$subject` - The invoked subject (may be ignored)
 412 - `$verb` - The invoked verb (may be ignored)
 413
 414 **Since:** TWiki::Plugins::VERSION 1.1
 415
 416 ## <a name="StaticMethod &lt;strong&gt;restDispatch&lt;/strong&gt; ($su"></a> [[StaticMethod]] **restDispatch** `($subject,$verb)=>\&fn`
 417
 418 Returns the handler function associated to the given $subject and $werb, or undef if none is found.
 419
 420 **Since:** TWiki::Plugins::VERSION 1.1
 421
 422 ## <a name="ObjectMethod &lt;strong&gt;handle_CommonTags*"></a> [[ObjectMethod]] \*handleCommonTags `($text,$web,$topic,$meta) -> $text`
 423
 424 Processes %VARIABLE%, and %TOC% syntax; also includes 'commonTagsHandler' plugin hook.
 425
 426 Returns the text of the topic, after file inclusion, variable substitution, table-of-contents generation, and any plugin changes from commonTagsHandler.
 427
 428 $meta may be undef when, for example, expanding templates, or one-off strings at a time when meta isn't available.
 429
 430 ## <a name="ObjectMethod &lt;strong&gt;add_ToHEAD&lt;/strong&gt; ($id,$"></a> [[ObjectMethod]] **addToHEAD** `($id,$html)`
 431
 432 Add `$html` to the HEAD tag of the page currently being generated.
 433
 434 Note that TWiki variables may be used in the HEAD. They will be expanded according to normal variable expansion rules.
 435
 436 The 'id' is used to ensure that multiple adds of the same block of HTML don't result in it being added many times.
 437
 438 ## <a name="StaticMethod &lt;strong&gt;initialize&lt;/strong&gt; ($path"></a> [[StaticMethod]] **initialize** `($pathInfo,$remoteUser,$topic,$url,$query) -> ($topicName,$webName,$scriptUrlPath,$userName,$dataDir)`
 439
 440 Return value: ( $topicName, $webName, $TWiki::cfg\{ScriptUrlPath\}, $userName, $TWiki::cfg\{DataDir\} )
 441
 442 Static method to construct a new singleton session instance. It creates a new TWiki and sets the Plugins $SESSION variable to point to it, so that TWiki::Func methods will work.
 443
 444 This method is **DEPRECATED** but is maintained for script compatibility.
 445
 446 Note that $theUrl, if specified, must be identical to $query-&gt;url()
 447
 448 ## <a name="StaticMethod &lt;strong&gt;readFile&lt;/strong&gt; ($filena"></a> [[StaticMethod]] **readFile** `($filename) -> $text`
 449
 450 Returns the entire contents of the given file, which can be specified in any format acceptable to the Perl open() function. Fast, but inherently unsafe.
 451
 452 WARNING: Never, ever use this for accessing topics or attachments! Use the Store API for that. This is for global control files only, and should be used **only** if there is **absolutely no alternative**.
 453
 454 ## <a name="StaticMethod &lt;strong&gt;expand_StandardEsc"></a> [[StaticMethod]] \*expandStandardEscapes `($str) -> $unescapedStr`
 455
 456 Expands standard escapes used in parameter values to block evaluation. The following escapes are handled:
 457
 458 <table border="1" cellpadding="0" cellspacing="0">
 459   <tr>
 460     <th bgcolor="#99CCCC"><strong> Escape: </strong></th>
 461     <th bgcolor="#99CCCC"><strong> Expands To: </strong></th>
 462   </tr>
 463   <tr>
 464     <td><code>$n</code> or <code>$n()</code></td>
 465     <td> New line. Use <code>$n()</code> if followed by alphanumeric character, e.g. write <code>Foo$n()Bar</code> instead of <code>Foo$nBar</code></td>
 466   </tr>
 467   <tr>
 468     <td><code>$nop</code> or <code>$nop()</code></td>
 469     <td> Is a "no operation". </td>
 470   </tr>
 471   <tr>
 472     <td><code>$quot</code></td>
 473     <td> Double quote (<code>"</code>) </td>
 474   </tr>
 475   <tr>
 476     <td><code>$percnt</code></td>
 477     <td> Percent sign (<code>%</code>) </td>
 478   </tr>
 479   <tr>
 480     <td><code>$dollar</code></td>
 481     <td> Dollar sign (<code>$</code>) </td>
 482   </tr>
 483 </table>