Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
branch: master
Fetching contributors…

Octocat-spinner-32-eaf2f5

Cannot retrieve contributors at this time

file 946 lines (895 sloc) 36.666 kb
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945
<?php
/**
* Discount PHP extension.
*
* This extension is a wrapper for the discount library, written by David
* Parsons.
*
* This a file with dummy definitions written in order to generate the
* documentation.
*
* @copyright 2012 Gustavo Lopes (extension), David Parsons (library)
* @package Discount
* @link http://pecl.php.net/markdown Project homepage
* @link http://cataphract.github.com/php-discount/ Git development repository
* @link http://www.pell.portland.or.us/~orc/kbd/discount/ Discount library
*/

/**
* A class that represents a document written the markdown markup language,
* allowing it to be converted into an HTML document.
*
* Simple typical usage has the form (full examples linked below):
* {@example simple_usage.php 25 3}
*
* Unless otherwise noted, all the methods:
* <ul>
* <li>Return <var>FALSE</var> if there is a wrong number of arguments or if
* the type of the argument is unexpected and PHP does not provide an automatic
* conversion to the required type.</li>
* <li>Throw <var>LogicException</var> if the method is an instance method and,
* except for {@link MarkdownDocument::initFromStream()} and
* {@link MarkdownDocument::initFromString()}, is used without the document
* having been initialized. This can only happen in subclasses whose constructor
* doesn't call either {@link MarkdownDocument::initFromStream()} or
* {@link MarkdownDocument::initFromString()} (or calls to them fail but the
* constructor doesn't abort the object construction with an exception).</li>
* <li>Throw <var>LogicException</var> if the method is called from within a
* callback provided to {@link MarkdownDocument::setUrlCallback()} or
* {@link MarkdownDocument::setAttributeCallback()}.</li>
* <li>Throw <var>LogicException</var> if the method requires the Markdown
* document to be compiled, but it isn't (or not to be compiled, but it
* is).</li>
* </ul>
*
* The methods that take a stream can instead take a URL from which such
* stream can be opened, but beware that if the method is to write a result,
* the stream will be opened with mode <var>'w'</var>, most likely discarding
* the previous contents of the file.
*
* Explaining the Markdown syntax is beyond the scope of this documentation.
* For that purpose, you can consult the
* {@link http://daringfireball.net/projects/markdown/syntax syntax of the
* original Markdown}. Discount also implements
* {@link http://www.pell.portland.or.us/~orc/Code/discount/#Language.extensions
* several extensions}, which you can deactivate with great granularity by using
* the flags described in this document.
*
* @package Discount
* @author Gustavo Lopes
* @example simple_usage.php A simple example of the usage of this class.
* @example subclassing.php Simple subclassing to simplify usage.
* @example subclassing_2.php Subclassing example with table of contents & CSS.
* @link http://pecl.php.net/markdown Project homepage
* @link http://cataphract.github.com/php-discount/ Git development repository
* @link http://www.pell.portland.or.us/~orc/kbd/discount/ Discount library
* @since 0.1.0
*/
class MarkdownDocument {
/**
* A compile flag that disables processing the markdown elements that would
* otherwise create HTML links (like in
* <kbd>[text](http://www.example.com)</kbd>);
* additionally, it escapes any <kbd>A</kbd> (anchor) element it finds.
* @var int Compile flag to forbid links (HTML anchors).
* @see MarkdownDocument::compile()
* @see MarkdownDocument::transformFragment()
* @see MarkdownDocument::SAFELINK
* @see MarkdownDocument::NO_EXT
* @see MarkdownDocument::AUTOLINK
* @since 0.1.0
*/
const NOLINKS = 1;

/**
* A compile flag that disables processing the markdown elements that would
* otherwise create HTML images (like in
* <kbd>![alt text](http://www.example.com/myimg.jpg "title")</kbd>);
* additionally, it escapes any <kbd>IMG</kbd> element it finds.
* @var int Compile flag to forbid images (HTML img element)
* @see MarkdownDocument::compile()
* @see MarkdownDocument::transformFragment()
* @since 0.1.0
*/
const NOIMAGE = 2;

/**
* A compile flag that deactivates smartypants substitutions such as turning
* <kbd>(tm)</kbd> into <kbd>&trade;</kbd>, <kbd>don't</kbd> into
* <kbd>don&rsquo;t</kbd>, among others (see the example).
* @var int Compile flag to deactivate smartypants substitutions.
* @see MarkdownDocument::compile()
* @see MarkdownDocument::transformFragment()
* @link http://daringfireball.net/projects/smartypants/ Page for original
* SmartyPants project
* @example smartypants.php Smartypants-style substitutions in action
* @since 0.1.0
*/
const NOPANTS = 4;

/**
* A compile flag that disables all literal HTML present in the input by
* encoding all the tags.
* @var int Compile flag to deactivate literal HTML.
* @see MarkdownDocument::compile()
* @see MarkdownDocument::transformFragment()
* @since 0.1.0
*/
const NOHTML = 8;

/**
* A compile flags that has the effects of approximating the behavior of
* discount to that of the original Markdown, by disabling several
* extensions.
*
* In particular, it has the effect of combining
* {@link MarkdownDocument::NOSUPERSCRIPT},
* {@link MarkdownDocument::NORELAXED},
* {@link MarkdownDocument::NOSTRIKETHROUGH},
* {@link MarkdownDocument::NODLIST},
* {@link MarkdownDocument::NOALPHALIST},
* {@link MarkdownDocument::NODIVQUOTE} and,
* {@link MarkdownDocument::NOTABLES},
* @var into Compile flag to disable most discount extensions and
* increase compatibility with the original Markdown.
* @see MarkdownDocument::compile()
* @see MarkdownDocument::transformFragment()
* @since 0.1.0
*/
const STRICT = 16;

/**
* A compile flag that aims to process attribute-safe fragments.
*
* This flag disables <kbd>[]</kbd> expansion for images or links,
* (including literal HTML for them) smarty pants, ticks, autolink (even
* with {@link MarkdownDocument::AUTOLINK}), emphasis; it also transforms >
* into &gt; and " into &quote;. Its purpose is to transform text
* that could go into tag attributes. Best used with
* {@link MarkdownDocument::transformFragment()} or
* {@link MarkdownDocument::writeFragment()}, as many substitutions done
* by {@link MarkdownDocument::compile()} +
* {@link MarkdownDocument::getHtml()} are not covered.
* @var int Flag to make fragments more attribute-safe.
* @see MarkdownDocument::transformFragment()
* @since 0.1.0
*/
const TAGTEXT = 32;

/**
* A compile flag that disables the use of pseudo-protocols for links.
* Pseudo-protocols are link protocols that result in HTML elements other
* than anchors being generated. They are a discount extension. See the
* example for more details.
*
* @var int Compile flag to disable the use of pseudo-protocols.
* @example pseudoprotos.php Pseudo-protocols in action.
* @see MarkdownDocument::compile()
* @see MarkdownDocument::transformFragment()
* @see MarkdownDocument::NOLINKS
* @see MarkdownDocument::SAFELINK
* @since 0.1.0
*/
const NO_EXT = 64;

/**
* A compile flag that, for {@link MarkdownDocument::writeFragment()} and
* {@link MarkdownDocument::writeHtml()}, causes any <kbd>< </kbd>,
* <kbd> ></kbd>, <kbd>&</kbd>, <kbd>"</kbd> and <kbd>'</kbd> characters
* in the final output to be converted to their corresponding XML entities.
*
* @var int Compile flag to enable conversion into basic XML entities.
* @see MarkdownDocument::compile()
* @see MarkdownDocument::writeHtml()
* @see MarkdownDocument::writeFragment()
* @since 0.1.0
*/
const CDATA = 128;

/**
* A compile flag that deactivates the conversion of superscripts expressed
* with <kbd>^</kdb>, as in <kbd>A^B</kdd> or <kbd>A^(BC)</kbd> (a discount
* extension).
*
* <kbd>SUP</kbd> tags can still be included literally (but see
* {@link MarkdownDocument::NOHTML}).
*
* @var int Compile flag to disable superscripts.
* @see MarkdownDocument::compile()
* @see MarkdownDocument::transformFragment()
* @see MarkdownDocument::STRICT
* @since 0.1.0
*/
const NOSUPERSCRIPT = 256;

/**
* A compile flag that forces discount to substitute with EM elements all
* the pairs of underscores it finds. In normal circumstances, discount will
* ignore underscores that are surrounded by alphanumeric characters.
*
* For instance, this flag forces emphasis in <kbd>c d</kbd> for the input
* string <kbd>ab_c d_2</kbd>, which would otherwise not happen.
*
* The "relaxed" parsing of underscores is a discount extension borrowed
* from Markdown extra; this flag forces compliant behavior.
*
* @var int Compile flag to disable relaxed parsing of underscores.
* @see MarkdownDocument::compile()
* @see MarkdownDocument::transformFragment()
* @see MarkdownDocument::STRICT
* @link http://michelf.com/projects/php-markdown/extra/#em Markdown extra
* description of the relaxed emphasis rules.
* @since 0.1.0
*/
const NORELAXED = 512;

/**
* A compile flag that disables the parsing of tables. Tables are a discount
* extension borrowed by Markdown Extra.
*
* Tables can still be written with literal HTML (but see
* {@link MarkdownDocument::NOHTML}).
*
* @var int Compile flag to deactivate Markdown Extra tables.
* @see MarkdownDocument::STRICT
* @see MarkdownDocument::compile()
* @link http://michelf.com/projects/php-markdown/extra/#table Syntax for
* Markdown Extra tables.
* @since 0.1.0
*/
const NOTABLES = 1024;

/**
* A compile flag that deactivates the conversion of striken-through text,
* as in <kbd>~~text~~</kbd>, to be converted to <kbd><del>text</del></kbd>.
* This conversion is a discount extension.
*
* The <kbd>DEL</kbd> element can still be introduced with literal HTML
* (but see {@link MarkdownDocument::NOHTML}).
*
* @var int Compile flag to disable strike-through.
* @see MarkdownDocument::compile()
* @see MarkdownDocument::transformFragment()
* @see MarkdownDocument::STRICT
* @since 0.1.0
*/
const NOSTRIKETHROUGH = 2048;

/**
* A compile flag that forces a table of contents to be generated and the
* headings to have attributed an id.
*
* The generated table of contents can then be retrieved with
* {@link MarkdownDocument::getToc()} or written with
* {@link MarkdownDocument::writeToc()}.
*
* @var int Compile flag to activate table of contents generation.
* @see MarkdownDocument::compile()
* @see MarkdownDocument::getToc()
* @see MarkdownDocument::writeToc()
* @since 0.1.0
*/
const TOC = 4096;

/**
* A compile flag that applies some compatibility quirks in order to force
* discount passing some compatibility tests.
*
* Particularly, it makes:
* <ol>
* <li>the first line of every block has trailing whitespace trimmed
* off;</li>
* <li>require second [] for links/images instead of using label as key in
* the absence of it;</li>
* <li>more lax algorithm if content of []() link/image starts with <.</li>
* </ol>
*
* @var int Compile flag to turn on compatibility quirks.
* @see MarkdownDocument::compile()
* @see MarkdownDocument::transformFragment()
* @since 0.1.0
*/
const ONE_COMPAT = 8192;

/**
* A compile flag that turns every found URL into a link.
*
* In general, for a URL to linkified, it needs < and > around it. This flag
* drops that requirement and linkifies all the recognized URLs.
*
* @var int Compile flag to linkify every URL.
* @see MarkdownDocument::compile()
* @see MarkdownDocument::transformFragment()
* @see MarkdownDocument::NOLINKS
* @since 0.1.0
*/
const AUTOLINK = 16384;

/**
* A compile flag that limits generated links to certain protocols.
*
* The allowed protocols are <var>http</var>, <var>https</var>,
* <var>news</var> and <var>ftp</var>. Links starting with <var>/</var>, but
* not relative links, are also allowed.
*
* Pseudo-protocols are also deactivated, there is no need to include
* {@link MarkdownDocument::NO_EXT}.
*
* Links with arbitrary destinations are still allowed with literal HTML,
* but see {@link MarkdownDocument::NOHTML}.
*
* @var int Compile flag to generate links only for some protocols.
* @see MarkdownDocument::compile()
* @see MarkdownDocument::transformFragment()
* @see MarkdownDocument::NOLINKS
* @see MarkdownDocument::NO_EXT
* @since 0.1.0
*/
const SAFELINK = 32768;

/**
* An input flag that deactivates parsing of pandoc-style headers.
*
* Note that Markdown does not currently support multi-line headers.
*
* @var int Input flag to process pandoc-style headers.
* @see MarkdownDocument::createFromString()
* @see MarkdownDocument::createFromStream()
* @see MarkdownDocument::initFromStream()
* @see MarkdownDocument::initFromString()
* @example pandoc_headers.php Pandoc headers in action.
* @link http://johnmacfarlane.net/pandoc/README.html#title-blocks
* Documentation on pandoc-style headers.
* @since 0.1.0
*/
const NOHEADER = 65536;

/**
* An input flag to treat tab stops as 4 spaces � has no effect unless the
* extension was compiled with a different tab stop.
*
* The default tab stop is 4 spaces, so this flag usually has no effect.
*
* @var int Input flag to force tab stops to be 4 spaces longs, even when
* discount was compiled otherwise.
* @since 0.1.0
*/
const TABSTOP = 131072;

/**
* Compile flag that deactivates turning certain special block quotes into
* <kbd>DIV</kbd> elements with a certain class.
*
* In discount, blockquotes whose first line has the form
* <kbd> > %classname%</kbd> will be transformed into a <kbd>DIV</kbd>
* element with the indicated class instead of a <kbd>BLOCKQUOTE</kbd>
* element. This is a discount extension that can be deactivated with this
* class.
*
* @var int Compile flag to deactivate turning certain quoted blocks into
* <kbd>DIV</kbd> elements with an arbitrary class.
* @see MarkdownDocument::compile()
* @see MarkdownDocument::STRICT
* @since 0.1.0
*/
const NODIVQUOTE = 262144;

/**
* Compile flag that deactivates alphabetically ordered lists. These lists
* are a discount extension.
*
* @var int Compile flag to deactivate alphabetically ordered lists.
* @see MarkdownDocument::compile()
* @see MarkdownDocument::STRICT
* @since 0.1.0
*/
const NOALPHALIST = 524288;

/**
* Compile flag that deactivates definition lists, either discount-style or
* Markdown-extra style.
*
* @var int Compile flag to deactivate definition lists. These lists are a
* discount extension.
*
* @see MarkdownDocument::STRICT
* @see MarkdownDocument::compile()
* @example definition_list.php Definitions list and NODLIST.
* @since 0.1.0
*/
const NODLIST = 1048576;

/**
* A combination of the compile flags {@link MarkdownDocument::NOLINKS},
* {@link MarkdownDocument::NOIMAGE} and {@link MarkdownDocument::TAGTEXT}.
* Effectively, the same effect as {@link MarkdownDocument::TAGTEXT}.
*
* It's unclear why discount includes this flag since the effects of
* {@link MarkdownDocument::NOLINKS} and {@link MarkdownDocument::NOIMAGE}
* are included in those of {@link MarkdownDocument::TAGTEXT}.
*
* @var int Combination of compile flags with the same effect as
* {@link MarkdownDocument::TAGTEXT}.
* @see MarkdownDocument::transformFragment()
* @see MarkdownDocument::TAGTEXT
* @see MarkdownDocument::NOIMAGE
* @see MarkdownDocument::NOLINKS
* @since 0.1.0
*/
const EMBED = 35;

/**
* Compile flag that enables the use of PHP Markdown Extra-style footnotes.
*
* @var int Compile flag that enables footnotes. Footnotes are a discount
* extension borrowed from Markdown Extra.
*
* @link http://michelf.com/projects/php-markdown/extra/#footnotes Syntax
* for Markdown Extra footnotes
* @see MarkdownDocument::compile()
* @since 1.0.0
*/
const EXTRA_FOOTNOTE = 2097152;

/**
* Compile flag that disables the processing of &lt;style> sections (for inclusion
* in the return of {@link MarkdownDocument::getCss()}). It has no effect if
* {@link MarkdownDocument:NOHTML} is already enabled.
*
* @var int Bit for disabling processing &lt;style> sections.
* @see MarkdownDocument::NOHTML
* @see MarkdownDocument::getCss()
* @since 1.1.0
*/
const NOSTYLE = 4194304;

/**
* Creates a {@link MarkdownDocument} from a stream.
*
* This is one of the two public methods available for creating an object of
* this type, which is required as an initial step for full markdown
* processing.
*
* @param mixed $markdown_stream Either a stream resource opened with
* reading permissions or a URL from which such a stream can be opened.
* @param integer $flags Data input type flags. Only the flags
* {@link MarkdownDocument::NOHEADER} and {@link MarkdownDocument::TABSTOP}
* are allowed.
* @return MarkdownDocument An object of the type of this class, created
* from data read from the specified stream.
* @see MarkdownDocument::createFromString()
* @see MarkdownDocument::initFromStream()
* @since 0.1.0
*/
static public function createFromStream($markdown_stream, $flags = 0) {}

/**
* Creates a {@link MarkdownDocument} from a string.
*
* This is one of the two public methods available for creating an object of
* this type, which is required as an initial step for full markdown
* processing.
*
* @param mixed $markdown_doc A string containing the document expressed
* in the markdown markup language.
* @param integer $flags Data input type flags. Only the flags
* {@link MarkdownDocument::NOHEADER} and {@link MarkdownDocument::TABSTOP}
* are allowed.
* @return MarkdownDocument An object of the type of this class, created
* from data read from the specified string.
* @see MarkdownDocument::createFromStream()
* @see MarkdownDocument::initFromString()
* @since 0.1.0
*/
static public function createFromString($markdown_doc, $flags = 0) {}

/**
* Reads markdown from a string and transforms it to HTML without creating
* any block elements.
*
* In this form (inline markdown), the transformations made are much more
* limited than with the combination of
* {@link MarkdownDocument::createFromString()},
* {@link MarkdownDocument::compile()} and
* {@link MarkdownDocument::getHtml()}. No paragraph tags are added and no
* tables, block quotes, code blocks, pandoc headers or reference-style
* links/images or lists are processed.
*
* Arbitrary HTML is still allowed, unless the
* {@link MarkdownDocument::NOHTML} flag is given.
*
* @param string $markdown_fragment The markdown fragment to convert.
* @param integer $flags Compile flags appropriate for inline markdown
* (several features are disabled in inline markdown, so many flags have
* no effect).
* @return string A string with the HTML resulting from transforming the
* markdown fragment.
* @see MarkdownDocument::writeFragment()
* @since 0.1.0
*/
static public function transformFragment($markdown_fragment, $flags = 0) {}

/**
* Reads markdown from a string, transforms it to HTML without creating
* any block elements and writes the result to a stream.
*
* In this form (inline markdown), the transformations made are much more
* limited than with the combination of
* {@link MarkdownDocument::createFromString()},
* {@link MarkdownDocument::compile()} and
* {@link MarkdownDocument::writeHtml()}. No paragraph tags are added and no
* tables, block quotes, code blocks, pandoc headers or reference-style
* links/images or lists are processed.
*
* Arbitrary HTML is still allowed, unless the
* {@link MarkdownDocument::NOHTML} flag is given.
*
* @param string $markdown_fragment The markdown fragment to convert.
* @param mixed $out_stream A resource stream that can be written to or a
* URL with which a stream with writing permissions can be opened.
* @param integer $flags Compile flags appropriate for inline markdown
* (several features are disabled in inline markdown, so many flags have
* no effect).
* @return boolean <var>TRUE</var> if all the data is successfully written;
* if there is an error when writing to the stream, <var>FALSE</var> is
* returned and a warning is raised. The usual error handling for
* {@link MarkdownDocument} objects still apply.
* @see MarkdownDocument::transformFragment()
* @since 0.1.0
*/
static public function writeFragment($markdown_fragment, $out_stream, $flags = 0) {}

/**
* A no-op protected constructor.
*
* This method prevents instantiation of the {@link MarkdownDocument}
* class with <var>new</var>, forcing the usage of
* {@link MarkdownDocument::createFromString()} or
* {@link MarkdownDocument::createFromStream()}.
*
* It is protected to, nevertheless, allow subclassing in a straightforward
* manner by overriding this constructor. The overriding constructor need
* not call this method, as it is a no-op. It should, however, call either
* the {@link MarkdownDocument::initFromString()} or
* {@link MarkdownDocument::initFromStream()}.
*
* @see MarkdownDocument::createFromString()
* @see MarkdownDocument::createFromStream()
* @see MarkdownDocument::initFromString()
* @see MarkdownDocument::initFromStream()
* @since 0.1.0
*/
protected function __construct() {}

/**
* Initialize the native part of the object using an input stream.
*
* This method reads markdown data from the passed stream and initializes
* the native discount data structure. It should be called in the
* constructor of subclasses; if not, it should at least be called before
* any of the {@link MarkdownDocument} methods be called. Alternatively,
* {@link MarkdownDocument::initFromString()} can be called instead.
*
* @param mixed $markdown_stream Either a stream resource opened with
* reading permissions or a URL from which such a stream can be opened.
* @param integer $flags Data input type flags. Only the flags
* {@link MarkdownDocument::NOHEADER} and {@link MarkdownDocument::TABSTOP}
* are allowed.
* @return boolean <var>TRUE</var> unless one of the usual error
* conditions for the {@link MarkdownDocument} class is triggered.
* @throws LogicException If the object has already been initialized.
* @see MarkdownDocument::initFromString()
* @see MarkdownDocument::createFromStream()
* @since 0.1.0
*/
final protected function initFromStream ($markdown_stream, $flags = 0) {}

/**
* Initialize the native part of the object using a string.
*
* This method reads markdown data from the passed string and initializes
* the native discount data structure. It should be called in the
* constructor of subclasses; if not, it should at least be called before
* any of the {@link MarkdownDocument} methods be called. Alternatively,
* {@link MarkdownDocument::initFromStream()} can be called instead.
*
* @param mixed $markdown_doc Either a stream resource opened with
* reading permissions or a URL from which such a stream can be opened.
* @param integer $flags Data input type flags. Only the flags
* {@link MarkdownDocument::NOHEADER} and {@link MarkdownDocument::TABSTOP}
* are allowed.
* @return boolean <var>TRUE</var> unless one of the usual error
* conditions for the {@link MarkdownDocument} class is triggered.
* @throws LogicException if the object has already been initialized.
* @see MarkdownDocument::initFromString()
* @since 0.1.0
*/
final protected function initFromString($markdown_doc, $flags = 0) {}

/**
* Compiles this document, preparing the HTML data to be retrieved.
*
*
* @param integer $flags A combination of the compile flags, i.e., all but
* {@link MarkdownDocument::NOHEADER} and {@link MarkdownDocument::TABSTOP}.
* @return boolean <var>TRUE</var> unless one of the usual error
* conditions for the {@link MarkdownDocument} class is triggered.
* @throws LogicException if the object has already been compiled.
* @since 0.1.0
*
*/
public function compile($flags) {}

/**
* Tells whether this document has already been compiled.
*
* This method will return <var>TRUE</var> if
* {@link MarkdownDocument::compile()} has already been successfully called
* and <var>FALSE</var> otherwise.
*
* @return boolean Whether the document has already been compiled.
* @see MarkdownDocument::compile()
* @since 0.1.0
*/
public function isCompiled() {}

/**
* Write an outline view of the document.
*
* @param mixed $out_stream A resource stream opened with write permissions
* or a URL that can be opened to yield such a stream, for writing the
* output.
* @param string $title A string to be prefixed to the tree.
* @return boolean Returns <var>TRUE</var>, except for the situations covered
* in the class summary.
* @example dump_tree.php dumpTree() in action.
* @since 0.1.0
*/
public function dumpTree($out_stream, $title = "") {}

/**
* The title found in the pandoc-style header.
*
* Note that discount does not currently support multi-line titles.
*
* The document need not have been compiled.
*
* @example pandoc_headers.php getTitle() in action.
* @link http://johnmacfarlane.net/pandoc/README.html#title-blocks
* Documentation on pandoc-style headers.
* @return string The title found in the pandoc-style header. An empty
* string is returned if no title was found or if
* {@link MarkdownDocument::NOHEADER} was used.
* @see MarkdownDocument::getAuthor()
* @see MarkdownDocument::getDate()
* @see MarkdownDocument::NOHEADER
* @since 0.1.0
*/
public function getTitle() {}

/**
* The author or authors found in the pandoc-style hader.
*
* Note that discount does not currently support multi-line authors.
*
* The document need not have been compiled.
*
* @link http://johnmacfarlane.net/pandoc/README.html#title-blocks
* Documentation on pandoc-style headers.
* @return string The authors found in the pandoc-style header. An empty
* string is returned if no authors were found or if
* {@link MarkdownDocument::NOHEADER} was used.
* @see MarkdownDocument::getTitle()
* @see MarkdownDocument::getDate()
* @see MarkdownDocument::NOHEADER
* @since 0.1.0
*/
public function getAuthor() {}

/**
* The date found in the pandoc-style header.
*
* The document need not have been compiled.
*
* @link http://johnmacfarlane.net/pandoc/README.html#title-blocks
* Documentation on pandoc-style headers.
* @return string The date found in the pandoc-style header. An empty
* string is returned if no date was found or if
* {@link MarkdownDocument::NOHEADER} was used.
* @see MarkdownDocument::getTitle()
* @see MarkdownDocument::getAuthor()
* @see MarkdownDocument::NOHEADER
* @since 0.1.0
*/
public function getDate() {}

/**
* Generate and return the body HTML data that results from processing this
* document.
*
* This includes all the data present in the given markup with the exception
* of the pandoc-style headers and the style blocks. The unprocessed headers
* will, however, show up if {@link MarkdownDocument::NOHEADER} is given,
* and the escaped style blocks will show up if
* {@link MarkdownDocument::NOHTML} is given.
*
* The document should already have been compiled.
*
* If defined, this method calls the callbacks specified through
* {@link MarkdownDocument::setUrlCallback()} and
* {@link MarkdownDocument::setAttributesCallback()} for each link
* generated. If any of these callbacks throws an exception, this method
* throws another exception on top of it on the first time.
*
* @return string The body of the final HTML that results from processing
* this document.
* @see MarkdownDocument::writeHtml()
* @see MarkdownDocument::writeXhtmlPage()
* @see MarkdownDocument::transformFragment()
* @since 0.1.0
*/
public function getHtml() {}


/**
* Writes the HTML contents of the body of the processed markup document.
*
* This includes all the data present in the given markup with the exception
* of the pandoc-style headers and the style blocks. The unprocessed headers
* will, however, show up if {@link MarkdownDocument::NOHEADER} is given,
* and the escaped style blocks will show up if
* {@link MarkdownDocument::NOHTML} is given.
*
* The document should already have been compiled.
*
* If defined, this method calls the callbacks specified through
* {@link MarkdownDocument::setUrlCallback()} and
* {@link MarkdownDocument::setAttributesCallback()} for each link
* generated. If any of these callbacks throws an exception, this method
* throws another exception on top of it on the first time.
*
* @param mixed $markdown_outstream A resource stream opened with write
* permissions or a URL that can be opened to yield such a stream, for
* writing the output.
* @return boolean <var>TRUE</var> on normal conditions or
* <var>FALSE</var> and raises a warning if there was an I/O error when
* writing to the given stream (or to a successfully opened stream, if a URL
* was provided instead). The usual error handling described in the class
* synopsis still applies.
* @see MarkdownDocument::compile()
* @see MarkdownDocument::getHtml()
* @see MarkdownDocument::writeCss()
* @see MarkdownDocument::writeXhtmlPage()
* @since 0.1.0
*/
public function writeHtml($markdown_outstream) {}

/**
* Writes a complete XHTML page.
*
* The style blocks found in the markdown data are put in the
* <kbd>HEAD</kbd> element, the <kbd>TITLE</kbd> element is built from the
* title extracted from the pandoc-style header and the
* <kbd>BODY</kbd> is composed by what
* {@link MarkdownDocument::writeHtml()} would return.
*
* The document should already have been compiled.
*
* @param mixed $markdown_outstream A resource stream opened with write
* permissions or a URL that can be opened to yield such a stream.
* @return boolean <var>TRUE</var> on normal conditions or
* <var>FALSE</var> and raises a warning if there was an I/O error when
* writing to the given stream or to a successfully opened stream, if a URL
* was provided instead.
* @see MarkdownDocument::writeHtml()
* @see MarkdownDocument::writeCss()
* @see MarkdownDocument::getTitle()
* @since 0.1.0
*/
public function writeXhtmlPage($markdown_outstream) {}

/**
* Returns the table of contents HTML data.
*
* This method must be called after the document has been compiled with
* {@link MarkdownDocument::TOC}.
*
* @return string the table of contents HTML data or <var>FALSE</var> if
* {@link MarkdownDocument::TOC} was not given to
* {@link MarkdownDocument::compile()}.
* @see MarkdownDocument::TOC
* @since 0.1.0
*/
public function getToc() {}

/**
* Give all the <kbd><style></kbd> elements found in the
* markdown document. These elements will not be included in the result
* returned by {@link MarkdownDocument::getHtml()}.
*
* This function returns an empty string if the flag
* {@link MarkdownDocument::NOHTML} was specified.
*
* The markdown document must have already been compiled.
*
* @return string All the <kbd><style></kbd> elements found in the
* markdown document.
* @see MarkdownDocument::writeCss()
* @since 0.1.0
*/
public function getCss() {}

/**
* Writes the table of contents HTML data into a file.
*
* This method must be called after the document has been compiled with
* {@link MarkdownDocument::TOC}.
*
* @param mixed $markdown_outstream A stream resource where the HTML table
* of contents can be written or a URL that can be opened for writing.
* @return boolean <var>TRUE</var> if the table of contents was built and
* successfully written; <var>FALSE</var> if
* {@link MarkdownDocument::TOC} was not given or if writing failed, in the
* last case, a warning is also raised. The usual handling of the errror
* conditions described in the introduction to the {@link MarkdownDocument}
* class still apply.
* @see MarkdownDocument::TOC
* @since 0.1.0
*/
public function writeToc($markdown_outstream) {}

/**
* Writes all the <kbd><style></kbd> elements found in the
* markdown document. These elements will not be included in the result
* returned by {@link MarkdownDocument::getHtml()} or written by
* {@link MarkdownDocument::writeHtml()}.
*
* This function returns an empty string if the flag
* {@link MarkdownDocument::NOHTML} was specified.
*
* The markdown document must have already been compiled.
*
* @param mixed $markdown_outstream A stream resource where the style
* elements can be written or a URL that can be opened for writing.
* @return boolean <var>TRUE</var> on normal conditions or
* <var>FALSE</var> and raises a warning if there was an I/O error when
* writing to the given stream (or to a successfully opened stream, if a URL
* was provided instead). The usual error handling described in the class
* synopsis also applies.
* @see MarkdownDocument::getCss()
* @since 0.1.0
*/
public function writeCss($markdown_outstream) {}

/**
* Sets a callback to replace the URLs in generated links.
*
* The callback refers to a function that will receive one argument, a
* string with the URL that would be included with a generated link and
* returns either a replacement URL that will be used instead or
* <var>NULL</var>, to use the original URLs.
*
* Links that were written as literal HTML in the input will <b>not</b> be
* passed to the callback!
*
* The object need not have been compiled before this function is called.
*
* The actual URL conversion and calling of the callback happens when
* {@link MarkdownDocument::getHtml()} or
* {@link MarkdownDocument::writeHtml()} are called.
*
* @return boolean Returns <var>TRUE</var>, except for the situations
* covered in the class summary.
* @param callback $callback Callback function to replace URLs. Receives
* a string and should return either a string or NULL. This parameter can be
* <var>NULL</var> to remove the callback.
* @see MarkdownDocument::setAttributesCallback()
* @since 0.1.0
*/
public function setUrlCallback($callback) {}

/**
* Sets a callback to add attributes to <kbd>A</kbd> elements in generated
* links.
*
* The callback refers to a function that will receive one argument, a
* string with the URL that would be included with a generated link and
* returns either a string with the attributes and their values, to be
* appended to the generated <kbd>A</kbd> element or <var>NULL</var>, which
* has the same effect as an empty string and causes no extra attributes to
* be appended.
*
* Links that were written as literal HTML in the input will <b>not</b>
* cause the callback to be called!
*
* The object need not have been compiled before this function is called.
*
* The actual URL conversion and calling of the callback happens when
* {@link MarkdownDocument::getHtml()} or
* {@link MarkdownDocument::writeHtml()} are called.
*
* @return boolean Returns <var>TRUE</var>, except for the situations
* covered in the class summary.
* @param callback $callback Callback function to add attributes to links.
* Receives a string and should return either a string or NULL. This
* parameter can be <var>NULL</var> to remove the callback.
* @see MarkdownDocument::setUrlCallback()
* @since 0.1.0
*/
public function setAttributesCallback($callback) {}


/**
* This function allows customizing the prefix used in footnote references.
* More specifically, it changes the <kbd>name</kbd> attributes of the
* anchors from <kbd>fn:N</kbd> and <kbd>fnref:N</kbd> to
* <kbd>{$prefix}:N</kbd> and <kbd>{$prefix}ref:N</kbd>. This allows, for
* instance, for displaying several articles rendered individually in the
* same page without clashes in the footnote links.
*
* This function can only be called if the document has not yet been
* compiled.
*
* Usage of footnotes requires the {@link MarkdownDocument::EXTRA_FOOTNOTE}
* compile flag.
*
* @return boolean Returns <var>TRUE</var>, except for the situations
* covered in the class summary.
* @param string $prefix The prefix to use.
* @see MarkdownDocument::EXTRA_FOOTNOTE
* @see MarkdownDocument::compile()
* @since 1.0.0
*/
public function setReferencePrefix($prefix) {}
}

Something went wrong with that request. Please try again.