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 • nofollow_extended
85 When used with the "extended" flag, any extended links will be
87 turned into HTML tags with the "rel="nofollow"" attribute. By
88 default, this option is off.
89 Wiki Format
91 Wiki formatting is very simple. An item wrapped in three single quotes
92 is strong. An item wrapped in two single quotes is emphasized. Any
93 word with multiple CapitalLetters (e. g., StudlyCaps) will become a
94 link. Four or more hyphen characters at the start of a line create a
95 horizontal line. Newlines turn into the appropriate tags. Headers are
96 matching equals signs around the header text -- the more signs, the
97 lesser the header.
98 Lists are indented text, by one tab or four spaces by default. You may
100 disable indentation. In unordered lists, where each item has its own
101 bullet point, each item needs a leading asterisk and space. Ordered
102 lists consist of items marked with combination of one or more
103 alphanumeric characters followed by a period and an optional space.
104 Any indented text without either marking is code, handled literally.
105 You can nest lists.
106 The following is valid Wiki formatting, with an extended link as
108 marked.
109 = my interesting text =
111 ANormalLink
113 [let the Sun shine|AnExtendedLink]
114 == my interesting lists ==
116 * unordered one
118 * unordered two
119 1. ordered one
121 2. ordered two
122 a. nested one
123 b. nested two
124 code one
126 code two
127 The first line of a normal paragraph.
129 The second line of a normal paragraph. Whee.
130
132 If you'd like to make your life more convenient, you can optionally
133 import a subroutine that already has default tags and options set up.
134 This is especially handy if you use a prefix:
135 use Text::WikiFormat prefix => 'http://www.example.com/';
137 wikiformat( 'some text' );
138 Tags are interpreted as, well, tags, except for five special keys:
140 • "prefix", interpreted as a link prefix
142 • "extended", interpreted as the extended link flag
144 • "implicit_links", interpreted as the flag to control implicit links
146 • "absolute_links", interpreted as the flag to control absolute links
148 • "as", interpreted as an alias for the imported function
150 Use the "as" flag to control the name by which your code calls the
152 imported functionFor example,
153 use Text::WikiFormat as => 'formatTextInWikiStyle';
155 formatTextInWikiStyle( 'some text' );
156 You might choose a better name, though.
158 The calling semantics are effectively the same as those of the format()
160 function. Any additional tags or options to the imported function will
161 override the defaults. This code:
162 use Text::WikiFormat as => 'wf', extended => 0;
164 wf( 'some text', {}, { extended => 1 });
165 enables extended links, though the default is to disable them.
167 Tony Bowden <tony@kasei.com> suggested this feature, but all
169 implementation blame rests solely with me. Kate L Pugh
170 (<kake@earth.li>) pointed out that it didn't work, with tests. It
171 works now.
172
174 Tags
175 There are two types of Wiki markup: line items and blocks. Blocks
176 include lists, which are made up of lines and can also contain other
177 lists.
178 Line items
180 There are two classes of line items: simple tags, and tags that contain
182 data. The simple tags are "newline" and "line". The module inserts a
183 newline tag whenever it encounters a newline character ("\n"). It
184 inserts a line tag whenever four or more dash characters ("----") occur
185 at the start of a line. No whitespace is allowed. These default to
186 the <br> and <hr> HTML tags, respectively. To override either, simply
187 pass tags such as:
188 my $html = format($text, { newline => "\n" });
190 The three line items are more complex, and require subroutine
192 references. This category includes the "strong" and "emphasized" tags
193 as well as "link"s. The first argument passed to the subref will be
194 the data found in between the marks. The second argument is the $opts
195 hash reference. The default action for a strong tag is equivalent to:
196 my $html = format($text, { strong => sub { "<b>$_[0]</b>" } });
198 As of version 0.70, you can change the regular expressions used to find
200 strong and emphasized tags:
201 %tags = (
203 strong_tag => qr/\*(.+?)\*/,
204 emphasized_tag => qr|(?<!<)/(.+?)/|,
205 );
206 $wikitext = 'this is *strong*, /emphasized/, and */emphasized strong/*';
208 $htmltext = Text::WikiFormat::format( $wikitext, \%tags, {} );
209 Be aware that using forward slashes to mark anything leads to the hairy
211 regular expression -- use something else. This interface is
212 experimental and may change if I find something better. It's nice to
213 be able to override those tags, though.
214 Finally, there are "extended_link_delimiters", which allow you to use
216 delimiters other than single square brackets for marking extended
217 links. Pass the tags as:
218 my $html = format( $text, { extended_link_delimiters => [ '[[', ']]' ] });
220 This allows you to use double square brackets as UseMod supports:
222 [[an extended link]]
224 [[a titled extended link|title]]
225 Blocks
227 There are five default block types: "paragraph", "header", "code",
229 "unordered", and "ordered". The parser usually finds these by
230 indentation, either one or more tabs or four or more whitespace
231 characters. (This does not include newlines, however.) Any line that
232 does not fall in any of these three categories is a "paragraph".
233 Code, unordered, and ordered blocks do not require indentation, but the
235 parser uses it to control nesting in lists. Be careful. To mark a
236 block as requiring indentation, use the "indented" tag, which contains
237 a reference to a hash:
238 my $html = format($text, {
240 indented => { map { $_ => 1 } qw( ordered unordered code )}
241 });
242 Block entries in the tag hashes must contain array references. The
244 first two items are the tags used at the start and end of the block.
245 The last items contain the tags used at the start and end of each line.
246 Where there needs to be more processing of individual lines, use a
247 subref as the third item. This is how the module numbers ordered lines
248 in HTML lists:
249 my $html = format($text, { ordered => [ '<ol>', "</ol>\n",
251 sub { qq|<li value="$_[2]">$_[0]</li>\n| } ] });
252 The first argument to these subrefs is the post-processed text of the
254 line itself. (Processing removes the indentation and tokens used to
255 mark this as a list and checks the rest of the line for other line
256 formattings.) The second argument is the indentation level. The
257 subsequent arguments are captured variables in the regular expression
258 used to find this list type. The regexp for ordered lists is:
259 qr/^([\dA-Za-z]+)\.\s*/;
261 The module processes indentation first, if applicable, and stores the
263 indentation level (the length of the indentation removed). The line
264 must contain one or more alphanumeric character followed by a single
265 period and optional whitespace to be an ordered list item. The module
266 saves the contents of this last group, the value of the list item, and
267 passes it to the subref as the third argument.
268 Lists automatically start and end as necessary.
270 Because of the indentation issue, there is a specific blocks processing
272 in a specific order. The "blockorder" tag governs this order. It
273 contains a reference to an array of the names of the appropriate blocks
274 to process. If you add a block type, be sure to add an entry for it in
275 "blockorder":
276 my $html = format($text, {
278 escaped => [ '', '', '', '' ],
279 blocks => {
280 invisible => qr!^--(.*?)--$!,
281 },
282 blockorder =>
283 [qw( header line ordered unordered code paragraph invisible )],
284 });
285 Finding blocks
287 Text::WikiFormat uses regular expressions to find blocks. These are in
289 the %tags hash under the "blocks" key. To change the regular
290 expression to find code block items, use:
291 my $html = format($wikitext, {
293 blocks => {
294 code => qr/^:\s+/,
295 },
296 indented => {
297 code => 1,
298 },
299 );
300 This will require indentation and a colon to mark code lines. A
302 potential shortcut is to use the "indent" tag to match or to change the
303 indentation marker.
304 Note: if you want to mark a block type as non-indented, you cannot use
306 an empty regex such as "qr//". Use a mostly-empty, always-true regex
307 such as "qr/^/" instead.
308 Finding Blocks in the Correct Order
310 As intrepid bug reporter Tom Hukins pointed out in CPAN RT bug #671,
312 the order in which Text::WikiFormat searches for blocks varies by
313 platform and version of Perl. Because some block-finding regular
314 expressions are more specific than others, what you intend to be one
315 type of block may turn into a different list type.
316 If you're adding new block types, be aware of this. The "blockorder"
318 entry in %tags exists to force Text::WikiFormat to apply its regexes
319 from most specific to least specific. It contains an array reference.
320 By default, it looks for ordered lists first, unordered lists second,
321 and code references at the end.
322
324 chromatic, "chromatic@wgz.org", with much input from the Jellybean team
325 (including Jonathan Paulett). Kate L Pugh has also provided several
326 patches, many failing tests, and is usually the driving force behind
327 new features and releases. If you think this module is worth buying me
328 a beer, she deserves at least half of it.
329 Alex Vandiver added a nice patch and tests for extended links.
331 Tony Bowden, Tom Hukins, and Andy H. all suggested useful features that
333 are now implemented.
334 Sam Vilain, Chris Winters, Paul Schmidt, and Art Henry have all found
336 and reported silly bugs.
337 Blame me for the implementation.
339
341 The link checker in "format_line()" may fail to detect existing links
342 that do not follow HTML, XML, or SGML style. They may die with some
343 SGML styles too. Sic transit gloria mundi.
344
346 • Find a nicer way to mark list as having unformatted lines
347 • Optimize "format_line()" to work on a list of lines
349 • Handle nested "strong" and "emphasized" markings better
351
353 Brian "Ingy" Ingerson's CGI::Kwiki has a fairly nice parser.
354 John McNamara's Pod::Simple::Wiki looks like a good project.
356 Matt Sergeant keeps threatening to write a nice SAX-throwing Wiki
358 formatter.
359
361 Copyright (c) 2002 - 2006, chromatic. All rights reserved. This
362 module is distributed under the same terms as Perl itself.
363perl v5.34.0 2021-07-23 Text::WikiFormat(3)