loop.1

.TH LOOP 1 "July 2011" "Matze's Toolbox" "Shell Utilities"

.SH NAME
loop \- syntactic sugar for commandline loops

.SH SYNOPSIS
.nf
.RI "loop [\-cfhrvw] [\-d " seconds "] [\-i " iterations "] " command
.fi

.SH DESCRIPTION
.RB "The " loop " utility eases the creation of common commandline loops"
.RB "one would usually build upon " while " or " for "."
.RB "It's primarily designed to reduce the number of keystrokes during a"
.RB "shell session."

.SH OPTIONS
.TP
.BR "\-c, \-C"
.RB "Enables (-c) or disables (-C) " clear "(1) mode, where the screen is"
.RI "cleared every single iteration, before the " command " is executed."
.TP
.BI "\-d " seconds ", \-D"
.RI "Enables or disables delay mode. In this mode, after each execution of"
.IR command ", the script is paused for the given number of " seconds "."
.TP
.BR "\-f, \-F"
.RI "Enables or disables failure ignore mode. In this mode, the loop will"
.RI "continue even if the " command " exits with a failure status."
.TP
.BR "\-h, \-H"
.RB "Print a short help message on STDOUT or STDERR and exit."
.TP
.BI "\-i " iterations ", \-I"
.RI "Enables or disables iteration limit mode. In this mode, the loop will"
.RI "be aborted after the given number of " iterations " - unless another"
.RI "break condition has occured before."
.TP
.BR "\-r, \-R"
.RB "Enables or disables readline mode. In this mode, the loop will invoke"
.RB "the " read "(1) command for every iteration and export the content in"
.RB "the " $LINE " environment variable. Execution is stopped as soon as"
.BR EOF " is encountered."
.TP
.BR "\-v, \-V"
.RB "Enables or disables verbose mode."
.TP
.BR "\-w, \-W"
.RB "Enables or disables waitkey mode, where the loop is paused after each"
.RB "iteration until the RETURN key is pressed."

.SH COMMANDS
.RI "The " command " may be any shell command applicable. One should note"
.RI "the common pitfalls with shell escaping, such as the fact that the"
.RB "exported " $LINE " and " $ITER " variables have to be escaped and, "
.RI "e.g., stream redirection can get a bit tricky. The easiest way to get"
.RI "around this is usually to simply put the " command " in quotes."

.SH EXAMPLES
.nf
# Print "Hello World!" twice
loop -i 2 echo Hello World!

# Clear screen, run phpunit(1), ignore failures but do not start over
# until RETURN is pressed
loop -fc phpunit --wait --colors MyTestCase.php

# Display the source of loop(1), one line per second, enumerated
loop -rd 1 'echo "`printf %3d $ITER` $LINE"' < `which loop`
.fi

.SH ENVIRONMENT VARIABLES
.RB "The " loop " utility does not need any setup. However, it's possible"
.RB "to assign a default for the most common options:"
.TP
.BR LOOP_CLEAR
.RB "Corresponds to the " -c " option; if nonempty, " loop " will be in"
.BR clear "(1) mode by default. Can be overridden with " -C "."
.TP
.BR LOOP_IGNORE_FAILURES
.RB "Corresponds to the " -f " option; if nonempty, " loop " will ignore"
.RB "failures by default. Can be overridden with " -F "."
.TP
.BR LOOP_VERBOSE
.RB "Corresponds to the " -v " option; if nonempty, " loop " will create"
.RB "verbose output by default. Can be overriden with " -V "."
.TP
.BR LOOP_WAITKEY
.RB "Corresponds to the " -w " option; if nonempty, " loop " will wait for"
.RB "keystrokes by default. Can be overridden with " -W "."

.SH BUGS
.RB "Probably infinite. Especially the 'wait' mode, which is currently "
.RB "based on " dd "(1) and " stty "(1), may not be that portable."

.SH SEE ALSO
.BR clear "(1), " getopt "(1), " sh "(1)"

.SH COPYING
Mathias J. Hennig wrote this script and it's manual page. As long as you
retain this notice you can do whatever you want with this stuff.
If we meet some day, and you think this stuff is worth it, you can buy me
a beer in return.