commit f7ae9d0251a54a843d9cc4969c43776a0b27c282 · anil.recoil.org/ocaml-kgp

+49

.tangled/workflows/build.yml

···

       1
       1
       +
       when:

     

       2
       2
       +
         - event: ["push", "pull_request"]

     

       3
       3
       +
           branch: ["main"]

     

       4
       4
       +
       

     

       5
       5
       +
       engine: nixery

     

       6
       6
       +
       

     

       7
       7
       +
       dependencies:

     

       8
       8
       +
         nixpkgs:

     

       9
       9
       +
           - shell

     

       10
       10
       +
           - stdenv

     

       11
       11
       +
           - findutils

     

       12
       12
       +
           - binutils

     

       13
       13
       +
           - libunwind

     

       14
       14
       +
           - ncurses

     

       15
       15
       +
           - opam

     

       16
       16
       +
           - git

     

       17
       17
       +
           - gawk

     

       18
       18
       +
           - gnupatch

     

       19
       19
       +
           - gnum4

     

       20
       20
       +
           - gnumake

     

       21
       21
       +
           - gnutar

     

       22
       22
       +
           - gnused

     

       23
       23
       +
           - gnugrep

     

       24
       24
       +
           - diffutils

     

       25
       25
       +
           - gzip

     

       26
       26
       +
           - bzip2

     

       27
       27
       +
           - gcc

     

       28
       28
       +
           - ocaml

     

       29
       29
       +
       

     

       30
       30
       +
       steps:

     

       31
       31
       +
         - name: opam

     

       32
       32
       +
           command: |

     

       33
       33
       +
              opam init --disable-sandboxing -any

     

       34
       34
       +
         - name: switch

     

       35
       35
       +
           command: |

     

       36
       36
       +
              opam install . --confirm-level=unsafe-yes --deps-only

     

       37
       37
       +
         - name: build

     

       38
       38
       +
           command: |

     

       39
       39
       +
              opam exec -- dune build

     

       40
       40
       +
         - name: switch-test

     

       41
       41
       +
           command: |

     

       42
       42
       +
              opam install . --confirm-level=unsafe-yes --deps-only --with-test

     

       43
       43
       +
         - name: test

     

       44
       44
       +
           command: |

     

       45
       45
       +
              opam exec -- dune runtest --verbose

     

       46
       46
       +
         - name: doc

     

       47
       47
       +
           command: |

     

       48
       48
       +
              opam install -y odoc

     

       49
       49
       +
              opam exec -- dune build @doc

CHANGES.md

···

       1
       1
       +
       v1.0.0 (dev)

     

       2
       2
       +
       ------------

     

       3
       3
       +
       

     

       4
       4
       +
       - Initial public release (@avsm)

+18

LICENSE.md

···

       1
       1
       +
       (*

     

       2
       2
       +
        * ISC License

     

       3
       3
       +
        * 

     

       4
       4
       +
        * Copyright (c) 2025 Anil Madhavapeddy <anil@recoil.org>

     

       5
       5
       +
        *

     

       6
       6
       +
        * Permission to use, copy, modify, and distribute this software for any

     

       7
       7
       +
        * purpose with or without fee is hereby granted, provided that the above

     

       8
       8
       +
        * copyright notice and this permission notice appear in all copies.

     

       9
       9
       +
        *

     

       10
       10
       +
        * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES

     

       11
       11
       +
        * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF

     

       12
       12
       +
        * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR

     

       13
       13
       +
        * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES

     

       14
       14
       +
        * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN

     

       15
       15
       +
        * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF

     

       16
       16
       +
        * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

     

       17
       17
       +
        *

     

       18
       18
       +
        *)

+66

README.md

···

       1
       1
       +
       # kgp - Kitty Graphics Protocol for OCaml

     

       2
       2
       +
       

     

       3
       3
       +
       An OCaml library for displaying images in terminals using the [Kitty Graphics Protocol](https://sw.kovidgoyal.net/kitty/graphics-protocol/).

     

       4
       4
       +
       

     

       5
       5
       +
       This library can display PNG images in supported terminals (e.g. Kitty, WezTerm, Konsole, Ghostty) with varying levels of support depending on the terminal. Most core features work but some advanced things like animations might be only partially supported outside of Kitty.

     

       6
       6
       +
       

     

       7
       7
       +
       Other features include:

     

       8
       8
       +
       - Image transmission with automatic chunking and base64 encoding

     

       9
       9
       +
       - Multiple placements of the same image

     

       10
       10
       +
       - Animation support with frame deltas

     

       11
       11
       +
       - Unicode placeholder mode for proper scrolling

     

       12
       12
       +
       - tmux passthrough support (requires tmux 3.3+)

     

       13
       13
       +
       - Terminal capability detection

     

       14
       14
       +
       

     

       15
       15
       +
       The library provides a Cmdliner term via the `kgp.cli` package to make integration into other CLI tools easier.

     

       16
       16
       +
       

     

       17
       17
       +
       ## Installation

     

       18
       18
       +
       

     

       19
       19
       +
       ```

     

       20
       20
       +
       opam install kgp

     

       21
       21
       +
       ```

     

       22
       22
       +
       

     

       23
       23
       +
       ## Usage

     

       24
       24
       +
       

     

       25
       25
       +
       ### Library

     

       26
       26
       +
       

     

       27
       27
       +
       ```ocaml

     

       28
       28
       +
       (* Display a PNG image *)

     

       29
       29
       +
       let png_data = read_file "image.png" in

     

       30
       30
       +
       let cmd = Kgp.transmit_and_display ~format:`Png () in

     

       31
       31
       +
       let buf = Buffer.create 1024 in

     

       32
       32
       +
       Kgp.write buf cmd ~data:png_data;

     

       33
       33
       +
       print_string (Buffer.contents buf)

     

       34
       34
       +
       ```

     

       35
       35
       +
       

     

       36
       36
       +
       ```ocaml

     

       37
       37
       +
       (* Transmit once, display multiple times *)

     

       38
       38
       +
       let cmd = Kgp.transmit ~image_id:1 ~format:`Png () in

     

       39
       39
       +
       Kgp.write buf cmd ~data:png_data;

     

       40
       40
       +
       

     

       41
       41
       +
       let cmd = Kgp.display ~image_id:1 () in

     

       42
       42
       +
       Kgp.write buf cmd ~data:""

     

       43
       43
       +
       ```

     

       44
       44
       +
       

     

       45
       45
       +
       ### CLI

     

       46
       46
       +
       

     

       47
       47
       +
       ```

     

       48
       48
       +
       # Display an image

     

       49
       49
       +
       kgpcat image.png

     

       50
       50
       +
       

     

       51
       51
       +
       # Display at specific size and position

     

       52
       52
       +
       kgpcat --place 40x20@10,5 image.png

     

       53
       53
       +
       

     

       54
       54
       +
       # Display from stdin

     

       55
       55
       +
       curl -s https://example.com/image.png | kgpcat

     

       56
       56
       +
       

     

       57
       57
       +
       # Detect terminal support

     

       58
       58
       +
       kgpcat --detect-support

     

       59
       59
       +
       

     

       60
       60
       +
       # Clear displayed images

     

       61
       61
       +
       kgpcat --clear

     

       62
       62
       +
       ```

     

       63
       63
       +
       

     

       64
       64
       +
       ## License

     

       65
       65
       +
       

     

       66
       66
       +
       ISC