.\" SPDX-License-Identifier: GPL-2.0-only
.\" Copyright (c) 1997-2007 Ralf S. Engelschall.
.\"
.Dd @ISELECT_VERSION_MDOC_DATE@
.Dt ISELECT 1
.ds doc-volume Ralf S. Engelschall
.Os ossp-iselect @ISELECT_VERSION_RAW@
.
.Sh NAME
.Nm iSelect
.Nd Interactive Selection Tool
.Sh SYNOPSIS
.Nm iselect
.Op Fl d Ar beg Ns Cm ,\& Ns Ar end
.Op Fl cfae
.Op Fl p Ar linenum
.Op Fl k Ar key Ns Op Cm :\& Ns Ar okey
.Op Fl m
.Op Fl n Ar name
.Op Fl t Ar title
.Op Fl SKP
.Op Fl Q Ar fallback
.Ar line Ns …
.
.Nm iselect
.Op Fl d Ar beg Ns Cm ,\& Ns Ar end
.Op Fl cfae
.Op Fl p Ar linenum
.Op Fl k Ar key Ns Op Cm :\& Ns Ar okey
.Op Fl m
.Op Fl n Ar name
.Op Fl t Ar title
.Op Fl SKP
.Op Fl Q Ar fallback
.Li <
.Pa lines
.
.Nm iselect
.Fl V Ns \&| Ns Fl h
.
.Sh DESCRIPTION
.Ss Intent
.Nm
is an interactive line selection tool,
operating via a full-screen Curses-based terminal session.
It can be used either as a user interface frontend
controlled by the shell, Perl, or another type of script backend as its wrapper,
or in batch as a pipe filter
.Pq usually between Nm grep Ns \& and the final executing command .
In other words:
.Nm
was designed to be used for any type of interactive line-based selection.
.
.Ss Input Data
If no arguments are given, lines are read from the standard input stream.
Otherwise,
.Ar line Ns s
are used directly.
.Pp
Each selectable line is fully bold;
parts of other lines may be set in bold by wrapping them in
.Ql <b>...</b> .
.
.Ss Selections
By default, a single line may be chosen;
with
.Fl m
multiple lines can be selected.
By default, only lines containing the tag
.Ql <s>
.Pq or with different delimiters set with Fl d
may be selected.
.Fl a
allows selecting all lines,
but the tag is always removed.
Selected lines are written to the standard output stream
.Pp
The tag has a variant that looks like
.Ql <s:result\ text> ,
which, instead of writing the line itself, writes
.Ar result\ text .
Every format specifier in the form
.Ql %[prompt\ string]s
or
.Ql %[prompt\ string]S
in the output is replaced by a line entered in an interactive prompt.
The
.Sy s
variant allows empty responses;
.Sy S
doesn't.
.
.Sh OPTIONS
.Ss Input Options
.Bl -tag -width 2n
.It Fl d Ar beg Ns Cm ,\& Ns Ar end , Fl -delimiter Ns = Ns Ar beg Ns Cm ,\& Ns Ar end
Sets the delimiters for the selection tags.
The default is
.Sy <
and
.Sy >
\(em the selection tags have to read
.Ql <s>
and
.Ql <s:result\ text> .
.
.It Fl c , -strip-comments
Discard input lines starting with
.Ql # .
.
.It Fl f , -force-browse
Open the full-screen browser even if input contains less than
.Pf < Em 2
lines.
This may happen anyway if a
.Ql %[prompt]s
needs to be substituted.
.
.It Fl a , -all-select
Force all lines to be selectable.
.Ql <s>
tags are still removed.
.
.It Fl e , -exit-no-select
Exit immediately if no lines are selectable.
.El
.
.Ss Display Options
.Bl -tag -width 2n
.It Fl p , -position Ns = Ns Ar linenum
Sets the cursor position to
.Sy 1 Ns -based
.Ar linenum Ns ber .
.
.It Fl k , -key Ns = Ns Ar key Ns Cm :\& Ns Ar okey
Maps
.Ar key
to
.Ar okey .
Both may be either a printable character or one of
.Sy SPACE ,
.Sy RETURN ,
.Sy KEY_UP
(\(ua),
.Sy KEY_DOWN
(\(da),
.Sy KEY_LEFT
(\(<-),
.Sy KEY_RIGHT
(\(->),
.Sy KEY_PPAGE
(PgUp),
.Sy KEY_NPAGE
(PgDn).
This can be given any number of times, and is applied in order.
.
.It Fl k , -key Ns = Ns Ar key
Same as
.Fl k Ar key Ns Cm :\& Ns Li RETURN .
For example,
.Fl k Ar f
allows using
.Ql f
to confirm the selection.
.
.It Fl m , -multi-line
Allow selecting more than one line with Space.
.
.It Fl n , -name Ns = Ns Ar name
Changes the string displayed flush left at the bottom of the browser window from "iSelect".
.
.It Fl t , -title Ns = Ns Ar title
Sets the
.Ar ,
displayed centered at the bottom of the browser window.
.El
.
.Ss Output Options
.Bl -tag -width 2n
.It Fl S , -strip-result
Strip all leading and trailing whitespace from the result string.
.
.It Fl K , -key-result
Prefix each result with the key used to confirm the selection.
This is usually
.Qq Sy RETURN
or
.Qq Sy KEY_RIGHT ,
but in the presence of
.Fl k ,
this is the (unmapped)
.Ar key ;
thus, with
.Fl k Ar f ,
selecting line
.Li Foo Bar
by pressing
.Ql f
yields
.Ql f:Foo\ Bar .
A Space is rendered as a literal space, not as
.Qq Sy SPACE .
.
.It Fl P , -position-result
Prefix each result with its
.Sy 1 Ns -based
line number in the buffer.
.
.It Fl Q , -quit-result Ns Li = Ns Ar fallback
Write
.Ar fallback
to the standard output stream when quitting.
.El
.
.Ss Giving Feedback
.Bl -tag -width 2n
.It Fl V , -version
Write the version and licence information to the standard output stream, exit
.Sy 0 .
.
.It Fl h , -help
Write the usage string information to the standard error stream, exit
.Sy 0 .
.El
.
.Sh KEYSTROKES
.Ss Cursor Movement
Use these to browse through the selection list:
.Bd -literal -compact
  CURSOR-UP ..... Move cursor one line up
  CURSOR-DOWN ... Move cursor one line down
  PAGE-UP ....... Move cursor one page up
  PAGE-DOWN ..... Move cursor one page down
  g ............. Goto first line
  G ............. Goto last line
.Ed
.
.Ss Line Selection
Use these to select one line and exit in standard mode,
or one or more lines in multi-line mode:
.Bd -literal -compact
  RETURN ........ Select line and exit
  CURSOR-RIGHT .. Select line and exit
  SPACE ......... Select line and stay (multi-line mode only)
  C ............. Clear current marks  (multi-line mode only)
.Ed
.
.Ss Others
Use these to quit
.Nm
or to show the help or version pages:
.Bd -literal -compact
  q ............. Quit (exit without selection)
  CURSOR-LEFT ... Quit (exit without selection)
  h ............. Help Page
  v ............. Version Page
.Ed
.
.Sh FILES
The Curses session is always opened on
.Pa /dev/tty ,
because the standard I/O streams are usually tied to pipes.
.
.Sh EXIT STATUS
.Bl -tag -compact -width ".Sy 0"
.It Sy 0
if a selection was made, a selection wasn't made, or succumbed to
.Dv SIGINT
or
.Dv SIGTERM .
.
.It Sy 1
if an unknown
.Oo Ar o Oc Ns Ar key
was given or an I/O error occurred.
.El
.
.Sh EXAMPLES
As an example we present a real-life situation where
.Nm
can enhance existing functionality.
We define two shell functions
.Pq for your Pa $HOME/.bashrc Ns \& file
which enhance the shell's
.Ic cd
built-in.
.
.Bd -literal -compact -offset 2n
.\" chdir/.bashrc inserted here
.Ed
.Pp
This
.Fn cd
is compatible with the built-in in the case
where the specified directory actually exists.
When it doesn't, the original
.Ic cd
would immediately give an error
.Pq assuming Ev CDPATH Ns \& is not set .
This version tries harder by searching for such a directory in a previously-built
.Pq via Fn cds
.Pq $HOME/.dirs
file.
When no match is found,
.Nm
just returns the given directory as the default result and
.Ic cd
fails as usual.
When only one directory was found,
.Nm
gives it to
.Ic cd
silently.
Only when more then one directory was found,
.Nm
shows a menu to pick between matches interactively.
The chosen directory is then given to
.Ic cd .
.Pp
For more useful examples on how to use
.Nm ,
see
@ISELECT_1_EXAMPLE_LOCATION@ .
.
.Sh AUTHORS
.An Ralf S. Engelschall Aq rse@engelschall.com
.Pq Lk http://www.engelschall.com
.
.Sh SEE ALSO
.Lk https://sr.ht/~nabijaczleweli/ossp New iSelect Home