1 .\" Copyright (c) 2012 Devin Teske
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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.
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
30 .Nd loader dynamic submenu boot module
32 The file that goes by the name of
34 is a set of commands designed to add submenu functionality to the dynamic menu
37 Submenus are managed through a system of carefully named environment variables.
40 by themselves are not enough for most uses.
41 Please refer to the examples below for the most common situations, and to
43 for additional commands.
45 Before using any of the commands provided in
50 .Dl include menusets.4th
52 This line is present in the default
53 .Pa /boot/forth/menu-commands.4th
54 file, so it is not needed (and should not be re-issued) in a normal setup.
56 The commands provided by it are:
58 .Bl -tag -width menuset-loadinitial -compact -offset indent
59 .It Ic menuset-loadsetnum
60 Takes a single integer on the stack to identify the menuset environment
61 variables to be activated (see environment variables below).
62 .It Ic menuset-loadinitial
63 If $menuset_initial is set, passes the value to menuset-loadsetnum.
64 The value must be a number.
66 Unsets the environment variables associated with all menusets.
67 Increments starting at 1 and stops at the first unconfigured menuset.
68 A menuset is considered configured if the caption for item 1 is set.
71 The environment variables that effect its behavior are:
72 .Bl -tag -width bootfile -offset indent
73 .It Va menuset_initial
74 Number to pass to menuset-loadsetnum when menuset-loadinitial is called.
76 Used to give a name to a menuset.
79 When a menuset is NOT given a name (the default),
80 menuset N is comprised of the following environment variables:
82 .Bl -tag -width menusetN_caption[x][y] -compact -offset indent
83 .It Va ansisetN_caption[x]
85 .It Va ansisetN_caption[x][y]
89 .It Va menusetN_caption[x]
91 .It Va menusetN_caption[x][y]
93 .It Va menusetN_command[x]
98 .It Va menusetN_init[x]
100 .It Va menusetN_keycode[x]
102 .It Va menusetN_options
104 .It Va menusetN_optionstext
106 .It Va menusetN_reboot
108 .It Va toggledsetN_ansi[x]
110 .It Va toggledsetN_text[x]
114 When you choose to give a menuset a name (by setting $menuset_nameN),
115 menuset N is instead comprised of the following environment variables:
117 .Bl -tag -width NAMEmenu_caption[x][y] -compact -offset indent
118 .It Va NAMEansi_caption[x]
120 .It Va NAMEansi_caption[x][y]
121 -> ansi_caption[x][y]
124 .It Va NAMEmenu_caption[x]
126 .It Va NAMEmenu_caption[x][y]
127 -> menu_caption[x][y]
128 .It Va NAMEmenu_command[x]
133 .It Va NAMEmenu_init[x]
135 .It Va NAMEmenu_keycode[x]
137 .It Va NAMEmenu_options
139 .It Va NAMEmenu_optionstext
141 .It Va NAMEmenu_reboot
143 .It Va NAMEtoggled_ansi[x]
145 .It Va NAMEtoggled_text[x]
151 is the value of $menuset_nameN.
152 In the case of $NAMEmenu_init ($menusetN_init when $menuset_nameN is unset),
153 the value is evaluated as an FICL statement.
154 This can be used to dynamically adjust the menuset variables right before the
159 provides the following FICL words:
161 .Bl -tag -width menuset -compact -offset indent
162 .It Ic menuset-checksetnum ( N -- )
163 Given a single integer on the stack, sets a global variable
165 to a boolean based on whether $menuset_nameN is set (true) or not (false).
166 Also sets $affix temporary variable (prefix or infix depending on
168 Automatically called by menuset-loadsetnum and menusets-unset.
169 .It Ic menuset-loadvar ( -- )
170 Used indirectly to shorten syntax and mitigate dictionary size.
171 Requires the following temporary environment variables:
173 .Bl -tag -width affix -compact -offset indent
175 should be set to one of: menu toggled ansi
177 should be set to one of: caption command keycode text ...
179 either a prefix (menuset_use_name is true) or infix (menuset_use_name is false)
184 is true, the variable ${type}_${var} is made to
185 equal the value of the variable ${affix}${type}_${var}
186 (note: in this case menuset-checksetnum has set $affix to $menuset_nameN).
189 is false), the variable ${type}_${var} is made to
190 equal the value of the variable ${type}set${affix}_${var}
191 (note: in this case menuset-checksetnum has set $affix to N).
193 Both the global variable
195 and the environment variable $affix are automatically handled by
196 menuset-checksetnum above (which is automatically called by
198 .It Ic menuset-unloadvar ( -- )
199 Used indirectly to shorten syntax and mitigate dictionary size.
200 Like menuset-loadvar except it unsets the menuset variable.
203 is true ($affix is $menuset_nameN),
204 variable ${affix}${type}_${var} is unset.
205 Otherwise, $affix is N and variable ${type}set${affix}_${var} is unset.
206 .It Ic menuset-loadmenuvar ( -- )
209 and calls menuset-loadvar.
210 .It Ic menuset-unloadmenuvar ( -- )
213 and calls menuset-unloadvar.
214 .It Ic menuset-loadxvar ( -- )
215 Like menuset-loadvar except it takes an additional temporary variable $x.
218 is true (making $affix equal $menuset_nameN),
219 sets variable ${type}_${var}[${x}] to variable ${affix}${type}_${var}[${x}].
220 Otherwise ($affix being N), sets the same variable to instead
221 ${type}set{affix}_${var}[${x}].
222 .It Ic menuset-unloadxvar ( -- )
223 Like menuset-loadxvar except it unsets the menuset variable.
226 is true, unsets ${affix}${type}_${var}[${x}].
227 Otherwise, unsets ${type}set${affix}_${var}[${x}].
228 .It Ic menuset-loadansixvar ( -- )
231 and calls menuset-loadxvar
232 .It Ic menuset-unloadansixvar ( -- )
235 and calls menuset-unloadxvar
236 .It Ic menuset-loadmenuxvar ( -- )
239 and calls menuset-loadxvar
240 .It Ic menuset-unloadmenuxvar ( -- )
243 and calls menuset-unloadxvar
244 .It Ic menuset-loadtoggledxvar ( -- )
247 and calls menuset-loadxvar
248 .It Ic menuset-unloadtoggledxvar ( -- )
251 and calls menuset-unloadxvar
252 .It Ic menuset-loadxyvar ( -- )
253 Like menuset-loadxvar except it takes an additional temporary variable $y.
256 is true ($affix is $menuset_nameN),
257 sets variable ${type}_${var}[${x}][${y}] to ${affix}${type}_${var}[${x}][${y}].
258 Otherwise ($affix is N) sets the same variable to instead
259 ${type}set${affix}_${var}[${x}][${y}].
260 .It Ic menuset-unloadxyvar ( -- )
261 Like menuset-loadxyvar except it unsets the menuset variable.
264 is true, unsets ${affix}${type}_${var}[${x}][${y}].
265 Otherwise, unsets ${type}set${affix}_${var}[${x}][${y}].
266 .It Ic menuset-loadansixyvar ( -- )
269 and calls menuset-loadxyvar.
270 .It Ic menuset-unloadansixyvar ( -- )
273 and calls menuset-unloadxyvar.
274 .It Ic menuset-loadmenuxyvar ( -- )
277 and calls menuset-loadxyvar.
278 .It Ic menuset-unloadmenuxyvar ( -- )
281 and calls menuset-unloadxyvar.
282 .It Ic menuset-setnum-namevar ( N -- C-Addr/U )
283 Takes a single integer on the stack and replaces it with a string (in c-addr/u
284 format) whose value is
286 For example, if given 1 returns
288 .It Ic menuset-cleanup ( N -- )
289 Unsets all the various temporary variables, currently
300 above, use any number between 1 through 9. Sorry, double-digits are not
304 above, use any number between 1 and 65535.
306 .Bl -tag -width /boot/menu-commands.4th -compact
310 .It Pa /boot/forth/menu.4th
312 .It Pa /boot/forth/menu-commands.4th
313 Contains the goto_menu command.
314 .It Pa /boot/forth/menusets.4th
317 .It Pa /boot/loader.rc
319 bootstrapping script.
322 A simple boot menu with a submenu:
324 .Bd -literal -offset indent -compact
325 include /boot/forth/menu.4th
326 include /boot/forth/menu-commands.4th
328 set menuset1_caption[1]="Boot"
329 set menuset1_command[1]="boot"
330 set menuset1_caption[2]="Submenu..."
331 set menuset1_command[2]="2 goto_menu"
332 set menuset2_caption[1]="Back"
333 set menuset2_command[1]="1 goto_menu"
334 set menuset_initial=2
339 The same boot menu with named menusets:
341 .Bd -literal -offset indent -compact
342 include /boot/forth/menu.4th
343 include /boot/forth/menu-commands.4th
345 set menuset_name1=main
346 set mainmenu_caption[1]="Boot"
347 set mainmenu_command[1]="boot"
348 set mainmenu_caption[2]="Submenu..."
349 set mainmenu_command[2]="2 goto_menu"
350 set menuset_name2=sub
351 set submenu_caption[1]="Back"
352 set submenu_command[1]="1 goto_menu"