Text::Smart(3) User Contributed Perl Documentation Text::Smart(3)NAMEText::Smart - Processor for 'smart text' markup
SYNOPSIS
use Text::Smart;
my $markup = Text::Smart->new(entities => \%entities);
my $text = $markup->process($text, %opts);
my $text = $markup->process_divider($text);
my $text = $markup->process_itemize($text, %opts);
my $text = $markup->process_enumeration($text, %opts);
my $text = $markup->process_paragraph($text, %opts);
my $text = $markup->process_smart($text, %opts);
# Virtual methods for subclasses to implement
my $text = $markup->generate_divider();
my $text = $markup->generate_itemize(@items);
my $text = $markup->generate_enumeration(@items);
my $text = $markup->generate_paragraph($text);
my $text = $markup->generate_bold($text);
my $text = $markup->generate_italic($text)
my $text = $markup->generate_monospace($text);
my $text = $markup->generate_link($text, $url);
my $text = $markup->escape($text);
DESCRIPTION
This module provides an interface for converting smarttext markup into
an arbitrary text based markup language, such as HTML, Latex, or Troff.
SMARTTEXT MARKUP
Smarttext markup can be split into two categories, block level and
inline. Block level elements are separated by one or more completely
blank lines. Inline elements encompass one or more words within a
block. Valid inline markup is:
*foo* - Puts the word 'foo' in bold face
/foo/ - Puts the word 'foo' in italic face
=foo= - Puts the word 'foo' in fixed width face
@foo(bar) - Makes the word 'foo' a link to the url 'bar'
There are six pre-defined entities
(C) - Insert copyright symbol
(TM) - Insert trademark symbol
(R) - Insert registered symbol
1/2 - insert a fraction
1/4 - insert a fraction
3/4 - insert a fraction
There are six levels of heading available
&title(Main document heading)
&subtitle(Secondary document heading)
§ion(Section heading)
&subsection(Secondary section heading)
&subsubsection(Tertiary section heading)
¶graph(Paragraph heading)
There are three special blocks. Horizontal dividing bars can be formed
using
---
___
Numbered lists using
+ item one
+ item two
+ item three
Bulleted lists using
* item one
* item two
* item three
Anything not fitting these forms is treated as a standard paragraph.
OPTIONS
All the "process_XXX" family of methods accept a number of options
which control which pieces of markup are permitted in the text. The
following options are recognised:
no_links
no_symbols
no_lists
no_rules
no_inline
To use this options pass them as a named parameter:
$markup->process($text, no_links => 1, no_lists => 1);
SUBCLASSING
This module provides the basic parsing routines and framework for
outputting text, however, it must be subclassed to generate the markup
language specific tags. The primary subclass is Text::Smart::HTML which
is used to generate HTML markup.
METHODS
The 'generate_XXX' methods are virtual and need to be implemented by
subclasses.
my $proc = Text::Smart->new();
Create a new smart text processor. This constructor would not
normally be called by application code, since this module must be
sub-classed to be useful. The primary subclass is for generating
HTML, Text::Smart::HTML.
my $markup = $proc->process($text)
Converts a piece of smart text, passed in as the parameter into the
target markup language of this processor. The markedup text is
returned
my $markup = $proc->generate_divider()
Called to generate a horizontal section divider. The generated text
must be returned in string format. This method must be implemented
by subclasses.
my $markup = $proc->generate_itemize(@items)
Called to generate an itemized list of bullet points. The (already
marked up) text for each item is passed as a list of parameters.
The generated text must be returned in string format. This method
must be implemented by subclasses.
my $markup = $proc->generate_enumeration(@items)
Called to generate an itemized list of numbered points. The
(already marked up) text for each item is passed as a list of
parameters. The generated text must be returned in string format.
This method must be implemented by subclasses.
my $markup = $proc->generate_paragraph($text)
Called to generate a paragraph of text. The (already marked up)
text for the body of the paragraph is passed in as the only
parameter. The generated text must be returned in string format.
This method must be implemented by subclasses.
my $markup = $proc->generate_bold($text)
Called to generate bold text. The plain text is passed in as the
parameter, and the marked up text should be returned in string
format. This method must be implemented by subclasses.
my $markup = $proc->generate_italic($text)
Called to generate italic text. The plain text is passed in as the
parameter, and the marked up text should be returned in string
format. This method must be implemented by subclasses.
my $markup = $proc->generate_monospace($text)
Called to generate fixed-width text. The plain text is passed in as
the parameter, and the marked up text should be returned in string
format. This method must be implemented by subclasses.
my $markup = $proc->generate_link($url, $text)
Called to generate a hyperlink. The destination of the link is the
first parameter, and the text being linked is the second parameter.
The marked up text must be returned in string format. This method
must be implemented by subclasses.
my $markup = $proc->generate_entity($name);
Called to generated a special named entity. There are 6 named
entities which need to be supported:
fraction12
The fraction 1/2
fraction14
The fraction 1/4
fraction 34
The fraction 3/4
copyright
The copyright symbol
trademark
The trademark symbol
registered
The rights registered symbol
The markup corresponding to the specified entity must be returned
in string format.
my $text = $proc->escape($text)
Called to escape any characters which have special meaning in the
destination markup language. For example, in HTML, this would
escape angle brackets and the ampersand symbol. The escaped text
must be returned in string format.
AUTHORS
Daniel Berrange <dan@berrange.com>
COPYRIGHT
Copyright (C) 2000-2004 Daniel P. Berrange <dan@berrange.com>
SEE ALSOperl(1)perl v5.14.1 2008-02-23 Text::Smart(3)
