require 5.004;
use strict;
package HTML::FromText;
use Carp;
use Exporter;
use Text::Tabs 'expand';
use vars qw($RCSID $VERSION $QUIET @EXPORT @ISA);
@ISA = qw(Exporter);
@EXPORT = qw(text2html);
$RCSID = q$Id: FromText.pm,v 1.14 1999/10/06 10:53:37 garethr Exp $;
$VERSION = '1.005';
$QUIET = 0;
# This list of protocols is taken from RFC 1630: "Universal Resource
# Identifiers in WWW". The protocol "file" is omitted because
# experience suggests that it results in many false positives; "https"
# postdates RFC 1630. The protocol "mailto" is handled separately, by
# the email address matching code.
my $protocol = join '|',
qw(afs cid ftp gopher http https mid news nntp prospero telnet wais);
# The regular expressions matching email addresses use the following
# syntax elements from RFC 822. I can't use the full details of
# structured field bodies, because that would give too many false
# positives. (See Tom Christiansen's ckaddr.gz for a full
# implementation of the RFC 822.)
#
# addr-spec = local-part "@" domain
# local-part = word *("." word)
# word = atom
# domain = sub-domain *("." sub-domain)
# sub-domain = domain-ref
# domain-ref = atom
# atom = 1*
# specials = "(" / ")" / "<" / ">" / "@" / "," / ";" / ":" / "\"
# / <"> / "." / "[" / "]"
#
# I have ignored quoting, domain literals and comments.
#
# Note that '&' can legally appear in email addresses (for example,
# 'fred&barney@stonehenge.com'). If the 'metachars' option is passed to
# text2html then I must use '&' to recognize '&'. Thus the regular
# expression $atom[0] recognizes an atom in the case where the option
# 'metachars' is false; $atom[1] recognizes an atom in the case where
# 'metachars' is true. Similarly for the regular expressions $email[0]
# and $email[1], which recognize email addresses.
my @atom =
( '[!#$%&\'*+\\-/0123456789=?ABCDEFGHIJKLMNOPQRSTUVWXYZ^_`abcdefghijklmnopqrstuvwxyz{|}~]+',
'(?:&|[!#$%\'*+\\-/0123456789=?ABCDEFGHIJKLMNOPQRSTUVWXYZ^_`abcdefghijklmnopqrstuvwxyz{|}~])+' );
my @email = ( "$atom[0](\\.$atom[0])*\@$atom[0](\\.$atom[0])*",
"$atom[1](\\.$atom[1])*\@$atom[1](\\.$atom[1])*" );
my @alignments = ( '', '', ' ALIGN="RIGHT"', ' ALIGN="CENTER"' );
sub string2html ($$) {
my $options = $_[1];
for ($_[0]) { # Modify in-place.
# METACHARS: mark up HTML metacharacters as corresponding entities.
if ($options->{metachars}) {
s/&/&/g;
s/</g;
s/>/>/g;
s/\"/"/g;
}
# EMAIL, URLS: spot electronic mail addresses and turn them into
# links. Note (1) if `urls' is set but not `email', then only
# addresses prefixed by `mailto:' will be marked up; (2) that we leave
# the `mailto:' prefix in the anchor text.
if ($options->{email} or $options->{urls}) {
s|((?:mailto:)?)($email[$options->{metachars}?1:0])|
($options->{email} or $1)
? "$1$2" : $2|gex;
}
# URLS: mark up URLs as links (note that `mailto' links are handled
# above).
if ($options->{urls}) {
s|\b((?:$protocol):\S+[\w/])|$1|g;
}
# BOLD: mark up words in *asterisks* as bold.
if ($options->{bold}) {
s#(^|\s)\*([^*]+)\*(?=\s|$)#$1$2#g;
}
# UNDERLINE: mark up words in _underscores_ as underlined.
if ($options->{underline}) {
s#(^|\s)_([^_]+?)_(?=\s|$)#$1$2#g;
}
}
return $_[0];
}
sub text2html {
local $_ = shift; # Take a copy; don't modify in-place.
return $_ unless $_;
my %options = ( metachars => 1, @_ );
# Check options for sanity.
unless ($QUIET) {
carp "text2html: `spaces' will be ignored since `lines' is not specified"
if $options{spaces} and not $options{lines};
if ($options{paras}) {
if ($options{blockparas}) {
foreach my $o (qw(blockquotes blockcode)) {
carp "text2html: `$o' will be ignored since `blockparas' is specified" if $options{$o};
}
} elsif ($options{blockcode} and $options{blockquotes}) {
carp "text2html: `blockquotes' will be ignored since `blockcode' is specified";
}
} else {
foreach my $o (qw(bullets numbers blockquotes blockparas blockcode
title headings tables)) {
carp "text2html: `$o' will be ignored since `paras' is not specified"
if $options{$o};
}
}
}
# Expand tabs.
$_ = join "\n", expand(split /\r?\n/);
# PRE: put text in element.
if ($options{pre}) {
string2html($_, \%options);
s|^||;
s|$||;
}
# LINES: preserve line breaks from original text.
elsif ($options{lines}) {
string2html($_, \%options);
s/\n/
\n/gm;
# SPACES: preserve spaces from original text.
s/ / /g if $options{spaces};
}
# PARAS: treat text as sequence of paragraphs.
elsif ($options{paras}) {
my @paras;
# Remove initial and final blank lines.
s/^(?:\s*?\n)+//;
s/(?:\n\s*?)+$//;
# Split on a different regexp depending on what kinds of paragraphs
# will be recognised later. The idea is that bulleted lists like
# this:
#
# * item 1
# * item 2
#
# will be recognised as multiple paragraphs if the 'bullets' option
# is supplied, but as a single paragraph otherwise. (Similarly for
# numbered lists).
if ($options{bullets} and $options{numbers}) {
@paras = split
/(?:\s*\n)+ # (0 or more blank lines, followed by LF)
(?:\s*\n # Either 1 or more blank lines, or
|(?=\s*[*-]\s+ # bulleted item follows, or
|\s*(?:\d+)[.\)\]]?\s+)) # numbered item follows
/x;
} elsif ($options{bullets}) {
@paras = split
/(?:\s*\n)+ # (0 or more blank lines, followed by LF)
(?:\s*\n # Either 1 or more blank lines, or
|(?=\s*[*-]\s+)) # bulleted item follows.
/x;
} elsif ($options{numbers}) {
@paras = split
/(?:\s*\n)+ # (0 or more blank lines, followed by LF)
(?:\s*\n # Either 1 or more blank lines, or
|(?=\s*(?:\d+)[.\)\]]?\s+)) # numbered item follows.
/x;
} else {
@paras = split
/\s*\n(?:\s*\n)+ # 1 or more blank lines.
/x;
}
my $last = ''; # List type (OL/UL) of last paragraph
my $this; # List type (OL/UL) of this paragraph
my $first = 1; # True if this is first paragraph
foreach (@paras) {
my (@rows,@starts,@ends);
$this = '';
# TITLE: mark up first paragraph as level-1 heading.
if ($options{title} and $first) {
string2html($_,\%options);
s|^||;
s|$|
|;
}
# HEADINGS: mark up paragraphs with numbers at the start of the
# first line as headings.
elsif ($options{headings} and /^(\d+(\.\d+)*)\.?\s/) {
my $number = $1;
my $level = 1 + ($number =~ tr/././);
$level = 6 if $level > 6;
string2html($_,\%options);
s|^||;
s|$||;
}
# BULLETS: mark up paragraphs starting with bullets as items in an
# unnumbered list.
elsif ($options{bullets} and /^\s*[*-]\s+/) {
string2html($_,\%options);
s/^\s*[*-]\s+//;
s|$|
|;
$this = 'UL';
}
# NUMBERS: mark up paragraphs starting with numbers as items in a
# numbered list.
elsif ($options{numbers} and /^\s*(\d+)[.\)\]]?\s+/) {
string2html($_,\%options);
s/^\s*(\d+)[.\)\]]?\s+//;
s|$|
|;
$this = 'OL';
}
# TABLES: spot and mark up tables. We combine the lines of the
# paragraph using the string bitwise or (|) operator, the result
# being in $spaces. A character in $spaces is a space only if
# there was a space at that position in every line of the
# paragraph. $space can be used to search for contiguous spaces
# that occur on all lines of the paragraph. If this results in at
# least two columns, the paragraph is identified as a table.
#
# Note that this option appears before the various 'blockquotes'
# options because a table may well have whitespace to the left, in
# which case it must not be incorrectly recognised as a
# blockquote.
elsif ($options{tables} and do {
@rows = split /\n/, $_;
my $spaces;
my $max = 0;
my $min = length;
foreach my $row (@rows) {
($spaces |= $row) =~ tr/ /\xff/c;
$min = length $row if length $row < $min;
$max = length $row if $max < length $row;
}
$spaces = substr $spaces, 0, $min;
push(@starts, 0) unless $spaces =~ /^ /;
while ($spaces =~ /((?:^| ) +)(?=[^ ])/g) {
push @ends, pos($spaces) - length $1;
push @starts, pos($spaces);
}
shift(@ends) if $spaces =~ /^ /;
push(@ends, $max);
# Two or more rows and two or more columns indicate a table.
2 <= @rows and 2 <= @starts
}) {
# For each column, guess whether it should be left, centre or
# right aligned by examining all cells in that column for space
# to the left or the right. A simple majority among those cells
# that actually have space to one side or another decides (if no
# alignment gets a majority, left alignment wins by default).
my @align;
foreach my $col (0 .. $#starts) {
my @count = (0, 0, 0, 0);
foreach my $row (@rows) {
my $width = $ends[$col] - $starts[$col];
my $cell = substr $row, $starts[$col], $width;
++ $count[($cell =~ /^ / ? 2 : 0)
+ ($cell =~ / $/ || length($cell) < $width ? 1 : 0)];
}
$align[$col] = 0;
my $population = $count[1] + $count[2] + $count[3];
foreach (1 .. 3) {
if ($count[$_] * 2 > $population) {
$align[$col] = $_;
last;
}
}
}
foreach my $row (@rows) {
$row = join '', '', (map {
my $cell = substr $row, $starts[$_], $ends[$_] - $starts[$_];
$cell =~ s/^ +//;
$cell =~ s/ +$//;
string2html($cell,\%options);
('| ', $cell, ' | ')
} 0 .. $#starts), '
';
}
my $tag = $starts[0] == 0 ? 'P' : 'BLOCKQUOTE';
$_ = join "\n", "<$tag>$tag>";
}
# BLOCKPARAS, BLOCKCODE, BLOCKQUOTES: mark up indented paragraphs
# as block quotes of various kinds.
elsif (($options{blockparas} or $options{blockquotes}
or $options{blockcode}) and /^(\s+).*(?:\n\1.*)*$/) {
string2html($_,\%options);
# Every line in the paragraph starts with at white space, the common
# whitespace being in $1. Remove the common initial whitespace,
s/^$1//gm;
# BLOCKPARAS: treat as a paragraph.
if ($options{blockparas}) {
s|^||;
s|$|
|;
}
# BLOCKCODE, BLOCKQUOTES: preserve line breaks.
else {
s/\n/
\n/gm;
# BLOCKCODE: preserve spaces, use fixed-width font.
if ($options{blockcode}) {
s| | |g;
s|^||;
s|$||;
}
}
s|^||;
s|$|
|;
}
# Didn't match any of the above, so just an ordinary paragraph.
else {
string2html($_,\%options);
s|^||;
s|$|
|;
}
# Insert , or
if this paragraph belongs to a
# different list type than the previous one.
if ($this ne $last) {
s|^|<$this>| if ($this ne '');
s|^|$last>| if ($last ne '');
}
$last = $this;
$first = 0;
}
if ($this ne '') {
push @paras, "$this>";
}
$_ = join "\n", @paras;
}
# None of PRE, LINES, PARAS specified: apply basic transformations.
else {
string2html($_,\%options);
}
return $_;
}
1;
__END__
=head1 NAME
HTML::FromText - mark up text as HTML
=head1 SYNOPSIS
use HTML::FromText;
print text2html($text, urls => 1, paras => 1, headings => 1);
=head1 DESCRIPTION
The C function marks up plain text as HTML. By default it
expands tabs and converts HTML metacharacters into the corresponding
entities. More complicated transformations, such as splitting the text
into paragraphs or marking up bulleted lists, can be carried out by
setting the appropriate options.
=head1 SUMMARY OF OPTIONS
These options always apply:
metachars Convert HTML metacharacters to entity references
urls Convert URLs to links
email Convert email addresses to links
bold Mark up words with *asterisks* in bold
underline Mark up words with _underscores_ as underlined
You can then choose to treat the text according to one of these options:
pre Treat text as preformatted
lines Treat text as line-oriented
paras Treat text as paragraph-oriented
(If more than one of these is specified, C takes precedence over
C which takes precedence over C.) The following option
applies when the C option is specified:
spaces Preserve spaces from the original text
The following options apply when the C option is specified:
blockparas Mark up indented paragraphs as block quote
blockquotes Ditto, also preserve lines from original
blockcode Ditto, also preserve spaces from original
bullets Mark up bulleted paragraphs as unordered list
headings Mark up headings
numbers Mark up numbered paragraphs as ordered list
tables Mark up tables
title Mark up first paragraph as level 1 heading
C will issue a warning if it is passed nonsensical options,
for example C but not C. These warnings can be
supressed by setting $HTML::FromText::QUIET to true.
=head1 OPTIONS
=over 4
=item blockparas
=item blockquotes
=item blockcode
These options cause to C to spot paragraphs where every line
begins with whitespace, and mark them up as block quotes. If more than
one of these options is specified, C takes precedence over
C, which takes precedence over C. All three
options are ignored unless the C option is also set.
The C option marks up the paragraph as a block quote with no
other changes. For example,
Turing wrote,
I propose to consider the question,
"Can machines think?"
becomes
Turing wrote,
I propose to consider the question,
"Can machines think?"
The C option preserves line breaks in the original text.
For example,
From "The Waste Land":
Phlebas the Phoenecian, a fortnight dead,
Forgot the cry of gulls, and the deep sea swell
becomes
From "The Waste Land":
Phlebas the Phoenecian, a fortnight dead,
Forgot the cry of gulls, and the deep sea swell
The C option preserves line breaks and spaces in the original
text and renders the paragraph in a fixed-width font. For example:
Here's how to output numbers with commas:
sub commify {
local $_ = shift;
1 while s/^(-?\d+)(\d{3})/$1,$2/;
$_;
}
becomes
Here's how to output numbers with commas:
sub commify {
local $_ = shift;
1 while s/^(-?\d+)(\d{3})/$1,$2/;
$_;
}
=item bold
Words surrounded with asterisks are marked up in bold, so C<*abc*>
becomes CBEabcE/BE>.
=item bullets
Spots bulleted paragraphs (beginning with optional whitespace, an
asterisk or hyphen, and whitespace) and marks them up as an unordered
list. Bulleted paragraphs don't have to be separated by blank lines.
For example,
Shopping list:
* apples
* pears
becomes
Shopping list:
This option is ignored unless the C option is set.
=item email
Spots email addresses in the text and converts them to links. For example
Mail me at web@perl.com.
becomes
Mail me at web@perl.com.
=item headings
Spots headings (paragraphs starting with numbers) and marks them up as
headings of the appropriate level. For example,
1. Introduction
1.1 Background
1.1.1 Previous work
2. Conclusion
becomes
1. Introduction
1.1 Background
1.1.1 Previous work
2. Conclusion
This option is ignored unless the C option is set.
=item lines
Formats the text so as to preserve line breaks. For example,
Line 1
Line 2
becomes
Line 1
Line 2
If two or more of the options C, C and C are set,
then C takes precedence over C, which takes precedence over
C.
=item metachars
Converts HTML metacharacters into their corresponding entity references.
Ampersand (C>) becomes Camp;>, less than (C>)
becomes Clt;>, greater than (C>) becomes Cgt;>, and
quote (") becomes Cquot;>. This option is 1 by default.
=item numbers
Spots numbered paragraphs (beginning with whitespace, digits, an
optional period/parenthesis/bracket, and whitespace) and marks them up
as an ordered list. Numbered paragraphs don't have to be separated by
blank lines. For example,
To do:
1. Write thesis
2. Submit it
3. Celebrate
becomes
To do:
Write thesis
Submit it
Celebrate
This option is ignored unless the C option is set.
=item paras
Format the text into paragraphs. Paragraphs are separated by one or
more blank lines. For example,
Paragraph 1
Paragraph 2
becomes
Paragraph 1
Paragraph 2
If two or more of the options C, C and C are set,
then C takes precedence over C, which takes precedence over
C.
=item pre
Wrap the whole input in a CPREE> element. For example,
preformatted
text
becomes
preformatted
text
If two or more of the options C, C and C are set,
then C takes precedence over C, which takes precedence over
C.
=item spaces
Preserves spaces throughout the text. For example,
Line 1
Line 2
Line 3
becomes
Line 1
Line 2
Line 3
This option is ignored unless the C option is set.
=item tables
Spots tables and marks them up appropriately. Columns must be separated
by two or more spaces (this prevents accidental incorrect recognition of
a paragraph where interword spaces happen to line up). If there are two
or more rows in a paragraph and all rows share the same set of (two or
more) columns, the paragraph is assumed to be a table. For example
-e File exists.
-z File has zero size.
-s File has nonzero size (returns size).
becomes
| -e | File exists. |
| -z | File has zero size. |
| -s | File has nonzero size (returns size). |
C guesses for each column whether it is intended to be left,
centre or right aligned.
This option is ignored unless the C option is set.
=item title
Formats the first paragraph of the text as a first-level heading.
For example,
Paragraph 1
Paragraph 2
becomes
Paragraph 1
Paragraph 2
This option is ignored unless the C option is set.
=item underline
Words surrounded with underscores are marked up with underline, so C<_abc_>
becomes CUEabcE/UE>.
=item urls
Spots Uniform Resource Locators (URLs) in the text and converts them
to links. For example
See https://perl.com/.
becomes
See https://perl.com/.
=back
=head1 SEE ALSO
The C module (part of the LWP package) provides
functions for encoding and decoding HTML entities.
Tom Christiansen has a complete implementation of RFC 822 structured
field bodies. See
C.
Seth Golub's C utility does everything that C
does, and a few things that it would like to do. See
C.
RFC 822: "Standard for the Format of ARPA Internet Text Messages"
describes the syntax of email addresses (the more esoteric features of
structured field bodies, in particular quoted-strings, domain literals
and comments, are not recognized by C). See
C.
RFC 1630: "Universal Resource Identifiers in WWW" lists the protocols
that may appear in URLs. C also recognizes "https:",
but ignores "file:" because experience suggests that it results in too
many false positives. See C.
=head1 AUTHOR
Gareth Rees Cgarethr@cre.canon.co.ukE>.
=head1 COPYRIGHT
Copyright (c) 1999 Canon Research Centre Europe. All rights reserved.
This module is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
=cut