README

   1                                     /\        /\
   2    ____   ____   ________   ____   / / ___   / /_   ___
   3   / ___\ / __ \ / __  __ \ / __ \ / /.'__ \ / ___\.'__ \
   4  / /__  / /_/ // / / / / // /_/ // // ____// /   / ____/
   5  \____\ \____/ \/  \/  \// ____/ \/ \___\  \/    \___\                2016-09-20
   6 =========================\/=====================================================
   7 Filter lines form stdin to print to stdout using user keyboard input
   8
   9         I will hopefully write this in ANSI C some day...  At least I
  10         really wish I will ever be able to!
  11
  12         The goal is to learn (ANSI) C, and mostly to be able to do
  13         interfaces like those of vimperator.
  14
  15
  16 OPTIONS / FEATURES                                                    2016-09-19
  17 --------------------------------------------------------------------------------
  18 Description of the features I will possibly implement.
  19
  20         Lower case switches for interface, uppercase switches for
  21         input/output.
  22
  23         -p PROMPT
  24                 Aditionnal part of the prompt to add before the '> '.
  25
  26         -n
  27                 Display line number before the match.
  28
  29         -N
  30                 Only return the line number.
  31
  32         -k VALIDATEKEY
  33                 Aditionnal key to use to return current selection.
  34                 This can a space for use as a word completion engine
  35                 (Ctrl + N in vim).
  36
  37         -s SEPARATOR
  38                 Separator for the output:  The selected candidate will be
  39                 printed up to this separator, rather than being printed
  40                 completely.  The separator will be aligned according
  41                 to 2 rules: 1. The biggest part before separator; 2. Do
  42                 not outreach the half of the screen horizontally.
  43
  44                 The right part will also be grayed, and not printed in
  45                 the prompt.
  46
  47                 This is why this needs to be dynamic and be coded in
  48                 the source rather than in the integration tools (do ONE
  49                 THING and do it well...).
  50
  51         -c COMMENT
  52                 Comment char: Every line starting with this character
  53                 will be treated as a header.  Header are always visible
  54                 and bold (\033[1m), even when not matched.  This is
  55                 convenient to prompt the user items from multiple
  56                 categories at the same time.
  57
  58         -l LINES
  59                 Number of lines to display at once.  Default is 10.
  60
  61         -b
  62                 Display (and update) the prompt to be at the bottom of
  63                 the candidates, and at the bottom of the screen.
  64
  65         -t
  66                 Display (and update) the prompt to be at the top of the
  67                 candidates, and at the bottom of the screen.
  68
  69         -d DEFAULT
  70                 Set the input a DEFAULT string before to start.
  71
  72         -h HEADER
  73                 Set the character to use to mark header and delimit
  74                 sections.
  75
  76
  77 KEYBINDINGS                                                           2016-09-18
  78 --------------------------------------------------------------------------------
  79
  80         Ctrl + I
  81         Tab
  82                 Switch between candidates, and finally come back to the
  83                 original input without completion.
  84
  85         Ctrl + H
  86         Backspace
  87                 Delete one char backward, but if there is no char
  88                 backward, it should return an error code of 1.
  89
  90         Ctrl + C
  91                 Cancel, and make filter return the error code of 1.
  92
  93         Ctrl + V  KEY
  94                 Insert the next KEY pressed literally.
  95
  96         Ctrl + W
  97                 Deletes the last entered word.
  98
  99         Ctrl + U
 100                 Deletes the entire input.
 101
 102 MATCHING                                                              2016-09-19
 103 --------------------------------------------------------------------------------
 104
 105         I like the lines order to be preserved while matching.  This can
 106         be convenient to pipe a file through filter, moreover.
 107
 108         Spaces are considered as a '*' wildchar or '.*' regular
 109         expression.  All other characters are consecutive characters
 110         to match.  This is hence not a fuzzy matching.  There are fzf
 111         and the very good fzy for that
 112
 113         While numbers are displayed (-n option), the number typed at
 114         the beginning of input match in priority these displayed numbers.
 115
 116
 117 INTERFACE                                                             2016-09-18
 118 --------------------------------------------------------------------------------
 119 Differences and similarity with vimperator input.
 120
 121         In adition to vimperator behavior, a count would be displayed
 122         in top right hand corner of the current input line, not used as
 123         the completion may be rather small.  I will need a way to manage
 124         long line in input anyway, because the case with long lines and
 125         small screen _will_ occur.
 126
 127         In vimperator, there is a grayed text after the input,
 128         corresponding to the completion.  This is a nice feature and I
 129         plan to do this: \033[1;0m can output gray text even it TTY.
 130
 131         The matched string should be highlighted in candidates.
 132
 133         The current candidate should be highlighted with '\033[7m' prevent
 134         the matched string to appear liht yellow on white background.
 135
 136         It could be nice if the candidates could be loaded dynamically,
 137         to act like `fzf` does.  Because it look good, and I would not
 138         have to wait find on ~ to find a file to select it.
 139
 140
 141 USAGE                                                                 2016-09-18
 142 --------------------------------------------------------------------------------
 143 Example that can replicate advanced vimperator completion features
 144
 145         In vimperator, while space is pressed, it prompts for the next
 146         input to enter, and still keep the current input onscreen.
 147         Backspace delete the input.
 148
 149         This can be performed with filter:
 150
 151         By setting '-k' to a space, at every word, the completion
 152         is stored.
 153
 154         Then a new prompt is generated using the previous word as a prompt
 155
 156         By checking for the return value, and if it is >0 (there was
 157         an error, the user cancelled (Ctrl + C) or pressed backspace at
 158         the beginning of the line), then reiterate the previous prompt.
 159
 160         This then permits to select from a first level input (like
 161         commands), then according to the command, select second level
 162         input different for each command (like flags or 'empty'), and
 163         then, select a third level input (like filename)...