code / tomo

   1 '\" t
   2 .\" Copyright (c) 2025 Bruce Hill
   3 .\" All rights reserved.
   4 .\"
   5 .TH ask 3 2025-11-29 "Tomo man-pages"
   6 .SH NAME
   7 ask \- get user input
   8 .SH LIBRARY
   9 Tomo Standard Library
  10 .SH SYNOPSIS
  11 .nf
  12 .BI ask\ :\ func(prompt:\ Text,\ bold:\ Bool\ =\ yes,\ force_tty:\ Bool\ =\ yes\ ->\ Text?)
  13 .fi
  14 .SH DESCRIPTION
  15 Gets a line of user input text with a prompt.
  16 
  17 
  18 .SH ARGUMENTS
  19 
  20 .TS
  21 allbox;
  22 lb lb lbx lb
  23 l l l l.
  24 Name	Type	Description	Default
  25 prompt	Text	The text to print as a prompt before getting the input. 	-
  26 bold	Bool	Whether or not to print make the prompt appear bold on a console. 	yes
  27 force_tty	Bool	Whether or not to force the use of /dev/tty. 	yes
  28 .TE
  29 .SH RETURN
  30 A line of user input text without a trailing newline, or empty text if something went wrong (e.g. the user hit `Ctrl-D`).
  31 
  32 .SH NOTES
  33 When a program is receiving input from a pipe or writing its output to a pipe, this flag (which is enabled by default) forces the program to write the prompt to `/dev/tty` and read the input from `/dev/tty`, which circumvents the pipe. This means that `foo | ./tomo your-program | baz` will still show a visible prompt and read user input, despite the pipes. Setting this flag to `no` will mean that the prompt is written to `stdout` and input is read from `stdin`, even if those are pipes.
  34 
  35 .SH EXAMPLES
  36 .EX
  37 assert ask("What's your name? ") == "Arthur Dent"
  38 .EE