README

   1  ,--.                 |      |
   2  |    ,--. --.-. ---. | ,--. |-- ,--.
   3  |    |  | | | | |  | | |--' |   |--'
   4  `--' `--' ' ' ' |--' ' `--' '   `--'                                 2016-10-18
   5 ---------------- | -------------------------------------------------------------
   6 Filter lines form stdin to print to stdout using user keyboard input
   7
   8         I will hopefully write this in ANSI C some day...  At least I
   9         really wish I will ever be able to!
  10
  11         The goal is to learn (ANSI) C, and mostly to be able to do
  12         interfaces like those of vimperator.
  13
  14
  15 OPTIONS / FEATURES
  16 --------------------------------------------------------------------------------
  17 Description of the features I will possibly implement.
  18
  19         Lower case switches for interface, uppercase switches for
  20         input/output.
  21
  22         -p PROMPT
  23                 Aditionnal part of the prompt to add before the '> '.
  24
  25         -n
  26                 Display line number before the match.
  27
  28         -N
  29                 Only return the line number.
  30
  31         -r
  32                 Output the current candidate repeteadly every time it
  33                 changes: at each movement.
  34
  35         -k VALIDATEKEY
  36                 Aditionnal key to use to return current selection.
  37                 This can a space for use as a word completion engine
  38                 (Ctrl + N in vim).
  39
  40         -s SEPARATOR
  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.
  46
  47                 The right part will also be grayed, and not printed in
  48                 the prompt.
  49
  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...).
  53
  54         -c COMMENT
  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.
  60
  61         -l LINES
  62                 Number of lines to display at once.  Default is 10.
  63
  64         -b
  65                 Display (and update) the prompt to be at the bottom of
  66                 the candidates, and at the bottom of the screen.
  67
  68         -t
  69                 Display (and update) the prompt to be at the top of the
  70                 candidates, and at the bottom of the screen.
  71
  72         -d DEFAULT
  73                 Set the input a DEFAULT string before to start.
  74
  75         -h HEADER
  76                 Set the character to use to mark header and delimit
  77                 sections.
  78
  79
  80 KEYBINDINGS
  81 --------------------------------------------------------------------------------
  82
  83         Ctrl + I
  84         Tab
  85                 Switch between candidates, and finally come back to the
  86                 original input without completion.
  87
  88         Ctrl + H
  89         Backspace
  90                 Delete one char backward, but if there is no char
  91                 backward, it should return an error code of 1.
  92
  93         Ctrl + C
  94                 Cancel, and make filter return the error code of 1.
  95
  96         Ctrl + V  KEY
  97                 Insert the next KEY pressed literally.
  98
  99         Ctrl + W
 100                 Deletes the last entered word.
 101
 102         Ctrl + U
 103                 Deletes the entire input.
 104
 105 MATCHING
 106 --------------------------------------------------------------------------------
 107
 108         I like the lines order to be preserved while matching.  This can
 109         be convenient to pipe a file through filter, moreover.
 110
 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
 115
 116         While numbers are displayed (-n option), the number typed at
 117         the beginning of input match in priority these displayed numbers.
 118
 119
 120 INTERFACE
 121 --------------------------------------------------------------------------------
 122 Differences and similarity with vimperator input.
 123
 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.
 129
 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.
 133
 134         The matched string should be highlighted in candidates.
 135
 136         The current candidate should be highlighted with '\033[7m' prevent
 137         the matched string to appear liht yellow on white background.
 138
 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.
 142
 143
 144 USAGE
 145 --------------------------------------------------------------------------------
 146 Example that can replicate advanced vimperator completion features
 147
 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.
 151
 152         This can be performed with filter:
 153
 154         By setting '-k' to a space, at every word, the completion
 155         is stored.
 156
 157         Then a new prompt is generated using the previous word as a prompt
 158
 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.
 162
 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)...
 167
 168
 169 RESOURCES
 170 --------------------------------------------------------------------------------
 171
 172         These resources were very conveninent while making this software.
 173         Thank you to the respective authors, that taught me C by writing
 174         some:
 175
 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
 179
 180