2 | ,--. --.-. ---. | ,--. |-- ,--.
3 | | | | | | | | | |--' | |--'
4 `--' `--' ' ' ' |--' ' `--' ' `--' 2016-10-18
5 ---------------- | -------------------------------------------------------------
6 Filter lines form stdin to print to stdout using user keyboard input
8 I will hopefully write this in ANSI C some day... At least I
9 really wish I will ever be able to!
11 The goal is to learn (ANSI) C, and mostly to be able to do
12 interfaces like those of vimperator.
16 --------------------------------------------------------------------------------
17 Description of the features I will possibly implement.
19 Lower case switches for interface, uppercase switches for
23 Aditionnal part of the prompt to add before the '> '.
26 Display line number before the match.
29 Only return the line number.
32 Output the current candidate repeteadly every time it
33 changes: at each movement.
36 Aditionnal key to use to return current selection.
37 This can a space for use as a word completion engine
41 Separator for the output: The selected candidate will be
42 printed up to this separator, rather than being printed
43 completely. The separator will be aligned according
44 to 2 rules: 1. The biggest part before separator; 2. Do
45 not outreach the half of the screen horizontally.
47 The right part will also be grayed, and not printed in
50 This is why this needs to be dynamic and be coded in
51 the source rather than in the integration tools (do ONE
52 THING and do it well...).
55 Comment char: Every line starting with this character
56 will be treated as a header. Header are always visible
57 and bold (\033[1m), even when not matched. This is
58 convenient to prompt the user items from multiple
59 categories at the same time.
62 Number of lines to display at once. Default is 10.
65 Display (and update) the prompt to be at the bottom of
66 the candidates, and at the bottom of the screen.
69 Display (and update) the prompt to be at the top of the
70 candidates, and at the bottom of the screen.
73 Set the input a DEFAULT string before to start.
76 Set the character to use to mark header and delimit
81 --------------------------------------------------------------------------------
85 Switch between candidates, and finally come back to the
86 original input without completion.
90 Delete one char backward, but if there is no char
91 backward, it should return an error code of 1.
94 Cancel, and make filter return the error code of 1.
97 Insert the next KEY pressed literally.
100 Deletes the last entered word.
103 Deletes the entire input.
106 --------------------------------------------------------------------------------
108 I like the lines order to be preserved while matching. This can
109 be convenient to pipe a file through filter, moreover.
111 Spaces are considered as a '*' wildchar or '.*' regular
112 expression. All other characters are consecutive characters
113 to match. This is hence not a fuzzy matching. There are fzf
114 and the very good fzy for that
116 While numbers are displayed (-n option), the number typed at
117 the beginning of input match in priority these displayed numbers.
121 --------------------------------------------------------------------------------
122 Differences and similarity with vimperator input.
124 In adition to vimperator behavior, a count would be displayed
125 in top right hand corner of the current input line, not used as
126 the completion may be rather small. I will need a way to manage
127 long line in input anyway, because the case with long lines and
128 small screen _will_ occur.
130 In vimperator, there is a grayed text after the input,
131 corresponding to the completion. This is a nice feature and I
132 plan to do this: \033[1;0m can output gray text even it TTY.
134 The matched string should be highlighted in candidates.
136 The current candidate should be highlighted with '\033[7m' prevent
137 the matched string to appear liht yellow on white background.
139 It could be nice if the candidates could be loaded dynamically,
140 to act like `fzf` does. Because it look good, and I would not
141 have to wait find on ~ to find a file to select it.
145 --------------------------------------------------------------------------------
146 Example that can replicate advanced vimperator completion features
148 In vimperator, while space is pressed, it prompts for the next
149 input to enter, and still keep the current input onscreen.
150 Backspace delete the input.
152 This can be performed with filter:
154 By setting '-k' to a space, at every word, the completion
157 Then a new prompt is generated using the previous word as a prompt
159 By checking for the return value, and if it is >0 (there was
160 an error, the user cancelled (Ctrl + C) or pressed backspace at
161 the beginning of the line), then reiterate the previous prompt.
163 This then permits to select from a first level input (like
164 commands), then according to the command, select second level
165 input different for each command (like flags or 'empty'), and
166 then, select a third level input (like filename)...
170 --------------------------------------------------------------------------------
172 These resources were very conveninent while making this software.
173 Thank you to the respective authors, that taught me C by writing
176 - https://github.com/martanne/vis/blob/master/vis-menu.c
177 - https://github.com/charles-l/pep/blob/master/pep.c
178 - http://git.suckless.org/sandy/tree/sandy.c