MENUSETS.4TH(8) 	  BSD System Manager's Manual	       MENUSETS.4TH(8)

NAME
     menusets.4th — FreeBSD dynamic submenu boot module

DESCRIPTION
     The file that goes by the name of menusets.4th is a set of commands
     designed to add submenu functionality to the dynamic menu system provided
     by menu.4th(8).  Submenus are managed through a system of carefully named
     environment variables.  The commands of menusets.4th by themselves are
     not enough for most uses.	Please refer to the examples below for the
     most common situations, and to menu.4th(8) for additional commands.

     Before using any of the commands provided in menusets.4th, it must be
     included through the command:

	   include menusets.4th

     This line is present in the default /boot/menu-commands.4th file, so it
     is not needed (and should not be re-issued) in a normal setup.

     The commands provided by it are:

	   menuset-loadsetnum	Takes a single integer on the stack to iden‐
				tify the menuset environment variables to be
				activated (see environment variables below).
	   menuset-loadinitial	If $menuset_initial is set, passes the value
				to menuset-loadsetnum.	The value must be a
				number.
	   menusets-unset	Unsets the environment variables associated
				with all menusets.  Increments starting at 1
				and stops at the first unconfigured menuset.
				A menuset is considered configured if the cap‐
				tion for item 1 is set.

     The environment variables that effect its behavior are:

	   menuset_initial
		     Number to pass to menuset-loadsetnum when menuset-load‐
		     initial is called.

	   menuset_nameN
		     Used to give a name to a menuset.

     When a menuset is NOT given a name (the default), menuset N is comprised
     of the following environment variables:

	   ansisetN_caption[x]	   -> ansi_caption[x]
	   ansisetN_caption[x][y]  -> ansi_caption[x][y]
	   menusetN_acpi	   -> menu_acpi
	   menusetN_caption[x]	   -> menu_caption[x]
	   menusetN_caption[x][y]  -> menu_caption[x][y]
	   menusetN_command[x]	   -> menu_command[x]
	   menusetN_init	   -> “evaluated”
	   menusetN_init[x]	   -> menu_init[x]
	   menusetN_keycode[x]	   -> menu_keycode[x]
	   menusetN_options	   -> menu_options
	   menusetN_optionstext    -> menu_optionstext
	   menusetN_reboot	   -> menu_reboot
	   toggledsetN_ansi[x]	   -> toggled_ansi[x]
	   toggledsetN_text[x]	   -> toggled_text[x]

     When you choose to give a menuset a name (by setting $menuset_nameN),
     menuset N is instead comprised of the following environment variables:

	   NAMEansi_caption[x]	   -> ansi_caption[x]
	   NAMEansi_caption[x][y]  -> ansi_caption[x][y]
	   NAMEmenu_acpi	   -> menu_acpi
	   NAMEmenu_caption[x]	   -> menu_caption[x]
	   NAMEmenu_caption[x][y]  -> menu_caption[x][y]
	   NAMEmenu_command[x]	   -> menu_command[x]
	   NAMEmenu_init	   -> “evaluated”
	   NAMEmenu_init[x]	   -> menu_init[x]
	   NAMEmenu_keycode[x]	   -> menu_keycode[x]
	   NAMEmenu_options	   -> menu_options
	   NAMEmenu_optionstext    -> menu_optionstext
	   NAMEmenu_reboot	   -> menu_reboot
	   NAMEtoggled_ansi[x]	   -> toggled_ansi[x]
	   NAMEtoggled_text[x]	   -> toggled_text[x]

     where “NAME” is the value of $menuset_nameN.  In the case of
     $NAMEmenu_init ($menusetN_init when $menuset_nameN is unset), the value
     is evaluated as an FICL statement.  This can be used to dynamically
     adjust the menuset variables right before the menu is activated.

     In addition, menusets.4th provides the following FICL words:

	   menuset-checksetnum (N --)
		    Given a single integer on the stack, sets a global vari‐
		    able menuset_use_name to a boolean based on whether
		    $menuset_nameN is set (true) or not (false).  Also sets
		    $affix temporary variable (prefix or infix depending on
		    menuset_use_name).	Automatically called by menuset-load‐
		    setnum and menusets-unset.
	   menuset-loadvar (--)
		    Used indirectly to shorten syntax and mitigate dictionary
		    size.  Requires the following temporary environment vari‐
		    ables:

			  type	 should be set to one of: menu toggled ansi
			  var	 should be set to one of: caption command key‐
				 code text ...
			  affix  either a prefix (menuset_use_name is true) or
				 infix (menuset_use_name is false)

		    If the global menuset_use_name is true, the variable
		    ${type}_${var} is made to equal the value of the variable
		    ${affix}${type}_${var} (note: in this case menuset-check‐
		    setnum has set $affix to $menuset_nameN).  Otherwise (when
		    menuset_use_name is false), the variable ${type}_${var} is
		    made to equal the value of the variable
		    ${type}set${affix}_${var} (note: in this case menuset-
		    checksetnum has set $affix to N).

		    Both the global variable menuset_use_name and the environ‐
		    ment variable $affix are automatically handled by menuset-
		    checksetnum above (which is automatically called by
		    menuset-loadsetnum).
	   menuset-unloadvar (--)
		    Used indirectly to shorten syntax and mitigate dictionary
		    size.  Like menuset-loadvar except it unsets the menuset
		    variable.  If global menuset_use_name is true ($affix is
		    $menuset_nameN), variable ${affix}${type}_${var} is unset.
		    Otherwise, $affix is N and variable
		    ${type}set${affix}_${var} is unset.
	   menuset-loadmenuvar (--)
		    Sets $type to “menu” and calls menuset-loadvar.
	   menuset-unloadmenuvar (--)
		    Sets $type to “menu” and calls menuset-unloadvar.
	   menuset-loadxvar (--)
		    Like menuset-loadvar except it takes an additional tempo‐
		    rary variable $x.  If the global menuset_use_name is true
		    (making $affix equal $menuset_nameN), sets variable
		    ${type}_${var}[${x}] to variable
		    ${affix}${type}_${var}[${x}].  Otherwise ($affix being N),
		    sets the same variable to instead
		    ${type}set{affix}_${var}[${x}].
	   menuset-unloadxvar (--)
		    Like menuset-loadxvar except it unsets the menuset vari‐
		    able.  If global menuset_use_name is true, unsets
		    ${affix}${type}_${var}[${x}].  Otherwise, unsets
		    ${type}set${affix}_${var}[${x}].
	   menuset-loadansixvar (--)
		    Sets $type to “ansi” and calls menuset-loadxvar
	   menuset-unloadansixvar (--)
		    Sets $type to “ansi” and calls menuset-unloadxvar
	   menuset-loadmenuxvar (--)
		    Sets $type to “ansi” and calls menuset-loadxvar
	   menuset-unloadmenuxvar (--)
		    Sets $type to “ansi” and calls menuset-unloadxvar
	   menuset-loadtoggledxvar (--)
		    Sets $type to “toggled” and calls menuset-loadxvar
	   menuset-unloadtoggledxvar (--)
		    Sets $type to “toggled” and calls menuset-unloadxvar
	   menuset-loadxyvar (--)
		    Like menuset-loadxvar except it takes an additional tempo‐
		    rary variable $y.  If the global menuset_use_name is true
		    ($affix is $menuset_nameN), sets variable
		    ${type}_${var}[${x}][${y}] to
		    ${affix}${type}_${var}[${x}][${y}].  Otherwise ($affix is
		    N) sets the same variable to instead
		    ${type}set${affix}_${var}[${x}][${y}].
	   menuset-unloadxyvar (--)
		    Like menuset-loadxyvar except it unsets the menuset vari‐
		    able.  If the global menuset_use_name is true, unsets
		    ${affix}${type}_${var}[${x}][${y}].  Otherwise, unsets
		    ${type}set${affix}_${var}[${x}][${y}].
	   menuset-loadansixyvar (--)
		    Sets $type to “ansi” and calls menuset-loadxyvar.
	   menuset-unloadansixyvar (--)
		    Sets $type to “ansi” and calls menuset-unloadxyvar.
	   menuset-loadmenuxyvar (--)
		    Sets $type to “menu” and calls menuset-loadxyvar.
	   menuset-unloadmenuxyvar (--)
		    Sets $type to “menu” and calls menuset-unloadxyvar.
	   menuset-setnum-namevar (N -- C-Addr/U)
		    Takes a single integer on the stack and replaces it with a
		    string (in c-addr/u format) whose value is
		    “menuset_nameN”.  For example, if given 1 returns
		    “menuset_name1”.
	   menuset-cleanup (N --)
		    Unsets all the various temporary variables, currently
		    type, var, x, y, and affix.

     For all values of “x” above, use any number between 1 through 9. Sorry,
     double-digits are not currently supported.  For all values of “N” above,
     use any number between 1 and 65535.

FILES
     /boot/loader	      The loader(8).
     /boot/menu.4th	      Dynamic menu module.
     /boot/menu-commands.4th  Contains the goto_menu command.
     /boot/menusets.4th       menusets.4th itself.
     /boot/loader.rc	      loader(8) bootstrapping script.

EXAMPLES
     A simple boot menu with a submenu:

	   include /boot/menu.4th
	   include /boot/menu-commands.4th
	   menu-init
	   set menuset1_caption[1]="Boot"
	   set menuset1_command[1]="boot"
	   set menuset1_caption[2]="Submenu..."
	   set menuset1_command[2]="2 goto_menu"
	   set menuset2_caption[1]="Back"
	   set menuset2_command[1]="1 goto_menu"
	   set menuset_initial=2
	   menuset-loadinitial
	   menu-display

     The same boot menu with named menusets:

	   include /boot/menu.4th
	   include /boot/menu-commands.4th
	   menu-init
	   set menuset_name1=main
	   set mainmenu_caption[1]="Boot"
	   set mainmenu_command[1]="boot"
	   set mainmenu_caption[2]="Submenu..."
	   set mainmenu_command[2]="2 goto_menu"
	   set menuset_name2=sub
	   set submenu_caption[1]="Back"
	   set submenu_command[1]="1 goto_menu"

SEE ALSO
     loader.conf(5), loader(8), loader.4th(8), menu.4th(8), beastie.4th(8)

HISTORY
     The menusets.4th set of commands first appeared in FreeBSD 10.0.

AUTHORS
     The menusets.4th set of commands was written by Devin Teske
     ⟨dteske@FreeBSD.org⟩.

BSD			       November 5, 2012 			   BSD