NAME

Text::Textile

SYNOPSIS

use Text::Textile qw(textile);
my $text = <<EOT;
h1. Heading

A _simple_ demonstration of Textile markup.

* One
* Two
* Three

"More information":http://www.textism.com/tools/textile is available.
EOT

# procedural usage
my $html = textile($text);
print $html;

# OOP usage
my $textile = new Text::Textile;
$html = $textile->process($text);
print $html;

ABSTRACT

Text::Textile is a Perl-based implementation of Dean Allen's Textile syntax. Textile is shorthand for doing common formatting tasks.

METHODS

• new

  Instantiates a new Text::Textile object.

• process( $str )

  Alternative method for invoking textile().

• flavor( $flavor )

  Assigns the HTML flavor of output from Text::Textile. Currently these are the valid choices: html, xhtml (behaves like 'xhtml1'), xhtml1, xhtml2.

• charset( $charset )

  Assigns the character set targetted for publication. At this time, Text::Textile only changes it's behavior if the 'utf-8' character set is assigned.

• docroot( $path )

  Physical file path to root of document files. This path is utilized when images are referenced and size calculations are needed (the Image::Size module is used to read the image dimensions).

• char_encoding( $encode )

  Assigns the character encoding logical flag. If character encoding is enabled, the HTML::Entities package is used to encode special characters. If character encoding is disabled, only <, >, " and & are encoded to HTML entities.

• filter_param( $data )

  Stores a parameter that may be passed to any filter.

• named_filters( \%filters )

  Optional %filters parameter assigns the list of named filters to make available for Text::Textile to use. Returns a hash reference of the currently assigned filters.

• text_filters( \@filters )

  Optional @filters parameter assigns the textual filters for Text::Textile to use. Returns an array reference of the currently assigned text filters.

• textile( $str )

  Can be called either procedurally or as a method. Transforms $str using Textile markup rules.

• format_paragraph( $str )

  Processes a single paragraph.

• format_inline( $str )

  Processes an inline element (plaintext) for Textile syntax.

• apply_text_filters( $str )

  Applies all the textual filters to $str.

• apply_named_filters( $str, \@list )

  Applies all the filters identified in @list to $str.

• format_tag( $tag, $pre, $text, @rest )

  Returns a constructed tag using the pieces given.

• format_list( $str )

  Takes a Textile formatted list (numeric or bulleted) and returns the markup for it.

• format_code( $code, $lang )

  Processes '@...@' type blocks (code snippets).

• format_block( $str )

  Processes '==xxxxx==' type blocks for filters.

• format_link( $text, $title, $url )

  Takes the Textile link attributes and transforms them into a hyperlink.

• format_url( $url )

  Takes the given $url and transforms it appropriately.

• mail_encode( $email )

  Encodes the email address in $email for 'mailto:' links.

• format_image( $src, $extra, $url, $class )

  Returns markup for the given image. $src is the location of the image, $extra contains the optional height/width and/or alt text. $url is an optional hyperlink for the image. $class holds the optional CSS class attribute.

• image_size( $src )

  Returns the size for the image identified in $src.

• format_table( $str )

  Takes a Wiki-ish string of data and transforms it into a full table.

• _repl( \@arr, $str )

  An internal routine that takes a string and appends it to an array. It returns a marker that is used later to restore the preserved string.

• _tokenize( $str )

  An internal routine responsible for breaking up a string into individual tag and plaintext elements.

SYNTAX

The formatting options of Textile are simple to understand, but difficult to master.

Textile looks at things in terms of paragraphs and lines.

LICENSE

Please see the file LICENSE that was included with this module.

AUTHOR & COPYRIGHT

Text::Textile was written by Brad Choate, brad@bradchoate.com, and converted to a CPAN module by Tom Insam, tom@jerakeen.org. It is an adaptation of Textile, developed by Dean Allen of Textism.com.