1.\" Copyright (c) 2012 Devin Teske 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.\" $FreeBSD$ 26.\" 27.Dd November 5, 2012 28.Dt MENUSETS.4TH 8 29.Os 30.Sh NAME 31.Nm menusets.4th 32.Nd FreeBSD dynamic submenu boot module 33.Sh DESCRIPTION 34The file that goes by the name of 35.Nm 36is a set of commands designed to add submenu functionality to the dynamic menu 37system provided by 38.Xr menu.4th 8 . 39Submenus are managed through a system of carefully named environment variables. 40The commands of 41.Nm 42by themselves are not enough for most uses. 43Please refer to the examples below for the most common situations, and to 44.Xr menu.4th 8 45for additional commands. 46.Pp 47Before using any of the commands provided in 48.Nm , 49it must be included 50through the command: 51.Pp 52.Dl include menusets.4th 53.Pp 54This line is present in the default 55.Pa /boot/menu-commands.4th 56file, so it is not needed (and should not be re-issued) in a normal setup. 57.Pp 58The commands provided by it are: 59.Pp 60.Bl -tag -width menuset-loadinitial -compact -offset indent 61.It Ic menuset-loadsetnum 62Takes a single integer on the stack to identify the menuset environment 63variables to be activated (see environment variables below). 64.It Ic menuset-loadinitial 65If $menuset_initial is set, passes the value to menuset-loadsetnum. 66The value must be a number. 67.It Ic menusets-unset 68Unsets the environment variables associated with all menusets. 69Increments starting at 1 and stops at the first unconfigured menuset. 70A menuset is considered configured if the caption for item 1 is set. 71.El 72.Pp 73The environment variables that effect its behavior are: 74.Bl -tag -width bootfile -offset indent 75.It Va menuset_initial 76Number to pass to menuset-loadsetnum when menuset-loadinitial is called. 77.It Va menuset_nameN 78Used to give a name to a menuset. 79.El 80.Pp 81When a menuset is NOT given a name (the default), 82menuset N is comprised of the following environment variables: 83.Pp 84.Bl -tag -width menusetN_caption[x][y] -compact -offset indent 85.It Va ansisetN_caption[x] 86-> ansi_caption[x] 87.It Va ansisetN_caption[x][y] 88-> ansi_caption[x][y] 89.It Va menusetN_acpi 90-> menu_acpi 91.It Va menusetN_caption[x] 92-> menu_caption[x] 93.It Va menusetN_caption[x][y] 94-> menu_caption[x][y] 95.It Va menusetN_command[x] 96-> menu_command[x] 97.It Va menusetN_init 98-> 99.Dq Li evaluated 100.It Va menusetN_init[x] 101-> menu_init[x] 102.It Va menusetN_keycode[x] 103-> menu_keycode[x] 104.It Va menusetN_options 105-> menu_options 106.It Va menusetN_optionstext 107-> menu_optionstext 108.It Va menusetN_reboot 109-> menu_reboot 110.It Va toggledsetN_ansi[x] 111-> toggled_ansi[x] 112.It Va toggledsetN_text[x] 113-> toggled_text[x] 114.El 115.Pp 116When you choose to give a menuset a name (by setting $menuset_nameN), 117menuset N is instead comprised of the following environment variables: 118.Pp 119.Bl -tag -width NAMEmenu_caption[x][y] -compact -offset indent 120.It Va NAMEansi_caption[x] 121-> ansi_caption[x] 122.It Va NAMEansi_caption[x][y] 123-> ansi_caption[x][y] 124.It Va NAMEmenu_acpi 125-> menu_acpi 126.It Va NAMEmenu_caption[x] 127-> menu_caption[x] 128.It Va NAMEmenu_caption[x][y] 129-> menu_caption[x][y] 130.It Va NAMEmenu_command[x] 131-> menu_command[x] 132.It Va NAMEmenu_init 133-> 134.Dq Li evaluated 135.It Va NAMEmenu_init[x] 136-> menu_init[x] 137.It Va NAMEmenu_keycode[x] 138-> menu_keycode[x] 139.It Va NAMEmenu_options 140-> menu_options 141.It Va NAMEmenu_optionstext 142-> menu_optionstext 143.It Va NAMEmenu_reboot 144-> menu_reboot 145.It Va NAMEtoggled_ansi[x] 146-> toggled_ansi[x] 147.It Va NAMEtoggled_text[x] 148-> toggled_text[x] 149.El 150.Pp 151where 152.Dq Li NAME 153is the value of $menuset_nameN. 154In the case of $NAMEmenu_init ($menusetN_init when $menuset_nameN is unset), 155the value is evaluated as an FICL statement. 156This can be used to dynamically adjust the menuset variables right before the 157menu is activated. 158.Pp 159In addition, 160.Nm 161provides the following FICL words: 162.Pp 163.Bl -tag -width menuset -compact -offset indent 164.It Ic menuset-checksetnum ( N -- ) 165Given a single integer on the stack, sets a global variable 166.Va menuset_use_name 167to a boolean based on whether $menuset_nameN is set (true) or not (false). 168Also sets $affix temporary variable (prefix or infix depending on 169menuset_use_name). 170Automatically called by menuset-loadsetnum and menusets-unset. 171.It Ic menuset-loadvar ( -- ) 172Used indirectly to shorten syntax and mitigate dictionary size. 173Requires the following temporary environment variables: 174.Pp 175.Bl -tag -width affix -compact -offset indent 176.It Va type 177should be set to one of: menu toggled ansi 178.It Va var 179should be set to one of: caption command keycode text ... 180.It Va affix 181either a prefix (menuset_use_name is true) or infix (menuset_use_name is false) 182.El 183.Pp 184If the global 185.Va menuset_use_name 186is true, the variable ${type}_${var} is made to 187equal the value of the variable ${affix}${type}_${var} 188(note: in this case menuset-checksetnum has set $affix to $menuset_nameN). 189Otherwise (when 190.Va menuset_use_name 191is false), the variable ${type}_${var} is made to 192equal the value of the variable ${type}set${affix}_${var} 193(note: in this case menuset-checksetnum has set $affix to N). 194.Pp 195Both the global variable 196.Va menuset_use_name 197and the environment variable $affix are automatically handled by 198menuset-checksetnum above (which is automatically called by 199menuset-loadsetnum). 200.It Ic menuset-unloadvar ( -- ) 201Used indirectly to shorten syntax and mitigate dictionary size. 202Like menuset-loadvar except it unsets the menuset variable. 203If global 204.Va menuset_use_name 205is true ($affix is $menuset_nameN), 206variable ${affix}${type}_${var} is unset. 207Otherwise, $affix is N and variable ${type}set${affix}_${var} is unset. 208.It Ic menuset-loadmenuvar ( -- ) 209Sets $type to 210.Dq menu 211and calls menuset-loadvar. 212.It Ic menuset-unloadmenuvar ( -- ) 213Sets $type to 214.Dq menu 215and calls menuset-unloadvar. 216.It Ic menuset-loadxvar ( -- ) 217Like menuset-loadvar except it takes an additional temporary variable $x. 218If the global 219.Va menuset_use_name 220is true (making $affix equal $menuset_nameN), 221sets variable ${type}_${var}[${x}] to variable ${affix}${type}_${var}[${x}]. 222Otherwise ($affix being N), sets the same variable to instead 223${type}set{affix}_${var}[${x}]. 224.It Ic menuset-unloadxvar ( -- ) 225Like menuset-loadxvar except it unsets the menuset variable. 226If global 227.Va menuset_use_name 228is true, unsets ${affix}${type}_${var}[${x}]. 229Otherwise, unsets ${type}set${affix}_${var}[${x}]. 230.It Ic menuset-loadansixvar ( -- ) 231Sets $type to 232.Dq ansi 233and calls menuset-loadxvar 234.It Ic menuset-unloadansixvar ( -- ) 235Sets $type to 236.Dq ansi 237and calls menuset-unloadxvar 238.It Ic menuset-loadmenuxvar ( -- ) 239Sets $type to 240.Dq ansi 241and calls menuset-loadxvar 242.It Ic menuset-unloadmenuxvar ( -- ) 243Sets $type to 244.Dq ansi 245and calls menuset-unloadxvar 246.It Ic menuset-loadtoggledxvar ( -- ) 247Sets $type to 248.Dq toggled 249and calls menuset-loadxvar 250.It Ic menuset-unloadtoggledxvar ( -- ) 251Sets $type to 252.Dq toggled 253and calls menuset-unloadxvar 254.It Ic menuset-loadxyvar ( -- ) 255Like menuset-loadxvar except it takes an additional temporary variable $y. 256If the global 257.Va menuset_use_name 258is true ($affix is $menuset_nameN), 259sets variable ${type}_${var}[${x}][${y}] to ${affix}${type}_${var}[${x}][${y}]. 260Otherwise ($affix is N) sets the same variable to instead 261${type}set${affix}_${var}[${x}][${y}]. 262.It Ic menuset-unloadxyvar ( -- ) 263Like menuset-loadxyvar except it unsets the menuset variable. 264If the global 265.Va menuset_use_name 266is true, unsets ${affix}${type}_${var}[${x}][${y}]. 267Otherwise, unsets ${type}set${affix}_${var}[${x}][${y}]. 268.It Ic menuset-loadansixyvar ( -- ) 269Sets $type to 270.Dq ansi 271and calls menuset-loadxyvar. 272.It Ic menuset-unloadansixyvar ( -- ) 273Sets $type to 274.Dq ansi 275and calls menuset-unloadxyvar. 276.It Ic menuset-loadmenuxyvar ( -- ) 277Sets $type to 278.Dq menu 279and calls menuset-loadxyvar. 280.It Ic menuset-unloadmenuxyvar ( -- ) 281Sets $type to 282.Dq menu 283and calls menuset-unloadxyvar. 284.It Ic menuset-setnum-namevar ( N -- C-Addr/U ) 285Takes a single integer on the stack and replaces it with a string (in c-addr/u 286format) whose value is 287.Dq menuset_nameN . 288For example, if given 1 returns 289.Dq menuset_name1 . 290.It Ic menuset-cleanup ( N -- ) 291Unsets all the various temporary variables, currently 292.Va type , 293.Va var , 294.Va x , 295.Va y , 296and 297.Va affix . 298.El 299.Pp 300For all values of 301.Dq Li x 302above, use any number between 1 through 9. Sorry, double-digits are not 303currently supported. 304For all values of 305.Dq Li N 306above, use any number between 1 and 65535. 307.Sh FILES 308.Bl -tag -width /boot/menu-commands.4th -compact 309.It Pa /boot/loader 310The 311.Xr loader 8 . 312.It Pa /boot/menu.4th 313Dynamic menu module. 314.It Pa /boot/menu-commands.4th 315Contains the goto_menu command. 316.It Pa /boot/menusets.4th 317.Nm 318itself. 319.It Pa /boot/loader.rc 320.Xr loader 8 321bootstrapping script. 322.El 323.Sh EXAMPLES 324A simple boot menu with a submenu: 325.Pp 326.Bd -literal -offset indent -compact 327include /boot/menu.4th 328include /boot/menu-commands.4th 329menu-init 330set menuset1_caption[1]="Boot" 331set menuset1_command[1]="boot" 332set menuset1_caption[2]="Submenu..." 333set menuset1_command[2]="2 goto_menu" 334set menuset2_caption[1]="Back" 335set menuset2_command[1]="1 goto_menu" 336set menuset_initial=2 337menuset-loadinitial 338menu-display 339.Ed 340.Pp 341The same boot menu with named menusets: 342.Pp 343.Bd -literal -offset indent -compact 344include /boot/menu.4th 345include /boot/menu-commands.4th 346menu-init 347set menuset_name1=main 348set mainmenu_caption[1]="Boot" 349set mainmenu_command[1]="boot" 350set mainmenu_caption[2]="Submenu..." 351set mainmenu_command[2]="2 goto_menu" 352set menuset_name2=sub 353set submenu_caption[1]="Back" 354set submenu_command[1]="1 goto_menu" 355.Ed 356.Sh SEE ALSO 357.Xr loader.conf 5 , 358.Xr beastie.4th 8 , 359.Xr loader 8 , 360.Xr loader.4th 8 , 361.Xr menu.4th 8 362.Sh HISTORY 363The 364.Nm 365set of commands first appeared in 366.Fx 10.0 . 367.Sh AUTHORS 368The 369.Nm 370set of commands was written by 371.An -nosplit 372.An Devin Teske Aq dteske@FreeBSD.org . 373