harehelper

A small tool for basic harelang interaction in Editors.

Harehelper is a small cli providing functionality needed to easily access hare
documentation from within an editor, and jump to definitions.

In principle, everything needed for basic completion should be in place, I
haven't attempted using harehelper for that yet though.

## Usage

```
harehelper: help with hare

Usage: harehelper [-hP] [-p <path>] [-t <tagset>] subcommand args

-h: show help
-p <path>: append to harepath
-P: return harepath
-t <tagset>: set/unset build tags

Subcommands:
  list: list symbols in module
  resolve: resolve namespace for identifier
  locate: return location of declaration for identifier
  list-modules: list all modules in current harepath
  find-references: find all references to symbol
```

### resolve namespaces

given a file.ha:
```hare
use os::{stdout};
use hare::parse;
...
```

```bash
$ harehelper resolve stdout /path/to/file.ha
os::stdout

$ harehelper resolve parse::identstr /path/to/file.ha
hare::parse::identstr
```

### locate declaration
(only works for toplevel declarations)

```bash
$ harehelper locate os::stdout
/usr/src/hare/stdlib/os/+linux/stdfd.ha:29
```

### find references

```bash
$ harehelper find-references <identifier> <path>
```

Returns a list of lines in harefiles under `path` that reference `identifier`.
Identifier is assumed to be relative to HAREPATH. The advantage over grep et. al
is that this command is aware of namespaces and will correctly return references
even if the symbol is aliased.

### print all modules in harepath

```bash
$ harehelper list-modules
```

### print all symbols in module

```bash
$ harehelper list <module>
```

## Contributing

If you encounter issues, have suggestions, want to contribute a patch, or just
let me know that you found this tool useful, you can reach me via
[mail](mailto:lou@repetitions.de) or open an issue or pull request at the
[codeberg repo](https://codeberg.org/lou/harehelper).

## Editor Integrations
### Emacs integration

`haredoc.el` provides an emacs interface to haredoc using harehelper. The main
entry points are, `haredoc` and `haredoc/describe-thing-at-point`. The package
also proves a
[xref](https://www.gnu.org/software/emacs/manual/html_node/emacs/Xref.html)-backend
for hare.

To enable the default keymap in hare-mode, add `haredoc-nav-mode` to your
`hare-mode-hook`.

```emacs-lisp
(add-hook 'hare-mode-hook #'haredoc-nav-mode)
```

- `C-c C-h`: haredoc
- `C-c C-d`: haredoc/describe-thing-at-point

Default keybindings in haredoc buffers:

- `s`: go to source of definition at point
- `<`: go back to previous haredoc page visited
- `>`: inverse of the former
- `n`: move cursor down one declaration
- `p`: move cursor up one declaration
- `d`: narrow haredoc to documentation of declaration at point
- `u`: show documentation for one namespace level up

#### Installation

The current version of the package assumes the `harehelper` executable to be
located in the same directory as `haredoc.el`. You can change this assumption by
modifying `haredoc-helperbin`.

The following `use-package` declarations include a build step for harehelper.

- with `package-vc`:

```emacs-lisp
(setq package-vc-allow-build-commands t)
(use-package reader
  :vc (:url "https://git.repetitions.de/harehelper"
       :make "all")
  :hook (hare-mode . haredoc-nav-mode)
  :config
  ;;...
)
```

- with [elpaca](https://github.com/progfolio/elpaca):

```emacs-lisp
(use-package haredoc
  :defer t
  :ensure (haredoc
           :type git
           :repo "https://git.repetitions.de/harehelper"
           :pre-build (("make"))
           :files (:defaults "harehelper"))
  :hook (hare-mode . haredoc-nav-mode)
  :config
  ;; ...
)
```

### Other

- [kakoune](https://kakoune.org/): https://codeberg.org/unicorn/harehelper.kak
- [vis](https://github.com/martanne/vis): https://codeberg.org/elb22/vis-harehelper