kak-tree/README.asciidoc

= xenia/kak-tree: Structural selections for Kakoune

This is a fork of https://github.com/ul/kak-tree[ul/kak-tree], with some changes mainly regarding the user interface. This fork is quite personalized and opinionated to work for me, but with some work shouldn't be too difficult to work with yourself.

== Usage

Once installed and configured (see below), the following commands are available:

[cols=2*]
|===

| tree-select-node [<KIND>]
| Selects the entire node the cursor is currently on. If KIND is provided, instead select the nearest ancestor of the kind.

| tree-select-parent-node [<KIND>]
| Select the closest visible ancestor or ancestor of KIND when provided.

| tree-select-next-node [<KIND>]
| Select the closest visible next sibling or next sibling of KIND when provided.

| tree-select-previous-node [<KIND>]
| Select the closest visible previous sibling or previous sibling of KIND when provided.

| tree-select-children [<KIND>]
| Select all immediate visible children or all descendants matching KIND when provided.

| tree-node-sexp
| Show info box with a syntax tree of the main selection parent.

| tree-node-highlight
| Highlights the currently selected node with the style `tree_highlight_style` (default: `black,blue`). Use `tree-node-clear-highlight` to clear the highlight.

| tree-node-always-highlight
| Continuously highlight the current node as the cursor moves around (hooks RawKey and switching files). Use `tree-node-always-highlight-disable` to stop highlighting.

| tree-quickjump <KIND>
| Highlights the nearest nodes of kind KIND with unique letters and opens a prompt to jump to the corresponding node.
|===

== Configuration

xenia/kak-tree supports the following options:

[cols=2*]
|===

| tree_cmd
| Path to the compiled executable. Defaults to `kak-tree`, and is automatically configured by the nix flake build system.

| tree_config
| Path to the configuration file (format described below). Defaults to `<installation_dir>/default_config.toml`.

| tree_log
| Path to a log file. Defaults to `/dev/null`

| tree_highlight_style
| Face to use for node highlighting. Defaults to `black,blue` (blue on black background).

| tree_quickjump_highlight_style
| Face to use for quick navigation highlights. Defaults to `black,green+F` (blue on black background, override all).
|===

In the configuration file `tree_config`, one can specify custom <KIND>s one can use in commands above. An example configuration can be found in `rc/default_config.toml`:

```toml
[filetype.rust]
group.identifier = ["identifier", "scoped_identifier"]
group.call = ["macro_invocation", "call_expression"]
group.arguments = ["arguments", "token_tree", "parameters"]
group.statement = ["expression_statement", "let_declaration"]
group.string = ["string_literal", "raw_string_literal"]
group.number = ["integer_literal", "float_literal", "negative_literal"]
[ ... ]
```

== Installation

If you are using nix, the `flake.nix` file provides an attribute `packages.kak-tree` resolving to a kakoune plugin one can use in home-manager's `programs.kakoune.plugins` or build yourself with `kakoune.override { plugins = ... }`.

If not, you will have to set up the build environment yourself. Since we use static linking, compile each tree sitter plugin to a statically linked library to `./sitters/libtree-sitter-LANG.a`, and then build:

```sh
$ [ compile tree sitter for i.e. javascript... ]
$ ls sitters
libtree-sitter-javascript.a
$ SITTERS=./sitters cargo build --no-default-features --features javascript --release
[ ... ]
$ ./target/release/kak-tree --do-you-understand javascript
Known language. Trying to load
Loaded successfully
```

Installing the plugin works as usual, putting the `./rc` folder in `../share/kak/plugins/kak-tree` relative to your kakoune binary, and either putting the kak-tree binary available in your `$PATH` or specifying to path to the binary in the `tree_cmd` option.

== (Opinionated) kakrc configuration

My `kakrc` configuration for this plugin can be found in `kakrc.sample`. It

* Binds `t` to a mode for all actions
* Binds `f` to `tree-quickjump`
* Binds `F` to `tree-next`
* Binds `<a-f>` to `tree-children`