.\" nroff source
.\" groff -man -Tascii replimenu.1
.\"
.TH replimenu 1 "Dec 2003" "replimenu 0.9" "replimenu"
.SH NAME
replimenu \- A small menu-system.
.SH VERSION
0.9
.SH SYNOPSIS
.BR "replimenu -h" | "-V"
.br
.BI "replimenu -f " "menufile " "[-c " colorscheme "] [-q] [-g " WxH "] [-a "item_names... "] [-e "i "]"
.SH DESCRIPTION
.B replimenu
is a small GNU GPL'ed menu-system mainly intended for use in shell
installation/configuration scripts, escpecially in an environment where size is
important, e.g. embedded systems.
.B replimenu
doesn't use (n)curses, something that results in small size and less hazzle.
.SH CHANGES IN VERSION 0.9
On slow consoles (e.g. VESA framebuffer) the menu would flicker whenever moving
up/down the menu, this has now been fixed (with a dirty hack). I have also
added a feature: inputboxes, msgboxes and yesnoboxes can now have a multi-line
message in them. Separate the string in \fBicaption\fP with a \fB\\n\fP to break
lines. Unfortunately, lines don't wrap.
.SH CHANGES IN VERSION 0.8 (0.8.1)
Bug fixes.
.SH CHANGES IN VERSION 0.7
Incorporated some features found in a patch for replimenu 0.3 contributed by
Paul Whittaker, made for his DIET-PC project (\fIhttp://diet-pc.sf.net/\fP).
The features include: Spacebar has the same effect as return on checkboxes and
radiobuttons. Added one new type, \fBdefaultfromenv\fP.
.SH CHANGES IN VERSION 0.6
Five new types; \fBhidden\fP, \fBpassword\fP, \fBchain\fP, \fBauto\fP and
\fBmsgbox\fP -- and one new variable; \fBexitafterauto\fP. The characteristics
of the \fBnotempty\fP type has been changed, it will now keep show the inputbox
until the user has entered a non-empty string. Also, three new command line
options; \fB-g\fP, \fB-a\fP and \fB-e\fP. One bug that caused segfaults has
also been found and resolved.
.SH CHANGES IN VERSION 0.5
You may specify a custom caption (using \fBicaption\fP) for input boxes and
\fByesno\fP (ask) types instead of the \fBlabel\fP of the menu item.
.SH CHANGES IN VERSION 0.4
You may now use `dummy' items both first and last (previously un-supported).
.SH CHANGES IN VERSION 0.3
Since 0.3 you have the ability to play with exit codes. The return code from
the \fBrunonexit\fP variable is passed to the exit code of replimenu. You may
also execute other `runonexit' commands by defining a \fBcommand\fP variable
for menu items named `QUIT'. The exit code of these commands are also passed to
replimenu. Yet another feature is to be able to execute the \fBrunonexit\fP
command before or after the \fBcommand\fP in a `QUIT' item, including choosing
which exit code to use. This is all done with the \fBrunonexitfirst\fP,
\fBrunonexitlast\fP, \fBusecommandretval\fP and \fBnocls\fP types. The default
is not to execute the \fBrunonexit\fP command in `QUIT' menu items that have a
non-empty \fBcommand\fP variable. There are two new variables in 0.3, \fBbr\fP
and \fBnocls\fP.
.SH HOW IT WORKS
In order to define a menu you have to write a menu configuration file,
.IR menufile .
This file holds the entire menu; items, commands, caption text, colour, etc.
.sp
\fBCommand line options\fP
.TP
.BI "-f " filename
This is the only obligatory option.
.I filename
is the name of a menu configuration file.
.TP
.BI "-c " colorscheme
.I colorscheme
is a number from 0 to 9 (currently available colour-schemes),
this will override the configuration file's colour-scheme (if any).
.TP
.B "-q"
This option will prevent the user from quitting replimenu, not even a
SIGTERM/SIGINT will quit. However, a menu item named \fBQUIT\fP will still quit
the menu.
.TP
.BI "-g " "WxH"
Force a geometry. This will prevent the ioctl() TIOCGWINSZ request to figure
out the current terminal size. It's useful for, e.g. telnet sessions that don't
DO NAWS. You may also consider using \fBstty cols 80 rows 25\fP on TTY:s (or
pseudo-tty:s) that are uninitialized. E.g.: \fBreplimenu -f fu.bar -g 80x25\fP.
.TP
.BI "-a " "item_names..."
A comma (\fB,\fP) separated list of menu item names to automatically execute on
start-up, e.g.: \fBreplimenu -f fu.bar -a fubar,snafu\fP.
.TP
.BI "-e " i
Set the `exitafterauto' flag. \fIi\fP is an integer (only 0 or 1 makes sense).
Can be used with the \fB-a\fP option. This option overrides the `exitafterauto'
variable in the menufile. E.g.: \fBreplimenu -f fu.bar -a fubar,snafu -e1\fP
(will auto-execute the items named \fIfubar\fP and \fIsnafu\fP then exit
replimenu).
.TP
.B "-h"
Help.
.TP
.B "-V"
Print version and exit immediately.
.SH MENU CONFIGURATION FILE
The menufile basically consists of two areas, a global where you specify
caption text, colour-scheme, textindent, etc. and one where you define the menu
items and their commands. All definitions are done in the manner of
\fIvariable=value\fP. Please note that you can not (yet) specify multi-line
variables (using e.g. a trailing \fB\\\fP).
.sp
.B Menufile variables
.RS
.TP
.B caption
The text that should appear in the caption on the first row.
.TP
.B text
The text that should appear in the body, right before the menu. This overrides
the environment variable \fBREPLIMENU_TEXT\fP.
.TP
.B aftertext
The text that should appear after the menu, just above the copyright-line. This
overrides the environment variable \fBREPLIMENU_AFTERTEXT\fP.
.TP
.B textindent
On what column the text in \fItext\fP should start on the screen, default is 2.
.TP
.B aftertextindent
On what column the text in \fIaftertext\fP should start on the screen, default is 2.
.TP
.B colorscheme
Which colour-scheme to use, default is 0. Available colour-schemes are 0 to 9.
.TP
.B runonexit
What command to run when exiting replimenu.
.TP
.B br
An alias for a \fBdummy\fP-type structure (see below). You may use this to
easily put space or comments between menu items. You may also use \fBdummy\fP,
an alias for \fBbr\fP.
.TP
.B nocls
This variable, defined alone without option, will prevent replimenu from
clearing the screen upon exit. For `QUIT' menu items you must use the
\fBnocls\fP type, as the default for `QUIT' menu items is to always clear the
screen.
.TP
.B exitafterauto
Defined alone without parameters this variable will tell replimenu to exit
immediately after running through menu items with the \fBauto\fP type set. If
there are no \fBauto\fP types available, replimenu will not exit. Because the
exit is like pressing Q, \fBrunonexit\fP can be used together with this option.
.TP
.B "begin menuitem"
Indicates the start of a menu item structure. This can also be \fBbegin
item\fP, \fBdefine item\fP or \fBstart item\fP.
./"************************************
.RS
.TP
.B name
The name of the menu item. If \fIname\fP is \fBQUIT\fP then this menu item can
be used to quit replimenu.
.TP
.B label
The label text that will visually appear in the menu.
.TP
.B icaption
Only for input boxes and `yesno' (`ask') types. You may use this variable to
optionally specify a different caption than \fBlabel\fP.
.TP
.B bullet
The icon next to the label text, defaults to \fBNUMBERED\fP which will
enumerate each menu item according to their position, starting from 1.
.TP
.B type
The type and characteristics of this menu item. The variables below can be OR'd
together to shape the item differently (e.g. \fBpause | input\fP).
./"************************************
.RS
.TP
.B regular
A regular menu item, that is, it will execute the command and return. This will
override any other value.
.TP
.B ask
Will ask whether to execute this command or not. Can also be \fByesno\fP.
.TP
.B input
Will produce a pop-up box with an input field. The user's input will be passed
to the environment variable \fBRM_INPUT\fP, that is, you can use it in the
\fBcommand\fP variable. Can also be \fBinputbox\fP.
.TP
.B pause
This will present a prompt just after a command returns and force the user to
press any key to continue.
.TP
.B msgbox
Or \fBmessagebox\fP, displays a simple one line message box with an
"OK-button".
.TP
.B variable
Or \fBvar\fP, changes the characteristics of the menu item entirely. This makes
the item a variable, basically an \fBinputbox\fP without a command. The
environment variable \fBRM_name\fP is set (where \fIname\fP is the name of the
menu item) to the value of the variable. If \fBvariable\fP is used together
with \fBask\fP then the value can only be \fIyes\fP or \fIno\fP. When replimenu
is initialized \fBRM_name\fP is set to the value of \fBdefault\fP.
.TP
.B checkbox
Or \fBoption\fP, creates a selectable menu item. When the item has an \fBX\fP
in it's checkbox the environment variable \fBRM_name\fP will be set to the
value of \fBdefault\fP. If the item is not selected, \fBRM_name\fP will not
exist in the environment. \fIname\fP is changed to the actual \fBname\fP of the
menu item. This item can be used together with \fBselected\fP.
.TP
.B radiobutton
Or \fBradio\fP. This menu item is for creating an array of selectable items
where only one of the items can be selected. To use this item, each
\fBradiobutton\fP that you want to be part of the same array must share the
same \fBname\fP, and each must have different \fBdefault\fP values. When an
item is selected \fBRM_name\fP (\fIname\fP is changed to the name of the item)
is set to \fBdefault\fP. This item can be used together with \fBselected\fP.
.TP
.B selected
To be used together with \fBcheckbox\fP or \fBradiobutton\fP, makes the item
selected by default.
.TP
.B setenvrmitem
Or \fBsetenvitem\fP, sets the environment variable \fBRM_ITEM\fP to this menu
item's name on execution of the command.
.TP
.B defaultfromenv
Or \fBdefaultfromenvironment\fP, or simply \fBdfenv\fP. If the \fBdefault\fP
field is empty, this option will cause replimenu to look for \fBRM_name\fP
(\fIname\fP is the name of the menu item) among the environment variables, if
it exists replimenu will use it's value as the \fBdefault\fP value.
.TP
.B runonexitfirst
This is only applicable for menu items named \fBQUIT\fP. \fBrunonexitfirst\fP
(or simply \fBrunonexit\fP) will execute the \fBrunonexit\fP command before
executing the command specified for the `QUIT' menu item. In order to use this,
the \fBcommand\fP variable for the `QUIT' item must not be empty. The default
behaviour of this option is to exit with the exit code of the \fBrunonexit\fP
command. You may choose which exit code to use by specifying the
\fBusecommandretval\fP type (e.g. \fBrunonexitfirst|usecommandretval\fP).
.TP
.B runonexitlast
Same as above, only execute the \fBrunonexit\fP command last. The default
behaviour of this option is to exit with the exit code of the \fBrunonexit\fP
command. You may choose which exit code to use by specifying the
\fBusecommandretval\fP type (e.g. \fBrunonexitfirst|usecommandretval\fP).
.TP
.B usecommandretval
Will tell replimenu to use the exit code of the \fBcommand\fP in a `QUIT' menu
item instead of the \fBrunonexit\fP code.
.TP
.B nocls
This type is specifically for `QUIT' menu items. It prevents replimenu from
clearing the screen upon exit.
.TP
.B hidden
This type will prevent the menu item from visually appearing in the menu. It's
still useful as a regular menu item, but only as either a variable or as a
member of a \fBchain\fP.
.TP
.B chain
If you wish to chain, that is, tie the current menu item together with the next
menu item. By pressing enter on a menu item with the \fBchain\fP type the
following menu item will also be executed (as if one pressed the next menu item
consecutively). It is mainly useful together with \fBhidden\fP types where only
the first chained item is visible.
.TP
.B password
Or simply \fBpasswd\fP. This will tell an \fBinput\fP type to show stars
(\fB*\fP) instead of actual characters.
.TP
.B auto
Also \fBautoexec\fP. Automatically execute this menu item on start-up. Every
menu item marked \fBauto\fP will be executed consecutively until there are no
\fBauto\fP types left to execute. You may also make replimenu exit once the
\fBauto\fP run is complete, see \fBexitafterauto\fP.
.TP
.B notempty
Don't allow a variable or input box value to be empty. If the user enters an
empty string in an inputbox (including \fBvar\fP type input boxes) replimenu
will keep show the inputbox and ask for input until a non-empty string has been
entered.
.TP
.B dummy
The characteristics of the \fBdummy\fP type has been changed since version 0.2.
You may now use it to separate menu items from each other or, e.g. add text
above a menu item. See the example configuration file below.
.RE
./"************************************
.TP
.B default
The default value of this menu item. Used together with \fBinputbox\fP,
\fBvar\fP, \fBcheckbox\fP or \fBradiobutton\fP.
.TP
.B command
The command to execute (if this menu item is not a variable) when pressing
return in the menu.
.RE
./"************************************
.TP
.B end
Ends the definition of a menu item structure. This can also be \fBstop\fP.
.RE
.sp
.B Example configuration file
.sp
.RS
.nf
caption = Example Menu
colorscheme = 2
text = Scroll up and down using the arrow-keys.
aftertext = For more info, visit:\\nhttp://replimenu.sf.net
runonexit = printenv | grep "RM_"
# don't clear the screen when exiting.
nocls

begin item
    name = option1
    type = checkbox | selected
    label = Check me please (-i)
    default = -i
    command = echo hello; read
end

begin item
    name = option2
    type = checkbox
    label = Check me too (-o)
    default = -o /tmp/tmpfile
end

## The old dummy way...

#begin item
#	type = dummy
#end
#begin item
#	type = dummy
#	label = Make your selection below
#end

## The new way (since 0.3) to do it...

br
br Make your selection below
br

begin item
    name = radio1
    type = radiobutton
    label = First choice
    default = 1
end

begin item
    name = radio1
    type = radiobutton|selected
    label = Second choice
    default = 2
end

begin item
    name = radio1
    type = radiobutton
    label = Third choice
    default = 3
end

br

## a few chained items
begin item
    name = uname
    label = Enter login info
    icaption = Enter user name:
    type = input | var | notempty | chain
    default = anonymous
end
begin item
    name = passwd
    label = password
    icaption = Enter password:
    type = input | var | notempty | chain | hidden | password
end
begin item
    name = doit
    label = show the results
    type = pause | hidden
    command = echo " uname: $RM_uname" ; echo "passwd: $RM_passwd"
end
## end of chained items

br

start item
    name = item2
    label = View mounts
    type = pause
    command = cat /proc/mounts
stop

begin item
    name = item3
    label = Enter your garbage code
    icaption = Enter your garbage code below:
    type = input | var | notempty
    default = Hello world
end

begin item
    name = item4
    label = fdformat /dev/fd0
    icaption = Really fdformat /dev/fd0 ?
    type = ask | pause
    command = fdformat /dev/fd0
end

br

begin item
    name = QUIT
    type = runonexitlast|usecommandretval
    bullet = <--
    label = Quit (condition 1)
    command = echo "Hello world"; exit 1
end

begin item
# since no runonexit was specified here,
# it will not run the runonexit command.
    name = QUIT
    bullet = <--
    label = Quit (condition 2)
    command = exit 2
end
.fi
.RE
.sp
.SH ENVIRONMENT VARIABLES
All \fBRM_\fP variables can be used when executing commands within the menu.
.TP
.B RM_ITEM
If \fBsetenvrmitem\fP is specified then this variable's value will be the name
of the menu item.
.TP
.B RM_INPUT
The value of an \fBinputbox\fP.
.TP
.B RM_name
In variables, checkboxes and radiobuttons, the \fIname\fP is replaced with the
item's name. This is a global variable, it can be used in every item in the
menu.
.TP
.B REPLIMENU_TEXT
Same as the \fBtext\fP variable in the menu file. The value of this variable
will be printed in the body before the menu.
.TP
.B REPLIMENU_AFTERTEXT
Same as the \fBaftertext\fP variable in the menu file. The value of this variable
will be printed in the body after the menu.
./"************************************
.SH NAVIGATION
You may use the \fIarrow keys\fP, \fIPage Up\fP, \fIPage Down\fP, \fIHome\fP
and \fIEnd\fP to navigate the menu. When an \fBinputbox\fP or an \fBask\fP item
is displayed you may press \fIESC\fP two times to cancel. Pressing \fIF10\fP or
\fIQ\fP will quit the menu (unless the \fB-q\fP option was specified).
./"************************************
.SH BUGS
Certainly. Report bugs to \fBreplichaun@zebra.ath.cx\fP, please be as specific
as possible and explain for me how to repeat the bug.
.SH COPYRIGHT
.B replimenu
is Copyright (C) 2003,2004 Michel Blomgren

.B replimenu
is free software; you can redistribute it and/or modify it under the terms of
the GNU General Public License as published by the Free Software Foundation;
either version 2 of the License, or (at your option) any later version.
.sp
.B replimenu
is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE.  See the GNU General Public License for more details (refer
to the COPYING-file).
.SH AUTHOR
Michel Blomgren
.RB ( replichaun@zebra.ath.cx )
.br
http://zebra.ath.cx
.br
http://replimenu.sourceforge.net
.SH SEE ALSO
.BR dialog (1),
.BR ncurses (3)