Feature Proposal: Implement buildWikiWord function

Motivation

You want to determine the corresponding TWiki page for a given text link target as the core would do. So there should be a buildWikiWord function, which must be implemented exactly the same as the TWiki core code. So it would be nice if there is one "official" function, which the core uses and all users can use.

See Support/SID-00168 for the hole story.

Description and Documentation

Because it's not up to me totally twiki newbie to change the core code, I suggest the following and kindly request the core team to change the files. Please move the lines

# filter out &any; entities (legacy)
$link =~ s/\&[a-z]+\;//gi;
# filter out { entities (legacy)
$link =~ s/\&\#[0-9]+\;//g;
# Filter junk
$link =~ s/$TWiki::cfg{NameFilter}+/ /g;
# Capitalise first word
$link =~ s/^(.)/\U$1/;
# Collapse spaces and capitalise following letter
$link =~ s/\s([$TWiki::regex{mixedAlphaNum}])/\U$1/go;
# Get rid of remaining spaces, i.e. spaces in front of -'s and ('s
$link =~ s/\s//go;

to a new buildWikiWord method located in Render.pm which takes $link as a parameter and returns the changed $link (WikiWord).

# Converts arbitrary text to a WikiWord
sub buildWikiWord {
    my( $this, $link ) = @_;

    # filter out &any; entities (legacy)
    $link =~ s/\&[a-z]+\;//gi;
    # filter out { entities (legacy)
    $link =~ s/\&\#[0-9]+\;//g;
    # Filter junk
    $link =~ s/$TWiki::cfg{NameFilter}+/ /g;
    # Capitalise first word
    $link =~ s/^(.)/\U$1/;
    # Collapse spaces and capitalise following letter
    $link =~ s/\s([$TWiki::regex{mixedAlphaNum}])/\U$1/go;
    # Get rid of remaining spaces, i.e. spaces in front of -'s and ('s
    $link =~ s/\s//go;

    return $link;
}

Call the new buildWikiWord method at the original location.

$link = $this->buildWikiWord( $link );

Add a TWiki::Func::buildWikiWord that calls the new buildWikiWord method.

=pod

---+++ buildWikiWord( $text ) -> $text

Converts arbitrary text to a WikiWord.
   * =$pre=        - Arbitrary Text
Return: =$text=

*Since:* TWiki::Plugins::VERSION ###### INSERT VERSION AND DATE HERE ######

=cut

sub buildWikiWord {
    ASSERT($TWiki::Plugins::SESSION) if DEBUG;
    return $TWiki::Plugins::SESSION->{renderer}->buildWikiWord( @_ );
}

May you please chance the code as suggested?

Examples

Impact

Implementation

-- Contributors: HorstEsser - 2009-11-12

Discussion

Sounds good to me.

-- PeterThoeny - 2009-11-22

Since the feature proposal is accepted by the 14-days rule, I want to start implementing it now.

Is the API version number affected by it? It should be, or not?

And what to do to change the API version number?

Or is it enough if the comment says that?

Since: TWiki::Plugins::VERSION 1.2 (03 Dec 2009)

-- HorstEsser - 2009-12-03

Corresponding bug tracker item: Item6385

As discussed by email, I've set the version number to 1.3.

I've checked in the code on the trunk now.

EDIT: After the check in http://develop.twiki.org/~twiki4/cgi-bin/view/Main/WebHome says "This site is running TWiki version TWiki-5.0.0, Sat, 02 Jan 2010, build 18269, Plugin API version 1.3", but it should say "This site is running TWiki version TWiki-5.0.0, Mon, 18 Jan 2010, build 18286, Plugin API version 1.3"

-- HorstEsser - 2010-01-18

Thank you Horst!

The release date and number is taken from the $VERSION in lib/TWiki.pm. It gets updated automatically when you checkin TWiki.pm after making a change to it. Don't worry about updating TWiki.pm (unless you are working on it), the release manager is taking care of that at the time of a release.

-- PeterThoeny - 2010-01-18