Class: Parser

Textile parser.

The Parser class takes Textile input and
converts it to well formatted HTML. This is
the library's main class, hosting the parsing
functionality and exposing a simple
public interface for you to use.

The most basic use case would involve initialising
a instance of the class and calling the textileThis
method, parsing the given Textile input in unrestricted
mode.

<code>
$parser = new \Netcarver\Textile\Parser();
echo $parser->textileThis('h1. Hello World!');
</code>

__construct($doctype = 'xhtml')  line: 860

Constructor. The constructor allows setting options that affect the class instance as a whole, such as the output doctype. To instruct the parser to return HTML5 markup instead of XHTML, set $doctype argument to 'html5'. <code> $parser = new \Netcarver\Textile\Parser('html5'); echo $parser->textileThis('HTML(HyperText Markup Language)"); </code> param: string $doctype The output document type, either 'xhtml' or 'html5'

setSymbol($name, $value)  line: 954

Defines a substitution symbol. Call this you need to redefine a substitution symbol to be used when parsing a Textile document. return: Parser param: string $name  Name of the symbol to assign a new value to. param: string $value New value for the symbol.

getSymbol($name = null)  line: 973

Gets a symbol definitions. This method can be used to get a symbol definition, or an array containing the full symbol table. return: array|string The symbol table or the requested symbol param: string|null  $name The name of the symbol, or NULL if requesting the symbol table

setRelativeImagePrefix($prefix = '')  line: 998

Sets base image directory path. This is used when Textile is supplied with a relative image path. Allows client systems to have PHP-Textile convert relative image paths to absolute or prefixed paths. This method is used to set that base path, usually a absolute HTTP address pointing to a directory. <code> $parser = new \Netcarver\Textile\Parser(); $parser->setRelativeImagePrefix('http://static.example.com/'); </code> return: Parser param: string $prefix  The string to prefix all relative image paths with

setDimensionlessImages($dimensionless = true)  line: 1022

Toggles image dimension attributes. If $dimensionless is set to TRUE, image width and height attributes will not be included in rendered image tags. Normally, Textile will add dimensions height images that specify a relative path, as long as the image file can be accessed. <code> $parser = new \Netcarver\Textile\Parser(); echo $parser->setDimensionlessImages(false)->textileThis('Hello World!'); </code> return: Parser param: bool   $dimensionless TRUE to disable image dimensions, FALSE to enable

getDimensionlessImages()  line: 1046

Whether images will get dimensions or not. This method will return the state of the state of the $dimensionless_images property. <code> $parser = new \Netcarver\Textile\Parser(); if ($parser->getDimensionlessImages() === true) { echo 'Images do not get dimensions.'; } </code> return: bool TRUE if images will not get dimensions, FALSE otherwise

getVersion()  line: 1069

Gets Textile version number. <code> $parser = new \Netcarver\Textile\Parser(); echo $parser->getVersion(); </code> return: string Version

textileEncode($text)  line: 1086

Encodes the given text. <code> $parser = new \Netcarver\Textile\Parser(); $parser->textileEncode('Some content to encode.'); </code> return: string The encoded text param: string $text The text to be encoded

textileThis($text, $lite = false, $encode = false, $noimage = false, $strict = false, $rel = '')  line: 1106

Parses the given Textile input in un-restricted mode. This method should be used to parse any trusted Textile input, such as articles created by well-known authorised users. This method allows users to mix raw HTML and Textile. If you want to parse untrusted input, see the textileRestricted method instead. Using this less restrictive method on untrusted input, like comments and forum posts, will lead to XSS issues, as users will be able to use any HTML code, JavaScript links and Textile attributes in their input. <code> $parser = new \Netcarver\Textile\Parser(); echo $parser->textileThis('h1. Hello World!'); </code> return: string Parsed $text param: string $text    The Textile input to parse param: bool   $lite    Switch to lite mode param: bool   $encode  Encode input and return param: bool   $noimage Disables images param: bool   $strict  This argument is ignored param: string $rel     Relationship attribute applied to generated links

textileRestricted($text, $lite = true, $noimage = true, $rel = 'nofollow')  line: 1153

Parses the given Textile input in restricted mode. This method should be used for any untrusted user input, including comments or forum posts. This method escapes any raw HTML input, ignores unsafe attributes, links only whitelisted URL schemes and by default also prevents the use of images and extra Textile formatting, accepting only paragraphs and blockquotes as valid block tags. <code> $parser = new \Netcarver\Textile\Parser(); echo $parser->textileRestricted('h1. Hello World!'); </code> return: string Parsed $text param: string $text    The Textile input to parse param: bool   $lite    Controls lite mode, allowing extra formatting param: bool   $noimage Allow images param: string $rel     Relationship attribute applied to generated links

textileCommon($text, $lite)  line: 1191

Parses Textile syntax. This method performs common parse actions. return: string Parsed input param: string $text The input to parses param: bool   $lite Controls lite mode

prepGlyphs()  line: 1234

Prepares the glyph patterns from the symbol table.

getMaxLinkIndex()  line: 1356

Sets the maximum allowd link index. return: int

prepare($lite, $noimage, $rel)  line: 1368

Prepares the parser for parsing. This method prepares the transient internal state of Textile parser in preparation for parsing a new document. param: bool   $lite    Controls lite mode param: bool   $noimage Disallow images param: string $rel     A relationship attribute applied to links

cleanAttribs($in)  line: 1402

Cleans a HTML attribute value. This method checks for presence of URL encoding in the value. If the number encoded characters exceeds the thereshold, the input is discarded. Otherwise the encoded instances are decoded. This method also strips any ", ' and = characters from the given value. This method does not guarantee valid HTML or full sanitization. return: string Cleaned string param: string $in The input string

newTag($name, $atts, $selfclosing = true)  line: 1443

Constructs a HTML tag from an object. This is a helper method that creates a new instance of \Netcarver\Textile\Tag. return: Tag param: string $name        The HTML element name param: array  $atts        HTML attributes applied to the tag param: bool   $selfclosing Determines if the tag should be selfclosing

parseAttribs($in, $element = '', $include_id = true, $autoclass = '')  line: 1460

Parses Textile attributes. return: string HTML attribute list param: string $in         The Textile attribute string to be parsed param: string $element    Focus the routine to interpret the attributes as applying to a specific HTML tag param: bool   $include_id If FALSE, IDs are not included in the attribute list param: string $autoclass  An additional classes applied to the output

formatAttributeString(array $attribute_array)  line: 1478

Converts an array of named attribute => value mappings to a string. return: string param: array $attribute_array

parseAttribsToArray($in, $element = '', $include_id = true, $autoclass = '')  line: 1498

Parses Textile attributes into an array. return: array  HTML attributes as key => value mappings param: string $in         The Textile attribute string to be parsed param: string $element    Focus the routine to interpret the attributes as applying to a specific HTML tag param: bool   $include_id If FALSE, IDs are not included in the attribute list param: string $autoclass  An additional classes applied to the output

hasRawText($text)  line: 1677

Checks whether the text is not enclosed by a block tag. return: bool   TRUE if the text is not enclosed param: string $text The input string

tables($text)  line: 1695

Parses textile table structures into HTML. return: string The parsed text param: string $text The textile input

fTable($matches)  line: 1713

Constructs a HTML table from a textile table structure. This method is used by Parser::tables() to process found table structures. return: string HTML table param: array  $matches

redclothLists($text)  line: 1875

Parses RedCloth-style definition lists into HTML. return: string The parsed text param: string $text The textile input

fRedclothList($m)  line: 1891

Constructs a HTML definition list from a RedCloth-style definition structure. This method is used by Parser::redclothLists() to process found definition list structures. return: string HTML definition list param: array  $m

textileLists($text)  line: 1958

Parses Textile list structures into HTML. Searches for ordered, un-ordered and definition lists in the textile input and generates HTML lists for them. return: string The parsed text param: string $text The input

fTextileList($m)  line: 1977

Constructs a HTML list from a Textile list structure. This method is used by Parser::textileLists() to process found list structures. return: string HTML list param: array  $m

liType($in)  line: 2077

Determines the list type from the Textile input symbol. return: string Either 'd', 'o', 'u' param: string $in Textile input containing the possible list marker

doTagBr($tag, $in)  line: 2094

Adds br tags within the specified container tag. return: string param: string $tag The tag param: string $in  The input

doPBr($in)  line: 2111

Adds br tags to paragraphs and headings. return: string param: string $in The input

fPBr($m)  line: 2127

Less restrictive version of fBr method. Used only in paragraphs and headings where the next row may start with a smiley or perhaps something like '#8 bolt...' or '*** stars...'. return: string param: string $m The input

fBr($m)  line: 2152

Formats line breaks. return: string param: string $m The input

blocks($text)  line: 2165

Splits the given input into blocks. Blocks are separated by double line-break boundaries, and processed the blocks one by one. return: string Input text with blocks processed param: string $text Textile source text

fBlock($m)  line: 2270

Formats the given block. Adds block tags and formats the text content inside the block. return: array param: string $m The block content to format

formatFootnote($marker, $atts = '', $anchor = true)  line: 2374

Formats a footnote. return: string Processed footnote param: string $marker The marker param: string $atts   Attributes param: bool   $anchor TRUE, if its a reference link

replaceMarkers($text, $replacements)  line: 2389

Replaces markers with replacements in the given input. return: string param: string $text         The input param: array  $replacements Marker replacement pairs

getHTMLComments($text)  line: 2407

Parses HTML comments in the given input. This method finds HTML comments in the given input and replaces them with reference tokens. return: string $text Processed input param: string $text Textile input

fParseHTMLComments($m)  line: 2427

Formats a HTML comment. Stores the comment on the shelf and returns a reference token wrapped in to a HTML comment. return: string Reference token wrapped to a HTML comment tags param: array  $m Options

graf($text)  line: 2442

Parses paragraphs in the given input. return: string Processed input param: string $text Textile input

spans($text)  line: 2501

Replaces Textile span tags with their equivalent HTML inline tags. return: string The Textile document with spans replaced by their HTML inline equivalents param: string $text The Textile document to perform the replacements in

fSpan($m)  line: 2538

Formats a span tag and stores it on the shelf. return: string Content wrapped to reference tokens param: array  $m Options

storeTags($opentag, $closetag = '')  line: 2570

Stores a tag pair in the tag cache. return: array  Reference tokens for both opening and closing tag param: string $opentag  Opening tag param: string $closetag Closing tag

retrieveTags($text)  line: 2593

Replaces reference tokens with corresponding shelved span tags. This method puts all shelved span tags back to the final, parsed input. return: string Processed text param: string $text The input

fRetrieveTags($m)  line: 2621

Retrieves a tag from the tag cache. return: string param: array $m Options

placeNoteLists($text)  line: 2634

Parses note lists in the given input. This method should be ran after other blocks have been processed, but before reference tokens have been replaced with their replacements. return: string Processed input param: string $text Textile input

fNoteLists($m)  line: 2680

Formats a note list. return: string Processed note list param: array  $m Options

makeBackrefLink(&$info, $g_links, $i)  line: 2733

Renders a note back reference link. This method renders an array of back reference links for notes. return: string Processed input param: array  $info    Options param: string $g_links Reference type param: int    $i       Instance count

fParseNoteDefs($m)  line: 2780

Formats note definitions. This method formats notes and stores them in note cache for later use and to build reference links. return: string Empty string param: array  $m Options

noteRefs($text)  line: 2814

Parses note references in the given input. This method replaces note reference tags with links. return: string param: string $text Textile input

fParseNoteRefs($m)  line: 2834

Formats note reference links. By the time this function is called, all note lists will have been processed into the notes array, and we can resolve the link numbers in the order we process the references. return: string Note reference param: array  $m Options

parseURI($uri, &$m)  line: 2882

Parses URI into component parts. This method splits a URI-like string apart into component parts, while also providing validation. return: bool   TRUE if the string validates as a URI param: string $uri The string to pick apart (if possible) param: array  $m   Reference to an array the URI component parts are assigned to

addPart(&$mask, $name, &$parts)  line: 2906

Checks whether a component part can be added to a URI. return: bool   TRUE if the component can be added param: array  $mask  An array of allowed component parts param: string $name  The component to add param: array  $parts An array of existing components to modify

rebuildURI($parts, $mask = 'scheme,authority,path,query,fragment', $encode = true)  line: 2920

Rebuild a URI from parsed parts and a mask. return: string         The rebuilt URI param: array  $parts  Full array of URI parts param: string $mask   Comma separated list of URI parts to include in the rebuilt URI param: bool   $encode Flag to control encoding of the path part of the rebuilt URI

links($text)  line: 2971

Parses and shelves links in the given input. This method parses the input Textile document for links. Formats and encodes them, and stores the created link elements in cache. return: string The input document with link pulled out and replaced with tokens param: string $text Textile input

markStartOfLinks($text)  line: 2988

Finds and marks the start of well formed links in the input text. return: string Text with links marked param: string $text String to search for link starting positions

replaceLinks($text)  line: 3106

Replaces links with tokens and stores them on the shelf. return: string Processed input param: string $text The input

fLink($m)  line: 3132

Formats a link and stores it on the shelf. return: string Reference token for the shelved content param: array  $m Options

getRefs($text)  line: 3340

Finds URI aliases within the given input. This method finds URI aliases in the Textile input. Links are stored in an internal cache, so that they can be referenced from any link in the document. This operation happens before the actual link parsing takes place. return: string The Textile document with any URI aliases removed param: string $text Textile input

refs($m)  line: 3369

Parses, encodes and shelves the current URI alias. return: string Empty string param: array $m Options

shelveURL($text)  line: 3386

Shelves parsed URLs. Stores away a URL fragments that have been parsed and requires no more processing. return: string The fragment's unique reference ID param: string $text The URL

retrieveURLs($text)  line: 3407

Replaces reference tokens with corresponding shelved URL. This method puts all shelved URLs back to the final, parsed input. return: string Processed text param: string $text The input

retrieveURL($m)  line: 3423

Retrieves an URL from the shelve. return: string The URL param: array  $m Options

relURL($url)  line: 3444

Completes and formats a URL. return: string param: string $url The URL

isRelURL($url)  line: 3464

Checks if an URL is relative. The given URL is considered relative if it doesn't contain scheme and hostname. return: bool   TRUE if relative, FALSE otherwise param: string $url The URL

images($text)  line: 3480

Parses and shelves images in the given input. This method parses the input Textile document for images and generates img HTML tags for each one found, caching the generated img tag internally and replacing the Textile image with a token to the cached tag. return: string The input document with images pulled out and replaced with tokens param: string $text Textile input

fImage($m)  line: 3513

Formats an image and stores it on the shelf. return: string Reference token for the shelved content param: array  $m Options

code($text)  line: 3581

Parses code blocks in the given input. return: string Processed text param: string $text The input

fCode($m)  line: 3596

Formats inline code tags. return: string param: array  $m

fPre($m)  line: 3608

Formats pre tags. return: string param: array  $m Options

shelve($val)  line: 3620

Shelves parsed content. Stores away a fragment of the source text that have been parsed and requires no more processing. return: string The fragment's unique reference ID param: string $val The content

retrieve($text)  line: 3638

Replaces reference tokens with corresponding shelved content. This method puts all shelved content back to the final, parsed input. return: string Processed text param: string $text The input

cleanWhiteSpace($text)  line: 3661

Removes BOM and unifies line ending in the given input. return: string Cleaned version of the input param: string $text Input Textile

cleanUniqueTokens($text)  line: 3681

Removes any unique tokens from the input. return: string Cleaned input param: string $text The input to clean

doSpecial($text, $start, $end, $method)  line: 3694

Uses the specified callback method to format the content between end and start nodes. return: string Processed input param: string $text   The input to format param: string $start  The start node to look for param: string $end    The end node to look for param: string $method The callback method

noTextile($text)  line: 3713

Parses notextile tags in the given input. return: string Processed input param: string $text The input

fTextile($m)  line: 3726

Format notextile blocks. return: string param: array $m Options

footnoteRefs($text)  line: 3738

Parses footnote reference links in the given input. This method replaces [n] instances with links. return: string $text Processed input param: string $text The input

footnoteID($m)  line: 3758

Renders a footnote reference link or ID. return: string Footnote link, or ID param: array  $m Options

glyphQuotedQuote($text, $find = '"?|"[^"]+"')  line: 3781

Parses and shelves quoted quotes in the given input. return: string param: string $text The text to search for quoted quotes

fGlyphQuotedQuote($m)  line: 3797

Formats quoted quotes and stores it on the shelf. return: string Input with quoted quotes removed and replaced with tokens param: array  $m Named regular expression parts

glyphs($text)  line: 3835

Replaces glyphs in the given input. This method performs typographical glyph replacements. The input is split across HTML-like tags in order to avoid attempting glyph replacements within tags. return: string param: string $text Input Textile

replaceGlyphs($text)  line: 3868

Replaces glyph references in the given input. This method removes temporary glyph: instances from the input. return: string Processed input param: string $text The input

hAlign($in)  line: 3883

Translates alignment tag into corresponding CSS text-align property value. return: string CSS text-align value param: string $in The Textile alignment tag

vAlign($in)  line: 3905

Translates vertical alignment tag into corresponding CSS vertical-align property value. return: string CSS vertical-align value param: string $in The Textile alignment tag

encodeHigh($text, $charset = 'UTF-8')  line: 3923

Converts character codes in the given input from HTML numeric character reference to character code. Conversion is done according to Textile's multi-byte conversion map. return: string Processed input param: string $text    The input param: string $charset The character set

decodeHigh($text, $charset = 'UTF-8')  line: 3942

Converts numeric HTML character references to character code. return: string Processed input param: string $text    The input param: string $charset The character set

encodeHTML($str, $quotes = true)  line: 3961

Convert special characters to HTML entities. This method's functionality is identical to PHP's own htmlspecialchars(). In Textile this is used for sanitising the input. return: string Encoded string param: string $str    The string to encode param: bool   $quotes Encode quotes

rEncodeHTML($str, $quotes = true)  line: 3992

Convert special characters to HTML entities. This is identical to encodeHTML(), but takes restricted mode into account. When in restricted mode, only escapes quotes. return: string Encoded string param: string $str    The string to encode param: bool   $quotes Encode quotes

isMultiByteStringSupported()  line: 4015

Whether multiple mbstring extensions is loaded. return: bool

isUnicodePcreSupported()  line: 4031

Whether PCRE supports UTF-8. return: bool