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