lws-md.h

Go to the documentation of this file.

/*
 * libwebsockets - small server side websockets and web server implementation
 *
 * Copyright (C) 2010 - 2026 Andy Green <andy@warmcat.com>
 *
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to
 * deal in the Software without restriction, including without limitation the
 * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
 * sell copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice shall be included in
 * all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
 * IN THE SOFTWARE.
 *
 * Streaming markdown to structured events renderer
 *
 * Hostile-input-hardened, alloc-free, streaming renderer for the well-behaved
 * markdown subset used by readme and blog content: headings, paragraphs,
 * fenced and indented code blocks, blockquotes, lists, pipe tables, rules,
 * inline code / emphasis / strong, links, images and autolinks.
 *
 * Markdown input is never passed through as markup: the driver only issues
 * structural events from a closed vocabulary plus data events for text, urls,
 * image alt text and fence info strings.  All markup synthesis and all
 * security decisions about data bytes belong to the sink; the stock html sink
 * (lws_md_html_t) entity-escapes everything and applies a url scheme policy,
 * producing strict-CSP-compatible output with no inline styles or scripts.
 *
 * Structure that cannot be decided without a line of lookahead (is this the
 * table header row?) is held in a side buffer and the decision deferred until
 * the start of the next line; giving up on the decision past the hold cap
 * reclassifies the held line as text, it never drops content.
 */
 
#if !defined(LMD_LINE_MAX)
#define LMD_LINE_MAX                      8192
#endif
#if !defined(LMD_HOLD_MAX)
#define LMD_HOLD_MAX                      LMD_LINE_MAX
#endif
#if !defined(LMD_INFO_MAX)
#define LMD_INFO_MAX                      32
#endif
#if !defined(LMD_NEST_MAX)
#define LMD_NEST_MAX                      24
#endif
#if !defined(LMD_TEXT_PIECE)
#define LMD_TEXT_PIECE                    256
#endif

typedef enum {
        LMD_EL_NONE,            
 
        LMD_EL_H,               
        LMD_EL_P,               
        LMD_EL_BQ,              
        LMD_EL_UL,              
        LMD_EL_OL,              
        LMD_EL_LI,              
        LMD_EL_TABLE,           
        LMD_EL_TR,              
        LMD_EL_CELL,            
        LMD_EL_HR,              
        LMD_EL_CODE,            
 
        /* inline */
 
        LMD_EL_EM,              
        LMD_EL_STRONG,          
        LMD_EL_CS,              
        LMD_EL_A,               
        LMD_EL_IMG,             
} lws_md_el_t;

typedef enum {
        LMD_EV_TEXT = 1,        
        LMD_EV_URL,             
        LMD_EV_ALT,             
        LMD_EV_INFO,            
        LMD_EV_BEGIN,           
        LMD_EV_END,             
} lws_md_ev_t;

typedef lws_stateful_ret_t (*lws_md_ev_cb)(void *user, lws_md_ev_t ev,
                                           lws_md_el_t el, unsigned int aux,
                                           const uint8_t *data, size_t len);

typedef struct lws_md_ctx {
        lws_md_ev_cb            cb;
        void                    *user;
 
        /* private below */
 
        uint32_t                evseq;  /* issue index within the txn in flight */
        uint32_t                evdone; /* watermark of accepted events */
 
        uint8_t                 txn;    /* 0 idle, 1 line, 2 hold flush, 3 finish */
        uint8_t                 in_link;/* inside link text: no nested links */
 
        uint8_t                 para;   /* paragraph open */
        uint8_t                 list;   /* 0 none, else LMD_EL_UL / _OL */
        uint8_t                 li;     /* inside a list item */
        uint8_t                 table;  /* inside a table */
        uint8_t                 hold;   /* line held for table decision */
        uint8_t                 bq;     /* open blockquote depth */
        uint8_t                 code_ind;/* inside an indented code block */
 
        uint8_t                 fence;  /* inside a fenced code block */
        uint8_t                 fchr;   /* the fence character */
        uint8_t                 flen;   /* the opening fence length */
        uint8_t                 fmatch; /* fence chars matched at line start */
        uint8_t                 fbol;   /* at start of a fence body line */
        uint8_t                 fclose; /* swallowing a closing fence line */
 
        uint8_t                 over;   /* past the cap, streaming a line */
 
        uint8_t                 fin_n;  /* finish: closers remaining */
        uint8_t                 fin_list[3 + 2 * LMD_NEST_MAX];
 
        uint32_t                llen;   /* staged line length */
        uint32_t                hlen;   /* held line length */
 
        uint32_t                infolen;
        char                    info[LMD_INFO_MAX];
 
        char                    line[LMD_LINE_MAX];
        char                    holdb[LMD_HOLD_MAX];
} lws_md_ctx_t;

LWS_VISIBLE LWS_EXTERN int
lws_md_construct(lws_md_ctx_t *ctx, lws_md_ev_cb cb, void *user);

LWS_VISIBLE LWS_EXTERN lws_stateful_ret_t
lws_md_parse(lws_md_ctx_t *ctx, const uint8_t **buf, size_t *len);

LWS_VISIBLE LWS_EXTERN lws_stateful_ret_t
lws_md_finish(lws_md_ctx_t *ctx);
 
#if !defined(LMD_URL_MAX)
#define LMD_URL_MAX                       768
#endif
#if !defined(LMD_HTML_BUF)
#define LMD_HTML_BUF                      4096
#endif
 
typedef lws_stateful_ret_t (*lws_md_write_cb)(void *user, const uint8_t *buf,
                                              size_t len);

typedef size_t (*lws_md_resolve_cb)(void *user, int is_image,
                                    const char *url, size_t len,
                                    char *dest, size_t dest_len);
 
#if defined(LWS_WITH_HL)
#include "lws-hl.h"
#endif

typedef struct lws_md_html {
        /* private */
        lws_md_write_cb         wc;
        void                    *user;
        lws_md_resolve_cb       resolve;
        void                    *resolve_user;
 
#if defined(LWS_WITH_HL)
        lws_hl_ctx_t            hlctx;
        lws_hl_html_t           hlhtml;
        uint8_t                 hl_on;  /* bridging a fenced code block */
        uint8_t                 hl_fin; /* hl finish issued */
        uint8_t                 hl_closed;
        uint8_t                 hl_hold; /* a byte held for the tokenizer */
        uint8_t                 hl_holdb;
        size_t                  hl_off; /* fed offset into current TEXT */
#endif
 
        char                    url[LMD_URL_MAX];
        size_t                  url_len;
        uint8_t                 pending;        /* 0 none, 1 A, 2 IMG */
        uint8_t                 a_open;         /* the <a...> tag flushed */
        uint8_t                 alt_open;       /* inside the img alt attr */
        uint8_t                 code_open;      /* inside a fence */
        uint8_t                 pre_done;       /* the <pre><code> flushed */
        char                    info[LMD_INFO_MAX];
        uint8_t                 infolen;
 
        char                    buf[LMD_HTML_BUF];
        size_t                  buflen;
} lws_md_html_t;

LWS_VISIBLE LWS_EXTERN int
lws_md_html_construct(lws_md_html_t *h, lws_md_write_cb wc, void *user,
                      lws_md_resolve_cb resolve, void *resolve_user);

LWS_VISIBLE LWS_EXTERN lws_stateful_ret_t
lws_md_html_event(void *user, lws_md_ev_t ev, lws_md_el_t el,
                  unsigned int aux, const uint8_t *data, size_t len);

LWS_VISIBLE LWS_EXTERN lws_stateful_ret_t
lws_md_html_close(lws_md_html_t *h);