1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
|
= remembering(1)
== NAME
remembering - add memory to dmenu, fzf and similar menu tools.
== SYNOPSYS
*remembering* [_-p PROFILE_] -- _COMMAND_...
== EXAMPLES
=== A dmenu launcher that learns
[source,sh]
....
$ printf 'firefox\nmpv\nmutt\n' | remembering -p apps -- dmenu
....
The first time, the menu comes up alphabetical. Pick `mutt` a few
times and it comes up first.
=== Open a file with fzf, most-used first
[source,sh]
....
$ ls | remembering -- fzf
....
Without _-p_, the profile is derived from the current directory,
so every directory gets its own ranking with no setup.
== DESCRIPTION
*remembering* sits between a list of choices and the menu tool
that picks from them. It reads the choices from _stdin_, feeds
them to _COMMAND_ sorted by how often each one was picked before,
takes what _COMMAND_ prints as the pick, bumps that pick's count
in the profile, and prints the pick.
The lines on _stdin_ define what is offered: the profile only
ranks them. Most-picked lines come first; ties are broken in byte
order; never-picked lines keep their byte order at the bottom.
The pick does not have to be one of the offered lines --- whatever
_COMMAND_ prints is learnt, so menu tools that accept free text
(such as `dmenu`) grow new entries on first use. Lines that were
offered but never picked are remembered with a count of zero, and
profile entries that stop appearing on _stdin_ are kept --- the
profile accumulates the universe of choices it has seen.
The profile is rewritten atomically (a sibling `.tmp` file plus
rename), so a crash never leaves a half-written profile.
*remembering* is transparent in pipelines: _COMMAND_'s _stderr_
(where dmenu and fzf draw their interface) passes through, and its
exit status is forwarded. A cancelled menu --- a nonzero exit ---
aborts the run with the same status and learns nothing. A
successful run that picks nothing (empty output) also learns
nothing, and exits 0.
== OPTIONS
*-p* _PROFILE_::
The profile name to gather and store the ranking under (default:
the current directory, with every `/` turned into `!`). The
attached getopts form (`-pPROFILE`) is accepted too.
== IO
=== STDIN
The menu choices, one per line, in any order.
=== STDOUT
The pick, when there is one, followed by a newline. _COMMAND_'s
own output is captured, not echoed.
=== STDERR
_COMMAND_'s _stderr_, passed through untouched, and error
messages.
=== INPUT AND OUTPUT FILES
The profile, at:
[source,sh]
....
${XDG_DATA_HOME:-$HOME/.local/share}/remembering/$PROFILE
....
It is a plain text file with one line per known choice:
[source,sh]
....
2 profile firefox
0 profile mpv
7 profile mutt
....
The count comes first, the literal word `profile` second, and the
choice's text --- spaces included --- runs to the end of the line.
Lines are kept in byte order, with a newly learnt pick appended at
the end. The file is made to be hand-edited: delete a line to
forget it, edit a count to re-rank it.
== EXIT STATUS
0:: The pick was learnt and printed, or there was nothing to
learn (empty pick).
1:: A runtime error, such as an unreadable or unwritable profile.
2:: Usage error: an unknown option, or a missing _COMMAND_.
Otherwise, _COMMAND_'s own nonzero exit status, forwarded as-is
(or 128 plus the signal number when it was killed by a signal).
== SEE ALSO
dmenu(1), fzf(1), sort(1)
== AUTHORS
mailto:eu@euandre.org[EuAndreh] and contributors.
== BUGS
* Report bugs to the mailto:~euandreh/public-inbox@lists.sr.ht[mailing list].
Use the subject "[remembering] BUG or TASK: <description>".
* Browse bugs https://euandre.org/git/remembering/TODOs.html[online].
* https://euandre.org/git/remembering/[Homepage].
* https://lists.sr.ht/~euandreh/public-inbox?search=%5Bremembering%5D[Comments and discussions].
|
