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.

>>

Spaces out a wiki word by inserting a string between each word component.
Word component boundaries are transitions from lowercase to uppercase or numeric,
from numeric to uppercase or lowercase, and from uppercase to numeric characters.

Parameter $sep defines the separator between the word components, the default is a space.

Returns the MIME type corresponding to the extension of the $filename based on
the file specified by {MimeTypesFileName}. If there is no extension or the
extension is not found in the {MimeTypesFileName} file, 'text/plain' is
returned.

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

Changed:

<<

.../view/x/y?a=1&b=2#XXX

>>

.../view/x/y?a=1&b=2#XXX

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

Line: 203 to 219

(including web and topic). Otherwise will generate only up to the script
name. An undefined web will default to the main web name.

Added:

>>

The returned URL takes ReadOnlyAndMirrorWebs into account.
If the specified $web is slave on this site, with the scripts
edit, save, attach, upload, and rename, this method returns
the URLs on the master site because it does not make sense to execute
those scripts on the master site of the web.

Even with the other scripts, you may need to get the URLs on the master site.
You can get those URLs by providing $master => 1 as a name value pair.

Spaces out a wiki word by inserting a string (default: one space) between each word component.

Line: 623 to 676

Changed:

<<

%<nop}RENDERHEAD%

>>

%RENDERHEAD%

== should be written where you want the sorted head tags to be generated. This will normally be in a template. The variable expands to a sorted list of the head blocks added up to the point the RENDERHEAD variable is expanded. Each expanded head block is preceded by an HTML comment that records the ID of the head block.

Head blocks are sorted to satisfy all their requires constraints.

Line: 666 to 719

$n or $n()

New line. Use $n() if followed by alphanumeric character, e.g. write Foo$n()Bar instead of Foo$nBar

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".

Changed:

<<

... - 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

>>

... - 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

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

Line: 195 to 199

when running from the command line, or when generating rss). If
$script is not given, absolute URLs will always be generated.

Changed:

<<

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.

>>

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.

Note that TWiki variables may be used in the HEAD. They will be expanded
according to normal variable expansion rules.

Changed:

<<

The 'id' is used to ensure that multiple adds of the same block of HTML don't
result in it being added many times.

>>

%ADDTOHEAD%

You can write == in a topic or template. This variable accepts the following parameters:

_DEFAULT optional, id of the head block. Used to generate a comment in the output HTML.

text optional, text to use for the head block. Mutually exclusive with topic.

topic optional, full TWiki path name of a topic that contains the full text to use for the head block. Mutually exclusive with text. Example: topic="TWiki.MyTopic".

requires optional, comma-separated list of id's of other head blocks this one depends on.

%ADDTOHEAD% expands in-place to the empty string, unless there is an error in which case the variable expands to an error string.

Use %RENDERHEAD% to generate the sorted head tags.

%<nop}RENDERHEAD%

<-- ... -->

... should be written where you want the sorted head tags to be generated. This will normally be in a template. The variable expands to a sorted list of the head blocks added up to the point the RENDERHEAD variable is expanded. Each expanded head block is preceded by an HTML comment that records the ID of the head block.

Added:

>>

Head blocks are sorted to satisfy all their requires constraints.
The output order of blocks with no requires value is undefined. If cycles
exist in the dependency order, the cycles will be broken but the resulting
order of blocks in the cycle is undefined.

Normally this method will ignore parameters to the current query.
If $passthrough is set, then it will pass all parameters that were passed
to the current query on to the redirect target. If the request_method was
GET, then all parameters can be passed in the URL. If the
request_method was POST then it caches the form data and passes over a
cache reference in the redirect GET.

>>

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.

Changed:

<<

Passthrough is only meaningful if the redirect target is on the same server.

>>

NOTE: Passthrough is only meaningful if the redirect target is on the same
server.

Line: 112 to 156

system web names are considered valid (names starting with _)
otherwise only user web names are valid

Added:

>>

If $TWiki::cfg{EnableHierarchicalWebs} is off, it will also return false
when a nested web name is passed to it.

Composes a URL for an "oops" error page. The @options consists of a list
of key => value pairs. The following keys are used:

-web - web name

-topic - topic name

-def - optional template def within the main template file

-params - a single parameter, or a reference to an array of parameters These are passed in the URL as '&param1=' etc.

>>

See TWikiFuncDotPm for a full specification of the expansion (not duplicated
here)

Changed:

<<

Do not include the "oops" part in front of the template name.

>>

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.

Deleted:

<<

Alternatively you can pass a reference to an OopsException in place of the template. All other parameters will be ignored.

Deleted:

<<

The returned URL ends up looking something like this:
"http://host/twiki/bin/oops/$web/$topic?template=$template&param1=$scriptParams[0]..."

Changed:

<<

Note: if {keep} is true in the params, then they will also be pushed into the
current query.

Get a reference to the renderer object. Done lazily because not everyone
needs the renderer.

Deleted:

<<

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.

For attachments, URL-encode specially to 'freeze' any characters >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.

This encoding is required to handle the cases of:

- 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

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.

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.

...Only alphanumerics [0-9a-zA-Z], the special
characters $-_.+!*'(), and reserved characters used for their
reserved purposes may be used unencoded within a URL.

Line: 356 to 450

Reserved characters are $&+,/:;=?@ - these are also encoded by
this method.

Changed:

<<

SMELL: For non-ISO-8859-1 $TWiki::cfg{Site}{CharSet}, need to convert to
UTF-8 before URL encoding. This encoding only supports 8-bit
character codes.

>>

This URL-encoding handles all character encodings including ISO-8859-*,
KOI8-R, EUC-* and UTF-8.

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.

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:

Tags are expanded left to right, in the order they are encountered.

Tags are recursively expanded as soon as they are encountered - the algorithm is inherently single-pass

A tag is not "encountered" until the matching }% has been seen, by which time all tags in parameters will have been expanded

Tag expansions that create new tags recursively are limited to a set number of hierarchical levels of expansion

Normally this method will ignore parameters to the current query.
If $passthrough is set, then it will pass all parameters that were passed
to the current query on to the redirect target. If the request_method was
GET, then all parameters can be passed in the URL. If the
request_method was POST then it caches the form data and passes over a
cache reference in the redirect GET.

Changed:

<<

Generate a CGI redirect to $url unless (1) $session->{cgiQuery} is undef or
(2) $query->param('noredirect') is set to a true value. Thus a redirect is
only generated when in a CGI context.

>>

Passthrough is only meaningful if the redirect target is on the same server.

Deleted:

<<

The ... parameters are concatenated to the message written when printing
to STDOUT, and are ignored for a redirect.

Changed:

<<

Redirects the request to $url, via the CGI module object $query unless
overridden by a plugin declaring a redirectCgiQueryHandler.

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.

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.

Line: 111 to 134

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".

Changed:

<<

... - 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#XXX?a=1&b=2

>>

... - 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

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

Line: 170 to 193

The returned URL ends up looking something like this:
"http://host/twiki/bin/oops/$web/$topic?template=$template&param1=$scriptParams[0]..."

Added:

>>

Note: if {keep} is true in the params, then they will also be pushed into the
current query.

SMELL: WARNING: this function defaults the web and topic names.
Be very careful where you use it!

>>

See TWikiFuncDotPm for a full specification of the expansion (not duplicated here)

Added:

>>

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.

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.

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.

See test/unit/Fn_SECTION.pm for detailed testcases that
round out the spec.

Package TWiki

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.

Global variables are avoided wherever possible to avoid problems
with CGI accelerators such as mod_perl.

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".

... - 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#XXX?a=1&b=2

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.

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.

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.

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.

$web, $topic and $attachment are optional. A partial URL path will be
generated if one or all is not given.

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).

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%

Escape special characters to HTML numeric entities. This is not a generic
encoding, it is tuned specifically for use in TWiki.

HTML4.0 spec:
"Certain characters in HTML are reserved for use as markup and must be
escaped to appear literally. The "<" character may be represented with
an entity, &lt;. Similarly, ">"
is escaped as &gt;, and "&" is escaped
as &amp;. If an attribute value contains a
double quotation mark and is delimited by double quotation marks, then the
quote should be escaped as &quot;.

Other entities exist for special characters that cannot easily be entered
with some keyboards..."

This method encodes HTML special and any non-printable ascii
characters (except for \n and \r) using numeric entities.

FURTHER this method also encodes characters that are special in TWiki
meta-language.

$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.

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 ?.

RFC 1738, Dec. '94:

>
...Only alphanumerics [0-9a-zA-Z], the special
characters $-_.+!*'(), and reserved characters used for their
reserved purposes may be used unencoded within a URL.

Reserved characters are $&+,/:;=?@ - these are also encoded by
this method.

SMELL: For non-ISO-8859-1 $TWiki::cfg{Site}{CharSet}, need to convert to
UTF-8 before URL encoding. This encoding only supports 8-bit
character codes.

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.

If the value is undef, then $default is returned. If $default is
not specified it is taken as 0.

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.

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.

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.

Contexts are not just useful for tag expansion; they are also
relevant when rendering.

Contexts are intended for use mainly by plugins. Core modules can
use $session->inContext( $id ) to determine if a context is active.