.\" Manpage for ask.
.\" Contact bruce@bruce-hill.com to correct errors or typos.
.TH man 8 "4 June 2019" "1.0" "ask manual page"
.SH NAME
ask \- A tiny command line tool for getting user input
.SH SYNOPSIS
.B ask
[\fI-Q\fR|\fI--quickpick\fR]
[\fI-P\fR|\fI--password\fR]
[\fI-0\fR|\fI--read0\fR]
[\fI-y\fR|\fI--yes\fR]
[\fI-n\fR|\fI--no\fR]
[(\fI-H \fR|\fI--history=\fR) name]
[\fI-h\fR|\fI--help\fR]
[\fI-v\fR|\fI--version\fR]
[(\fI-q\fR |\fI--query=\fR) initial]
[(\fI-p\fR |\fI--prompt=\fR) prompt]
[\fIoptions...\fR]
.SH DESCRIPTION
\fBask\fR is a tiny console application that displays a prompt, gets user input
(with line editing and fuzzy finding functionality), and prints the result to
standard output
.SH OPTIONS
.B \-Q
.B \--quickpick
When used with fuzzy finding, as soon as exactly one match is found, exit and
print it.

.B \-P
.B \--password
Use password mode, which does not print user input as it's being typed.

.B \-0
.B \--read0
Read input delineated by NULL bytes instead of newlines.

.B \-v
.B \--version
Print \fBask\fR's version and exit.

.B \-h
.B \--help
Print \fBask\fR's usage and exit.

.B \-q <query>
.B \--query=<query>
If given, pre-populate the user input with this value.

.B \-p <prompt>
.B \--prompt=<prompt>
If provided, display the given prompt in bold. If the \fI-p\fR and
\fI--prompt=\fR flags are not used, the first positional argument is used as
the prompt, or \fB"> "\fR if there are no positional arguments.

.B \-H <file>
.B \--history=<file>
Use the given file as a history file. With a history file, you can browse
previously selected values with the up/down arrow keys.

.B \-y
.B \--yes
Quickpick between "y" and "n" with "[Y/n]" appended to the prompt, exiting with
success if "n" is not chosen.

.B \-n
.B \--no
Quickpick between "y" and "n" with "[y/N]" appended to the prompt, exiting with
failure if "y" is not chosen.

.B options...
If additional command line arguments are provided, or if any input is piped in,
\fBask\fR will operate in fuzzy finding mode, attempting to pick one of the
given options.

.SH EXAMPLES
.TP
.B
foo="`ask 'What is foo? '`"
Store user input in a variable. (Equivalent of \fBread -p 'What is foo? ' foo\fR)

.TP
.B
rm "`ls | ask 'Delete file: '`"
Fuzzy find a file. (Equivalent of \fBrm "`ls | fzf --prompt='Delete file: '`"\fR)

.TP
.B
if ask -y 'Do thing? '; then dothing; fi
Ask user for confirmation (default: yes).

.SH AUTHOR
Bruce Hill (bruce@bruce-hill.com)