Pod/Simple/Wiki.pm

package Pod::Simple::Wiki;

###############################################################################
#
# Pod::Simple::Wiki - A class for creating Pod to Wiki filters.
#
#
# Copyright 2003-2005, John McNamara, jmcnamara@cpan.org
#
# Documentation after __END__
#

use strict;
#use Pod::Simple::Debug (5);
use Pod::Simple;
use vars qw(@ISA $VERSION);

@ISA     = qw(Pod::Simple);
$VERSION = '0.05';

my $_debug = 0;


###############################################################################
###############################################################################
#
# The tag mappings for various Wiki text formats
#

my %tags = (
                'wiki' =>       {
                                    '<b>'    => "'''",
                                    '</b>'   => "'''",
                                    '<i>'    => "''",
                                    '</i>'   => "''",
                                    '<tt>'   => '"',
                                    '</tt>'  => '"',
                                    '<pre>'  => '',
                                    '</pre>' => "\n\n",

                                    '<h1>'   => "\n----\n'''",
                                    '</h1>'  => "'''\n\n",
                                    '<h2>'   => "\n'''''",
                                    '</h2>'  => "'''''\n\n",
                                    '<h3>'   => "\n''",
                                    '</h3>'  => "''\n\n",
                                    '<h4>'   => "\n",
                                    '</h4>'  => "\n\n",
                                },

                'kwiki' =>      {
                                    '<b>'    => '*',
                                    '</b>'   => '*',
                                    '<i>'    => '/',
                                    '</i>'   => '/',
                                    '<tt>'   => '[=',
                                    '</tt>'  => ']',
                                    '<pre>'  => '',
                                    '</pre>' => "\n\n",

                                    '<h1>'   => "\n----\n= ",
                                    '</h1>'  => " =\n\n",
                                    '<h2>'   => "\n== ",
                                    '</h2>'  => " ==\n\n",
                                    '<h3>'   => "\n=== ",
                                    '</h3>'  => " ===\n\n",
                                    '<h4>'   => "==== ",
                                    '</h4>'  => "\n\n",
                                },

                'usemod' =>     {
                                    '<b>'    => '<b>',
                                    '</b>'   => '</b>',
                                    '<i>'    => '<i>',
                                    '</i>'   => '</i>',
                                    '<tt>'   => '<tt>',
                                    '</tt>'  => '</tt>',
                                    '<pre>'  => "\n<pre>\n",
                                    '</pre>' => "\n</pre>\n\n",

                                    '<h1>'   => "\n= ",
                                    '</h1>'  => " =\n\n",
                                    '<h2>'   => "\n== ",
                                    '</h2>'  => " ==\n\n",
                                    '<h3>'   => "\n=== ",
                                    '</h3>'  => " ===\n",
                                    '<h4>'   => "\n==== ",
                                    '</h4>'  => " ====\n\n",
                                },

                'usemod_classic' => {
                                    '<b>'    => "'''",
                                    '</b>'   => "'''",
                                    '<i>'    => "''",
                                    '</i>'   => "''",
                                    '<tt>'   => '<tt>',
                                    '</tt>'  => '</tt>',
                                    '<pre>'  => "\n<pre>\n",
                                    '</pre>' => "\n</pre>\n\n",

                                    '<h1>'   => "\n= ",
                                    '</h1>'  => " =\n\n",
                                    '<h2>'   => "\n== ",
                                    '</h2>'  => " ==\n\n",
                                    '<h3>'   => "\n=== ",
                                    '</h3>'  => " ===\n",
                                    '<h4>'   => "\n==== ",
                                    '</h4>'  => " ====\n\n",
                                },


               'twiki'       => {
                                    '<b>'    => "*",
                                    '</b>'   => "*",
                                    '<i>'    => "_",
                                    '</i>'   => "_",
                                    '<tt>'   => '=',
                                    '</tt>'  => '=',
                                    '<pre>'  => "\n<verbatim>\n",
                                    '</pre>' => "\n</verbatim>\n\n",

                                    '<h1>'   => "---+ ",
                                    '</h1>'  => "\n\n",
                                    '<h2>'   => "---++ ",
                                    '</h2>'  => "\n\n",
                                    '<h3>'   => "---+++ ",
                                    '</h3>'  => "\n\n",
                                    '<h4>'   => "---++++ ",
                                    '</h4>'  => "\n\n",
                                },
                'wikipedia' =>  {
                                    '<b>'    => "'''",
                                    '</b>'   => "'''",
                                    '<i>'    => "''",
                                    '</i>'   => "''",
                                    '<tt>'   => '<tt>',
                                    '</tt>'  => '</tt>',
                                    '<pre>'  => "\n<code>\n",
                                    '</pre>' => "\n</code>\n",

                                    '<h1>'   => "==",
                                    '</h1>'  => "==\n",
                                    '<h2>'   => "===",
                                    '</h2>'  => "===\n",
                                    '<h3>'   => "====",
                                    '</h3>'  => "====\n",
                                    '<h4>'   => "=====",
                                    '</h4>'  => "=====\n",
                                },
                'socialtext' => {
                                    '<b>'    => '*',
                                    '</b>'   => '*',
                                    '<i>'    => '_',
                                    '</i>'   => '_',
                                    '<tt>'   => '`',
                                    '</tt>'  => '`',
                                    '<pre>'  => "\n.pre\n",
                                    '</pre>' => "\n.pre\n",

                                    '<h1>'   => "^ ",
                                    '</h1>'  => "\n",
                                    '<h2>'   => "^^ ",
                                    '</h2>'  => "\n",
                                    '<h3>'   => "^^^ ",
                                    '</h3>'  => "\n",
                                    '<h4>'   => "^^^^ ",
                                    '</h4>'  => "\n",
                                },

);


###############################################################################
#
# new()
#
# Simple constructor inheriting from Pod::Simple.
#
sub new {

    my $class               = shift;
    my $format              = lc shift || 'wiki';
       $format              = 'wikipedia' if $format eq 'mediawiki';
       $format              = 'wiki' unless exists $tags{$format};

    my $self                = Pod::Simple->new(@_);
       $self->{_wiki_text}  = '';
       $self->{_format}     = $format;
       $self->{_tags}       = $tags{$format};
       $self->{output_fh} ||= *STDOUT{IO};

    bless  $self, $class;
    return $self;
}


###############################################################################
#
# _append()
#
# Appends some text to the buffered Wiki text.
#
sub _append {

    my $self = shift;

    $self->{_wiki_text} .= $_[0];
}


###############################################################################
#
# _output()
#
# Appends some text to the buffered Wiki text and then emits it. Also resets
# the buffer.
#
sub _output {

    my $self = shift;
    my $text = $_[0];

    $text = '' unless defined $text;

    print {$self->{output_fh}} $self->{_wiki_text}, $text;

    $self->{_wiki_text} = '';
}


###############################################################################
#
# _indent_item()
#
# Indents an "over-item" to the correct level.
#
sub _indent_item {

    my $self         = shift;
    my $item_type    = $_[0];
    my $item_param   = $_[1];
    my $indent_level = $self->{_item_indent};

    if ($self->{_format} eq 'wiki') {

        if    ($item_type eq 'bullet') {
             $self->_append("*" x $indent_level);
             # This was the way C2 Wiki used to define a bullet list
             # $self->_append("\t" x $indent_level . '*');
        }
        elsif ($item_type eq 'number') {
             $self->_append("\t" x $indent_level . $item_param);
        }
        elsif ($item_type eq 'text') {
             $self->_append("\t" x $indent_level);
        }
    }
    elsif ($self->{_format} eq 'kwiki') {

        if    ($item_type eq 'bullet') {
             $self->_append('*' x $indent_level . ' ');
        }
        elsif ($item_type eq 'number') {
             $self->_append('0' x $indent_level . ' ');
        }
        elsif ($item_type eq 'text') {
             $self->_append(";" x $indent_level . ' ');
        }
    }
    elsif ($self->{_format} eq 'usemod') {

        if    ($item_type eq 'bullet') {
             $self->_append('*' x $indent_level);
        }
        elsif ($item_type eq 'number') {
             $self->_append('#' x $indent_level);
        }
        elsif ($item_type eq 'text') {
             $self->_append(";" x $indent_level);
        }
    }
    elsif ($self->{_format} eq 'twiki') {

        if    ($item_type eq 'bullet') {
             $self->_append('   ' x $indent_level . "* ");
        }
        elsif ($item_type eq 'number') {
             $self->_append('   ' x $indent_level . $item_param . ". ");
        }
        elsif ($item_type eq 'text') {
             $self->_append('   ' x $indent_level . '$ ' );
        }
    }
    elsif ($self->{_format} eq 'wikipedia') {

        if    ($item_type eq 'bullet') {
             $self->_append('*' x $indent_level . ' ');
        }
        elsif ($item_type eq 'number') {
             $self->_append('#' x $indent_level . ' ');
        }
        elsif ($item_type eq 'text') {
             $self->_append(";" x $indent_level . ' ');
        }
        }
    elsif ($self->{_format} eq 'socialtext') {

        if    ($item_type eq 'bullet') {
             $self->_append('*' x $indent_level . ' ');
        }
        elsif ($item_type eq 'number') {
             $self->_append('#' x $indent_level . ' ');
        }
        elsif ($item_type eq 'text') {
             $self->_append(">" x $indent_level . ' ');
        }
    }
}


###############################################################################
#
# _skip_headings()
#
# Formatting in headings doesn't look great or is ignored in some formats.
#
sub _skip_headings {

    my $self = shift;

    return (
            $self->{_format} eq 'kwiki' and
            ($self->{_in_head1} or
             $self->{_in_head2} or
             $self->{_in_head3} or
             $self->{_in_head4})
           );
}


###############################################################################
#
# _append_tag()
#
# Add an open or close tag to the current text.
#
sub _append_tag {

    my $self = shift;
    my $tag  = $_[0];

    $self->_append($self->{_tags}->{$tag});
}


###############################################################################
###############################################################################
#
# The methods in the following section are required by Pod::Simple to handle
# Pod directives and elements.
#
# The methods _handle_element_start() _handle_element_end() and _handle_text()
# are called by Pod::Simple in response to Pod constructs. We use
# _handle_element_start() and _handle_element_end() to generate calls to more
# specific methods. This is basically a long-hand version of Pod::Simple::
# Methody with the addition of location tracking.
#


###############################################################################
#
# _handle_element_start()
#
# Call a method to handle the start of a element if one has been defined.
# We also set a flag to indicate that we are "in" the element type.
#
sub _handle_element_start {

    my $self    = shift;
    my $element = $_[0];

    $element =~ tr/-/_/;

    print "<$element>\n" if $_debug;

    $self->{"_in_". $element}++;

    if (my $method = $self->can('_start_' . $element)) {
        $method->($self, $_[1]);
    }
}


###############################################################################
#
# _handle_element_end()
#
# Call a method to handle the end of a element if one has been defined.
# We also set a flag to indicate that we are "out" of the element type.
#
sub _handle_element_end {

    my $self    = shift;
    my $element = $_[0];

    $element =~ tr/-/_/;

    if (my $method = $self->can('_end_' . $element)) {
        $method->($self);
    }

    $self->{"_in_". $element}--;

    print "</$element>\n" if $_debug;
}


###############################################################################
#
# _handle_text()
#
# Perform any necessary transforms on the text. This is mainly used to escape
# inadvertent CamelCase words.
#
sub _handle_text {

    my $self = shift;
    my $text = $_[0];

    # Only escape CamelCase in Kwiki paragraphs
    if ($self->{_format} eq 'kwiki' and not $self->{_in_Para}) {
        $self->{_wiki_text} .= $text;
        return;
    }

    # Split the text into tokens but maintain the whitespace
    my @tokens = split /(\s+)/, $text;

    if ($self->{_format} eq 'wiki') {
        for (@tokens) {
            next unless /\S/;                    # Ignore the whitespace
            next if m[^(ht|f)tp://];             # Ignore URLs
            s/([A-Z][a-z]+)(?=[A-Z])/$1''''''/g  # Escape with 6 single quotes

        }
    }
    elsif ($self->{_format} eq 'kwiki') {
        for (@tokens) {
            next unless /\S/;                    # Ignore the whitespace
            next if m[^(ht|f)tp://];             # Ignore URLs
            s/([A-Z][a-z]+[A-Z]\w+)/!$1/g;       # Escape with !
        }
    }
    # TODO: Add usemod <nowiki> escapes

    # Rejoin the tokens and whitespace.
    $self->{_wiki_text} .= join '', @tokens;
}


###############################################################################
#
# Functions to deal with the I<>, B<> and C<> formatting codes.
#
sub _start_I  {$_[0]->_append_tag('<i>')   unless $_[0]->_skip_headings()}
sub _start_B  {$_[0]->_append_tag('<b>')   unless $_[0]->_skip_headings()}
sub _start_C  {$_[0]->_append_tag('<tt>')  unless $_[0]->_skip_headings()}
sub _start_F  {$_[0]->_start_I}

sub _end_I    {$_[0]->_append_tag('</i>')  unless $_[0]->_skip_headings()}
sub _end_B    {$_[0]->_append_tag('</b>')  unless $_[0]->_skip_headings()}
sub _end_C    {$_[0]->_append_tag('</tt>') unless $_[0]->_skip_headings()}
sub _end_F    {$_[0]->_end_I}


###############################################################################
#
# Functions to deal with the Pod =head directives
#
sub _start_head1 {$_[0]->_append_tag('<h1>')}
sub _start_head2 {$_[0]->_append_tag('<h2>')}
sub _start_head3 {$_[0]->_append_tag('<h3>')}
sub _start_head4 {$_[0]->_append_tag('<h4>')}

sub _end_head1   {$_[0]->_append_tag('</h1>'); $_[0]->_output()}
sub _end_head2   {$_[0]->_append_tag('</h2>'); $_[0]->_output()}
sub _end_head3   {$_[0]->_append_tag('</h3>'); $_[0]->_output()}
sub _end_head4   {$_[0]->_append_tag('</h4>'); $_[0]->_output()}


###############################################################################
#
# Functions to deal with verbatim paragraphs. We emit the text "as is" for now.
# TODO: escape any Wiki formatting in text such as ''code''.
#
sub _start_Verbatim {$_[0]->_append_tag('<pre>')}
sub _end_Verbatim   {$_[0]->_append_tag('</pre>'); $_[0]->_output()}


###############################################################################
#
# Functions to deal with =over ... =back regions for
#
# Bulleted lists
# Numbered lists
# Text     lists
# Block    lists
#
sub _start_over_bullet {$_[0]->{_item_indent}++}
sub _start_over_number {$_[0]->{_item_indent}++}
sub _start_over_text   {$_[0]->{_item_indent}++}

sub _end_over_bullet   {$_[0]->{_item_indent}--;
                        $_[0]->_output("\n") unless $_[0]->{_item_indent}}

sub _end_over_number   {$_[0]->{_item_indent}--;
                        $_[0]->_output("\n") unless $_[0]->{_item_indent}}

sub _end_over_text     {$_[0]->{_item_indent}--;
                        $_[0]->_output("\n") unless $_[0]->{_item_indent}}

sub _start_item_bullet {$_[0]->_indent_item('bullet')}
sub _start_item_number {$_[0]->_indent_item('number', $_[1]->{number})}
sub _start_item_text   {$_[0]->_indent_item('text')}

sub _end_item_bullet   {$_[0]->_output("\n")}
sub _end_item_number   {$_[0]->_output("\n")}
sub _end_item_text     {$_[0]->_output(":\t") if $_[0]->{_format} eq 'wiki';
                        $_[0]->_output(" ; ") if $_[0]->{_format} eq 'kwiki';
                        $_[0]->_output(":"  ) if $_[0]->{_format} eq 'usemod';
                        $_[0]->_output(": " ) if $_[0]->{_format} eq 'twiki';
                        $_[0]->_output(" : ") if $_[0]->{_format} eq 'wikipedia';
                        $_[0]->_output("\n") if $_[0]->{_format} eq 'socialtext';}

sub _start_over_block  {$_[0]->{_item_indent}++}
sub _end_over_block    {$_[0]->{_item_indent}--}


###############################################################################
#
# _start_Para()
#
# Special handling for paragraphs that are part of an "over" block.
#
sub _start_Para {

    my $self         = shift;
    my $indent_level = $self->{_item_indent};

    if ($self->{_in_over_block}) {

        if ($self->{_format} eq 'wiki') {
            $self->_append(("\t" x $indent_level) . " :\t");
        }
        elsif ($self->{_format} eq 'usemod') {
            $self->_append(":" x $indent_level);
        }
    }
}


###############################################################################
#
# _end_Para()
#
# Special handling for paragraphs that are part of an "over_text" block.
# This is mainly required  be Kwiki.
#
sub _end_Para {

    my $self = shift;

    # Only add a newline if the paragraph isn't part of a text
    if ($self->{_in_over_text}) {
        # Workaround for the fact that Kwiki doesn't have a definition block
        #$self->_output("\n") if $self->{_format} eq 'kwiki';
    }
    else {
        $self->_output("\n");
    }

    $self->_output("\n")
}


1;


__END__

=head1 NAME

Pod::Simple::Wiki - A class for creating Pod to Wiki filters.

=head1 SYNOPSIS

To create a simple C<pod2wiki> filter:

    #!/usr/bin/perl -w

    use strict;
    use Pod::Simple::Wiki;


    my $parser = Pod::Simple::Wiki->new();

    if (defined $ARGV[0]) {
        open IN, $ARGV[0]  or die "Couldn't open $ARGV[0]: $!\n";
    } else {
        *IN = *STDIN;
    }

    if (defined $ARGV[1]) {
        open OUT, ">$ARGV[1]" or die "Couldn't open $ARGV[1]: $!\n";
    } else {
        *OUT = *STDOUT;
    }

    $parser->output_fh(*OUT);
    $parser->parse_file(*IN);

    __END__


=head1 DESCRIPTION

The C<Pod::Simple::Wiki> module is used for converting Pod text to Wiki text.

Pod (Plain Old Documentation) is a simple markup language used for writing Perl documentation.

A Wiki is a user extensible web site. It uses very simple mark-up that is converted to Html.

For an introduction to Wikis see: http://en.wikipedia.org/wiki/Wiki


=head1 METHODS

=head2 new()

The C<new> method is used to create a new L<Pod::Simple::Wiki> object. It is also used to set the output Wiki format.

  my $parser1 = Pod::Simple::Wiki->new('wiki');
  my $parser2 = Pod::Simple::Wiki->new('kwiki');
  my $parser3 = Pod::Simple::Wiki->new(); # Defaults to 'wiki'

The currently supported formats are:

=over 4

=item wiki

This is the original Wiki format as used on Ward Cunningham's Portland repository of Patterns. The formatting rules are given at http://c2.com/cgi/wiki?TextFormattingRules

=item kwiki

This is the format as used by Brian Ingerson's CGI::Kwiki: http://search.cpan.org/dist/CGI-Kwiki/

=item usemod

This is the format used by the Usemod wikis. See: http://www.usemod.com/cgi-bin/wiki.pl?WikiFormat

=item twiki

This is the format used by TWiki wikis.  See: http://www.twiki.org/

=item wikipedia or mediawiki

This is the format used by Wikipedia and MediaWiki wikis.  See: http://www.wikipedia.org/

=back

If no format is specified the parser defaults to C<wiki>.

Any other parameters in C<new> will be passed on to the parent L<Pod::Simple> object. See L<Pod::Simple> for more details.


=head2 Other methods

Pod::Simple::Wiki inherits all of the methods of L<Pod::Simple>. See L<Pod::Simple> for more details.


=head1 TODO

=over 4

=item *

Add more code, more tests and a few more users if possible.

=item *

Add other Wiki formats. Send requests or patches.

=item *

Fix some of the C<=over> edge cases. See the TODOs in the test programs.

=back


=head1 SEE ALSO

This module also installs a C<pod2wiki> command line utility. See C<pod2wiki --help> for details.


=head1 ACKNOWLEDGEMENTS

Thanks to Sean M. Burke for C<Pod::Simple>. It may not be simple but sub-classing it is. C<:-)>

Thanks to Sam Tregar for TWiki support.

Thanks Tony Sidaway for Wikipedia/MediaWiki support.


=head1 AUTHOR

John McNamara jmcnamara@cpan.org


=head1 COPYRIGHT

© MMIII-MMV, John McNamara.

All Rights Reserved. This module is free software. It may be used, redistributed and/or modified under the same terms as Perl itself.

1	package Pod::Simple::Wiki;
2
3	###############################################################################
4	#
5	# Pod::Simple::Wiki - A class for creating Pod to Wiki filters.
6	#
7	#
8	# Copyright 2003-2005, John McNamara, jmcnamara@cpan.org
9	#
10	# Documentation after __END__
11	#
12
13	use strict;
14	#use Pod::Simple::Debug (5);
15	use Pod::Simple;
16	use vars qw(@ISA $VERSION);
17
18	@ISA = qw(Pod::Simple);
19	$VERSION = '0.05';
20
21	my $_debug = 0;
22
23
24	###############################################################################
25	###############################################################################
26	#
27	# The tag mappings for various Wiki text formats
28	#
29
30	my %tags = (
31	'wiki' => {
32	'<b>' => "'''",
33	'</b>' => "'''",
34	'<i>' => "''",
35	'</i>' => "''",
36	'<tt>' => '"',
37	'</tt>' => '"',
38	'<pre>' => '',
39	'</pre>' => "\n\n",
40
41	'<h1>' => "\n----\n'''",
42	'</h1>' => "'''\n\n",
43	'<h2>' => "\n'''''",
44	'</h2>' => "'''''\n\n",
45	'<h3>' => "\n''",
46	'</h3>' => "''\n\n",
47	'<h4>' => "\n",
48	'</h4>' => "\n\n",
49	},
50
51	'kwiki' => {
52	'<b>' => '*',
53	'</b>' => '*',
54	'<i>' => '/',
55	'</i>' => '/',
56	'<tt>' => '[=',
57	'</tt>' => ']',
58	'<pre>' => '',
59	'</pre>' => "\n\n",
60
61	'<h1>' => "\n----\n= ",
62	'</h1>' => " =\n\n",
63	'<h2>' => "\n== ",
64	'</h2>' => " ==\n\n",
65	'<h3>' => "\n=== ",
66	'</h3>' => " ===\n\n",
67	'<h4>' => "==== ",
68	'</h4>' => "\n\n",
69	},
70
71	'usemod' => {
72	'<b>' => '<b>',
73	'</b>' => '</b>',
74	'<i>' => '<i>',
75	'</i>' => '</i>',
76	'<tt>' => '<tt>',
77	'</tt>' => '</tt>',
78	'<pre>' => "\n<pre>\n",
79	'</pre>' => "\n</pre>\n\n",
80
81	'<h1>' => "\n= ",
82	'</h1>' => " =\n\n",
83	'<h2>' => "\n== ",
84	'</h2>' => " ==\n\n",
85	'<h3>' => "\n=== ",
86	'</h3>' => " ===\n",
87	'<h4>' => "\n==== ",
88	'</h4>' => " ====\n\n",
89	},
90
91	'usemod_classic' => {
92	'<b>' => "'''",
93	'</b>' => "'''",
94	'<i>' => "''",
95	'</i>' => "''",
96	'<tt>' => '<tt>',
97	'</tt>' => '</tt>',
98	'<pre>' => "\n<pre>\n",
99	'</pre>' => "\n</pre>\n\n",
100
101	'<h1>' => "\n= ",
102	'</h1>' => " =\n\n",
103	'<h2>' => "\n== ",
104	'</h2>' => " ==\n\n",
105	'<h3>' => "\n=== ",
106	'</h3>' => " ===\n",
107	'<h4>' => "\n==== ",
108	'</h4>' => " ====\n\n",
109	},
110
111
112	'twiki' => {
113	'<b>' => "*",
114	'</b>' => "*",
115	'<i>' => "_",
116	'</i>' => "_",
117	'<tt>' => '=',
118	'</tt>' => '=',
119	'<pre>' => "\n<verbatim>\n",
120	'</pre>' => "\n</verbatim>\n\n",
121
122	'<h1>' => "---+ ",
123	'</h1>' => "\n\n",
124	'<h2>' => "---++ ",
125	'</h2>' => "\n\n",
126	'<h3>' => "---+++ ",
127	'</h3>' => "\n\n",
128	'<h4>' => "---++++ ",
129	'</h4>' => "\n\n",
130	},
131	'wikipedia' => {
132	'<b>' => "'''",
133	'</b>' => "'''",
134	'<i>' => "''",
135	'</i>' => "''",
136	'<tt>' => '<tt>',
137	'</tt>' => '</tt>',
138	'<pre>' => "\n<code>\n",
139	'</pre>' => "\n</code>\n",
140
141	'<h1>' => "==",
142	'</h1>' => "==\n",
143	'<h2>' => "===",
144	'</h2>' => "===\n",
145	'<h3>' => "====",
146	'</h3>' => "====\n",
147	'<h4>' => "=====",
148	'</h4>' => "=====\n",
149	},
150	'socialtext' => {
151	'<b>' => '*',
152	'</b>' => '*',
153	'<i>' => '_',
154	'</i>' => '_',
155	'<tt>' => '`',
156	'</tt>' => '`',
157	'<pre>' => "\n.pre\n",
158	'</pre>' => "\n.pre\n",
159
160	'<h1>' => "^ ",
161	'</h1>' => "\n",
162	'<h2>' => "^^ ",
163	'</h2>' => "\n",
164	'<h3>' => "^^^ ",
165	'</h3>' => "\n",
166	'<h4>' => "^^^^ ",
167	'</h4>' => "\n",
168	},
169
170	);
171
172
173	###############################################################################
174	#
175	# new()
176	#
177	# Simple constructor inheriting from Pod::Simple.
178	#
179	sub new {
180
181	my $class = shift;
182	my $format = lc shift \|\| 'wiki';
183	$format = 'wikipedia' if $format eq 'mediawiki';
184	$format = 'wiki' unless exists $tags{$format};
185
186	my $self = Pod::Simple->new(@_);
187	$self->{_wiki_text} = '';
188	$self->{_format} = $format;
189	$self->{_tags} = $tags{$format};
190	$self->{output_fh} \|\|= *STDOUT{IO};
191
192	bless $self, $class;
193	return $self;
194	}
195
196
197	###############################################################################
198	#
199	# _append()
200	#
201	# Appends some text to the buffered Wiki text.
202	#
203	sub _append {
204
205	my $self = shift;
206
207	$self->{_wiki_text} .= $_[0];
208	}
209
210
211	###############################################################################
212	#
213	# _output()
214	#
215	# Appends some text to the buffered Wiki text and then emits it. Also resets
216	# the buffer.
217	#
218	sub _output {
219
220	my $self = shift;
221	my $text = $_[0];
222
223	$text = '' unless defined $text;
224
225	print {$self->{output_fh}} $self->{_wiki_text}, $text;
226
227	$self->{_wiki_text} = '';
228	}
229
230
231	###############################################################################
232	#
233	# _indent_item()
234	#
235	# Indents an "over-item" to the correct level.
236	#
237	sub _indent_item {
238
239	my $self = shift;
240	my $item_type = $_[0];
241	my $item_param = $_[1];
242	my $indent_level = $self->{_item_indent};
243
244	if ($self->{_format} eq 'wiki') {
245
246	if ($item_type eq 'bullet') {
247	$self->_append("*" x $indent_level);
248	# This was the way C2 Wiki used to define a bullet list
249	# $self->_append("\t" x $indent_level . '*');
250	}
251	elsif ($item_type eq 'number') {
252	$self->_append("\t" x $indent_level . $item_param);
253	}
254	elsif ($item_type eq 'text') {
255	$self->_append("\t" x $indent_level);
256	}
257	}
258	elsif ($self->{_format} eq 'kwiki') {
259
260	if ($item_type eq 'bullet') {
261	$self->_append('*' x $indent_level . ' ');
262	}
263	elsif ($item_type eq 'number') {
264	$self->_append('0' x $indent_level . ' ');
265	}
266	elsif ($item_type eq 'text') {
267	$self->_append(";" x $indent_level . ' ');
268	}
269	}
270	elsif ($self->{_format} eq 'usemod') {
271
272	if ($item_type eq 'bullet') {
273	$self->_append('*' x $indent_level);
274	}
275	elsif ($item_type eq 'number') {
276	$self->_append('#' x $indent_level);
277	}
278	elsif ($item_type eq 'text') {
279	$self->_append(";" x $indent_level);
280	}
281	}
282	elsif ($self->{_format} eq 'twiki') {
283
284	if ($item_type eq 'bullet') {
285	$self->_append(' ' x $indent_level . "* ");
286	}
287	elsif ($item_type eq 'number') {
288	$self->_append(' ' x $indent_level . $item_param . ". ");
289	}
290	elsif ($item_type eq 'text') {
291	$self->_append(' ' x $indent_level . '$ ' );
292	}
293	}
294	elsif ($self->{_format} eq 'wikipedia') {
295
296	if ($item_type eq 'bullet') {
297	$self->_append('*' x $indent_level . ' ');
298	}
299	elsif ($item_type eq 'number') {
300	$self->_append('#' x $indent_level . ' ');
301	}
302	elsif ($item_type eq 'text') {
303	$self->_append(";" x $indent_level . ' ');
304	}
305	}
306	elsif ($self->{_format} eq 'socialtext') {
307
308	if ($item_type eq 'bullet') {
309	$self->_append('*' x $indent_level . ' ');
310	}
311	elsif ($item_type eq 'number') {
312	$self->_append('#' x $indent_level . ' ');
313	}
314	elsif ($item_type eq 'text') {
315	$self->_append(">" x $indent_level . ' ');
316	}
317	}
318	}
319
320
321	###############################################################################
322	#
323	# _skip_headings()
324	#
325	# Formatting in headings doesn't look great or is ignored in some formats.
326	#
327	sub _skip_headings {
328
329	my $self = shift;
330
331	return (
332	$self->{_format} eq 'kwiki' and
333	($self->{_in_head1} or
334	$self->{_in_head2} or
335	$self->{_in_head3} or
336	$self->{_in_head4})
337	);
338	}
339
340
341	###############################################################################
342	#
343	# _append_tag()
344	#
345	# Add an open or close tag to the current text.
346	#
347	sub _append_tag {
348
349	my $self = shift;
350	my $tag = $_[0];
351
352	$self->_append($self->{_tags}->{$tag});
353	}
354
355
356	###############################################################################
357	###############################################################################
358	#
359	# The methods in the following section are required by Pod::Simple to handle
360	# Pod directives and elements.
361	#
362	# The methods _handle_element_start() _handle_element_end() and _handle_text()
363	# are called by Pod::Simple in response to Pod constructs. We use
364	# _handle_element_start() and _handle_element_end() to generate calls to more
365	# specific methods. This is basically a long-hand version of Pod::Simple::
366	# Methody with the addition of location tracking.
367	#
368
369
370	###############################################################################
371	#
372	# _handle_element_start()
373	#
374	# Call a method to handle the start of a element if one has been defined.
375	# We also set a flag to indicate that we are "in" the element type.
376	#
377	sub _handle_element_start {
378
379	my $self = shift;
380	my $element = $_[0];
381
382	$element =~ tr/-/_/;
383
384	print "<$element>\n" if $_debug;
385
386	$self->{"_in_". $element}++;
387
388	if (my $method = $self->can('_start_' . $element)) {
389	$method->($self, $_[1]);
390	}
391	}
392
393
394	###############################################################################
395	#
396	# _handle_element_end()
397	#
398	# Call a method to handle the end of a element if one has been defined.
399	# We also set a flag to indicate that we are "out" of the element type.
400	#
401	sub _handle_element_end {
402
403	my $self = shift;
404	my $element = $_[0];
405
406	$element =~ tr/-/_/;
407
408	if (my $method = $self->can('_end_' . $element)) {
409	$method->($self);
410	}
411
412	$self->{"_in_". $element}--;
413
414	print "</$element>\n" if $_debug;
415	}
416
417
418	###############################################################################
419	#
420	# _handle_text()
421	#
422	# Perform any necessary transforms on the text. This is mainly used to escape
423	# inadvertent CamelCase words.
424	#
425	sub _handle_text {
426
427	my $self = shift;
428	my $text = $_[0];
429
430	# Only escape CamelCase in Kwiki paragraphs
431	if ($self->{_format} eq 'kwiki' and not $self->{_in_Para}) {
432	$self->{_wiki_text} .= $text;
433	return;
434	}
435
436	# Split the text into tokens but maintain the whitespace
437	my @tokens = split /(\s+)/, $text;
438
439	if ($self->{_format} eq 'wiki') {
440	for (@tokens) {
441	next unless /\S/; # Ignore the whitespace
442	next if m[^(ht\|f)tp://]; # Ignore URLs
443	s/([A-Z][a-z]+)(?=[A-Z])/$1''''''/g # Escape with 6 single quotes
444
445	}
446	}
447	elsif ($self->{_format} eq 'kwiki') {
448	for (@tokens) {
449	next unless /\S/; # Ignore the whitespace
450	next if m[^(ht\|f)tp://]; # Ignore URLs
451	s/([A-Z][a-z]+[A-Z]\w+)/!$1/g; # Escape with !
452	}
453	}
454	# TODO: Add usemod <nowiki> escapes
455
456	# Rejoin the tokens and whitespace.
457	$self->{_wiki_text} .= join '', @tokens;
458	}
459
460
461	###############################################################################
462	#
463	# Functions to deal with the I<>, B<> and C<> formatting codes.
464	#
465	sub _start_I {$_[0]->_append_tag('<i>') unless $_[0]->_skip_headings()}
466	sub _start_B {$_[0]->_append_tag('<b>') unless $_[0]->_skip_headings()}
467	sub _start_C {$_[0]->_append_tag('<tt>') unless $_[0]->_skip_headings()}
468	sub _start_F {$_[0]->_start_I}
469
470	sub _end_I {$_[0]->_append_tag('</i>') unless $_[0]->_skip_headings()}
471	sub _end_B {$_[0]->_append_tag('</b>') unless $_[0]->_skip_headings()}
472	sub _end_C {$_[0]->_append_tag('</tt>') unless $_[0]->_skip_headings()}
473	sub _end_F {$_[0]->_end_I}
474
475
476	###############################################################################
477	#
478	# Functions to deal with the Pod =head directives
479	#
480	sub _start_head1 {$_[0]->_append_tag('<h1>')}
481	sub _start_head2 {$_[0]->_append_tag('<h2>')}
482	sub _start_head3 {$_[0]->_append_tag('<h3>')}
483	sub _start_head4 {$_[0]->_append_tag('<h4>')}
484
485	sub _end_head1 {$_[0]->_append_tag('</h1>'); $_[0]->_output()}
486	sub _end_head2 {$_[0]->_append_tag('</h2>'); $_[0]->_output()}
487	sub _end_head3 {$_[0]->_append_tag('</h3>'); $_[0]->_output()}
488	sub _end_head4 {$_[0]->_append_tag('</h4>'); $_[0]->_output()}
489
490
491	###############################################################################
492	#
493	# Functions to deal with verbatim paragraphs. We emit the text "as is" for now.
494	# TODO: escape any Wiki formatting in text such as ''code''.
495	#
496	sub _start_Verbatim {$_[0]->_append_tag('<pre>')}
497	sub _end_Verbatim {$_[0]->_append_tag('</pre>'); $_[0]->_output()}
498
499
500	###############################################################################
501	#
502	# Functions to deal with =over ... =back regions for
503	#
504	# Bulleted lists
505	# Numbered lists
506	# Text lists
507	# Block lists
508	#
509	sub _start_over_bullet {$_[0]->{_item_indent}++}
510	sub _start_over_number {$_[0]->{_item_indent}++}
511	sub _start_over_text {$_[0]->{_item_indent}++}
512
513	sub _end_over_bullet {$_[0]->{_item_indent}--;
514	$_[0]->_output("\n") unless $_[0]->{_item_indent}}
515
516	sub _end_over_number {$_[0]->{_item_indent}--;
517	$_[0]->_output("\n") unless $_[0]->{_item_indent}}
518
519	sub _end_over_text {$_[0]->{_item_indent}--;
520	$_[0]->_output("\n") unless $_[0]->{_item_indent}}
521
522	sub _start_item_bullet {$_[0]->_indent_item('bullet')}
523	sub _start_item_number {$_[0]->_indent_item('number', $_[1]->{number})}
524	sub _start_item_text {$_[0]->_indent_item('text')}
525
526	sub _end_item_bullet {$_[0]->_output("\n")}
527	sub _end_item_number {$_[0]->_output("\n")}
528	sub _end_item_text {$_[0]->_output(":\t") if $_[0]->{_format} eq 'wiki';
529	$_[0]->_output(" ; ") if $_[0]->{_format} eq 'kwiki';
530	$_[0]->_output(":" ) if $_[0]->{_format} eq 'usemod';
531	$_[0]->_output(": " ) if $_[0]->{_format} eq 'twiki';
532	$_[0]->_output(" : ") if $_[0]->{_format} eq 'wikipedia';
533	$_[0]->_output("\n") if $_[0]->{_format} eq 'socialtext';}
534
535	sub _start_over_block {$_[0]->{_item_indent}++}
536	sub _end_over_block {$_[0]->{_item_indent}--}
537
538
539	###############################################################################
540	#
541	# _start_Para()
542	#
543	# Special handling for paragraphs that are part of an "over" block.
544	#
545	sub _start_Para {
546
547	my $self = shift;
548	my $indent_level = $self->{_item_indent};
549
550	if ($self->{_in_over_block}) {
551
552	if ($self->{_format} eq 'wiki') {
553	$self->_append(("\t" x $indent_level) . " :\t");
554	}
555	elsif ($self->{_format} eq 'usemod') {
556	$self->_append(":" x $indent_level);
557	}
558	}
559	}
560
561
562	###############################################################################
563	#
564	# _end_Para()
565	#
566	# Special handling for paragraphs that are part of an "over_text" block.
567	# This is mainly required be Kwiki.
568	#
569	sub _end_Para {
570
571	my $self = shift;
572
573	# Only add a newline if the paragraph isn't part of a text
574	if ($self->{_in_over_text}) {
575	# Workaround for the fact that Kwiki doesn't have a definition block
576	#$self->_output("\n") if $self->{_format} eq 'kwiki';
577	}
578	else {
579	$self->_output("\n");
580	}
581
582	$self->_output("\n")
583	}
584
585
586	1;
587
588
589	__END__
590
591	=head1 NAME
592
593	Pod::Simple::Wiki - A class for creating Pod to Wiki filters.
594
595	=head1 SYNOPSIS
596
597	To create a simple C<pod2wiki> filter:
598
599	#!/usr/bin/perl -w
600
601	use strict;
602	use Pod::Simple::Wiki;
603
604
605	my $parser = Pod::Simple::Wiki->new();
606
607	if (defined $ARGV[0]) {
608	open IN, $ARGV[0] or die "Couldn't open $ARGV[0]: $!\n";
609	} else {
610	IN = STDIN;
611	}
612
613	if (defined $ARGV[1]) {
614	open OUT, ">$ARGV[1]" or die "Couldn't open $ARGV[1]: $!\n";
615	} else {
616	OUT = STDOUT;
617	}
618
619	$parser->output_fh(*OUT);
620	$parser->parse_file(*IN);
621
622	__END__
623
624
625	=head1 DESCRIPTION
626
627	The C<Pod::Simple::Wiki> module is used for converting Pod text to Wiki text.
628
629	Pod (Plain Old Documentation) is a simple markup language used for writing Perl documentation.
630
631	A Wiki is a user extensible web site. It uses very simple mark-up that is converted to Html.
632
633	For an introduction to Wikis see: http://en.wikipedia.org/wiki/Wiki
634
635
636	=head1 METHODS
637
638	=head2 new()
639
640	The C<new> method is used to create a new L<Pod::Simple::Wiki> object. It is also used to set the output Wiki format.
641
642	my $parser1 = Pod::Simple::Wiki->new('wiki');
643	my $parser2 = Pod::Simple::Wiki->new('kwiki');
644	my $parser3 = Pod::Simple::Wiki->new(); # Defaults to 'wiki'
645
646	The currently supported formats are:
647
648	=over 4
649
650	=item wiki
651
652	This is the original Wiki format as used on Ward Cunningham's Portland repository of Patterns. The formatting rules are given at http://c2.com/cgi/wiki?TextFormattingRules
653
654	=item kwiki
655
656	This is the format as used by Brian Ingerson's CGI::Kwiki: http://search.cpan.org/dist/CGI-Kwiki/
657
658	=item usemod
659
660	This is the format used by the Usemod wikis. See: http://www.usemod.com/cgi-bin/wiki.pl?WikiFormat
661
662	=item twiki
663
664	This is the format used by TWiki wikis. See: http://www.twiki.org/
665
666	=item wikipedia or mediawiki
667
668	This is the format used by Wikipedia and MediaWiki wikis. See: http://www.wikipedia.org/
669
670	=back
671
672	If no format is specified the parser defaults to C<wiki>.
673
674	Any other parameters in C<new> will be passed on to the parent L<Pod::Simple> object. See L<Pod::Simple> for more details.
675
676
677	=head2 Other methods
678
679	Pod::Simple::Wiki inherits all of the methods of L<Pod::Simple>. See L<Pod::Simple> for more details.
680
681
682	=head1 TODO
683
684	=over 4
685
686	=item *
687
688	Add more code, more tests and a few more users if possible.
689
690	=item *
691
692	Add other Wiki formats. Send requests or patches.
693
694	=item *
695
696	Fix some of the C<=over> edge cases. See the TODOs in the test programs.
697
698	=back
699
700
701
702	=head1 SEE ALSO
703
704	This module also installs a C<pod2wiki> command line utility. See C<pod2wiki --help> for details.
705
706
707	=head1 ACKNOWLEDGEMENTS
708
709	Thanks to Sean M. Burke for C<Pod::Simple>. It may not be simple but sub-classing it is. C<:-)>
710
711	Thanks to Sam Tregar for TWiki support.
712
713	Thanks Tony Sidaway for Wikipedia/MediaWiki support.
714
715
716	=head1 AUTHOR
717
718	John McNamara jmcnamara@cpan.org
719
720
721	=head1 COPYRIGHT
722
723	© MMIII-MMV, John McNamara.
724
725	All Rights Reserved. This module is free software. It may be used, redistributed and/or modified under the same terms as Perl itself.
726