PHP Extension for Hoedown

This extension allows Hoedown.

Requirement

PHP 5.3 +

Build

% git clone --recursive --depth=1 https://github.com/kjdev/php-ext-hoedown.git
% cd php-ext-hoedown
% phpize
% ./configure
% make
% make test
% make install

Configuration

hoedown.ini:

extension=hoedown.so
; hoedown.options=tables,fenced-code,autolink,strikethrough,no-intra-emphasis

Usage

$hoedown = new Hoedown;
echo $hoedown->parse('markdown text');

Runtime Configuration

Name	Default	Changeable
hoedown.options	tables,fenced-code,autolink,strikethrough,no-intra-emphasis	PHP_INI_ALL

hoedown.options

Set the options for default of Hoedown class. (set in the constructor before calling)
- Hoedown::TABLES
- Hoedown::FENCED_CODE
- Hoedown::AUTOLINK
- Hoedown::STRIKETHROUGH
- Hoedown::NO_INTRA_EMPHASIS

Class synopsis

Hoedown {
  public __construct(array $options = [])
  public mixed getOption(int $option)
  public bool setOption(int $option, mixed $value)
  public void setOptions(array $options = [])
  public bool addRender(string $name, callable $callback)
  public array getRenders(void)
  public string parse(string $string, mixed &$state = NULL)
  public string parseString(string $string, mixed &$state = NULL)
  public string parseFile(string $filename, mixed &$state = NULL)
  static public string ofString(string $string, array $options = [], mixed &$state = NULL)
  static public string ofFile(string $filename, array $options = [], mixed &$state = NULL)
}

Predefined Constants

Name	Type	Default	Description
Hoedown::RENDERER_HTML	bool	TRUE	Render HTML.
Hoedown::RENDERER_TOC	bool	FALSE	Render the Table of Contents in HTML.
Hoedown::SKIP_HTML	bool	FALSE	Strip all HTML tags.
Hoedown::HARD_WRAP	bool	FALSE	Render each linebreak as <br>.
Hoedown::USE_XHTML	bool	FALSE	Render XHTML.
Hoedown::ESCAPE	bool	FALSE	Escaple all HTML.
Hoedown::USE_TASK_LIST	bool	FALSE	Render task lists.
Hoedown::LINE_CONTINUE	bool	FALSE	Render line continue.
Hoedown::HEADER_ID	bool	FALSE	Render header id.
Hoedown::FENCED_CODE_SCRIPT	bool	FALSE	Render script of fenced code blocks style.
Hoedown::TABLES	bool	TRUE	Parse PHP-Markdown style tables.
Hoedown::FENCED_CODE	bool	TRUE	Parse fenced code blocks.
Hoedown::FOOTNOTES	bool	FALSE	Parse footnotes.
Hoedown::AUTOLINK	bool	TRUE	Automatically turn URLs into links.
Hoedown::STRIKETHROUGH	bool	TRUE	Parse `~~strikethrough~~` spans.
Hoedown::UNDERLINE	bool	FALSE	Parse `_underline_` instead of emphasis.
Hoedown::HIGHLIGHT	bool	FALSE	Parse `==hightlight==` spans.
Hoedown::QUOTE	bool	FALSE	Render "quotes" as <q>.
Hoedown::SUPERSCRIPT	bool	FALSE	Parse super^script.
Hoedown::NO_INTRA_EMPHASIS	bool	TRUE	Disable emphasis_between_words.
Hoedown::SPACE_HEADERS	bool	FALSE	Requqire a space after '#' in headers.
Hoedown::DISABLE_INDENTED_CODE	bool	FALSE	Don't parse indented code blocks.
Hoedown::SPECIAL_ATTRIBUTE	bool	FALSE	Parse special attributes.
Hoedown::SCRIPT_TAGS	bool	FALSE	Parse script tags `<?..?>`.
Hoedown::META_BLOCK	bool	FALSE	Parse meta block `<!--..-->`.
Hoedown::TOC	bool	FALSE	Produce links to the Table of Contents.
Hoedown::TOC_BEGIN	int	0	Begin level for headers included in the TOC.
Hoedown::TOC_END	int	6	End level for headers included in the TOC.
Hoedown::TOC_HEADER	string	""	Render header in the TOC.
Hoedown::TOC_FOOTER	string	""	Render footer in the TOC.

Methods

Hoedown::__construct - Create a Hoedown instance
Hoedown::getOption - Retrieve a Hoedown option value
Hoedown::setOption - Set Hoedown option
Hoedown::setOptions - Set Hoedown options
Hoedown::parse - retrieve html by parse string as markdown
Hoedown::parseString - retrieve html by parse string as markdown
Hoedown::parseFile - retrieve html by parse file as markdown
Hoedown::ofString - retrieve html by parse string as markdown
Hoedown::ofFile - retrieve html by parse file as markdown
Hoedown::addRender - Set Hoedown renderer function
Hoedown::getRenders - retrieve renderer function

Hoedown::__construct

public __construct(array $options = [])

Create a Hoedown instance.

Parameters:

options

An associative array of options where the key is the option to set and the value is the new value for the option.

Return Values:

Returns a new Hoedown object

Hoedown::getOption

public mixed getOption(int $option)

Retrieve a Hoedown option value.

Parameters:

option

One of the Hoedown::* constants.

Return Values:

Returns the value of the requested option, or FALSE on error.

Hoedown::setOption

public bool setOption(int $option, mixed $value)

Set Hoedown option.

Parameters:

option

One of the Hoedown::* constants.
value

Set option value.

Return Values:

Returns TRUE on success or FALSE on failure.

Hoedown::setOptions

public void setOptions(array $options = [])

Set Hoedown options.

Parameters:

options

An associative array of options where the key is the option to set and the value is the new value for the option.

Hoedown::parse

public string parse(string $string, mixed &$state = NULL)

retrieve html by parse text as markdown.

Parameters:

string

Markdown text string.
state

Returns the value of extend parse.

Return Values:

Returns the retrieve html, or FALSE on error.

Hoedown::parseString

public string parseString(string $string, mixed &$state = NULL)

retrieve html by parse string as markdown.

alias: Hoedown::parse

Hoedown::parseFile

public string parseFile(string $filename, mixed &$state = NULL)

retrieve html by parse file as markdown.

Parameters:

filename

Markdown file name.
state

Returns the value of extend parse.

Return Values:

Returns the retrieve html, or FALSE on error.

Hoedown::ofString

static public string ofString(string $string, array $options = [], mixed &$state = NULL)

retrieve html by parse string as markdown (static method).

Parameters:

string

Markdown text string.
options

An associative array of options where the key is the option to set and the value is the new value for the option.
state

Returns the value of extend parse.

Return Values:

Returns the retrieve html, or FALSE on error.

Hoedown::ofFile

static public string ofFile(string $filename, array $options = [], mixed &$state = NULL)

retrieve html by parse file as markdown (static method).

Parameters:

filename

Markdown file name.
options

An associative array of options where the key is the option to set and the value is the new value for the option.
state

Returns the value of extend parse.

Return Values:

Returns the retrieve html, or FALSE on error.

Hoedown::addRender

public bool addRender(string $name, callable $callback)

Set Hoedown renderer function.

Parameters:

name

Hoedown rederer function name.
callback

The callable to be called.

Return Values:

Returns TRUE on success or FALSE on failure.

Hoedown::getRenders

public array getRenders(void)

retrieve renderer function.

Return Values:

Returns the retrieve renderer functions, or NULL.

Examples

Setting a Hoedown option

$hoedown = new Hoedown;
$hoedown->setOption(Hoedown::USE_XHTML, true);
$hoedown->setOption(Hoedown::HARD_WRAP, true);
// or $hoedown->setOptions([Hoedown::USE_XHTML => true, Hoedown::HARD_WRAP => true]);
// or new Hoedown([Hoedown::USE_XHTML => true, Hoedown::HARD_WRAP => true]);
echo $hoedown->parse("markdown\ntext");

The above example will output:

<p>markdown<br/>
text</p>

Retrieve the Table of Contents

$hoedown = new Hoedown;
$hoedown->setOption(Hoedown::TOC, true);
echo $hoedown->parse("# header\n##a\n##b", $state);
echo "-- Table of Contents --\n";
echo $state['toc'];

The above example will output:

<h1 id="header">header</h1>

<h2 id="a">a</h2>

<h2 id="b">b</h2>
-- Table of Contents --
<ul>
<li>
<a href="#header">header</a>
<ul>
<li>
<a href="#a">a</a>
</li>
<li>
<a href="#b">b</a>
</li>
</ul>
</li>
</ul>

Only retrieve the Table of Contents.

$hoedown = new Hoedown;
$hoedown->setOption(Hoedown::TOC, true);
$hoedown->setOption(Hoedown::RENDERER_TOC, true);
echo $hoedown->parse("# header\n##a\n##b");

The above example will output:

<ul>
<li>
<a href="#header">header</a>
<ul>
<li>
<a href="#a">a</a>
</li>
<li>
<a href="#b">b</a>
</li>
</ul>
</li>
</ul>

HTML render

$hoedown = new Hoedown;

$hoedown->addRender('blockcode', function($text, $lang, $attr) {
        // Use Pygmentize
        return Pygmentize::highlight($text, $lang);
    });

// or
// function blockCode($text, $lang, $attr) {
//     return Pygmentize::highlight($text, $lang);
// }
// $hoedown->addRender('blockcode', 'blockCode');

// or
// $hoedown->setOption(Hoedown::RENDERS, [
//                         'blockcode' => function($text, $lang, $attr) {
//                             return Pygmentize::highlight($text, $lang);
//                         }]);

echo $hoedown->parse("...markdown string...");

Render functions:

blockcode($text, $lang, $attr)
blockquote($text)
blockhtml($text)
paragraph($text)
header($text, $attr, $level)
hrule()
list($text, $attr, $flags)
listitem($text, $attr, $flags)
table($text, $attr)
tableheader($text)
tablebody($text)
tablerow($text)
tablecell($text, $flags)
footnotes($text)
footnotedef($text, $num)
footnoteref($num)
codespan($text, $attr)
underline($text)
highlight($text)
quote($text)
strikethrough($text)
superscript($text)
emphasis($text)
doubleemphasis($text)
tripleemphasis($text)
autolink($link, $type)
image($link, $title, $alt, $attr)
link($content, $link, $title, $attr)
linebreak()
rawhtmltag($tag)
entity($entity)
normaltext($text)
userblock($text)

User block

simple php code.

$hoedown = new Hoedown;

$hoedown->setOption(Hoedown::USER_BLOCK, function($text) {
        // Returns the value of user block length
        if (preg_match('/^<\?php.*\?>/is', $text, $matches)) {
            return strlen($matches[0]);
        }
        return 0;
    });

echo $hoedown->parse("<?php echo 'test'; ?>"), PHP_EOL;

$hoedown->setOption(Hoedown::RENDERS, ['userblock' => function($text) {
            ob_start();
            eval(substr($text, 5, -2));
            $retval = ob_get_contents();
            ob_end_clean();
            return $retval;
        }]);

echo $hoedown->parse("<?php echo 'test'; ?>"), PHP_EOL;

output:

<?php echo "test"; ?>
test

Meta block

Add the Hoedown::META_BLOCK to options.

Get a meta block by running in the following program.

$text = <<<EOT
<!--*
  author: user
  title: Welcom to use
  tags: [ markdown, metadata ]
*-->
test
EOT;

$hoedown = new Hoedown;

$hoedown->setOption(Hoedown::META_BLOCK, true);

echo $hoedown->parse($text, $meta), PHP_EOL;

var_dump($meta);

output:

<p>test</p>

array(1) {
  ["meta"]=>
  string(69) "  author: user
  title: Welcom to use
  tags: [ markdown, metadata ]
"
}

Parse meta block

Set the Hoedown::META_PARSE function to options.

$text = <<<EOT
<!--*
  author: user
  title: Welcom to use
  tags: [ markdown, metadata ]
*-->
test
EOT;

$hoedown = new Hoedown;

$hoedown->setOption(Hoedown::META_BLOCK, true);
$hoedown->setOption(Hoedown::META_PARSE, function($text) {
    return yaml_parse($text);
});

echo $hoedown->parse($text, $meta), PHP_EOL;

var_dump($meta);

output:

<p>test</p>

array(1) {
  ["meta"]=>
  array(3) {
    ["author"]=>
    string(4) "user"
    ["title"]=>
    string(13) "Welcom to use"
    ["tags"]=>
    array(2) {
      [0]=>
      string(8) "markdown"
      [1]=>
      string(8) "metadata"
    }
  }
}

cafuego / php-ext-hoedown Goto Github PK

php-ext-hoedown's Introduction

PHP Extension for Hoedown

Requirement

Build

Configuration

Usage

Runtime Configuration

Class synopsis

Predefined Constants

Methods

Hoedown::__construct

Hoedown::getOption

Hoedown::setOption

Hoedown::setOptions

Hoedown::parse

Hoedown::parseString

Hoedown::parseFile

Hoedown::ofString

Hoedown::ofFile

Hoedown::addRender

Hoedown::getRenders

Examples

HTML render

User block

Meta block

php-ext-hoedown's People

Contributors

Watchers

Recommend Projects

Recommend Topics

Recommend Org

Jobs