Tcl Library Source Code

[vset VERSION 1.1]
[comment {-*- tcl -*- doctools manpage}]
[manpage_begin markdown n [vset VERSION]]
[moddesc   {Markdown to HTML Converter}]
[titledesc {Converts Markdown text to HTML}]
[category  {Text processing}]
[require Tcl 8.5]
[require Markdown [vset VERSION]]
[require textutil [opt 0.8]]
[description]

The package [package Markdown] provides a command to convert
Markdown annotated text into HMTL. 

[list_begin definitions]
[call [cmd ::Markdown::convert] [arg "markdown"]]

This command takes in a block of Markdown text, and returns a block
of HTML.

[para] The converter supports two types of syntax highlighting for
fenced code blocks: highlighting via a registered converter
(see [cmd ::Markdown::register]), or pure JavaScript highlighting,
e.g. via "highlight.js", where the language specifier used in the
markup is set as CSS class of the "code" element in the returned markup.

[call [cmd ::Markdown::register] [arg "langspec"] [arg "converter"]]

Register a language specific converter for prettifying a code block
(e.g. syntax highlighting).  Markdown supports fenced code blocks with
an optional language specifier (e.g. "tcl"). When the markdown parser
processes such a code block and a converter for the specified langspec
is registered, the converter is called with the raw code block as
argument. The converter is supposed to return the markup of the code
block as result. The specified converter can be an arbitrary Tcl
command, the raw text block is added as last argument upon invocation.

[call [cmd ::Markdown::get_lang_counter]]

Return a dict of language specifier and number of occurrences in
fenced code blocks. This function can be used e.g. to detect, whether
some CSS or JavaScript headers should be included for rendering
without the need of postprocessing the rendered result.

[call [cmd ::Markdown::reset_lang_counter]]

Reset the language counters.

[list_end]

[vset CATEGORY textutil]
[include ../doctools2base/include/feedback.inc]
[manpage_end]

        # COLLECT REFERENCES
        array unset ::Markdown::_references
        array set ::Markdown::_references [collect_references markdown]

        # PROCESS
        return [apply_templates markdown]
    }

    #
    # Register a language specific converter. This converter can be
    # used for fenced code blocks to transform the code block into a
    # prettified HTML.
    #
    proc register {lang_specifier converter} {
	set ::Markdown::converter($lang_specifier) $converter
    }

    #
    # Return a dict (attribute value pairs) of language specifiers and
    # the number of occurrences as they were used in fenced code blocks.
    #
    proc get_lang_counter {} {
	return [array get ::Markdown::lang_counter]
    }

    #
    # Reset the language counters of fenced code blocks.
    #
    proc reset_lang_counter {} {
	array unset ::Markdown::lang_counter
    }

    ## \private
    proc collect_references {markdown_var} {
        upvar $markdown_var markdown

        set lines [split $markdown \n]
        set no_lines [llength $lines]

        set ul_match {^[ ]{0,3}(?:\*(?!\s*\*\s*\*\s*$)|-(?!\s*-\s*-\s*$)|\+) }
        set ol_match {^[ ]{0,3}\d+\. }

        # PROCESS MARKDOWN
        while {$index < $no_lines} {
            set line [lindex $lines $index]

            switch -regexp -matchvar matches -- $line {
                {^\s*$} {
                    # EMPTY LINES
                    if {![regexp {^\s*$} [lindex $lines [expr $index - 1]]]} {
                        append result "\n\n"
                    }
                    incr index
                }

                        set line [lindex $lines $index]
                    }
                    set code_result [join $code_result \n]

                    append result <pre><code> $code_result \n </code></pre>
                }
                {^(?:(?:`{3,})|(?:~{3,}))\{?(\S+)?\}?\s*$} {
                    # FENCED CODE BLOCKS
                    set code_result {}

                    if {[string index $line 0] eq {`}} {
                        set end_match {^`{3,}\s*$}
                    } else {
                        set end_match {^~{3,}\s*$}
                    }
		    #
		    # A language specifier might be provided
		    # immediately after the leading delimiters.
		    #
		    #     ```tcl
		    #
		    # The language specifier is used for two purposes:
		    # a) As a CSS class name 
		    #    (useful e.g. for highlight.js)
		    # b) As a name for a source code to HTML converter.
		    #    When such a converter is registered,
		    #    the codeblock will be sent through this converter.
		    #
		    set lang_specifier [string tolower [lindex $matches end]]
		    if {$lang_specifier ne ""} {
			set code_CCS_class " class='$lang_specifier'"
			incr ::Markdown::lang_counter($lang_specifier)
		    } else {
			set code_CCS_class ""
		    }

                    while {$index < $no_lines} {
                        incr index

                        set line [lindex $lines $index]

                        if {[regexp $end_match $line]} {
                            incr index
                            break
                        }

                        lappend code_result $line
                    }
                    set code_result [join $code_result \n]

		    #
		    # If there is a converter registered, apply it on
		    # the resulting snippet.
		    #
		    if {[info exists ::Markdown::converter($lang_specifier)]} {
			set code_result [{*}$::Markdown::converter($lang_specifier) $code_result]
		    } else {
                        set code_result [html_escape $code_result]
                }
                    append result \
			"<pre class='code'>" \
			<code$code_CCS_class> \
			$code_result \
			</code></pre>
                }
		
                {^[ ]{0,3}(?:\*|-|\+) |^[ ]{0,3}\d+\. } {
                    # LISTS
                    set list_result {}

                    # continue matching same list type
                    if {[regexp $ol_match $line]} {
                        set list_type ol

    ## \private
    proc html_escape {text} {
        return [string map {& &amp; < &lt; > &gt; \" &quot;} $text]
    }
}

package provide Markdown 1.1

} -result {
    <ul>
    <li>asterisk 1
    </li></ul>
    
    <hr/>
}

test mdtest-1.10 {fenced code block without language specifier} -body {
    
    convert {
	Here comes a generic example:
	
	```
	set x 1
	```
    }
} -result {
    <p>Here comes a generic example:</p>
    
    <pre class='code'><code>set x 1</code></pre>
}

test mdtest-1.11 {fenced code block with language specifier} -body {
    
    convert {
	Here comes a Tcl example:
	
	```tcl
	set x 1
	```
    }
} -result {
    <p>Here comes a Tcl example:</p>
    
    <pre class='code'><code class='tcl'>set x 1</code></pre>
}

#-------------------------------------------------------------------------
# Cleanup

testsuiteCleanup

package ifneeded Markdown 1.1 [list source [file join $dir markdown.tcl]]