1 .TH "SELECTOR" "1.1.7" "February 2013" "Francois Fleuret" "User Commands"
3 \" This man page was written by Francois Fleuret <francois@fleuret.org>
4 \" and is distributed under a Creative Commons Attribution-Share Alike
9 selector \- A simple command line utility for dynamic pattern selection
13 \fBselector\fP [\fIoptions\fR] [\fI<filename1>\fR [\fI<filename2>\fR ...]]
17 \fBselector\fP is a command line utility for interactive real-time
18 pattern matching. It reads the content of the specified files, and as
19 the user types a list of strings separated by ";" (or a regexp), the
20 display is updated in real time to show only the lines containing all
21 the said strings (or matching the regexp).
23 This command was mainly designed as a way to search efficiently in the
24 shell history, for which it is substantially better than the standard
25 readline ^R binding. With the -v option, it injects the selected line
26 into the tty input buffer, hence allowing the user to edit the line
27 and execute it as a standard command.
29 Selector is also a handy tool to test regexps, or to display menus
30 with many possible choices. For the latter, the -x option allows to
31 show different strings than the ones returned.
33 Note that because this is an interactive command, the standard input
34 cannot be used as one of the input files.
36 .SH "USING SELECTOR IN BASH"
38 The selector command comes with a shell script for bash. If you add
42 .B source bash-selector.sh --hist --cd
45 in your \fB~/.bashrc\fR, it will remap M-r to the smart history search,
46 and redefine \fBcd\fR so that M-c provides a smart cd history.
48 This script relies on readline being configured with the default
49 emacs-style key bindings. You may have to hack a bit if you want to
50 use it with the vi-style mode.
54 Keys corresponding to ASCII codes between " " and "~" add a character
55 to the pattern string. The Backspace key, "^H" and "^?" delete the
56 character immediately on the left of the cursor, while the Delete key
57 and "^D" delete the character at cursor location.
59 The Left and Right cursor keys move the editing cursor
60 accordingly. The Up and Down cursor keys move the selected line one
61 entry at a time, and PageUp and PageDown move it by ten entries. The
62 Home and End key move to the top and the bottom of the list
63 respectively. The return key selects the current line and exits.
65 The keys "^A", "^E", "^U", and "^K" do somehow what they do in
66 readline, and you can exit selector without doing anything by either
67 interrupting the command with "^C" or by typing "^G" or the Escape
70 The key "^R" switches between the multi-substring and the regexp
71 selection mode, and "^I" between the case-sensitive and
72 case-insensitive modes.
76 \fB-h\fR, \fB--help\fR
79 \fB-m\fR, \fB--monochrome\fR
80 force the monochrome mode
82 \fB-i\fR, \fB--revert-order\fR
83 revert the order of the lines
85 \fB-b\fR, \fB--remove-bash-prefix\fR
86 remove the numeric prefix from bash history
88 \fB-z\fR, \fB--remove-zsh-prefix\fR
89 remove the time prefix from zsh history
91 \fB-d\fR, \fB--remove-duplicates\fR
92 remove duplicated lines (note that you can have two different lines
93 with the same visible part if you use the -x option)
95 \fB-e\fR, \fB--regexp\fR
98 \fB-a\fR, \fB--case-sensitive\fR
99 start in case-sensitive mode
101 \fB-j\fR, \fB--show-long-lines\fR
102 print a long-line indicator at the end of truncated lines
104 \fB-y\fR, \fB--show-hits\fR
105 highlight the part(s) of each line which match(es) the substrings or regexp
107 \fB-u\fR, \fB--upper-case-makes-case-sensitive\fR
108 using an upper case in the matching string makes the matching
111 \fB-q\fR, \fB--no-beep\fR
112 make a flash instead of a beep when there is an edition error
115 state that all following arguments are filenames
118 standard setting for bash history search, same as
120 -b -i -d -v -w -l ${HISTSIZE}
122 \fB-t \fI<title>\fR, \fB--title \fI<title>\fR
123 add a title in the modeline
125 \fB-r \fI<pattern>\fR, \fB--pattern \fI<pattern>\fR
128 \fB-c \fI<colors>\fR, \fB--colors \fI<colors>\fR
129 select the modeline and highlight color numbers with a color list of
132 \fI<fg_modeline>,<bg_modeline>,<fg_highlight>,<bg_highlight>\fR
134 \fB-v\fR, \fB--inject-in-tty\fR
135 inject the selected line into the tty input buffer
137 \fB-w\fR, \fB--add-control-qs\fR
138 add ^Q between characters during tty injection to quote control characters
140 \fB-o \fI<filename>\fR, \fB--output-file \fI<filename>\fR
141 write the selected line into the specified file
143 \fB-s \fI<separator>\fR, \fB--pattern-separator \fI<separator>\fR
144 specify the character to separate the substrings in the search pattern
146 \fB-x \fI<separator>\fR, \fB--label-separator \fI<separator>\fR
147 specify the character to separate what to show to the user during the
148 selection from the line to return. If the provided separator is "\\n",
149 the lines to show to the user alternate with the lines to return
151 \fB-l \fI<number>\fR, \fB--number-of-lines \fI<number>\fR
152 specify the maximum number of lines to take into account
156 To use selector to search into your bash history
160 .B selector -q --bash <(history)
163 To show a list of directories and insert a cd command to the selected
168 .B selector -v -x \(dq\\n\(dq <(find . -type d | awk \(aq{ print $0\(dq\\ncd \(dq$0 }\(aq)
171 To select a line in a long text and write the line number in /tmp/nb
175 .B selector -o /tmp/nb -x \(dq\\n\(dq <(awk < something.txt \(aq{ print $0\(dq\\n\(dqNR }\(aq)
179 There are modeline display problems if the pattern is too long. This
180 program does not handle multibyte characters.
182 The \fB-v\fR option does not work on FreeBSD 8.0 since the TIOCSTI
183 ioctl request is broken.
187 Written by Francois Fleuret <francois@fleuret.org> and distributed
188 under the terms of the GNU General Public License version 3 as
189 published by the Free Software Foundation. This is free software: you
190 are free to change and redistribute it. There is NO WARRANTY, to the
191 extent permitted by law.