new( [%options] )¶

Instantiates a new Text::Textile object. Optional optionscan be passed to initialize the object. Attributes for theoptions key are the same as the get/set method namesdocumented here.

set( $attribute, $value )¶

Used to set Textile attributes. Attribute names are the sameas the get/set method names documented here.

get( $attribute )¶

Used to get Textile attributes. Attribute names are the sameas the get/set method names documented here.

disable_html( [$disable] )¶

Gets or sets the "disable html" control, which allows you toprevent HTML tags from being used within the text processed.Any HTML tags encountered will be removed if disable html isenabled. Default behavior is to allow HTML.

flavor( [$flavor] )¶

Assigns the HTML flavor of output from Text::Textile. Currentlythese are the valid choices: html, xhtml (behaves like "xhtml1"),xhtml1, xhtml2. Default flavor is "xhtml1".

Note that the xhtml2 flavor support is experimental and incomplete(and will remain that way until the XHTML 2.0 draft becomes aproper recommendation).

css( [$css] )¶

Gets or sets the CSS support for Textile. If CSS is enabled,Textile will emit CSS rules. You may pass a 1 or 0 to enableor disable CSS behavior altogether. If you pass a hashref,you may assign the CSS class names that are used byText::Textile. The following key names for such a hash arerecognized:

class_align_right

defaults to "right"

class_align_left

defaults to "left"

class_align_center

defaults to "center"

class_align_top

defaults to "top"

class_align_bottom

defaults to "bottom"

class_align_middle

defaults to "middle"

class_align_justify

defaults to "justify"

class_caps

defaults to "caps"

class_footnote

defaults to "footnote"

id_footnote_prefix

defaults to "fn"

charset( [$charset] )¶

Gets or sets the character set targeted for publication.At this time, Text::Textile only changes its behaviorif the "utf-8" character set is assigned.

Specifically, if utf-8 is requested, any special characterscreated by Textile will be output as native utf-8 charactersrather than HTML entities.

docroot( [$path] )¶

Gets or sets the physical file path to root of document files.This path is utilized when images are referenced and sizecalculations are needed (the Image::Size module is used to readthe image dimensions).

trim_spaces( [$trim] )¶

Gets or sets the "trim spaces" control flag. If enabled, thiswill clear any lines that have only spaces on them (the newlineitself will remain).

preserve_spaces( [$preserve] )¶

Gets or sets the "preserve spaces" control flag. If enabled, thiswill replace any double spaces within the paragraph data with the&#8195; HTML entity (wide space). The default is 0. Spaces willpass through to the browser unchanged and render as a single space.Note that this setting has no effect on spaces within "<pre>", "<code>" or "<script>".

filter_param( [$data] )¶

Gets or sets a parameter that is passed to filters.

filters( [\%filters] )¶

Gets or sets a list of filters to make available forText::Textile to use. Returns a hash reference of the currentlyassigned filters.

char_encoding( [$encode] )¶

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

disable_encode_entities( $boolean )¶

Gets or sets the disable encode entities logical flag. If thisvalue is set to true no entities are encoded at all. Thisalso supersedes the "char_encoding" flag.

handle_quotes( [$handle] )¶

Gets or sets the "smart quoting" control flag. Returns thecurrent setting.

process( $str )¶

Alternative method for invoking the textile method.

textile( $str )¶

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

format_paragraph( [$args] )¶

Processes a single paragraph. The following attributes areallowed:

text

The text to be processed.

format_inline( [%args] )¶

Processes an inline string (plaintext) for Textile syntax.The following attributes are allowed:

text

The text to be processed.

format_macro( %args )¶

Responsible for processing a particular macro. Arguments passedinclude:

pre

open brace character

post

close brace character

macro

the macro to be executed

The return value from this method would be the replacementtext for the macro given. If the macro is not defined, it willreturn pre + macro + post, thereby preserving the originalmacro string.

format_cite( %args )¶

Processes text for a citation tag. The following attributesare allowed:

pre

Any text that comes before the citation.

text

The text that is being cited.

cite

The URL of the citation.

post

Any text that follows the citation.

format_code( %args )¶

Processes '@...@' type blocks (code snippets). The followingattributes are allowed:

text

The text of the code itself.

lang

The language (programming language) for the code.

format_classstyle( $clsty, $class, $style )¶

Returns a string of tag attributes to accommodate the class,style and symbols present in $clsty.

$clsty is checked for:

"{...}"

style rules. If present, they are appended to $style.

"(...#...)"

class and/or ID name declaration

"(" (one or more)

pad left characters

")" (one or more)

pad right characters

"[ll]"

language declaration

The attribute string returned will contain any combinationof class, id, style and/or lang attributes.

format_tag( %args )¶

Constructs an HTML tag. Accepted arguments:

tag

the tag to produce

text

the text to output inside the tag

pre

text to produce before the tag

post

text to produce following the tag

clsty

class and/or style attributes that should be assigned to the tag.

format_list( %args )¶

Takes a Textile formatted list (numeric or bulleted) andreturns the markup for it. Text that is passed in requiressubstantial parsing, so the format_list method is a littleinvolved. But it should always produce a proper orderedor unordered list. If it cannot (due to misbalanced input),it will return the original text. Arguments accepted:

text

The text to be processed.

format_block( %args )¶

Processes "==xxxxx==" type blocks for filters. A filterwould follow the open "==" sequence and is specified withinpipe characters, like so:

    ==|filter|text to be filtered==

You may specify multiple filters in the filter portion ofthe string. Simply comma delimit the filters you desireto execute. Filters are defined using the filters method.

format_link( %args )¶

Takes the Textile link attributes and transforms them intoa hyperlink.

format_url( %args )¶

Takes the given $url and transforms it appropriately.

format_span( %args )¶

format_image( %args )¶

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.

Arguments you may pass:

src

The "src" (URL) for the image. This may be a local path,ideally starting with a "/". Images can be located withinthe file system if the docroot method is used to specifywhere the docroot resides. If the image can be found, theimage_size method is used to determine the dimensions ofthe image.

extra

Additional parameters for the image. This would includealt text, height/width specification or scaling instructions.

align

Alignment attribute.

pre

Text to produce prior to the tag.

post

Text to produce following the tag.

link

Optional URL to connect with the image tag.

clsty

Class and/or style attributes.

format_table( %args )¶

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

apply_filters( %args )¶

The following attributes are allowed:

text

The text to be processed.

filters

An array reference of filter names to run for the given text.

encode_html( $html, $can_double_encode )¶

Encodes input $html string, escaping characters as needed to HTML entities. This relies on the HTML::Entities package for full effect. If unavailable, encode_html_basic is used as a fallback technique. If the "char_encoding" flag is set to false, encode_html_basic is used exclusively.

decode_html( $html )¶

Decodes HTML entities in $html to their natural character equivelants.

encode_html_basic( $html, $can_double_encode )¶

Encodes the input $html string for the following characters: <, >, & and ". If $can_double_encode is true, all ampersand characters are escaped even if they already were. If $can_double_encode is false, ampersands are only escaped when they aren't part of a HTML entity already.

image_size( $file )¶

Returns the size for the image identified in $file. This method relies upon the Image::Size Perl package. If unavailable, image_size will return undef. Otherwise, the expected return value is a list of the width and height (in that order), in pixels.

encode_url( $str )¶

Encodes the query portion of a URL, escaping charactersas necessary.

mail_encode( $email )¶

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

process_quotes( $str )¶

Processes string, formatting plain quotes into curly quotes.

default_macros¶

Returns a hashref of macros that are assigned to be processed bydefault within the format_inline method.

_halign( $alignment )¶

Returns the alignment keyword depending on the symbol passed.

"<>"

becomes "justify"

"<"

becomes "left"

">"

becomes "right"

"="

becomes "center"

_valign( $alignment )¶

Returns the alignment keyword depending on the symbol passed.

"^"

becomes "top"

"~"

becomes "bottom"

"-"

becomes "middle"

_imgalign( $alignment )¶

Returns the alignment keyword depending on the symbol passed.The following alignment symbols are recognized, and givenpreference in the order listed:

"^"

becomes "top"

"~"

becomes "bottom"

"-"

becomes "middle"

"<"

becomes "left"

">"

becomes "right"

_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 preservedstring.

_tokenize( $str )¶

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

_css_defaults¶

Sets the default CSS names for CSS controlled markup. Thisis an internal function that should not be called directly.

_strip_borders( $pre, $post )¶

This utility routine will take "border" characters off ofthe given $pre and $post strings if they match one of these conditions:

    $pre starts with "[", $post ends with "]"
    $pre starts with "{", $post ends with "}"

If neither condition is met, then the $pre and $post values are left untouched.

Extended Blocks¶

Normally, a block ends with the first blank line encountered.However, there are situations where you may want a block to continuefor multiple paragraphs of text. To cause a given block signatureto stay active, use two periods in your signature instead of one.This will tell Textile to keep processing using that signatureuntil it hits the next signature is found.

For example:

    bq.. This is paragraph one of a block quote.
    This is paragraph two of a block quote.
    p. Now we're back to a regular paragraph.

You can apply this technique to any signature (although forsome it doesn't make sense, like "h1" for example). This isespecially useful for "bc" blocks where your code mayhave many blank lines scattered through it.

Escaping¶

Sometimes you want Textile to just get out of the way andlet you put some regular HTML markup in your document. Youcan disable Textile formatting for a given block using the "=="escape mechanism:

    p. Regular paragraph
    ==
    Escaped portion -- will not be formatted
    by Textile at all
    ==
    p. Back to normal.

You can also use this technique within a Textile block,temporarily disabling the inline formatting functions:

    p. This is ==*a test*== of escaping.

Inline Formatting¶

Formatting within a block of text is covered by the "inline"formatting rules. These operators must be placed up againsttext/punctuation to be recognized. These include:

*"strong"*

Translates into <strong>strong</strong>.

"_emphasis_"

Translates into <em>emphasis</em>.

**"bold"**

Translates into <b>bold</b>.

"__italics__"

Translates into <i>italics</i>.

"++bigger++"

Translates into <big>bigger</big>.

"--smaller--"

Translates into: <small>smaller</small>.

"-deleted text-"

Translates into <del>deleted text</del>.

"+inserted text+"

Translates into <ins>inserted text</ins>.

"^superscript^"

Translates into ^superscript.

"~subscript~"

Translates into _subscript.

"%span%"

Translates into <span>span</span>.

"@code@"

Translates into <code>code</code>. Notethat within a "@...@" section, < and > aretranslated into HTML entities automatically.

Inline formatting operators accept the following modifiers:

"{style rule}"

A CSS style rule.

"[ll]"

A language identifier (for a "lang" attribute).

"(class)" or "(#id)" or "(class#id)"

For CSS class and id attributes.

Examples

    Textile is *way* cool.
    Textile is *_way_* cool.

Now this won't work, because the formattingcharacters need whitespace before and afterto be properly recognized.

    Textile is way c*oo*l.

However, you can supply braces or brackets tofurther clarify that you want to format, sothis would work:

    Textile is way c[*oo*]l.

Footnotes¶

You can create footnotes like this:

    And then he went on a long trip[1].

By specifying the brackets with a number inside, Textile willrecognize that as a footnote marker. It will replace that witha construct like this:

    And then he went on a long
    trip<sup class="footnote"><a href="#fn1">1</a></sup>

To supply the content of the footnote, place it at the end of yourdocument using a "fn" block signature:

    fn1. And there was much rejoicing.

Which creates a paragraph that looks like this:

    <p class="footnote" id="fn1"><sup>1</sup> And there was
    much rejoicing.</p>

Links¶

Textile defines a shorthand for formatting hyperlinks.The format looks like this:

    "Text to display":http://example.com

In addition to this, you can add "title" text to your link:

    "Text to display (Title text)":http://example.com

The URL portion of the link supports relative paths as wellas other protocols like ftp, mailto, news, telnet, etc.

    "E-mail me please":mailto:someone@example.com

You can also use single quotes instead of double-quotes ifyou prefer. As with the inline formatting rules, a hyperlinkmust be surrounded by whitespace to be recognized (anexception to this is common punctuation which can resideat the end of the URL). If you have to place a URL next tosome other text, use the bracket or brace trick to do that:

    You["gotta":http://example.com]seethis!

Textile supports an alternate way to compose links. You canoptionally create a lookup list of links and refer to themseparately. To do this, place one or more links in a blockof it's own (it can be anywhere within your document):

    [excom]http://example.com
    [exorg]http://example.org

For a list like this, the text in the square brackets isused to uniquely identify the link given. To refer to thatlink, you would specify it like this:

    "Text to display":excom

Once you've defined your link lookup table, you can usethe identifiers any number of times.

Images¶

Images are identified by the following pattern:

    !/path/to/image!

Image attributes may also be specified:

    !/path/to/image 10x20!

Which will render an image 10 pixels wide and 20 pixels high.Another way to indicate width and height:

    !/path/to/image 10w 20h!

You may also redimension the image using a percentage.

    !/path/to/image 20%x40%!

Which will render the image at 20% of it's regular widthand 40% of it's regular height.

Or specify one percentage to resize proprotionately:

    !/path/to/image 20%!

Alt text can be given as well:

    !/path/to/image (Alt text)!

The path of the image may refer to a locally hosted image orcan be a full URL.

You can also use the following modifiers after the opening "!"character:

"<"

Align the image to the left (causes the image to float ifCSS options are enabled).

">"

Align the image to the right (causes the image to float ifCSS options are enabled).

"-" (dash)

Aligns the image to the middle.

"^"

Aligns the image to the top.

"~" (tilde)

Aligns the image to the bottom.

"{style rule}"

Applies a CSS style rule to the image.

"(class)" or "(#id)" or "(class#id)"

Applies a CSS class and/or id to the image.

"(" (one or more)

Pads 1em on the left for each "(" character.

")" (one or more)

Pads 1em on the right for each ")" character.

Character Replacements¶

A few simple, common symbols are automatically replaced:

    (c)
    (r)
    (tm)

In addition to these, there are a whole set of charactermacros that are defined by default. All macros are enclosedin curly braces. These include:

    {c|} or {|c} cent sign
    {L-} or {-L} pound sign
    {Y=} or {=Y} yen sign

Many of these macros can be guessed. For example:

    {A'} or {'A}
    {a"} or {"a}
    {1/4}
    {*}
    {:)}
    {:(}

Lists¶

Textile also supports ordered and unordered lists.You simply place an asterisk or pound sign, followedwith a space at the start of your lines.

Simple lists:

    * one
    * two
    * three

Multi-level lists:

    * one
    ** one A
    ** one B
    *** one B1
    * two
    ** two A
    ** two B
    * three

Ordered lists:

    # one
    # two
    # three

Styling lists:

    (class#id)* one
    * two
    * three

The above sets the class and id attributes for the <ul>tag.

    *(class#id) one
    * two
    * three

The above sets the class and id attributes for the first <li>tag.

Definition lists:

    dl. textile:a cloth, especially one manufactured by weaving
    or knitting; a fabric
    format:the arrangement of data for storage or display.

Note that there is no space between the term and definition. Theterm must be at the start of the line (or following the "dl"signature as shown above).

Tables¶

Textile supports tables. Tables must be in their own block andmust have pipe characters delimiting the columns. An optionalblock signature of "table" may be used, usually for applyingstyle, class, id or other options to the table element itself.

From the simple:

    |a|b|c|
    |1|2|3|

To the complex:

    table(fig). {color:red}_|Top|Row|
    {color:blue}|/2. Second|Row|
    |_{color:green}. Last|

Modifiers can be specified for the table signature itself,for a table row (prior to the first "|" character) andfor any cell (following the "|" for that cell). Note that forcells, a period followed with a space must be placed afterany modifiers to distinguish the modifier from the cell content.

Modifiers allowed are:

"{style rule}"

A CSS style rule.

"(class)" or "(#id)" or "(class#id)"

A CSS class and/or id attribute.

"(" (one or more)

Adds 1em of padding to the left for each "(" character.

")" (one or more)

Adds 1em of padding to the right for each ")" character.

"<"

Aligns to the left (floats to left for tables if combined with the")" modifier).

">"

Aligns to the right (floats to right for tables if combined withthe "(" modifier).

"="

Aligns to center (sets left, right margins to "auto" for tables).

"<>"

For cells only. Justifies text.

"^"

For rows and cells only. Aligns to the top.

"~" (tilde)

For rows and cells only. Aligns to the bottom.

"_" (underscore)

Can be applied to a table row or cell to indicate a headerrow or cell.

"\2" or "\3" or "\4", etc.

Used within cells to indicate a colspan of 2, 3, 4, etc. columns.When you see "\", think "push forward".

"/2" or "/3" or "/4", etc.

Used within cells to indicate a rowspan or 2, 3, 4, etc. rows.When you see "/", think "push downward".

When a cell is identified as a header cell and an alignmentis specified, that becomes the default alignment forcells below it. You can always override this behavior byspecifying an alignment for one of the lower cells.

CSS Notes¶

When CSS is enabled (and it is by default), CSS class namesare automatically applied in certain situations.

Aligning a block or span or other element to left, right, etc.

"left" for left justified, "right" for right justified,"center" for centered text, "justify" for full-justifiedtext.

Aligning an image to the top or bottom

"top" for top alignment, "bottom" for bottom alignment,"middle" for middle alignment.

Footnotes

"footnote" is applied to the paragraph tag for thefootnote text itself. An id of "fn" plus the footnotenumber is placed on the paragraph for the footnote aswell. For the footnote superscript tag, a class of"footnote" is used.

Capped text

For a series of characters that are uppercased, aspan is placed around them with a class of "caps".

Miscellaneous¶

Textile tries to do it's very best to ensure proper XHTMLsyntax. It will even attempt to fix errors you may introducewriting in HTML yourself. Unescaped "&" characters withinURLs will be properly escaped. Singlet tags such as br, imgand hr are checked for the "/" terminator (and it's addedif necessary). The best way to make sure you produce validXHTML with Textile is to not use any HTML markup at all--use the Textile syntax and let it produce the markup for you.