1Text::WikiFormat(3) User Contributed Perl Documentation Text::WikiFormat(3)
2
6 Text::WikiFormat - module for translating Wiki formatted text into
7 other formats
8
10 use Text::WikiFormat;
11 my $html = Text::WikiFormat::format($raw);
12
14 The original Wiki web site had a very simple interface to edit and to
15 add pages. Its formatting rules are simple and easy to use. They are
16 also easy to translate into other, more complicated markup languages
17 with this module. It creates HTML by default, but can produce valid
18 POD, DocBook, XML, or any other format imaginable.
19 The most important function is "format()". It is not exported by
21 default.
22 format()
24 "format()" takes one required argument, the text to convert, and
25 returns the converted text. It allows two optional arguments. The
26 first is a reference to a hash of tags. Anything passed in here will
27 override the default tag behavior. The second argument is a hash
28 reference of options. They are currently:
29 · prefix
31 The prefix of any links. In HTML mode, this is the path to the
33 Wiki. The actual linked item itself will be appended to the
34 prefix. This is useful to create full URIs:
35 { prefix => 'http://example.com/wiki.pl?page=' }
37 · extended
39 A boolean flag, false by default, to use extended linking
41 semantics. This comes from the Everything Engine
42 (http://everydevel.com/), which marks links with square brackets.
43 An optional title may occur after the link target, preceded by an
44 open pipe. These are valid extended links:
45 [a valid link]
47 [link|title]
48 Where the linking semantics of the destination format allow it, the
50 result will display the title instead of the URI. In HTML terms,
51 the title is the content of an "A" element (not the content of its
52 "HREF" attribute).
53 You can use delimiters other than single square brackets for
55 marking extended links by passing a value for
56 "extended_link_delimiters" in the %tags hash when calling "format".
57 · implicit_links
59 A boolean flag, true by default, to create links from
61 StudlyCapsStringsNote that if you disable this flag, you should
62 probably enable the "extended" one also, or there will be no way of
63 creating links in your documents. To disable it, use the pair:
64 { implicit_links => 0 }
66 · absolute_links
68 A boolean flag, false by default, which treats any links that are
70 absolute URIs (such as http://www.cpan.org/) specially. Any prefix
71 will not apply and the URIs aren't quoted. Use this in conjunction
72 with the "extended" option to detect the link.
73 A link is any text that starts with a known schema followed by a
75 colon and one or more non-whitespace characters. This is a
76 distinct subset of what URI recognizes as a URI, but is a good
77 first-order approximation. If you need to recognize more complex
78 URIs, use the standard wiki formatting explained earlier.
79 The recognized schemas are those defined in the "schema" value in
81 the %tags hash. The defaults are "http", "https", "ftp", "mailto",
82 and "gopher".
83 Wiki Format
85 Wiki formatting is very simple. An item wrapped in three single quotes
86 is strong. An item wrapped in two single quotes is emphasized. Any
87 word with multiple CapitalLetters (e. g., StudlyCaps) will become a
88 link. Four or more hyphen characters at the start of a line create a
89 horizontal line. Newlines turn into the appropriate tags. Headers are
90 matching equals signs around the header text -- the more signs, the
91 lesser the header.
92 Lists are indented text, by one tab or four spaces by default. You may
94 disable indentation. In unordered lists, where each item has its own
95 bullet point, each item needs a leading asterisk and space. Ordered
96 lists consist of items marked with combination of one or more
97 alphanumeric characters followed by a period and an optional space.
98 Any indented text without either marking is code, handled literally.
99 You can nest lists.
100 The following is valid Wiki formatting, with an extended link as
102 marked.
103 = my interesting text =
105 ANormalLink
107 [let the Sun shine|AnExtendedLink]
108 == my interesting lists ==
110 * unordered one
112 * unordered two
113 1. ordered one
115 2. ordered two
116 a. nested one
117 b. nested two
118 code one
120 code two
121 The first line of a normal paragraph.
123 The second line of a normal paragraph. Whee.
124
126 If you'd like to make your life more convenient, you can optionally
127 import a subroutine that already has default tags and options set up.
128 This is especially handy if you use a prefix:
129 use Text::WikiFormat prefix => 'http://www.example.com/';
131 wikiformat( 'some text' );
132 Tags are interpreted as, well, tags, except for five special keys:
134 · "prefix", interpreted as a link prefix
136 · "extended", interpreted as the extended link flag
138 · "implicit_links", interpreted as the flag to control implicit links
140 · "absolute_links", interpreted as the flag to control absolute links
142 · "as", interpreted as an alias for the imported function
144 Use the "as" flag to control the name by which your code calls the
146 imported functionFor example,
147 use Text::WikiFormat as => 'formatTextInWikiStyle';
149 formatTextInWikiStyle( 'some text' );
150 You might choose a better name, though.
152 The calling semantics are effectively the same as those of the format()
154 function. Any additional tags or options to the imported function will
155 override the defaults. This code:
156 use Text::WikiFormat as => 'wf', extended => 0;
158 wf( 'some text', {}, { extended => 1 });
159 enables extended links, though the default is to disable them.
161 Tony Bowden <tony@kasei.com> suggested this feature, but all
163 implementation blame rests solely with me. Kate L Pugh
164 (<kake@earth.li>) pointed out that it didn't work, with tests. It
165 works now.
166
168 Tags
169 There are two types of Wiki markup: line items and blocks. Blocks
170 include lists, which are made up of lines and can also contain other
171 lists.
172 Line items
174 There are two classes of line items: simple tags, and tags that contain
176 data. The simple tags are "newline" and "line". The module inserts a
177 newline tag whenever it encounters a newline character ("\n"). It
178 inserts a line tag whenever four or more dash characters ("----") occur
179 at the start of a line. No whitespace is allowed. These default to
180 the <br> and <hr> HTML tags, respectively. To override either, simply
181 pass tags such as:
182 my $html = format($text, { newline => "\n" });
184 The three line items are more complex, and require subroutine
186 references. This category includes the "strong" and "emphasized" tags
187 as well as "link"s. The first argument passed to the subref will be
188 the data found in between the marks. The second argument is the $opts
189 hash reference. The default action for a strong tag is equivalent to:
190 my $html = format($text, { strong => sub { "<b>$_[0]</b>" } });
192 As of version 0.70, you can change the regular expressions used to find
194 strong and emphasized tags:
195 %tags = (
197 strong_tag => qr/\*(.+?)\*/,
198 emphasized_tag => qr|(?<!<)/(.+?)/|,
199 );
200 $wikitext = 'this is *strong*, /emphasized/, and */emphasized strong/*';
202 $htmltext = Text::WikiFormat::format( $wikitext, \%tags, {} );
203 Be aware that using forward slashes to mark anything leads to the hairy
205 regular expression -- use something else. This interface is
206 experimental and may change if I find something better. It's nice to
207 be able to override those tags, though.
208 Finally, there are "extended_link_delimiters", which allow you to use
210 delimiters other than single square brackets for marking extended
211 links. Pass the tags as:
212 my $html = format( $text, { extended_link_delimiters => [ '[[', ']]' ] });
214 This allows you to use double square brackets as UseMod supports:
216 [[an extended link]]
218 [[a titled extended link|title]]
219 Blocks
221 There are five default block types: "paragraph", "header", "code",
223 "unordered", and "ordered". The parser usually finds these by
224 indentation, either one or more tabs or four or more whitespace
225 characters. (This does not include newlines, however.) Any line that
226 does not fall in any of these three categories is a "paragraph".
227 Code, unordered, and ordered blocks do not require indentation, but the
229 parser uses it to control nesting in lists. Be careful. To mark a
230 block as requiring indentation, use the "indented" tag, which contains
231 a reference to a hash:
232 my $html = format($text, {
234 indented => { map { $_ => 1 } qw( ordered unordered code )}
235 });
236 Block entries in the tag hashes must contain array references. The
238 first two items are the tags used at the start and end of the block.
239 The last items contain the tags used at the start and end of each line.
240 Where there needs to be more processing of individual lines, use a
241 subref as the third item. This is how the module numbers ordered lines
242 in HTML lists:
243 my $html = format($text, { ordered => [ '<ol>', "</ol>\n",
245 sub { qq|<li value="$_[2]">$_[0]</li>\n| } ] });
246 The first argument to these subrefs is the post-processed text of the
248 line itself. (Processing removes the indentation and tokens used to
249 mark this as a list and checks the rest of the line for other line
250 formattings.) The second argument is the indentation level. The
251 subsequent arguments are captured variables in the regular expression
252 used to find this list type. The regexp for ordered lists is:
253 qr/^([\dA-Za-z]+)\.\s*/;
255 The module processes indentation first, if applicable, and stores the
257 indentation level (the length of the indentation removed). The line
258 must contain one or more alphanumeric character followed by a single
259 period and optional whitespace to be an ordered list item. The module
260 saves the contents of this last group, the value of the list item, and
261 passes it to the subref as the third argument.
262 Lists automatically start and end as necessary.
264 Because of the indentation issue, there is a specific blocks processing
266 in a specific order. The "blockorder" tag governs this order. It
267 contains a reference to an array of the names of the appropriate blocks
268 to process. If you add a block type, be sure to add an entry for it in
269 "blockorder":
270 my $html = format($text, {
272 escaped => [ '', '', '', '' ],
273 blocks => {
274 invisible => qr!^--(.*?)--$!,
275 },
276 blockorder =>
277 [qw( header line ordered unordered code paragraph invisible )],
278 });
279 Finding blocks
281 Text::WikiFormat uses regular expressions to find blocks. These are in
283 the %tags hash under the "blocks" key. To change the regular
284 expression to find code block items, use:
285 my $html = format($wikitext, {
287 blocks => {
288 code => qr/^:\s+/,
289 },
290 indented => {
291 code => 1,
292 },
293 );
294 This will require indentation and a colon to mark code lines. A
296 potential shortcut is to use the "indent" tag to match or to change the
297 indentation marker.
298 Note: if you want to mark a block type as non-indented, you cannot use
300 an empty regex such as "qr//". Use a mostly-empty, always-true regex
301 such as "qr/^/" instead.
302 Finding Blocks in the Correct Order
304 As intrepid bug reporter Tom Hukins pointed out in CPAN RT bug #671,
306 the order in which Text::WikiFormat searches for blocks varies by
307 platform and version of Perl. Because some block-finding regular
308 expressions are more specific than others, what you intend to be one
309 type of block may turn into a different list type.
310 If you're adding new block types, be aware of this. The "blockorder"
312 entry in %tags exists to force Text::WikiFormat to apply its regexes
313 from most specific to least specific. It contains an array reference.
314 By default, it looks for ordered lists first, unordered lists second,
315 and code references at the end.
316
318 chromatic, "chromatic@wgz.org", with much input from the Jellybean team
319 (including Jonathan Paulett). Kate L Pugh has also provided several
320 patches, many failing tests, and is usually the driving force behind
321 new features and releases. If you think this module is worth buying me
322 a beer, she deserves at least half of it.
323 Alex Vandiver added a nice patch and tests for extended links.
325 Tony Bowden, Tom Hukins, and Andy H. all suggested useful features that
327 are now implemented.
328 Sam Vilain, Chris Winters, Paul Schmidt, and Art Henry have all found
330 and reported silly bugs.
331 Blame me for the implementation.
333
335 The link checker in "format_line()" may fail to detect existing links
336 that do not follow HTML, XML, or SGML style. They may die with some
337 SGML styles too. Sic transit gloria mundi.
338
340 · Find a nicer way to mark list as having unformatted lines
341 · Optimize "format_line()" to work on a list of lines
343 · Handle nested "strong" and "emphasized" markings better
345
347 Brian "Ingy" Ingerson's CGI::Kwiki has a fairly nice parser.
348 John McNamara's Pod::Simple::Wiki looks like a good project.
350 Matt Sergeant keeps threatening to write a nice SAX-throwing Wiki
352 formatter.
353
355 Copyright (c) 2002 - 2006, chromatic. All rights reserved. This
356 module is distributed under the same terms as Perl itself.
357perl v5.12.0 2010-05-07 Text::WikiFormat(3)