hl

One query across every HyperList you own.

What it is for

A HyperList holds structure: a task list, an argument, a process, a system map. Once you keep more than a few, the question stops being "what is in this file" and becomes "where did I write that". Opening each file to look is the thing this replaces.

hl treats every list you own as one searchable body. It knows what the parts of a HyperList mean, so it can ask questions a plain grep cannot: which items carry this tag, which point at that reference, which boxes are still open, and what is the parent of the line that matched.

Its neighbours in the chain: scribe writes them, hl2web publishes them, hypergraph draws them.

Usage

hl --open                  # every unchecked box, in every list
hl --done                  # every checked one
hl --tag freewill          # every item carrying #freewill
hl --ref "THEOREM"         # every item pointing at that reference
hl W35                     # plain substring search
hl --tree W35              # each hit under its parent path
hl --short W35             # file names only, no directories
hl --open ~/Projects       # one directory instead of the roots
hl --tag teg ~/notes/x.hl  # or one named file
hl --roots                 # which roots would be searched

Output is path:line: item, so an editor or a pipe takes it from here. Nothing found exits 1, so hl --open && echo "still open" works in a script.

Use cases

Before you rename something. A HyperList reference is a promise: another item points at this line by its opening words. Ask what depends on it before you touch it.

$ hl --ref "THEOREM: The selection requirement"
TEG.hl:92: Not computable; a computation is rule-governed and <THEOREM: The selection requirement> excludes it

One dependant, so the rename is cheap. A dozen, and you plan the edit.

Finding your own answer. Someone raises an objection you have answered before, in a file you cannot name. The parent path tells you which part of the argument owns it.

$ hl --tree "renamed the mystery"
Objections.hl:54: OBJECTIONS: … / Objections to the identification (Paper 2)
                  OBJECTION: You have renamed the mystery

Monday morning. Everything still unchecked, across every list, in one screen. No file needs opening until something wants doing.

hl --open

One thread across many lists. A tag is the thread. This finds the task in the todo list, the claim in the argument map, and the objection that answers it, together.

hl --tag freewill

A file that should not exist. Sweeping by tag before publishing shows every copy. Two files answer where you expected two; a third is a stray copy in the tree.

Feeding an editor. The output is a standard file:line list, so your editor's quickfix, fzf, or a shell loop can take it.

hl --open | fzf | cut -d: -f1,2   # pick one, get file:line

Where it looks

~/.tasks, plus any root listed in ~/.config/hl/roots or in scribe's ~/.config/scribe/backlink-roots, so the editor and this command search the same set. One path per line, ~/ expands, # comments. Directories are walked four deep, and the sweep stops at 2000 files, so a mistyped root cannot walk half the disk.

Name files or directories on the command line to search those instead.

What it understands

• Tags #name, matched on the HyperList tag charset, so #Gödel works and a trailing comma does not join the tag.
• References <name>, matched on the START of the reference, the way a HyperList link resolves.
• Checkboxes [_] open, [x] done, at the head of an item.
• Indentation tabs, or whatever space step the file uses, so the parent path in --tree is right for 2, 3 and 4-space lists alike.

Install

git clone https://github.com/isene/hl
cd hl
cargo build --release
ln -s "$PWD/target/release/hl" ~/bin/hl

License

Public domain (Unlicense). Do what you want with it.