Date: Fri, 2 Mar 2018 05:36:04 +0000 (UTC) From: Kyle Evans <kevans@FreeBSD.org> To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: svn commit: r330268 - head/stand/lua Message-ID: <201803020536.w225a4UV054090@repo.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: kevans Date: Fri Mar 2 05:36:04 2018 New Revision: 330268 URL: https://svnweb.freebsd.org/changeset/base/330268 Log: Add menu.lua(8), but do not add to distribution Distribution will be done after all of the lualoader manpages are created. Reviewed by: rpokala Differential Revision: https://reviews.freebsd.org/D14480 Added: head/stand/lua/menu.lua.8 (contents, props changed) Added: head/stand/lua/menu.lua.8 ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ head/stand/lua/menu.lua.8 Fri Mar 2 05:36:04 2018 (r330268) @@ -0,0 +1,236 @@ +.\" +.\" 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$ +.\" +.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. +.Pp +Before hooking into the functionality provided by +.Nm , +it must be included with a statement such as the following: +.Pp +.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. +.Pp +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. +.Pp +.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: +.Bl -tag -width disable-module_module -offset indent +.It Ic entry_type +The type of this menu entry. +See +.Sx MENU ITEM TYPES . +.It 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. +.It Ic visible +A lambda that returns +.Dv true +if this menu item should be visible and +.Dv false +if it should not be visible. +.It Ic items +A table (or a lambda that returns a table) of the possible choices for this +carousel. +.It Ic name +A string (or a lambda that returns a string) containing the current name of this +item. +.It Ic func +The function executed when this entry is selected. +Every type except for +.Ic core.MENU_SEPARATOR +may have a +.Ic func . +.It Ic submenu +The submenu menu definition to draw when this entry is selected. +.It Ic alias +A table of case-sensitive aliases for this menu entry. +All menu entries that can be selected may have any number of +.Ic alias +entries. +.El +.Pp +.Ic entry_type +is the only required key for every entry type. +.Ic name +is required for all entry types except for +.Ic core.MENU_SEPARATOR . +.Ss MENU ITEM TYPES +The menu item type constants are defined in +.Xr core.lua 8 . +The following types are available: +.Bl -tag -width core.MENU_CAROUSEL_ENTRY -offset indent +.It 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 +.Ic func , +when selected, and has a +.Ic name . +.It Ic core.MENU_ENTRY +A normal menu entry that executes +.Ic func +when selected, and has a +.Ic name . +.It Ic core.MENU_SEPARATOR +A menu entry that serves as a separator. +It may have a +.Ic name . +.It Ic core.MENU_SUBMENU +A menu entry that opens +.Ic submenu +when selected. +It may have a +.Ic name . +.It Ic core.MENU_CAROUSEL_ENTRY +A menu entry that rotates through +.Ic items +like a carousel. +.Ic 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 : +.Bl -tag -width menu.boot_environments -offset indent +.It Ic menu.default +The default menu to draw. +Set to +.Ic menu.welcome +by default. +.It Ic menu.welcome +The welcome menu. +Contains single and multi user boot options, as well as entries to access other +menus. +.It Ic menu.boot_options +The "Boot Options" menu. +.It 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: +.Pp +.Bd -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 +.Pp +To add another option to the welcome menu: +.Pp +.Bd -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 .
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201803020536.w225a4UV054090>