About - harehelper - Basic editor integration for hare

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:

use os::{stdout};
use hare::parse;
...

$ 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)

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

find references

$ 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

$ harehelper list-modules

print all symbols in module

$ 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 or open an issue or pull request at the codeberg repo.

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-backend for hare.

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

(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:

(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:

(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
  ;; ...
)

harehelper