{"id":13502876,"url":"https://github.com/eburghar/kakpipe","last_synced_at":"2025-03-29T12:33:10.354Z","repository":{"id":128439526,"uuid":"372444920","full_name":"eburghar/kakpipe","owner":"eburghar","description":"Launch external tools inside colorful fifo buffers and display text with ansi colors in info boxes","archived":false,"fork":false,"pushed_at":"2024-02-06T19:17:05.000Z","size":371,"stargazers_count":28,"open_issues_count":3,"forks_count":1,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-08-01T22:57:50.502Z","etag":null,"topics":["ansi-codes","async","kakoune","plugin","rust"],"latest_commit_sha":null,"homepage":"https://git.itsufficient.me/rust/kakpipe","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/eburghar.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2021-05-31T09:02:26.000Z","updated_at":"2024-06-19T04:23:27.000Z","dependencies_parsed_at":"2024-01-18T23:25:41.489Z","dependency_job_id":"9b0729ad-e4b8-42b1-8405-082f3f8bd6e3","html_url":"https://github.com/eburghar/kakpipe","commit_stats":null,"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eburghar%2Fkakpipe","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eburghar%2Fkakpipe/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eburghar%2Fkakpipe/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eburghar%2Fkakpipe/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/eburghar","download_url":"https://codeload.github.com/eburghar/kakpipe/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":222495237,"owners_count":16993288,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ansi-codes","async","kakoune","plugin","rust"],"created_at":"2024-07-31T22:02:28.012Z","updated_at":"2024-10-31T22:30:59.038Z","avatar_url":"https://github.com/eburghar.png","language":"Rust","funding_links":[],"categories":["Rust"],"sub_categories":[],"readme":"# Kakpipe\n\n`kakpipe` is a binary executable meant to be used with the included [Kakoune](https://kakoune.org/) module\n`kakpipe.kak` for launching external tools inside colorful FIFO buffers, or displaying text with ANSI colors in\ninfo boxes.\n\n![kakpipe](kakpipe.png?raw=true \"colors in kakoune fifo buffer and info box\")\n\n[TOC]\n\n```\nkakpipe 0.5.7\n\nUsage: kakpipe \u003ccommand\u003e [\u003cargs\u003e]\n\nUtility to display text with ansi color codes inside kakoune fifo buffers or info boxes\n\nOptions:\n  --help            display usage information\n\nCommands:\n  fifo              Return kakoune commands for opening a fifo buffer and\n                    initializing highlighters for ansi-codes, then detach\n                    itself, forward command output to the fifo, and serve\n                    range-specs definitions through a unix socket that can be\n                    consumed to stdout with the `range-specs` subcommand.\n  range-specs       Consume all available range-specs up to a given selection\n                    range from a given unix socket.\n  faces             Forward stdin to stdout with ansi color codes converted to\n                    kakoune face definitions\n```\n\n## Simplify interface with external tools\n\nDefining a new command for interfacing external tool with Kakoune as described in\n[interfacing](https://github.com/mawww/kakoune/blob/master/doc/interfacing.asciidoc#interactive-output) is cumbersome\nfor simple workflows, and as FIFO buffer doesn't support ANSI codes, either you have the extra work of defining a new\nfile type and highlighting rules on top of some boilerplate code, or you have to accept to see everything in monochrome.\n\nAs a result you generally end up using a shell, traveling back and forth to Kakoune just to launch a command\nbecause it's simpler. You loose at the same time the comfort of staying inside the editor for something that\nsometimes needs attention but few interactions.\n\n`kakpipe` tackles these difficulties and allows you to launch any external tool in colorful read-only FIFO buffer by\njust giving the command to launch along its arguments.\n\n## Usage\n\n`kakpipe.kak` defines 2 Kakoune commands (one liner) built on top of `kakpipe fifo`\n\n- `:kakpipe` immediately switch to the buffer and let you see the result of the execution in real time,\n- `:kakpipe-bg` do the same without switching to the FIFO buffer\n\nOn the status line, `[fifo]` serves as an indicator to see if the process is still running.\n\nYou can quickly or fuzzily jump between the buffers, and inside a FIFO buffer created by `kakpipe` 2 commands speed\nup your workflows even more comparing to using a shell :\n\n- Closing the buffer with `:bd` stops `kakpipe` and the process,\n- `:!!` stop (if still running) and restart the same command that created the current FIFO buffer.\n\nYou can now focus on :\n\n- Adding new commands and aliases on top of `:kakpipe` to launch external tools inside Kakoune even faster,\n- and/or adding behavior on the FIFO buffer, by defining a new type and some key mappings.\n\nYou can read the section about how to integrate `kakpipe` to your module below and look at the forked\n[kakoune-cargo](https://gitlab.com/eburghar/kakoune-cargo) module to see how easy it is to simplify existing ones.\n\n## Installation\n\n### manual\n\nInstall `kakpipe` somewhere within you `$PATH`\n\n```sh\ncargo install --path . --root ~/.local\n```\n\nCopy `kakpipe.kak` in your autoload directory. Then enter in command prompt\n\n```\n:require-module kakpipe\n```\n\n### with plug.kak\n\nwith [plug.kak](https://github.com/andreyorst/plug.kak)\n\n```\nplug \"eburghar/kakpipe\" do %{\n\tcargo install --force --path . --root ~/.local\n}\n```\n\n## Examples\n\n### Buffers\n\n`kakpipe` command arguments are forwarded to `kakpipe fifo` executable, so you should use `--` to separate\narguments of the command from the executable ones in your scripts or at the command prompt.\n\nHere are all the accepted arguments by `kakpipe fifo`\n\n```\nkakpipe 0.5.7\n\nUsage: kakpipe fifo \u003ccmd\u003e [\u003cargs...\u003e] [-c] [-w] [-S] [-d] -s \u003csession\u003e [-N \u003cprefix\u003e] [-n \u003cname\u003e] [-k] [-V \u003cvars...\u003e] [-D \u003copts...\u003e]\n\nReturn kakoune commands for opening a fifo buffer and initializing highlighters for ansi-codes, then detach itself,\nforward command output to the fifo, and serve range-specs definitions through a unix socket that can be consumed\nto stdout with the `range-specs` subcommand.\n\nPositional Arguments:\n  cmd               command to spawn\n  args\n\nOptions:\n  -c, --close       close current buffer before starting kakpipe (used\n                    internally by :!!)\n  -w, --rw          turns the buffer editable. by default they are readonly\n  -S, --scroll      scroll down fifo buffer as new content arrives\n  -d, --debug       stderr goes to *debug* buffer instead of fifo\n  -s, --session     kakoune session\n  -N, --prefix      fifo buffer name prefix (default is the command name)\n  -n, --name        fifo buffer name (default is prefix + temporary id)\n  -k, --clear-env   clear environment\n  -V, --vars        environment variables to set (NAME=VALUE) or to export\n                    (NAME)\n  -D, --opts        options to set in the buffer scope (NAME=VALUE)\n  --help            display usage information\n```\n\nLaunch `cargo build` in a new FIFO buffer\n\n```\n:kakpipe -S -- cargo build --color=always\n```\n\nLaunch `cargo build` in a new FIFO buffer in the *background*\n\n```\n:kakpipe-bg -- cargo build --color=always\n```\n\nShow a file with syntax coloring managed by [bat](https://github.com/sharkdp/bat) in a FIFO buffer named `*main.rs*`\n\n```\n:kakpipe -n main.rs -- bat -p --color=always src/main.rs\n```\n\nShow a `rustdoc` page in a buffer using [rusty-man](https://git.sr.ht/~ireas/rusty-man)\n\n```\n:kakpipe -- rusty-man --viewer rich std::string::String\n```\n\nLaunch a one-liner script\n\n```\nkakpipe -S -N alive -- sh -c 'while true; do echo -e \"\\e[32malive !\"; sleep 1; done'\n```\n\nLaunch a long-running process in a new buffer with the variable `FORCE_COLOR` exported.\n\n```\n:kakpipe -S -V FORCE_COLOR=true -- npm run dev\n```\n\nLaunch `lualatex` each time the current file is modified using [`entr`](http://eradman.com/entrproject/)\n\n```\n:kakpipe -S -N lualatex -- sh -c \"echo '%val{buffile}' | entr -nr lualatex '%val{buffile}'\"\n```\n\nClosing the buffer will stop the process. You can also use `-k` to clean up the environment in conjunction with\n`-V PATH` to reexport explicitly a variable.\n\n### Info boxes\n\nFor info boxes you use the `kakpipe faces` binary inside shell expansions.\n\n```\nkakpipe 0.5.7\n\nUsage: kakpipe faces\n\nForward stdin to stdout with ansi color codes converted to kakoune face definitions\n\nOptions:\n  --help            display usage information\n```\n\nShow a calendar in an info box\n\n```\n:info -markup %sh{ TERM=xterm-256color cal --color=always | kakpipe faces }\n```\n\nShow diff of current file in info box\n\n```\n:info -markup %sh{ git diff --color=always $kak_buffile | kakpipe faces }\n```\n\n## Building new Commands\n\nMimicking shell commands inside Kakoune are generally one-liners.\n\n```\ndefine-command -override -params 1.. -docstring 'launch cargo with the given parameters inside kakoune' cargo %{\n\tkakpipe -S -- cargo --color=always %arg{@}\n}\n```\n\n```\ndefine-command -override -params 1 -docstring 'show a rustdoc page' rman %{\n\tkakpipe -n %arg{1} -- rusty-man --viewer rich %arg{@}\n}\n```\n\nAs well as for aliasing commands (shell like aliases)\n\n```\ndefine-command -params 0.. -docstring 'cargo check' cc %{\n\tcargo check %arg{@}\n}\n```\n\n```\ndefine-command -params 0.. -docstring 'cargo build' cb %{\n\tcargo build %arg{@}\n}\n```\n\n```\ndefine-command -docstring 'cargo install in ~/.local/bin' ci %{\n    cargo install --path . --root %sh{ echo -n ~/.local }\n}\n```\n\n```\ndefine-command -docstring 'cargo install current directory crate to ~/.local/bin' ci %{\n\tcargo install --path . --root %sh{ echo -n ~/.local }\n}\n```\n\n## Integrate `kakpipe` to your module\n\nYou can easily add custom behavior to the FIFO buffer created by `kakpipe` by using one or several `-D name=value`\ncommand line arguments to set up options values in the FIFO buffer scope.\n\nYou can for instance make a module defining custom mappings for a given file type and use `-D filetype=myfiletype`\nwith `kakpipe` inside the plugin to automatically set up the file type of the created FIFO buffer.\n\nThe `-n` options allows to use the same buffer (name) at each command invocation. By default, `kakpipe` open a new\nbuffer which name is a '`-`' separated string made of the command name (or the prefix given with `-N`) and a\nrandom ID. The random ID is also used as a prefix for all temporary files that are generated in `/tmp/kakpipe/`\n(socket, FIFO and PID files).\n\n```\ndefine-command -override -params 1.. -docstring 'launch cargo with the given parameters inside kakoune' cargo %{\n\tkakpipe -S -n cargo -D filetype=cargo -- cargo --color=always %arg{@}\n}\n```\n\nYou can see [a\npatch](https://gitlab.com/eburghar/kakoune-cargo/-/compare/b15c75180e8c851c8687c90550746dfedceebbed...master?from_project_id=27156852\u0026view=parallel)\nwhich shows how to use `kakpipe` as a replacement of highlighter and `mkfifo` boilerplate in the\n[kakoune-cargo](https://gitlab.com/Screwtapello/kakoune-cargo) plugin.\n\n## References\n\n[kak-ansi](https://github.com/eraserhd/kak-ansi) is a tiny (23K) executable (written in C with no dependencies)\nexclusively targeted at highlighting ANSI codes in selections. `kak-ansi` works by removing ANSI codes from selections\nand adding range-specs to bring color and faces, but as a consequence can only work on read-write buffers. It writes\nto temporary files and adds its own (tiny) layer of boilerplate code to be used in your commands and FIFO.\n\n`kakpipe` manage process lifecycle and sends asynchronously its output to the FIFO buffer already stripped out\nof ANSI codes while providing range-specs from a Unix socket to be consumed separately. It works by default on\nread-only buffers because this is what command outputs are expected to be.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feburghar%2Fkakpipe","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feburghar%2Fkakpipe","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feburghar%2Fkakpipe/lists"}