1/**
2 * @file paste.h
3 *
4 * Paste utilities - validate and encode paste data for terminal input.
5 */
6
7#ifndef GHOSTTY_VT_PASTE_H
8#define GHOSTTY_VT_PASTE_H
9
10/** @defgroup paste Paste Utilities
11 *
12 * Utilities for validating and encoding paste data for terminal input.
13 *
14 * ## Basic Usage
15 *
16 * Use ghostty_paste_is_safe() to check if paste data contains potentially
17 * dangerous sequences before sending it to the terminal.
18 *
19 * Use ghostty_paste_encode() to encode paste data for writing to the pty,
20 * including bracketed paste wrapping and unsafe byte stripping.
21 *
22 * ## Examples
23 *
24 * ### Safety Check
25 *
26 * @snippet c-vt-paste/src/main.c paste-safety
27 *
28 * ### Encoding
29 *
30 * @snippet c-vt-paste/src/main.c paste-encode
31 *
32 * @{
33 */
34
35#include <stdbool.h>
36#include <stddef.h>
37#include <ghostty/vt/types.h>
38
39#ifdef __cplusplus
40extern "C" {
41#endif
42
43/**
44 * Check if paste data is safe to paste into the terminal.
45 *
46 * Data is considered unsafe if it contains:
47 * - Newlines (`\n`) which can inject commands
48 * - The bracketed paste end sequence (`\x1b[201~`) which can be used
49 * to exit bracketed paste mode and inject commands
50 *
51 * This check is conservative and considers data unsafe regardless of
52 * current terminal state.
53 *
54 * @param data The paste data to check (must not be NULL)
55 * @param len The length of the data in bytes
56 * @return true if the data is safe to paste, false otherwise
57 */
58GHOSTTY_API bool ghostty_paste_is_safe(const char* data, size_t len);
59
60/**
61 * Encode paste data for writing to the terminal pty.
62 *
63 * This function prepares paste data for terminal input by:
64 * - Stripping unsafe control bytes (NUL, ESC, DEL, etc.) by replacing
65 * them with spaces
66 * - Wrapping the data in bracketed paste sequences if @p bracketed is true
67 * - Replacing newlines with carriage returns if @p bracketed is false
68 *
69 * The input @p data buffer is modified in place during encoding. The
70 * encoded result (potentially with bracketed paste prefix/suffix) is
71 * written to the output buffer.
72 *
73 * If the output buffer is too small, the function returns
74 * GHOSTTY_OUT_OF_SPACE and sets the required size in @p out_written.
75 * The caller can then retry with a sufficiently sized buffer.
76 *
77 * @param data The paste data to encode (modified in place, may be NULL)
78 * @param data_len The length of the input data in bytes
79 * @param bracketed Whether bracketed paste mode is active
80 * @param buf Output buffer to write the encoded result into (may be NULL)
81 * @param buf_len Size of the output buffer in bytes
82 * @param[out] out_written On success, the number of bytes written. On
83 * GHOSTTY_OUT_OF_SPACE, the required buffer size.
84 * @return GHOSTTY_SUCCESS on success, GHOSTTY_OUT_OF_SPACE if the buffer
85 * is too small
86 */
87GHOSTTY_API GhosttyResult ghostty_paste_encode(
88 char* data,
89 size_t data_len,
90 bool bracketed,
91 char* buf,
92 size_t buf_len,
93 size_t* out_written);
94
95#ifdef __cplusplus
96}
97#endif
98
99/** @} */
100
101#endif /* GHOSTTY_VT_PASTE_H */