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