mirrors/ghostty
1
0
Fork 0
mirror of https://github.com/ghostty-org/ghostty.git synced 2026-04-06 07:38:21 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: extract inline code examples into standalone projects

Browse Source 
Extract inline @code blocks from vt headers (size_report.h, modes.h,
sgr.h, paste.h, mouse.h, key.h) into standalone buildable examples
under example/. Each header now uses Doxygen @snippet tags to include
code from the example source files, keeping documentation in sync
with code that is verified to compile and run.

New example projects: c-vt-size-report and c-vt-modes. Existing
examples (c-vt-sgr, c-vt-paste, c-vt-mouse-encode, c-vt-key-encode)
gain snippet markers so their code can be referenced from the headers.
Conceptual snippets in key.h, mouse.h, and key/encoder.h that show
terminal-state usage patterns remain inline since they cannot be
compiled standalone.
This commit is contained in:
Mitchell Hashimoto
2026-03-17 17:00:51 -07:00
parent bb3b3ba615
commit 15b8976d64
18 changed files with 331 additions and 308 deletions
Download Patch File Download Diff File Expand all files Collapse all files

39
include/ghostty/vt/key.h
View File

@@ -32,44 +32,7 @@
*
* ## Example
*
* @code{.c}
* #include <assert.h>
* #include <stdio.h>
* #include <ghostty/vt.h>
*
* int main() {
* // Create encoder
* GhosttyKeyEncoder encoder;
* GhosttyResult result = ghostty_key_encoder_new(NULL, &encoder);
* assert(result == GHOSTTY_SUCCESS);
*
* // Enable Kitty keyboard protocol with all features
* ghostty_key_encoder_setopt(encoder, GHOSTTY_KEY_ENCODER_OPT_KITTY_FLAGS,
* &(uint8_t){GHOSTTY_KITTY_KEY_ALL});
*
* // Create and configure key event for Ctrl+C press
* GhosttyKeyEvent event;
* result = ghostty_key_event_new(NULL, &event);
* assert(result == GHOSTTY_SUCCESS);
* ghostty_key_event_set_action(event, GHOSTTY_KEY_ACTION_PRESS);
* ghostty_key_event_set_key(event, GHOSTTY_KEY_C);
* ghostty_key_event_set_mods(event, GHOSTTY_MODS_CTRL);
*
* // Encode the key event
* char buf[128];
* size_t written = 0;
* result = ghostty_key_encoder_encode(encoder, event, buf, sizeof(buf), &written);
* assert(result == GHOSTTY_SUCCESS);
*
* // Use the encoded sequence (e.g., write to terminal)
* fwrite(buf, 1, written, stdout);
*
* // Cleanup
* ghostty_key_event_free(event);
* ghostty_key_encoder_free(encoder);
* return 0;
* }
* @endcode
* @snippet c-vt-key-encode/src/main.c key-encode
*
* ## Example: Encoding with Terminal State
*

47
include/ghostty/vt/modes.h
View File

@@ -20,57 +20,14 @@
*
* ## Example
*
* @code{.c}
* #include <stdio.h>
* #include <ghostty/vt.h>
*
* int main() {
* // Create a mode for DEC mode 25 (cursor visible)
* GhosttyMode tag = ghostty_mode_new(25, false);
* printf("value=%u ansi=%d packed=0x%04x\n",
* ghostty_mode_value(tag),
* ghostty_mode_ansi(tag),
* tag);
*
* // Create a mode for ANSI mode 4 (insert mode)
* GhosttyMode ansi_tag = ghostty_mode_new(4, true);
* printf("value=%u ansi=%d packed=0x%04x\n",
* ghostty_mode_value(ansi_tag),
* ghostty_mode_ansi(ansi_tag),
* ansi_tag);
*
* return 0;
* }
* @endcode
* @snippet c-vt-modes/src/main.c modes-pack-unpack
*
* ## DECRPM Report Encoding
*
* Use ghostty_mode_report_encode() to encode a DECRPM response into a
* caller-provided buffer:
*
* @code{.c}
* #include <stdio.h>
* #include <ghostty/vt.h>
*
* int main() {
* char buf[32];
* size_t written = 0;
*
* // Encode a report that DEC mode 25 (cursor visible) is set
* GhosttyResult result = ghostty_mode_report_encode(
* GHOSTTY_MODE_CURSOR_VISIBLE,
* GHOSTTY_MODE_REPORT_SET,
* buf, sizeof(buf), &written);
*
* if (result == GHOSTTY_SUCCESS) {
* printf("Encoded %zu bytes: ", written);
* fwrite(buf, 1, written, stdout);
* printf("\n"); // prints: ESC[?25;1$y
* }
*
* return 0;
* }
* @endcode
* @snippet c-vt-modes/src/main.c modes-decrpm
*
* @{
*/

51
include/ghostty/vt/mouse.h
View File

@@ -29,56 +29,7 @@
*
* ## Example
*
* @code{.c}
* #include <assert.h>
* #include <stdio.h>
* #include <ghostty/vt.h>
*
* int main() {
* // Create encoder
* GhosttyMouseEncoder encoder;
* GhosttyResult result = ghostty_mouse_encoder_new(NULL, &encoder);
* assert(result == GHOSTTY_SUCCESS);
*
* // Configure SGR format with normal tracking
* ghostty_mouse_encoder_setopt(encoder, GHOSTTY_MOUSE_ENCODER_OPT_EVENT,
* &(GhosttyMouseTrackingMode){GHOSTTY_MOUSE_TRACKING_NORMAL});
* ghostty_mouse_encoder_setopt(encoder, GHOSTTY_MOUSE_ENCODER_OPT_FORMAT,
* &(GhosttyMouseFormat){GHOSTTY_MOUSE_FORMAT_SGR});
*
* // Set terminal geometry for coordinate mapping
* ghostty_mouse_encoder_setopt(encoder, GHOSTTY_MOUSE_ENCODER_OPT_SIZE,
* &(GhosttyMouseEncoderSize){
* .size = sizeof(GhosttyMouseEncoderSize),
* .screen_width = 800, .screen_height = 600,
* .cell_width = 10, .cell_height = 20,
* });
*
* // Create and configure a left button press event
* GhosttyMouseEvent event;
* result = ghostty_mouse_event_new(NULL, &event);
* assert(result == GHOSTTY_SUCCESS);
* ghostty_mouse_event_set_action(event, GHOSTTY_MOUSE_ACTION_PRESS);
* ghostty_mouse_event_set_button(event, GHOSTTY_MOUSE_BUTTON_LEFT);
* ghostty_mouse_event_set_position(event,
* (GhosttyMousePosition){.x = 50.0f, .y = 40.0f});
*
* // Encode the mouse event
* char buf[128];
* size_t written = 0;
* result = ghostty_mouse_encoder_encode(encoder, event,
* buf, sizeof(buf), &written);
* assert(result == GHOSTTY_SUCCESS);
*
* // Use the encoded sequence (e.g., write to terminal)
* fwrite(buf, 1, written, stdout);
*
* // Cleanup
* ghostty_mouse_event_free(event);
* ghostty_mouse_encoder_free(encoder);
* return 0;
* }
* @endcode
* @snippet c-vt-mouse-encode/src/main.c mouse-encode
*
* ## Example: Encoding with Terminal State
*

21
include/ghostty/vt/paste.h
View File

@@ -18,26 +18,7 @@
*
* ## Example
*
* @code{.c}
* #include <stdio.h>
* #include <string.h>
* #include <ghostty/vt.h>
*
* int main() {
* const char* safe_data = "hello world";
* const char* unsafe_data = "rm -rf /\n";
*
* if (ghostty_paste_is_safe(safe_data, strlen(safe_data))) {
* printf("Safe to paste\n");
* }
*
* if (!ghostty_paste_is_safe(unsafe_data, strlen(unsafe_data))) {
* printf("Unsafe! Contains newline\n");
* }
*
* return 0;
* }
* @endcode
* @snippet c-vt-paste/src/main.c paste-safety
*
* @{
*/

37
include/ghostty/vt/sgr.h
View File

@@ -31,42 +31,7 @@
*
* ## Example
*
* @code{.c}
* #include <assert.h>
* #include <stdio.h>
* #include <ghostty/vt.h>
*
* int main() {
* // Create parser
* GhosttySgrParser parser;
* GhosttyResult result = ghostty_sgr_new(NULL, &parser);
* assert(result == GHOSTTY_SUCCESS);
*
* // Parse "bold, red foreground" sequence: ESC[1;31m
* uint16_t params[] = {1, 31};
* result = ghostty_sgr_set_params(parser, params, NULL, 2);
* assert(result == GHOSTTY_SUCCESS);
*
* // Iterate through attributes
* GhosttySgrAttribute attr;
* while (ghostty_sgr_next(parser, &attr)) {
* switch (attr.tag) {
* case GHOSTTY_SGR_ATTR_BOLD:
* printf("Bold enabled\n");
* break;
* case GHOSTTY_SGR_ATTR_FG_8:
* printf("Foreground color: %d\n", attr.value.fg_8);
* break;
* default:
* break;
* }
* }
*
* // Cleanup
* ghostty_sgr_free(parser);
* return 0;
* }
* @endcode
* @snippet c-vt-sgr/src/main.c sgr-basic
*
* @{
*/

28
include/ghostty/vt/size_report.h
View File

@@ -22,33 +22,7 @@
*
* ## Example
*
* @code{.c}
* #include <stdio.h>
* #include <ghostty/vt.h>
*
* int main() {
* GhosttySizeReportSize size = {
* .rows = 24,
* .columns = 80,
* .cell_width = 9,
* .cell_height = 18,
* };
*
* char buf[64];
* size_t written = 0;
*
* GhosttyResult result = ghostty_size_report_encode(
* GHOSTTY_SIZE_REPORT_MODE_2048, size, buf, sizeof(buf), &written);
*
* if (result == GHOSTTY_SUCCESS) {
* printf("Encoded %zu bytes: ", written);
* fwrite(buf, 1, written, stdout);
* printf("\n");
* }
*
* return 0;
* }
* @endcode
* @snippet c-vt-size-report/src/main.c size-report-encode
*
* @{
*/