Hoedown

     AC_CHECK_LIB([hoedown],[hoedown_version],,
       [AC_MSG_FAILURE([test for Hoedown library failed])])
     AC_CHECK_HEADERS([hoedown/version.h],,
       [AC_MSG_FAILURE([test for Hoedown header failed])])

     hoedown [OPTION]... [FILE]

     smartypants [OPTION]... [FILE]

— Function: void hoedown_version (int * major, int * minor, int * revision)

Retrieve version numbers, storing them in the referenced int locations.

— Preprocessor Constant: HOEDOWN_VERSION

A string representing the full version number.

— Preprocessor Constant: HOEDOWN_MAJOR
— Preprocessor Constant: HOEDOWN_MINOR
— Preprocessor Constant: HOEDOWN_REVISION

Integers representing version number components.

— Function Pointer Typedef: hoedown_realloc_callback

Type definition for function pointers implementing a memory reallocation callback. It is meant to be used as follows:

          void *
          realloc_callback (void * ptr, size_t len)
          {
            ...
          }
          
          hoedown_realloc_callback R = realloc_callback;

This function pointer type is meant to match the one of the C Language Standard function realloc().

— Function Pointer Typedef: hoedown_free_callback

Type definition for function pointers implementing a memory release callback. It is meant to be used as follows:

          void
          free_callback (void * ptr)
          {
            ...
          }
          
          hoedown_free_callback F = free_callback;

This function pointer type is meant to match the one of the C Language Standard function free().

— Function: void * hoedown_malloc (size_t size)

Wrapper for the C Language Standard malloc(). If memory allocation fails: abort the process by calling abort().

— Function: void * hoedown_calloc (size_t nmemb, size_t size)

Wrapper for the C Language Standard calloc(). If memory allocation fails: abort the process by calling abort().

— Function: void * hoedown_realloc (void * ptr, size_t size)

Wrapper for the C Language Standard realloc(). If memory reallocation fails: abort the process by calling abort().

— Struct Typedef: hoedown_buffer

Type of structures representing data buffers. Instances of this type must be initialised by hoedown_buffer_init() and finalised by hoedown_buffer_uninit().

Basic allocation, initialisation and finalisation can be performed as:

          hoedown_buffer          B;
          
          hoedown_buffer_init(&B, 1, realloc, free, free);
          hoedown_buffer_uninit(&B);

or as:

          hoedown_buffer *        B;
          
          B = hoedown_buffer_new(1);
          hoedown_buffer_free(B);

Public fields in the data structure:

size

The number of octets used in the internal data area. It is the length in octets of the contained data.

— Function: void hoedown_buffer_init (hoedown_buffer * buffer, size_t reallocation-unit, hoedown_realloc_callback data_realloc, hoedown_free_callback data_free, hoedown_free_callback buffer_free)

Initialise a buffer with custom memory allocators.

buffer must be a pointer referencing an already allocated data structure. When the internal data area is reallocated to make it bigger: reallocation-unit is the minimum increase in the area size, measured in number of bytes.

data_realloc must reference a function used to allocate and/or reallocate a memory block. data_free must reference a function used to release the data area of the buffer. buffer_free must reference a function used to release the hoedown_buffer structure itself.

— Function: void hoedown_buffer_uninit (hoedown_buffer * buf)

Finalise the given buffer structure. Memory allocated for the internal data area is released using the registered data_free function. The memory block referenced by buf is not released.

— Function: hoedown_buffer * hoedown_buffer_new (size_t reallocation-unit)

Convenience function that allocates a new hoedown_buffer structure and initialises it with default memory handlers; internally it makes use of hoedown_buffer_init(). Return a pointer to the newly allocated structure.

The structure memory block is allocated with the C Language Standard malloc(). hoedown_realloc() is registered as data_realloc function. The C Language Standard free() is registered as both data_free and buffer_free function.

— Function: void hoedown_buffer_free (hoedown_buffer * buf)

Convenience function that finalises and releases the given buffer structure; internally it is similar to hoedown_buffer_uninit(). Release both the data area memory and the structure memory using the registered memory handlers.

— Function: void hoedown_buffer_reset (hoedown_buffer * buf)

Reset to empty the given buffer structure. Release the internal data area using the registered memory handlers.

— Function: void hoedown_buffer_grow (hoedown_buffer * buf, size_t neosz)

Increase the allocated data area size to the given value. Memory for the data area is allocated and reallocated with the registered memory handlers.

          hoedown_buffer              B;
          hoedown_buffer_init(&B, 1, realloc, free, free);
          {
            hoedown_buffer_grow(&B, 4096);
          }
          hoedown_buffer_uninit(&B);

— Function: void hoedown_buffer_put (hoedown_buffer * buf, const uint8_t * data, size_t size)

Append raw data to a buffer. The internal data area is resized as needed and octets referenced by data are copied into it.

          hoedown_buffer              B;
          static const char *         str = "Hello World!";
          hoedown_buffer_init(&B, 1024, realloc, free, free);
          {
            hoedown_buffer_put(&B, (const uint8_t*)str, strlen(str));
          }
          hoedown_buffer_uninit(&B);

— Function: void hoedown_buffer_puts (hoedown_buffer * buf, const char * str)

Append a NUL–terminated string to a buffer.

          hoedown_buffer              B;
          static const char *         str = "Hello World!";
          hoedown_buffer_init(&B, 1024, realloc, free, free);
          {
            hoedown_buffer_puts(&B, str);
          }
          hoedown_buffer_uninit(&B);

— Preprocessor Macro: void HOEDOWN_BUFPUTSL (hoedown_buffer * buf, const char * str)

Optimized hoedown_buffer_put() of a string literal. It is meant to be used when str references a literal string, as in:

          hoedown_buffer              B;
          static const char *         str  = "Hello World!";
          hoedown_buffer_init(&B, 1024, realloc, free, free);
          {
            HOEDOWN_BUFPUTSL(&B, "Hello ");
            HOEDOWN_BUFPUTSL(&B, "World!");
          }
          hoedown_buffer_uninit(&B);

— Function: void hoedown_buffer_putc (hoedown_buffer * buf, uint8_t c)

Append a single char to a buffer.

          hoedown_buffer              B;
          static const char *         str = "Hello World!";
          hoedown_buffer_init(&B, 1024, realloc, free, free);
          {
            for (int i=0; i<strlen(str); ++i) {
              hoedown_buffer_putc(&B, str[i]);
            }
          }
          hoedown_buffer_uninit(&B);

— Function: int hoedown_buffer_putf (hoedown_buffer * buf, FILE * file)

Read from a file and append to a buffer, until EOF or error.

          hoedown_buffer              B;
          FILE *                      M;
          char                        str[32];
          hoedown_buffer_init(&B, 1024, realloc, free, free);
          M = fopen("file.ext", "r");
          {
            hoedown_buffer_putf(&B, M);
          }
          fclose(M);
          hoedown_buffer_uninit(&B);

— Function: void hoedown_buffer_put_utf8 (hoedown_buffer * buf, unsigned int codepoint)

Put a Unicode character encoded as UTF-8.

          hoedown_buffer              B;
          uint32_t                    cp    = 0x10FFFF;
          uint8_t                     buf[] = {
            244, 143, 191, 191
          };
          hoedown_buffer_init(&B, 1024, realloc, free, free);
          {
            hoedown_buffer_put_utf8(&B, cp);
            assert(0 == memcmp(buf, B.data, B.size));
          }
          hoedown_buffer_uninit(&B);

— Function: void hoedown_buffer_set (hoedown_buffer * buf, const uint8_t * data, size_t size)

Replace the buffer's contents with raw data.

          hoedown_buffer              B;
          static const char *         str1 = "Hello World!";
          static const char *         str2 = "Ciao Mondo!";
          hoedown_buffer_init(&B, 1024, realloc, free, free);
          {
            hoedown_buffer_put(&B, (const uint8_t*)str1, strlen(str1));
            hoedown_buffer_set(&B, (const uint8_t*)str2, strlen(str2));
          }
          hoedown_buffer_uninit(&B);

— Function: void hoedown_buffer_sets (hoedown_buffer * buf, const char * str)

Replace the buffer's contents with a NUL-terminated string.

          hoedown_buffer              B;
          static const char *         str1 = "Hello World!";
          static const char *         str2 = "Ciao Mondo!";
          hoedown_buffer_init(&B, 1024, realloc, free, free);
          {
            hoedown_buffer_puts(&B, str1);
            assert(0 == memcmp(str1, B.data, B.size));
            hoedown_buffer_sets(&B, str2);
            assert(0 == memcmp(str2, B.data, B.size));
          }
          hoedown_buffer_uninit(&B);

— Preprocessor Macro: void HOEDOWN_BUFSETSL (hoedown_buffer * buf, const char * str)

Optimized hoedown_buffer_sets() of a string literal. It is meant to be used when str references a literal string, as in:

          hoedown_buffer              B;
          static const char *         str1 = "Hello World!";
          hoedown_buffer_init(&B, 1024, realloc, free, free);
          {
            hoedown_buffer_puts(&B, str1);
            HOEDOWN_BUFSETSL(&B, "Ciao Mondo!");
          }
          hoedown_buffer_uninit(&B);

— Function: int hoedown_buffer_eq (const hoedown_buffer * buf, const uint8_t * data, size_t size)

Compare a buffer's data with other data for equality: return true (non–zero) if the octets are equal, return false (zero) otherwise.

          hoedown_buffer              B;
          static const char *         str = "Hello World!";
          hoedown_buffer_init(&B, 1024, realloc, free, free);
          {
            hoedown_buffer_puts(&B, str);
            assert(0 != hoedown_buffer_eq(&B,
                          (const uint8_t*)str, strlen(str)));
          }
          hoedown_buffer_uninit(&B);

— Function: int hoedown_buffer_eqs (const hoedown_buffer * buf, const char * str)

Compare a buffer's data with a NUL–terminated string for equality: return true (non–zero) if the octets are equal, return false (zero) otherwise.

          hoedown_buffer              B;
          static const char *         str = "Hello World!";
          hoedown_buffer_init(&B, 1024, realloc, free, free);
          {
            hoedown_buffer_puts(&B, str);
            assert(0 != hoedown_buffer_eqs(&B, str));
          }
          hoedown_buffer_uninit(&B);

— Preprocessor Macro: int HOEDOWN_BUFEQSL (hoedown_buffer * buf, const char * str)

Optimized hoedown_buffer_eqs() of a string literal. It is meant to be used when str references a literal string, as in:

          hoedown_buffer              B;
          static const char *         str = "Hello World!";
          hoedown_buffer_init(&B, 1024, realloc, free, free);
          {
            hoedown_buffer_puts(&B, str);
            assert(0 != HOEDOWN_BUFEQSL(&B, "Hello World!"));
          }
          hoedown_buffer_uninit(&B);

— Function: int hoedown_buffer_prefix (const hoedown_buffer * buf, const char * prefix)

Compare the beginning of a buffer with a string: return zero if the octets are equal; return greater than zero if an octet in buf is found to be greater than the octet in prefix; return less than zero if an octet in buf is found to be less than the octet in prefix.

          hoedown_buffer              B;
          static const char *         str1 = "Hello World!";
          static const char *         str2 = "Hello";
          hoedown_buffer_init(&B, 1024, realloc, free, free);
          {
            hoedown_buffer_puts(&B, str1);
            assert(0 == hoedown_buffer_prefix(&B, str2));
          }
          hoedown_buffer_uninit(&B);

— Function: void hoedown_buffer_slurp (hoedown_buffer * buf, size_t size)

Remove a given number of bytes from the head of the buffer.

          hoedown_buffer              B;
          static const char *         str = "Hello World!";
          hoedown_buffer_init(&B, 1024, realloc, free, free);
          {
            hoedown_buffer_puts(&B, str);
            hoedown_buffer_slurp(&B, strlen("Hello "));
            assert(0 != hoedown_buffer_eqs(&B, "World!"));
          }
          hoedown_buffer_uninit(&B);

— Function: const char * hoedown_buffer_cstr (hoedown_buffer * buf)

Mutate the internal data area so that it valid as NUL-terminated C string. Return a pointer to the data area.

— Function: void hoedown_buffer_printf (hoedown_buffer * buf, const char * fmt, ...)

Formatted printing to a buffer.

          hoedown_buffer              B;
          static const char *         str1 = "Hello";
          static const char *         str2 = "World";
          hoedown_buffer_init(&B, 1024, realloc, free, free);
          {
            hoedown_buffer_printf(&B, "%s %s!", str1, str2);
            assert(0 != hoedown_buffer_eqs(&B, "Hello World!"));
          }
          hoedown_buffer_uninit(&B);

— Struct Typedef: hoedown_stack

Type of structures representing stacks of pointers. Instances of this type must be initialised by hoedown_stack_init() and finalised by hoedown_stack_uninit().

Basic allocation, initialisation and finalisation can be performed as:

          hoedown_stack          B;
          
          hoedown_stack_init(&B, 123);
          hoedown_stack_uninit(&B);

The data area of stack structures is allocated and reallocated with hoedown_realloc() and released with C Language Standard free().

— Function: void hoedown_stack_init (hoedown_stack * st, size_t initial_size)

Initialize an already allocated stack structures.

— Function: void hoedown_stack_uninit (hoedown_stack * st)

Free internal data of the stack.

— Function: void hoedown_stack_grow (hoedown_stack * st, size_t neosz)

Increase the allocated size to the given value.

— Function: void hoedown_stack_push (hoedown_stack * st, void * item)

Push an item to the top of the stack.

— Function: void * hoedown_stack_pop (hoedown_stack * st)

Retrieve and remove the item at the top of the stack. If the stack is empty: return NULL.

— Function: void * hoedown_stack_top (const hoedown_stack * st)

Retrieve the item at the top of the stack. If the stack is empty: return NULL.

— Function: void hoedown_escape_href (hoedown_buffer * ob, const uint8_t * data, size_t size)

Escape (part of) a URL inside HTML. Escape all the characters in the data memory block that cannot appear in a URL; append the result to the buffer ob.

          hoedown_buffer      B;
          const char *        str1 = "Father & Son";
          const char *        str2 = "Father%20&%20Son";
          hoedown_buffer_init(&B, 1024, realloc, free, free);
          {
            hoedown_escape_href(&B, (const uint8_t *)str1, strlen(str1));
            print_buffer(&B);
            assert(0 != hoedown_buffer_eqs(&B, str2));
          }
          hoedown_buffer_uninit(&B);

— Function: void hoedown_escape_html (hoedown_buffer * ob, const uint8_t * data, size_t size, int secure)

Escape HTML text from data and write the result in the buffer ob.

          hoedown_buffer      B;
          const char *        str1 = "Father & Son";
          const char *        str2 = "Father & Son";
          hoedown_buffer_init(&B, 1024, realloc, free, free);
          {
            hoedown_escape_html(&B, (const uint8_t *)str1, strlen(str1), 1);
            print_buffer(&B);
            assert(0 != hoedown_buffer_eqs(&B, str2));
          }
          hoedown_buffer_uninit(&B);

— Enum Typedef: hoedown_autolink_flags

Type of constants used to configure the behaviour of the autolink helper functions. The following constants are defined:

HOEDOWN_AUTOLINK_SHORT_DOMAINS

When checking the presence of a domain specification: do not enforce validation of a domain in the strict sense (with least one dot); so just make sure it's composed of valid domain characters and return the length of the the valid sequence.

— Function: int hoedown_autolink_is_safe (const uint8_t * data, size_t size)

Verify that a URL has a safe protocol. Assume data references a memory block holding a string of UTF-8 encoded characters. Return true (non–zero) if the prefix of the string matches one among:

          http://
          https://
          /
          #
          ftp://
          mailto:

case insensitively, and the first octet after the prefix represents an alphanumeric character; otherwise return false (zero).

— Function: size_t hoedown_autolink__www (size_t * rewind_p, hoedown_buffer * link, uint8_t * w_ptr, size_t input_offset, size_t input_len, hoedown_autolink_flags flags)

Find the limits of a WWW link in the input Markdown buffer.

This function assumes that:

• The input text is stored in a memory block as array of octets in UTF-8 encoding; the block is input_len octets wide.
• The pointer w_ptr references an octet in the input text at input_offset octets from the beginning.
• The pointer w_ptr references an octet representing the character w in UTF-8 encoding:

                 'w' == w_ptr[0]
  

• If input_offset is not zero (that is: w_ptr is not at the beginning of the input text): the octet w_ptr[-1] represents a space or a punctuation character according to the C Standard Library functions ispunct() and isspace():

                 ispunct(w_ptr[-1]) || isspace(w_ptr[-1])
  

This function scans the input text starting at w_ptr looking for a sequence of octets representing, in UTF-8 encoding, a web link. The sequence must begin with the prefix ‘www.’ (of which w_ptr[0] is the first ‘w’) followed by a string of octets representing:

• Alphanumeric characters according to the C Standard Library function isalnum().
• Colon characters ‘:’.
• Dot characters ‘.’.
• Dash characters ‘-’.

the string after ‘www.’ must contain at least one dot or one colon to be considered a valid web link.

If a valid web link is found:

• The string representing the link is appended to the buffer referenced by link, which must be already initialised.
• The number of octets to the left of w_ptr which are part of the web link, is stored in the location referenced by rewind_p. For this function: this value is always ‘0’, because w_ptr references the first octet in the link.
• The return value is the number of octets in the web link. This number is the offset to add to w_ptr to move it to the end of the link in the input text.

If a valid web link is not found: the return value is zero.

          char *              input_text   = \
             "the URL is www.hoedown.org/index.html, got it?";
          size_t              input_len    = strlen(input_text);
          size_t              input_offset = strlen("the URL is ");
          
          uint8_t *           w_ptr = (uint8_t*)(input_text+input_offset);
          
          hoedown_buffer      link;
          size_t              offset_delta;
          size_t              rewind;
          
          assert('w' == input_text[input_offset]);
          assert('w' == w_ptr[0]);
          
          hoedown_buffer_init(&link, 1024, realloc, free, free);
          {
            offset_delta = hoedown_autolink__www(&rewind, &link,
               w_ptr, input_offset, input_len, 0);
            assert(strlen("www.hoedown.org/index.html") == offset_delta);
            assert(0 == rewind);
            assert(hoedown_buffer_eqs(&link, "www.hoedown.org/index.html"));
            assert(0 == strcmp((char *)(w_ptr+offset_delta), ", got it?"));
          }
          hoedown_buffer_uninit(&link);

— Function: size_t hoedown_autolink__email (size_t * rewind_p, hoedown_buffer * link, uint8_t * at_ptr, size_t input_offset, size_t input_len, hoedown_autolink_flags flags)

Find the limits of an email address link in the input Markdown buffer.

This function assumes that:

• The input text is stored in a memory block as array of octets in UTF-8 encoding; the block is input_len octets wide.
• The pointer at_ptr references an octet in the input text at input_offset octets from the beginning.
• The pointer at_ptr references an octet representing the character @ in UTF-8 encoding:

                 '@' == at_ptr[0]
  

• If input_offset is not zero (that is: at_ptr is not at the beginning of the input text): the octets before at_ptr represent alphanumeric characters (according to the C Standard Library function isalnum()) or characters in the set ‘.+-_’.

This function scans the input text starting at at_ptr, both in the left and right directions, looking for a sequence of octets representing, in UTF-8 encoding, an email address. The sequence must begin, to the left of the ‘@’ character, with a non–empty prefix composed of:

• Alphanumeric characters according to the C Standard Library function isalnum().
• Characters in the set ‘.+-_’.

the sequence must end, to the right of the ‘@’ character, with a non–empty suffix composed of:

• Alphanumeric characters according to the C Standard Library function isalnum().
• Characters in the set ‘.-_’.

the suffix must represent a valid host name.

If a valid email address is found:

• The string representing the link is appended to the buffer referenced by link, which must be already initialised.
• The number of octets to the left of at_ptr which are part of the address, is stored in the location referenced by rewind_p.
• The return value is the number of octets in the email address at the right of the at_ptr pointer. This number is the offset to add to at_ptr to move it to the end of the address in the input text.

If a valid email address is not found: the return value is zero.

          char *              input_text   = \
            "the address is kate.beckinsale@underworld.earth, got it?";
          size_t              input_len    = strlen(input_text);
          size_t              input_offset = \
            strlen("the address is kate.beckinsale");
          
          uint8_t *           at_ptr = (uint8_t *)(input_text+input_offset);
          
          hoedown_buffer      link;
          size_t              offset_delta;
          size_t              rewind;
          
          assert('@' == input_text[input_offset]);
          assert('@' == at_ptr[0]);
          
          hoedown_buffer_init(&link, 1024, realloc, free, free);
          {
            offset_delta = hoedown_autolink__email(&rewind, &link,
               at_ptr, input_offset, input_len, 0);
            assert(strlen("@underworld.earth") == offset_delta);
            assert(strlen("kate.beckinsale") == rewind);
            assert(hoedown_buffer_eqs(&link,
               "kate.beckinsale@underworld.earth"));
            assert(rewind + offset_delta == link.size);
            assert(0 == strcmp((char *)(at_ptr+offset_delta), ", got it?"));
          }
          hoedown_buffer_uninit(&link);

— Function: size_t hoedown_autolink__url (size_t * rewind_p, hoedown_buffer * link, uint8_t * colon_ptr, size_t input_offset, size_t input_len, hoedown_autolink_flags flags)

Find the limits of a URL in the input Markdown buffer.

This function assumes that:

• The input text is stored in a memory block as array of octets in UTF-8 encoding; the block is input_len octets wide.
• The pointer colon_ptr references an octet in the input text at input_offset octets from the beginning.
• The pointer colon_ptr references an octet representing the character : in UTF-8 encoding:

                 ':' == colon_ptr[0]
  

• If input_offset is not zero (that is: colon_ptr is not at the beginning of the input text): the octets to the left of colon_ptr must represent alphabetic characters according to the C Standard Library function isalpha().

This function scans the input text starting at colon_ptr, both in the left and right directions, looking for a sequence of octets representing, in UTF-8 encoding, a URL. The sequence must begin, to the left of the colon character, with a non–empty prefix composed by alphabetic characters, according to the C Standard Library function isalpha(). The sequence must end, to the right of the colon character, with a non–empty suffix composed of:

• A sequence of 2 slash characters ‘/’.
• A valid domain name composed of:
  • Alphanumeric characters according to the C Standard Library function isalnum().
  • Colon characters ‘:’.
  • Dot characters ‘.’.
  • Dash characters ‘-’.

If a valid URL is found:

• The string representing the URL is appended to the buffer referenced by link, which must be already initialised.
• The number of octets to the left of colon_ptr which are part of the URL, is stored in the location referenced by rewind_p.
• The return value is the number of octets in the URL to the right of colon_ptr. This number is the offset to add to colon_ptr to move it to the end of the URL in the input text.

If a valid URL is not found: the return value is zero.

This function honours the ‘HOEDOWN_AUTOLINK_SHORT_DOMAINS’ flag in the flags argument.

          char *              input_text   = \
             "the URL is http://www.hoedown.org/index.html, got it?";
          size_t              input_len    = strlen(input_text);
          size_t              input_offset = strlen("the URL is http");
          
          uint8_t *           colon_ptr = \
             (uint8_t *)(input_text+input_offset);
          
          hoedown_buffer      link;
          size_t              offset_delta;
          size_t              rewind;
          
          assert(':' == input_text[input_offset]);
          assert(':' == colon_ptr[0]);
          
          hoedown_buffer_init(&link, 1024, realloc, free, free);
          {
            offset_delta = hoedown_autolink__url(&rewind, &link,
               colon_ptr, input_offset, input_len, 0);
            assert(strlen("://www.hoedown.org/index.html") == offset_delta);
            assert(4 == rewind);
            assert(hoedown_buffer_eqs(&link,
               "http://www.hoedown.org/index.html"));
            assert(rewind + offset_delta == link.size);
            assert(0 == strcmp((char *)(colon_ptr+offset_delta),
                               ", got it?"));
          }
          hoedown_buffer_uninit(&link);

     #include <hoedown/buffer.h>
     #include <hoedown/document.h>
     #include <hoedown/html.h>
     
     void
     html_rend (const char * in_str, const char * ou_str)
     {
       hoedown_buffer                B;
       hoedown_document *            D;
       hoedown_renderer *            R;
     
       hoedown_buffer_init(&B, 1024, realloc, free, free);
       R = hoedown_html_renderer_new(0, 0);
       D = hoedown_document_new(R, 0, 16);
       {
         hoedown_document_render(D, &B,
            (const uint8_t *)in_str, strlen(in_str));
         /* Here the HTML output is in B.*/
       }
       hoedown_document_free(D);
       hoedown_html_renderer_free(R);
       hoedown_buffer_uninit(&B);
     }

     char *  in_str = "Hello World!";
     char *  ou_str = "<p>Hello World!</p>\n";
     html_rend (in_str, ou_str);

— Opaque Struct Typedef: hoedown_document

Type of structure used to represent the processing of a Markdown document. Instances of this type are allocated with hoedown_document_new() and released with hoedown_document_free().

— Struct Typedef: hoedown_renderer_data

Type of structure used to represent custom state of Markdown processing. It has the following public fields:

void * opaque

A pointer that can be used for anything by client code.

Pointers to a structure of this type are handed as last argument to all the document rendering callbacks registered in instances of hoedown_renderer. In particular: the callback doc_header can be used to initialise this state, and the callback doc_footer can be used to finalise it. Custom renderer data structure, for details on the renderer.

— Function: hoedown_document * hoedown_document_new (const hoedown_renderer * renderer, hoedown_extensions extensions, size_t max_nesting)

Allocate a new document processor instance.

The renderer argument must be a pointer to an renderer instance, for example the built–in HTML renderers created by hoedown_html_renderer_new() and hoedown_html_toc_renderer_new() (see lib html renderer).

The argument extensions must be an OR combination of the enumeration constants hoedown_extensions (see Markdown processing extensions).

The argument max_nesting represents the maximum nesting level of Markdown blocks. This limit exists for security purposes: it avoids malicious input to cause runaways of nested function calls in an attempt to cripple the internal state of the parser. Most likely, setting this operand to 16 is fine for all the legitimate input documents.

— Function: void hoedown_document_free (hoedown_document * doc)

Deallocate a document processor instance.

— Function: void hoedown_document_render (hoedown_document * doc, hoedown_buffer * ob, const uint8_t * data, size_t size)
— Function: void hoedown_document_render_inline (hoedown_document * doc, hoedown_buffer * ob, const uint8_t * data, size_t size)

Render regular Markdown or inline Markdown using the document processor.

The argument doc must reference an already initialised Markdown document renderer. The argument ob must reference an already initialised buffer to which the output will be appended. The argument data must reference an array of size octets containing the input Markdown text.

The input Markdown text is processed with the following rules:

• The input text may optionally start with a UTF-8 Byte Order Mark (BOM), which is the sequence of 3 octets: ‘0xEF’, ‘0xBB’, ‘0xBF’. If present: this BOM is just skipped.
• Lines in the input text are terminated by ‘\n’ or ‘\r\n’; such line endings are normalised in the output into a single ‘\n’ character.
• Tabulation characters ‘\t’ (Unicode code point ‘0x09’) are expanded to 4 spaces in the output.

— Enum Typedef: hoedown_extensions

Enumeration typedef representing a combination of extensions to Markdown text processing. It defines the following constants:

• Block–level extensions:

  HOEDOWN_EXT_TABLES

  
  

  HOEDOWN_EXT_FENCED_CODE

  
  

  HOEDOWN_EXT_FOOTNOTES

• Span–level extensions:

  HOEDOWN_EXT_AUTOLINK

  
  

  HOEDOWN_EXT_STRIKETHROUGH

  
  

  HOEDOWN_EXT_UNDERLINE

  
  

  HOEDOWN_EXT_HIGHLIGHT

  
  

  HOEDOWN_EXT_QUOTE

  
  

  HOEDOWN_EXT_SUPERSCRIPT

  
  

  HOEDOWN_EXT_MATH

• Other flags:

  HOEDOWN_EXT_NO_INTRA_EMPHASIS

  
  

  HOEDOWN_EXT_SPACE_HEADERS

  
  

  HOEDOWN_EXT_MATH_EXPLICIT

• Negative flags:

  HOEDOWN_EXT_DISABLE_INDENTED_CODE

— Preprocessor Constant: HOEDOWN_EXT_BLOCK

An OR combination of the following constants:

          HOEDOWN_EXT_TABLES
          HOEDOWN_EXT_FENCED_CODE
          HOEDOWN_EXT_FOOTNOTES

— Preprocessor Constant: HOEDOWN_EXT_SPAN

An OR combination of the following constants:

          HOEDOWN_EXT_AUTOLINK
          HOEDOWN_EXT_STRIKETHROUGH
          HOEDOWN_EXT_UNDERLINE
          HOEDOWN_EXT_HIGHLIGHT
          HOEDOWN_EXT_QUOTE
          HOEDOWN_EXT_SUPERSCRIPT
          HOEDOWN_EXT_MATH

— Preprocessor Constant: HOEDOWN_EXT_FLAGS

An OR combination of the following constants:

          HOEDOWN_EXT_NO_INTRA_EMPHASIS
          HOEDOWN_EXT_SPACE_HEADERS
          HOEDOWN_EXT_MATH_EXPLICIT

— Preprocessor Constant: HOEDOWN_EXT_NEGATIVE

An OR combination of the following constants:

          HOEDOWN_EXT_DISABLE_INDENTED_CODE

— Struct Typedef: hoedown_renderer

Data structure typedef used to represent output renderers. Instances of this type must be dynamically allocated; the structure definition contains both public fields and private fields. When a struct field is unused: it must be set to NULL.

The following fields are defined:

blockcode

Block level callback; when set to NULL the block is skipped.

blockquote

Block level callback; when set to NULL the block is skipped.

header

Block level callback; when set to NULL the block is skipped.

hrule

Block level callback; when set to NULL the block is skipped.

list

Block level callback; when set to NULL the block is skipped.

listitem

Block level callback; when set to NULL the block is skipped.

paragraph

Block level callback; when set to NULL the block is skipped.

table

Block level callback; when set to NULL the block is skipped.

table_header

Block level callback; when set to NULL the block is skipped.

table_body

Block level callback; when set to NULL the block is skipped.

table_row

Block level callback; when set to NULL the block is skipped.

table_cell

Block level callback; when set to NULL the block is skipped.

footnotes

Block level callback; when set to NULL the block is skipped.

footnote_def

Block level callback; when set to NULL the block is skipped.

blockhtml

Block level callback; when set to NULL the block is skipped.

autolink

Span level callback; when set to NULL or set to a function pointer returning 0: the span is printed verbatim.

codespan

Span level callback; when set to NULL or set to a function pointer returning 0: the span is printed verbatim.

double_emphasis

Span level callback; when set to NULL or set to a function pointer returning 0: the span is printed verbatim.

emphasis

Span level callback; when set to NULL or set to a function pointer returning 0: the span is printed verbatim.

underline

Span level callback; when set to NULL or set to a function pointer returning 0: the span is printed verbatim.

highlight

Span level callback; when set to NULL or set to a function pointer returning 0: the span is printed verbatim.

quote

Span level callback; when set to NULL or set to a function pointer returning 0: the span is printed verbatim.

image

Span level callback; when set to NULL or set to a function pointer returning 0: the span is printed verbatim.

linebreak

Span level callback; when set to NULL or set to a function pointer returning 0: the span is printed verbatim.

link

Span level callback; when set to NULL or set to a function pointer returning 0: the span is printed verbatim.

triple_emphasis

Span level callback; when set to NULL or set to a function pointer returning 0: the span is printed verbatim.

strikethrough

Span level callback; when set to NULL or set to a function pointer returning 0: the span is printed verbatim.

superscript

Span level callback; when set to NULL or set to a function pointer returning 0: the span is printed verbatim.

footnote_ref

Span level callback; when set to NULL or set to a function pointer returning 0: the span is printed verbatim.

math

Span level callback; when set to NULL or set to a function pointer returning 0: the span is printed verbatim.

raw_html

Span level callback; when set to NULL or set to a function pointer returning 0: the span is printed verbatim.

entity

Low level callback; when set to NULL: copy the input directly into the output.

normal_text

Low level callback; when set to NULL: copy the input directly into the output.

doc_header

When set to NULL: no document header is generated.

doc_footer

When set to NULL: no document footer is generated.

— Callback Signature: void blockcode (hoedown_buffer * ob, const hoedown_buffer * text, const hoedown_buffer * lang, const hoedown_renderer_data * data)

Callbacks used to render code blocks:

are set in the field blockcode of structures of type howdown_renderer.

Output text must be appended to the output buffer ob. The pointer data references a custom rendering data.

— Callback Signature: void blockquote (hoedown_buffer * ob, const hoedown_buffer * content, const hoedown_renderer_data * data)

Callbacks used to render ???:

are set in the field blockquote of structures of type howdown_renderer.

Output text must be appended to the output buffer ob. The pointer data references a custom rendering data.

— Callback Signature: void header (hoedown_buffer * ob, const hoedown_buffer * content, int level, const hoedown_renderer_data * data)

Output text must be appended to the output buffer ob. The pointer data references a custom rendering data.

— Callback Signature: void hrule (hoedown_buffer * ob, const hoedown_renderer_data * data)

Output text must be appended to the output buffer ob. The pointer data references a custom rendering data.

— Enum Typedef: hoedown_list_flags

Enumeration typedef for constants describing numbered lists. It defines the following constants:

HOEDOWN_LIST_ORDERED

HOEDOWN_LI_BLOCK

‘<li>’ containing block data.

Bitwise OR compositions of these constants are used as argument to the list and listitem renderer callbacks.

— Callback Signature: void list (hoedown_buffer * ob, const hoedown_buffer * content, hoedown_list_flags flags, const hoedown_renderer_data * data)

Output text must be appended to the output buffer ob. The pointer data references a custom rendering data.

— Callback Signature: void listitem (hoedown_buffer * ob, const hoedown_buffer * content, hoedown_list_flags flags, const hoedown_renderer_data * data)

Output text must be appended to the output buffer ob. The pointer data references a custom rendering data.

— Callback Signature: void paragraph (hoedown_buffer * ob, const hoedown_buffer * content, const hoedown_renderer_data * data)

Output text must be appended to the output buffer ob. The pointer data references a custom rendering data.

— Enum Typedef: hoedown_table_flags

Enumeration typedef for constants describing tables. It defines the following constants:

HOEDOWN_TABLE_ALIGN_LEFT

HOEDOWN_TABLE_ALIGN_RIGHT

HOEDOWN_TABLE_ALIGN_CENTER

HOEDOWN_TABLE_ALIGNMASK

HOEDOWN_TABLE_HEADER

Bitwise OR compositions of these constants are used as argument to the table_cell renderer callback.

— Callback Signature: void table (hoedown_buffer * ob, const hoedown_buffer * content, const hoedown_renderer_data * data)

Output text must be appended to the output buffer ob. The pointer data references a custom rendering data.

— Callback Signature: void table_header (hoedown_buffer * ob, const hoedown_buffer * content, const hoedown_renderer_data * data)

Output text must be appended to the output buffer ob. The pointer data references a custom rendering data.

— Callback Signature: void table_body (hoedown_buffer * ob, const hoedown_buffer * content, const hoedown_renderer_data * data)

Output text must be appended to the output buffer ob. The pointer data references a custom rendering data.

— Callback Signature: void table_row (hoedown_buffer * ob, const hoedown_buffer * content, const hoedown_renderer_data * data)

Output text must be appended to the output buffer ob. The pointer data references a custom rendering data.

— Callback Signature: void table_cell (hoedown_buffer * ob, const hoedown_buffer * content, hoedown_table_flags flags, const hoedown_renderer_data * data)

Output text must be appended to the output buffer ob. The pointer data references a custom rendering data.

— Callback Signature: void footnotes (hoedown_buffer * ob, const hoedown_buffer * content, const hoedown_renderer_data * data)

Output text must be appended to the output buffer ob. The pointer data references a custom rendering data.

— Callback Signature: void footnote_def (hoedown_buffer * ob, const hoedown_buffer * content, unsigned int num, const hoedown_renderer_data * data)

Output text must be appended to the output buffer ob. The pointer data references a custom rendering data.

— Callback Signature: void blockhtml (hoedown_buffer * ob, const hoedown_buffer * text, const hoedown_renderer_data * data)

Output text must be appended to the output buffer ob. The pointer data references a custom rendering data.

— Enum Typedef: hoedown_autolink_type

Enumeration typedef for constants describing tables. It defines the following constants:

HOEDOWN_AUTOLINK_NONE

HOEDOWN_AUTOLINK_NORMAL

HOEDOWN_AUTOLINK_EMAIL

Bitwise OR compositions of these constants are used as argument to the autolink renderer callback.

— Callback Signature: int autolink (hoedown_buffer * ob, const hoedown_buffer *link, hoedown_autolink_type type, const hoedown_renderer_data * data)

Output text must be appended to the output buffer ob. The pointer data references a custom rendering data.

— Callback Signature: int codespan (hoedown_buffer * ob, const hoedown_buffer * text, const hoedown_renderer_data * data)

Output text must be appended to the output buffer ob. The pointer data references a custom rendering data.

— Callback Signature: int double_emphasis (hoedown_buffer * ob, const hoedown_buffer * content, const hoedown_renderer_data * data)

Output text must be appended to the output buffer ob. The pointer data references a custom rendering data.

— Callback Signature: int emphasis (hoedown_buffer * ob, const hoedown_buffer * content, const hoedown_renderer_data * data)

Output text must be appended to the output buffer ob. The pointer data references a custom rendering data.

— Callback Signature: int underline (hoedown_buffer * ob, const hoedown_buffer * content, const hoedown_renderer_data * data)

Output text must be appended to the output buffer ob. The pointer data references a custom rendering data.

— Callback Signature: int highlight (hoedown_buffer * ob, const hoedown_buffer * content, const hoedown_renderer_data * data)

Output text must be appended to the output buffer ob. The pointer data references a custom rendering data.

— Callback Signature: int quote (hoedown_buffer * ob, const hoedown_buffer * content, const hoedown_renderer_data * data)

Output text must be appended to the output buffer ob. The pointer data references a custom rendering data.

— Callback Signature: int image (hoedown_buffer * ob, const hoedown_buffer * link, const hoedown_buffer * title, const hoedown_buffer * alt, const hoedown_renderer_data * data)

Output text must be appended to the output buffer ob. The pointer data references a custom rendering data.

— Callback Signature: int linebreak (hoedown_buffer * ob, const hoedown_renderer_data * data)

Output text must be appended to the output buffer ob. The pointer data references a custom rendering data.

— Callback Signature: int link (hoedown_buffer * ob, const hoedown_buffer * content, const hoedown_buffer * link, const hoedown_buffer * title, const hoedown_renderer_data * data)

Output text must be appended to the output buffer ob. The pointer data references a custom rendering data.

— Callback Signature: int triple_emphasis (hoedown_buffer * ob, const hoedown_buffer * content, const hoedown_renderer_data * data)

Output text must be appended to the output buffer ob. The pointer data references a custom rendering data.

— Callback Signature: int strikethrough (hoedown_buffer * ob, const hoedown_buffer * content, const hoedown_renderer_data * data)

Output text must be appended to the output buffer ob. The pointer data references a custom rendering data.

— Callback Signature: int superscript (hoedown_buffer * ob, const hoedown_buffer * content, const hoedown_renderer_data * data)

Output text must be appended to the output buffer ob. The pointer data references a custom rendering data.

— Callback Signature: int footnote_ref (hoedown_buffer * ob, unsigned int num, const hoedown_renderer_data * data)

Output text must be appended to the output buffer ob. The pointer data references a custom rendering data.

— Callback Signature: int math (hoedown_buffer * ob, const hoedown_buffer * text, int displaymode, const hoedown_renderer_data * data)

Output text must be appended to the output buffer ob. The pointer data references a custom rendering data.

— Callback Signature: int raw_html (hoedown_buffer * ob, const hoedown_buffer * text, const hoedown_renderer_data * data)

Output text must be appended to the output buffer ob. The pointer data references a custom rendering data.

— Callback Signature: void entity (hoedown_buffer * ob, const hoedown_buffer * text, const hoedown_renderer_data * data)

Output text must be appended to the output buffer ob. The pointer data references a custom rendering data.

— Callback Signature: void normal_text (hoedown_buffer * ob, const hoedown_buffer * text, const hoedown_renderer_data * data)

Output text must be appended to the output buffer ob. The pointer data references a custom rendering data.

— Callback Signature: void doc_header (hoedown_buffer * ob, int inline_render, const hoedown_renderer_data * data)

Signature of callback functions used to render document headers; this callback is called before processing the input document. When the corresponding field in the hoedown_renderer is set to NULL: no document footer is generated.

Output text must be appended to the output buffer ob. The argument inline_render is true if this callback has been called while rendering an inline Markdown document; otherwise it is false. The pointer data references a custom rendering data.

— Callback Signature: void doc_footer (hoedown_buffer * ob, int inline_render, const hoedown_renderer_data * data)

Signature of callback functions used to render document footers; this callback is called after processing the input document. When the corresponding field in the hoedown_renderer is set to NULL: no document footer is generated.

Output text must be appended to the output buffer ob. The argument inline_render is true if this callback has been called while rendering an inline Markdown document; otherwise it is false. The pointer data references a custom rendering data.

     void
     html_rend (const char * in_str, const char * ou_str)
     {
       hoedown_buffer                B;
       hoedown_document *            D;
       hoedown_renderer *            R;
     
       hoedown_buffer_init(&B, 1024, realloc, free, free);
       R = hoedown_html_renderer_new(0, 0);
       D = hoedown_document_new(R, 0, 16);
       {
         hoedown_document_render(D, &B,
            (const uint8_t *)in_str, strlen(in_str));
         assert(hoedown_buffer_eqs(&B, ou_str));
       }
       hoedown_document_free(D);
       hoedown_html_renderer_free(R);
       hoedown_buffer_uninit(&B);
     }

     /* Simple text. */
     {
       char *  in_str = "Hello World!";
       char *  ou_str = "<p>Hello World!</p>\n";
       html_rend (in_str, ou_str);
     }
     
     /* Code markup. */
     {
       char *  in_str = "```Hello World!```";
       char *  ou_str = "<p><code>Hello World!</code></p>\n";
       html_rend (in_str, ou_str);
     }
     
     /* Emphasis markup. */
     {
       char *  in_str = "*Hello World!*";
       char *  ou_str = "<p><em>Hello World!</em></p>\n";
       html_rend (in_str, ou_str);
     }
     
     /* Emphasis markup. */
     {
       char *  in_str = "[Hello World!]()";
       char *  ou_str = \
         "<p><a href=\"http://localhost/\">Hello World!</a></p>\n";
       html_rend (in_str, ou_str);
     }

— Enum Typedef: hoedown_html_flags

Enumeration typedef used to configure the HTML renderer. It defines the following symbols:

HOEDOWN_HTML_SKIP_HTML

HOEDOWN_HTML_ESCAPE

HOEDOWN_HTML_HARD_WRAP

HOEDOWN_HTML_USE_XHTML

— Function: hoedown_renderer * hoedown_html_renderer_new (hoedown_html_flags render_flags, int nesting_level)

Allocate a regular HTML renderer.

The argument nesting_level is the maximum header nesting level to include in the table of contents: when set to ‘1’ only the top headers are included (‘<h1>’); when set to ‘2’ only the top headers and the subheaders are included (‘<h1>’ and ‘<h2>’); and so on. Here “inclusion in the table of contents” means that ‘<h1>’ and similar markups are generated with the anchor:

          <h1 id="toc_0">Heading</h1>

so that the table of contents can reference them using the fragment identifier:

          <a href="#toc_0">Heading</a>

— Function: hoedown_renderer * hoedown_html_toc_renderer_new (int nesting_level)

Like hoedown_html_renderer_new(), but the returned renderer produces the “Table of Contents” rather than a normal document.

The argument nesting_level is the maximum header nesting level to include in the table of contents: when set to ‘1’ only the top headers are included (‘<h1>’); when set to ‘2’ only the top headers and the subheaders are included (‘<h1>’ and ‘<h2>’); and so on.

We must be careful to generate a table of contents with nesting_level less than or equal to the value used when generating the full HTML document.

Rendering tables of contents, for examples of generating table of contents.

— Function: void hoedown_html_renderer_free (hoedown_renderer * renderer)

Deallocate an HTML renderer.

— Function: void hoedown_html_smartypants (hoedown_buffer * ob, const uint8_t * data, size_t size)

Take the memory block referenced by data, containing size octets, and process it as HTML text; the resulting output is appended to the buffer ob.

Translate plain ASCII punctuation characters into “smart” typographic punctuation HTML entities. SmartyPants performs the following transformations:

• Straight quotes into “curly” quote HTML entities. The input text:

                 <p>"Hello" 'World'!</p>
  

  is converted to:

                 <p>&ldquo;Hello&rdquo; &lsquo;World&rsquo;!</p>
  

• Backticks–style quotes into curly quote HTML entities. The input text:

                 <p>``Hello World!''</p>
  

  is converted to:

                 <p>&ldquo;Hello World!&rdquo;</p>
  

• Dashes (‘--’ and ‘---’) into en- and em-dash entities. The input text:

                 <p>Trouble--maker---that is what you are!</p>
  

  is converted to:

                 <p>Trouble&ndash;maker&mdash;that is what you are!</p>
  

• Three consecutive dots (‘...’) into an ellipsis entity.

— Enum Typedef: hoedown_html_tag

Enumeration type definitions used to qualify HTML markups. It includes the following symbols:

OEDOWN_HTML_TAG_NONE

Defined to be ‘0’. It means the analysed text is not a HTML markup.

HOEDOWN_HTML_TAG_OPEN,

It means the analysed text is not an opening HTML markup.

HOEDOWN_HTML_TAG_CLOSE

It means the analysed text is not a closing HTML markup.

— Function: hoedown_html_tag hoedown_html_is_tag (const uint8_t * data, size_t size, const char * tagname)

Check if data starts with a specific HTML markup whose name is tagname; return the markup type or ‘OEDOWN_HTML_TAG_NONE’ if the text is not a markup.

          static const char *  str = "Hello World!";
          assert(HOEDOWN_HTML_TAG_NONE == \
            hoedown_html_is_tag((const uint8_t *) str, strlen(str), "p"));
          
          static const char *  str = "<p>Hello World!</p>";
          assert(HOEDOWN_HTML_TAG_OPEN == \
            hoedown_html_is_tag((const uint8_t *) str, strlen(str), "p"));
          
          static const char *  str = "</p><p>Hello World!</p>";
          assert(HOEDOWN_HTML_TAG_CLOSE == \
            hoedown_html_is_tag((const uint8_t *) str, strlen(str), "p"));

     void
     print_buffer (hoedown_buffer * B)
     {
       fwrite(B->data, B->size, 1, stderr);
       fprintf(stderr, "\n");
     }
     static void
     html_toc_rend (const char * in_str, int nesting_level)
     {
       hoedown_buffer                B;
       hoedown_document *            D;
       hoedown_renderer *            R;
     
       hoedown_buffer_init(&B, 1024, realloc, free, free);
       R = hoedown_html_toc_renderer_new(nesting_level);
       D = hoedown_document_new(R, 0, 16);
       {
         hoedown_document_render(D, &B, (const uint8_t *)in_str, strlen(in_str));
         print_buffer(&B);
       }
       hoedown_document_free(D);
       hoedown_html_renderer_free(R);
       hoedown_buffer_uninit(&B);
     }