SPDX-License-Identifier: BSD-2-Clause-FreeBSD

Copyright (c) 2018 Kyle Evans <kevans@FreeBSD.org>
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.

$FreeBSD: stable/11/stand/lua/menu.lua.8 344220 2019-02-17 02:39:17Z kevans $

.Dd February 23, 2018 .Dt MENU.LUA 8 .Os .Sh NAME .Nm menu.lua .Nd FreeBSD dynamic menu boot module .Sh DESCRIPTION .Nm contains the main functionality required to build a dynamic menu system. It also contains definitions for the built-in menus, some of which are influenced by .Xr loader 8 environment variables.

p Before hooking into the functionality provided by .Nm , it must be included with a statement such as the following:

p .Dl local menu = require("menu") .Ss MENU DEFINITIONS Menus are represented in .Nm as a table. That table .Sy must contain an .Va entries key.

p If the value of the .Va entries key is itself a table, then each value in this table defines a single entry in this menu. See .Sx MENU ITEM DEFINITIONS for the structure of each entry.

p .Va entries may also be a function. This function must return a table, each value of which defines a single entry in this menu. See .Sx MENU ITEM DEFINITIONS . .Ss MENU ITEM DEFINITIONS The following keys may be defined for a menu item: l -tag -width disable-module_module -offset indent t Ic entry_type The type of this menu entry. See .Sx MENU ITEM TYPES . t Ic carousel_id A unique string id for this carousel. A carousel is a menu entry that rotates through a selection of items. Used for storage of the carousel's current setting. t Ic visible A lambda that returns .Dv true if this menu item should be visible and .Dv false if it should not be visible. t Ic items A table (or a lambda that returns a table) of the possible choices for this carousel. t Ic name A string (or a lambda that returns a string) containing the current name of this item. t Ic func The function executed when this entry is selected. Every type except for c core.MENU_SEPARATOR may have a c func . t Ic submenu The submenu menu definition to draw when this entry is selected. t Ic alias A table of case-sensitive aliases for this menu entry. All menu entries that can be selected may have any number of c alias entries. .El

p c entry_type is the only required key for every entry type. c name is required for all entry types except for c core.MENU_SEPARATOR . .Ss MENU ITEM TYPES The menu item type constants are defined in .Xr core.lua 8 . The following types are available: l -tag -width core.MENU_CAROUSEL_ENTRY -offset indent t Ic core.MENU_RETURN Return to the parent menu. If the current menu is the default menu, .Nm will exit the menu and begin the autoboot sequence (if applicable). This type of menu entry may execute c func , when selected, and has a c name . t Ic core.MENU_ENTRY A normal menu entry that executes c func when selected, and has a c name . t Ic core.MENU_SEPARATOR A menu entry that serves as a separator. It may have a c name . t Ic core.MENU_SUBMENU A menu entry that opens c submenu when selected. It may have a c name . t Ic core.MENU_CAROUSEL_ENTRY A menu entry that rotates through c items like a carousel. c func is executed when selected, and the callback is passed the choice index, name of the current choice, and the table of choices. .El .Ss EXPORTED MENUS The following menus are exported by .Nm : l -tag -width menu.boot_environments -offset indent t Ic menu.default The default menu to draw. Set to c menu.welcome by default. t Ic menu.welcome The welcome menu. Contains single and multi user boot options, as well as entries to access other menus. t Ic menu.boot_options The "Boot Options" menu. t Ic menu.boot_environments The "Boot Environments" menu. This menu is only visible if the system is booted on a ZFS partition and more than one boot environment was detected at boot. .El .Sh EXAMPLES To replace the default boot menu with a simple boot menu:

p d -literal -offset indent -compact local core = require("core") local menu = require("menu") menu.default = { entries = { { entry_type = core.MENU_ENTRY, name = "Boot", func = core.boot, }, { entry_type = core.MENU_CAROUSEL_ENTRY, carousel_id = "unique_boot_entry_name", items = {"NO", "YES"}, name = function(_, choice, _) return "Option: " .. choice end, func = function(_, _, _) loader.setenv("some_envvar", "some_value") end, }, }, } .Ed

p To add another option to the welcome menu:

p d -literal -offset indent -compact local core = require("core") local menu = require("menu") local welcome_entries = menu.welcome.all_entries welcome_entries[#welcome_entries + 1] = { entry_type = core.MENU_CAROUSEL_ENTRY, carousel_id = "unique_boot_entry_name", items = {"NO", "YES"}, name = function(_, choice, _) return "Option: " .. choice end, func = function(_, _, _) loader.setenv("some_envvar", "some_value") end, } .Ed .Sh SEE ALSO .Xr loader.conf 5 , .Xr core.lua 8 , .Xr loader 8 .Sh HISTORY The .Nm file first appeared in .Fx 12.0 . .Sh AUTHORS The .Nm file was originally written by .An Pedro Souza Aq Mt pedrosouza@FreeBSD.org . Later work and this manual page was done by .An Kyle Evans Aq Mt kevans@FreeBSD.org .