<li><a href="#get_CanonicalUserID( $user ) ->"> getCanonicalUserID( $user ) -> $cUID</a></li>
<li><a href="#get_WikiName( $user ) -> $wikiNa"> getWikiName( $user ) -> $wikiName</a></li>
<li><a href="#get_WikiUserName( $user ) -> $wi"> getWikiUserName( $user ) -> $wikiName</a></li>
- <li><a href="#wiki_ToUserName( $wikiName ) ->"> wikiToUserName( $wikiName ) -> $loginName</a></li>
+ <li><a href="#wiki_ToUserName( $id ) -> $login"> wikiToUserName( $id ) -> $loginName</a></li>
<li><a href="#user_ToWikiName( $loginName, $do"> userToWikiName( $loginName, $dontAddWeb ) -> $wikiName</a></li>
<li><a href="#email_ToWikiNames( $email, $dont"> emailToWikiNames( $email, $dontAddWeb ) -> @wikiNames</a></li>
- <li><a href="#wiki_NameToEmails( $wikiname ) -"> wikiNameToEmails( $wikiname ) -> @emails</a></li>
+ <li><a href="#wikiname_ToEmails( $user ) -> @e"> wikinameToEmails( $user ) -> @emails</a></li>
<li><a href="#isGuest( ) -> $boolean"> isGuest( ) -> $boolean</a></li>
- <li><a href="#is_AnAdmin( $login ) -> $boolean"> isAnAdmin( $login ) -> $boolean</a></li>
- <li><a href="#is_GroupMember( $group, $login )"> isGroupMember( $group, $login ) -> $boolean</a></li>
+ <li><a href="#is_AnAdmin( $id ) -> $boolean"> isAnAdmin( $id ) -> $boolean</a></li>
+ <li><a href="#is_GroupMember( $group, $id ) ->"> isGroupMember( $group, $id ) -> $boolean</a></li>
<li><a href="#eachUser() -> $iterator"> eachUser() -> $iterator</a></li>
- <li><a href="#eachMembership($wikiname) -> $it"> eachMembership($wikiname) -> $iterator</a></li>
+ <li><a href="#eachMembership($id) -> $iterator"> eachMembership($id) -> $iterator</a></li>
<li><a href="#eachGroup() -> $iterator"> eachGroup() -> $iterator</a></li>
<li><a href="#isGroup( $group ) -> $boolean"> isGroup( $group ) -> $boolean</a></li>
<li><a href="#each_GroupMember($group) -> $ite"> eachGroupMember($group) -> $iterator</a></li>
- <li><a href="#check_AccessPermission( $type, $"> checkAccessPermission( $type, $wikiName, $text, $topic, $web, $meta ) -> $boolean</a></li>
+ <li><a href="#check_AccessPermission( $type, $"> checkAccessPermission( $type, $id, $text, $topic, $web, $meta ) -> $boolean</a></li>
</ul>
</li>
<li><a href="#Webs, Topics and Attachments"> Webs, Topics and Attachments</a><ul>
### <a name="get_CanonicalUserID( $user ) - $"></a> getCanonicalUserID( $user ) -> $cUID
-Return the cUID of the specified user. A cUID is a unique identifier which is assigned by TWiki for each user. BEWARE: While the default [[TWikiUserMapping]] uses a cUID that looks like a user's [[LoginName]], some characters are modified to make them compatible with rcs. Additionally, other usermappings will use other conventions - the [[JoomlauserMapping]] for example, has cUIDs like 'JoomlaeUserMapping\_1234'.
+- `$user` can be a login, wikiname or web.wikiname
-If $user is undefined Get the cUID of logged in user, and will generally be 'BaseUserMapping\_666'
+Return the cUID of the specified user. A cUID is a unique identifier which is assigned by TWiki for each user. BEWARE: While the default [[TWikiUserMapping]] uses a cUID that looks like a user's [[LoginName]], some characters are modified to make them compatible with rcs. Other usermappings may use other conventions - the JoomlaUserMapping for example, has cUIDs like 'JoomlaeUserMapping\_1234'.
-- $user can be a cUID, login, wikiname or web.wikiname
+If $user is undefined, it assumes the currently logged-in user.
-Return: `$cUID` an internal unique and transportable escaped identifier for registered users (they can be autogenerated for an authenticated but unregistered user)
+Return: `$cUID`, an internal unique and portable escaped identifier for registered users. This may be autogenerated for an authenticated but unregistered user.
**Since:** TWiki::Plugins::VERSION 1.2
**Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
-### <a name="wiki_ToUserName( $wikiName ) - $"></a> wikiToUserName( $wikiName ) -> $loginName
+### <a name="wiki_ToUserName( $id ) - $loginN"></a> wikiToUserName( $id ) -> $loginName
-Translate a Wiki name (or login name or cUID, if it can) to a login name.
+Translate a Wiki name to a login name.
-- `$wikiName` - Wiki name, e.g. `'Main.JohnDoe'` or `'JohnDoe'`
+- `$id` - Wiki name, e.g. `'Main.JohnDoe'` or `'JohnDoe'`. Since TWiki 4.2.1, $id may also be a login name. This will normally be transparent, but should be borne in mind if you have login names that are also legal wiki names.
Return: `$loginName` Login name of user, e.g. `'jdoe'`, or undef if not matched.
Translate a login name to a Wiki name
-- `$loginName` - Login name, e.g. `'jdoe'`
+- `$loginName` - Login name, e.g. `'jdoe'`. Since TWiki 4.2.1 this may also be a wiki name. This will normally be transparent, but may be relevant if you have login names that are also valid wiki names.
- `$dontAddWeb` - Do not add web prefix if `"1"`
Return: `$wikiName` Wiki name of user, e.g. `'Main.JohnDoe'` or `'JohnDoe'`
-userToWikiName will always return a name, if the user does not exist in the mapping, the $loginName parameter is returned. (backward compatibility)
+userToWikiName will always return a name. If the user does not exist in the mapping, the $loginName parameter is returned. (backward compatibility)
**Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
**Since:** TWiki::Plugins::VERSION 1.2
-### <a name="wiki_NameToEmails( $wikiname ) -"></a> wikiNameToEmails( $wikiname ) -> @emails
+### <a name="wikiname_ToEmails( $user ) - @em"></a> wikinameToEmails( $user ) -> @emails
+
+- `$user` - wikiname of user to look up
-- `$wikiname` - wikiname of user to look up
+Returns the registered email addresses of the named user. If $user is undef, returns the registered email addresses for the logged-in user.
-Returns the registered email addresses of the named user. If $wikiname is undef, returns the registered email addresses for the logged-in user.
+Since TWiki 4.2.1, $user may also be a login name, or the name of a group.
**Since:** TWiki::Plugins::VERSION 1.2
**Since:** TWiki::Plugins::VERSION 1.000 (7 Dec 2002)
-### <a name="is_AnAdmin( $login ) - $boolean"></a> isAnAdmin( $login ) -> $boolean
+### <a name="is_AnAdmin( $id ) - $boolean"></a> isAnAdmin( $id ) -> $boolean
Find out if the user is an admin or not. If the user is not given, the currently logged-in user is assumed.
-- $login can be either a login, or a CUID
+- $id can be either a login name or a [[WikiName]]
**Since:** TWiki::Plugins::VERSION 1.2
-### <a name="is_GroupMember( $group, $login )"></a> isGroupMember( $group, $login ) -> $boolean
+### <a name="is_GroupMember( $group, $id ) -"></a><a name="is_GroupMember( $group, $id ) - "></a> isGroupMember( $group, $id ) -> $boolean
-Find out if $login is in the named group. e.g.
+Find out if $id is in the named group. e.g.
if( TWiki::Func::isGroupMember( "HesperionXXGroup", "jordi" )) {
...
If `$user` is `undef`, it defaults to the currently logged-in user.
-- $login can be a login name, or a cUID, or [[WikiName]]
+- $id can be a login name or a [[WikiName]]
**Since:** TWiki::Plugins::VERSION 1.2
**Since:** TWiki::Plugins::VERSION 1.2
-### <a name="eachMembership($wikiname) - $ite"></a> eachMembership($wikiname) -> $iterator
+### <a name="eachMembership($id) - $iterator"></a> eachMembership($id) -> $iterator
-Get an iterator over the names of all groups that the user is a member of. If `$wikiname` is `undef`, defaults to the currently logged-in user.
+- `$id` - [[WikiName]] or login name of the user. If `$id` is `undef`, defaults to the currently logged-in user.
+
+Get an iterator over the names of all groups that the user is a member of.
**Since:** TWiki::Plugins::VERSION 1.2
**Since:** TWiki::Plugins::VERSION 1.2
-### <a name="check_AccessPermission( $type, $"></a> checkAccessPermission( $type, $wikiName, $text, $topic, $web, $meta ) -> $boolean
+### <a name="check_AccessPermission( $type, $"></a> checkAccessPermission( $type, $id, $text, $topic, $web, $meta ) -> $boolean
Check access permission for a topic based on the [[%SYSTEMWEB%.TWikiAccessControl|SYSTEMWEB/TWikiAccessControl]] rules
- `$type` - Access type, required, e.g. `'VIEW'`, `'CHANGE'`.
-- `$wikiName` - [[WikiName]] of remote user, required, e.g. `"PeterThoeny"`. If `$wikiName` is '', 0 or `undef` then access is **always permitted**.
+- `$id` - [[WikiName]] of remote user, required, e.g. `"PeterThoeny"`. From TWiki 4.2.1, $id may also be a login name. If `$id` is '', 0 or `undef` then access is **always permitted**.
- `$text` - Topic text, optional. If 'perl false' (undef, 0 or ''), topic `$web.$topic` is consulted. `$text` may optionally contain embedded `%META:PREFERENCE` tags. Provide this parameter if:
1. You are setting different access controls in the text to those defined in the stored topic,
2. You already have the topic text in hand, and want to help TWiki avoid having to read it again,
A perl true result indicates that access is permitted.
-**Note** the wierd parameter order is due to compatibility constraints with earlier TWiki releases.
+**Note** the weird parameter order is due to compatibility constraints with earlier TWiki releases.
**Tip** if you want, you can use this method to check your own access control types. For example, if you:
my $iterator = TWiki::Func::eachChangeSince(
$web, time() - 7 * 24 * 60 * 60); # the last 7 days
- while ($it->hasNext()) {
- my $change = $it->next();
+ while ($iterator->hasNext()) {
+ my $change = $iterator->next();
# $change is a perl hash that contains the following fields:
# topic => topic name
# user => wikiname - wikiname of user who made the change
<td> don't log this change in twiki log </td>
</tr>
<tr>
- <td><code>comment</code></td>
- <td> comment for save </td>
+ <td><code>forcenewrevision</code></td>
+ <td> force the save to increment the revision counter </td>
</tr>
<tr>
<td><code>minor</code></td>
my( $meta, $text ) = TWiki::Func::readTopic( $web, $topic )
$text =~ s/APPLE/ORANGE/g;
- TWiki::Func::saveTopic( $web, $topic, $meta, $text, { comment => 'refruited' } );
+ TWiki::Func::saveTopic( $web, $topic, $meta, $text, { forcenewrevision => 1 } );
**_Note:_** Plugins handlers ( e.g. `beforeSaveHandler` ) will be called as appropriate.
### <a name="wiki_ToEmail( $wikiName ) - $ema"></a> wikiToEmail( $wikiName ) -> $email
-- `$wikiName` - wiki name of the user
+- `$wikiname` - wiki name of the user
Get the e-mail address(es) of the named user. If the user has multiple e-mail addresses (for example, the user is a group), then the list will be comma-separated.
**Since:** TWiki::Plugins::VERSION 1.1
+**Deprecated** in favour of wikinameToEmails, because this function only returns a single email address, where a user may in fact have several.
+
+Since TWiki 4.2.1, $wikiName may also be a login name.
+
## <a name="Creating New Topics"></a> Creating New Topics
### <a name="expand_VariablesOnTopicCreation"></a><a name="expand_VariablesOnTopicCreation "></a> expandVariablesOnTopicCreation ( $text ) -> $text
git://git.openafs.org / openafs-wiki.git / blobdiff