index : cgit

/*
 * The printing side of cgit, which every page is written through. Text is
 * handed in as plain strings and the call a renderer picks decides how it is
 * escaped for where it lands, whether that is page text, an attribute value, a
 * URL path, a query argument or a quoted HTTP header. Output is buffered
 * rather than written as it is produced, so the flush and capture calls below
 * are part of the contract for anything that reaches stdout by another route.
 */

#ifndef CGIT_HTML_H
#define CGIT_HTML_H

#include "cgit.h"

// How much of a generated run to build before handing it to html_raw. A run
// built whole would grow with the file it came from, to many times the blob's
// size, which max-blob-size never measures.
#define HTML_BATCH (64 * 1024)

extern void html_raw(const char *txt, size_t size);
extern void html(const char *txt);

/*
 * Write out whatever page output is still buffered. Call this before anything
 * other than html_raw writes to stdout.
 */
extern void html_flush(void);

/*
 * Drop whatever page output is still buffered and end any capture, so that
 * what follows reaches stdout. For the die path only.
 */
extern void html_discard(void);

/*
 * Collect page output into sb rather than writing it, until html_capture_end.
 * A capture must not span a filter or anything else that writes to stdout
 * directly, since that output would escape the capture.
 */
extern void html_capture_begin(struct strbuf *sb);
extern void html_capture_end(void);

__attribute__((format (printf,1,2)))
extern void htmlf(const char *format, ...);

__attribute__((format (printf,1,2)))
extern void html_txtf(const char *format, ...);

__attribute__((format (printf,1,0)))
extern void html_vtxtf(const char *format, va_list ap);

__attribute__((format (printf,1,2)))
extern void html_attrf(const char *format, ...);

extern void html_txt(const char *txt);

/*
 * Escape at most len bytes of txt, cutting short of a character the budget
 * would split. The return is what is left of that budget, and a caller prints
 * an ellipsis when it comes back negative.
 */
extern ssize_t html_ntxt(const char *txt, size_t len);

/*
 * The escape sequence a blob's text shows for the character at p when a
 * browser would start a new line at it though git does not, or NULL for any
 * other character. The character's length in bytes is stored in width.
 */
extern const char *html_line_break_escape(const char *p, const char *end, size_t *width);

/*
 * Escape the text of a blob for the page beside its line numbers, writing
 * each character html_line_break_escape names as its escape sequence.
 */
extern void html_blob_txt(const char *txt, size_t len);

extern void html_attr(const char *txt);
extern void html_url_path(const char *txt);

/*
 * Append txt to sb with the escaping html_url_path writes, for a url that is
 * assembled before it reaches a sink. Nothing is captured, so it is safe to
 * call while a capture is open.
 */
extern void cgit_add_url_path(struct strbuf *sb, const char *txt);

/*
 * Escape a whole url given in the configuration, such as a clone url, for an
 * attribute value. Only a byte no url may carry is percent-encoded, so the
 * scheme, the delimiters and any escape the url was written with are kept.
 */
extern void html_attr_url(const char *txt);

extern void html_url_arg(const char *txt);
extern void html_header_arg_in_quotes(const char *txt);

/*
 * Percent-encode txt as the value of an RFC 8187 header parameter such as
 * filename*, leaving out the charset and language the value opens with.
 */
extern void html_header_ext_value(const char *txt);

extern void html_header_query(const char *txt);
extern void html_hidden(const char *name, const char *value);

__attribute__((format (printf,1,2)))
extern char *cgit_fmt(const char *format, ...);

extern void html_option(const char *value, const char *text, const char *selected_value);
extern void html_intoption(int value, const char *text, int selected_value);
extern void html_include(const char *filename);

#endif // CGIT_HTML_H