/
README
335 lines (231 loc) · 9.48 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
NAME
HTML::FromText - Convert plain text to HTML.
SYNOPSIS
use HTML::FromText;
text2html( $text, %options );
# or
use HTML::FromText ();
my $t2h = HTML::FromText->new( \%options );
my $html = $t2h->parse( $html );
DESCRIPTION
"HTML::FromText" converts plain text to HTML. There are a handfull of
options that shape the conversion. There is a utility function,
"text2html", that's exported by default. This function is simply a
short- cut to the Object Oriented interface described in detail below.
Methods
The following methods may be used as the public interface.
new
my $t2h = HTML::FromText->new({
paras => 1,
blockcode => 1,
tables => 1,
bullets => 1,
numbers => 1,
urls => 1,
email => 1,
bold => 1,
underline => 1,
});
Constructs a new "HTML::FromText" object using the given configuration.
The resulting object can parse lots of objects using the "parse" method.
Options to "new" are passed by name, with the value being either true or
false. If true, the option will be turned on. If false, it will be
turned off. The following outlines all the options.
Decorators
metachars
This option is on by default.
All characters that are unsafe for HTML display will be encoded
using "HTML::Entities::encode_entities()".
urls This option is off by default.
Replaces URLs with links.
email
This option is off by default.
Replaces email addresses with "mailto:" links.
bold This option is off by default.
Replaces text surrounded by asterisks ("*") with the same text
surrounded by "strong" tags.
underline
This option is off by default.
Replaces text surrownded by underscores ("_") with the same text
surrounded by "span" tags with an underline style.
Output Modes
The following are three output modes and the options associated with
them. They are listed in order of precidence. If none of these modes are
supplied, the basic decorators are applied to the text in whole.
pre This option is off by default.
Wraps the entire text in "pre" tags.
lines
This option is off by default.
Preserves line breaks by inserting "br" tags at the end of each
line.
This mode has further options.
spaces
This option is off by default.
All spaces are HTML encoded.
paras
This option is off by default.
Preserves paragraphs by wrapping them in "p" tags.
This mode has further options.
bullets
This option is off by default.
Convert bulleted lists into unordered lists ("ul"). Bullets
can be either an asterisk ("*") or a hyphen ("-"). Lists can
be nested.
numbers
This option is off by default.
Convert numbered lists into ordered lists ("ol"). Numbered
lists are identified by numerals. Lists may be nested.
headings
This option is off by default.
Convert paragraphs identified as headings into HTML headings
at the appropriate level. The heading "1. Top" would be
heading level one ("h1"). The heading "2.5.1. Blah" would be
heading level three ("h3").
title
This option is off by default.
Convert the first paragraph to a heading level one ("h1").
tables
This option is off by default.
Convert paragraphs identified as tables to HTML tables. Tables
are two or more rows and two or more columns. Columns should
be separated by two or more spaces.
The following options apply specifically to indented paragraphs.
They are listed in order of precidence.
blockparas
This option is off by default.
Convert indented paragraphs to block quotes using the
"blockquote" tag.
blockquotes
Convert indented paragraphs as "blockparas" would, but also
preserving line breaks.
blockcode
Convert indented paragraphs as "blockquotes" would, but also
preserving spaces using "pre" tags.
parse
my $html = $t2h->parse( $text );
Parses text supplied as a single scalar string and returns the HTML as a
single scalar string. All the tabs in your text will be expanded using
"Text::Tabs::expand()".
Functions
text2html
my $html = text2html(
$text,
urls => 1,
email => 1,
);
Functional interface that just wraps the OO interface. This function is
exported by default. If you don't want it you can "require" the module
or "use" it with an empty list.
require HTML::FromText;
# or ...
use HTML::FromText ();
Subclassing
Note: At the time of this release, the internals of "HTML::FromText" are
in a state of development and cannot be expected to stay the same from
release to release. I expect that release version 3.00 will be analogous
to a 1.00 release of other software. This is because the current
maintainer has rewritten this distribution from the ground up for the
"2.x" series. You have been warned.
The following methods may be used for subclassing "HTML::FromText" to
create your own text to HTML conversions. Each of these methods is
passed just one argument, the object ($self), unless otherwise stated.
The structure of $self is as follows for this release.
{
options => {
option_name => $value,
...
},
text => $text, # as passed to parse(), with tabs expanded
html => $html, # the HTML that will be returned from parse()
}
pre
Used when "pre" mode is specified.
Should set "$self->{html}".
Return value is ignored.
lines
Used when "lines" mode is specified.
Implements the "spaces" option internally when the option is set to a
true value.
Should set "$self->{html}".
Return value is ignored.
paras
Used when the "paras" mode is specified.
Splits "$self->{text}" into paragraphs internally and sets up
"$self->{paras}" as follows.
paras => {
0 => {
text => $text, # paragraph text
html => $html, # paragraph html
},
... # and so on for all paragraphs
},
Implements the "title" option internally when the option is turned on.
Converts any normal paragraphs to HTML paragraphs (surrounded by "p"
tags) internally.
Should set "$self->{html}".
Return value is ignored.
headings
Used to format headings when the "headings" option is turned on.
Return value is ignored.
bullets
Format bulleted lists when the "bullets" option is turned on.
Return value is ignored.
numbers
Format numbered lists when the "numbers" option is turned on.
Return value is ignored.
tables
Format tables when the "tables" option is turned on.
Return value is ignored.
blockparas
Used when the "blockparas" option is turned on.
Return value is ignored.
blockquotes
Used when the "blockquotes" option is turned on.
Return value is ignored.
blockcode
Used when the "blockcode" option is turned on.
Return value is ignored.
urls
Turn urls into links when "urls" option is turned on.
Should operate on "$self->{html}".
Return value is ignored.
email
Turn email addresses into "mailto:" links when "email" option is turned
on.
Should operate on "$self->{html}".
Return value is ignored.
underline
Underline things between _underscores_ when "underline" option is turned
on.
Should operate on "$self->{html}".
Return value is ignored.
bold
Bold things between *asterisks* when "bold" option is turned on.
Should operate on "$self->{html}".
Return value is ignored.
metachars
Encode meta characters when "metachars" option is turned on.
Should operate on "$self->{html}".
Return value is ignored.
Output
The output from "HTML::FromText" has been updated to pass XHTML 1.1
validation. Every HTML tag that should have a CSS class name does. They
are prefixed with "hft-" and correspond to the names of the options to
"new()" (or "text2html()"). For example "hft-lines", "hft-paras", and
"hft-urls".
One important note is the output for "underline". Because the <u> tag is
deprecated in this specification a "span" is used with a style attribute
of "text-decoration: underline". The class is "hft- underline". If you
want to override the "text-decoration" style in the CSS class you'll
need to do so like this.
text-decoration: none !important;
SEE ALSO
text2html(1).
AUTHOR
Casey West <casey@geeknest.com>.
AUTHOR EMERITUS
Gareth Rees <garethr@cre.canon.co.uk>.
COPYRIGHT
Copyright (c) 2003 Casey West. All rights reserved.
This module is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.