lws-hl.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 syntax highlighting tokenizer
 *
 * Hostile-input-hardened, alloc-free, streaming tokenizer for producing
 * syntax highlighting markup from arbitrary source text.  Input is fed in
 * fragments of any size (including 0 or 1 bytes); classified token pieces
 * are passed to a caller token sink callback.  A second layer provides a
 * stock token sink that emits strict-CSP-compatible HTML markup (entity-
 * escaped text wrapped in <span class=...>) through a caller write callback.
 *
 * The tokenizer never revises emitted decisions, never backtracks, and holds
 * O(1) state regardless of input; unterminated constructs at end of input are
 * closed out with a best-guess classification.
 */
 
#if !defined(__LWS_HL_H__)
#define __LWS_HL_H__
 
#if !defined(LHL_SCRATCH_SIZE)
#define LHL_SCRATCH_SIZE                  40
#endif
#if !defined(LHL_PIECE_MAX)
#define LHL_PIECE_MAX                     96
#endif
 
/* the scratch cursor is a byte, and pieces are bounded two units in */
#if LHL_SCRATCH_SIZE > 255 || LHL_PIECE_MAX < 8
#error "LHL_SCRATCH_SIZE must be <= 255 and LHL_PIECE_MAX >= 8"
#endif

typedef enum {
        LHL_CLS_PLAIN,          
        LHL_CLS_IDENT,          
        LHL_CLS_KEYWORD,        
        LHL_CLS_TYPE,           
        LHL_CLS_NUMBER,         
        LHL_CLS_STRING,         
        LHL_CLS_CHARLIT,        
        LHL_CLS_COMMENT,        
        LHL_CLS_PREPROC,        
 
        /* diff presentation (lines, including their newline) */
 
        LHL_CLS_DIFF_ADD,       
        LHL_CLS_DIFF_REM,       
        LHL_CLS_DIFF_HUNK,      
        LHL_CLS_DIFF_META,      
 
        LHL_CLS_COUNT           
} lws_hl_class_t;
 
struct lws_hl_ctx;
typedef struct lws_hl_ctx lws_hl_ctx_t;

typedef lws_stateful_ret_t (*lws_hl_token_cb)(void *user, lws_hl_class_t cls,
                                              const uint8_t *tok, size_t len);
 
typedef struct lws_hl_ops {
        const char      *name;
 
        int             (*construct)(lws_hl_ctx_t *ctx);
 
        lws_stateful_ret_t      (*parse)(lws_hl_ctx_t *ctx,
                                          const uint8_t **buf, size_t *len);
 
        lws_stateful_ret_t      (*finish)(lws_hl_ctx_t *ctx);
} lws_hl_ops_t;

typedef struct lws_hl_ctx {
        const lws_hl_ops_t      *ops;
        lws_hl_token_cb         cb;
        void                    *user;
 
        /* private below */
 
        const uint8_t           *chunk;         /* current input chunk base */
        size_t                  pos;            /* scan cursor (offset in chunk) */
        size_t                  tok;            /* current token start offset */
        size_t                  epos;           /* emitted watermark offset */
        uint8_t                 state;          /* driver private */
        uint8_t                 scratch_pos;    /* driver private */
        uint8_t                 flags;          /* driver private */
        uint8_t                 tokcls;         /* driver private */
        uint8_t                 scratch[LHL_SCRATCH_SIZE];
} lws_hl_ctx_t;

LWS_VISIBLE LWS_EXTERN int
lws_hl_construct(lws_hl_ctx_t *ctx, const lws_hl_ops_t *lang,
                 lws_hl_token_cb cb, void *user);

LWS_VISIBLE LWS_EXTERN lws_stateful_ret_t
lws_hl_parse(lws_hl_ctx_t *ctx, const uint8_t **buf, size_t *len);

LWS_VISIBLE LWS_EXTERN lws_stateful_ret_t
lws_hl_finish(lws_hl_ctx_t *ctx);
 
#if defined(LWS_WITH_HL_LANG_C)
LWS_VISIBLE LWS_EXTERN const lws_hl_ops_t *
lws_hl_lang_c(void);
#endif
 
#if defined(LWS_WITH_HL_LANG_DIFF)
LWS_VISIBLE LWS_EXTERN const lws_hl_ops_t *
lws_hl_lang_diff(void);
#endif
 
/*
 * One piece's markup is composed whole before it is written: a closing
 * </span>, the opening <span class="..."> and the worst-case escape of
 * LHL_PIECE_MAX bytes (8 each).  Class names longer than about
 * LHL_HTML_BUF - 800 bytes do not fit, and pieces of those classes are
 * emitted escaped but unwrapped rather than refused.
 */
#if !defined(LHL_HTML_BUF)
#define LHL_HTML_BUF                      1024
#endif
 
typedef lws_stateful_ret_t (*lws_hl_write_cb)(void *user, const uint8_t *buf,
                                              size_t len);

typedef struct lws_hl_html {
        /* private */
        lws_hl_write_cb         wc;
        void                    *user;
        const char * const      *cls;
        lws_hl_class_t          last;
        size_t                  buflen;
        uint8_t                 open;
        char                    buf[LHL_HTML_BUF];
} lws_hl_html_t;

LWS_VISIBLE LWS_EXTERN int
lws_hl_html_construct(lws_hl_html_t *h, lws_hl_write_cb wc, void *user,
                      const char * const *cls);

LWS_VISIBLE LWS_EXTERN lws_stateful_ret_t
lws_hl_html_token(void *user, lws_hl_class_t cls, const uint8_t *tok,
                  size_t len);

LWS_VISIBLE LWS_EXTERN lws_stateful_ret_t
lws_hl_html_close(lws_hl_html_t *h);

LWS_VISIBLE LWS_EXTERN lws_stateful_ret_t
lws_html_escape(lws_hl_write_cb wc, void *user, const uint8_t *src,
                size_t len);
#endif