Changeset View
Changeset View
Standalone View
Standalone View
stand/lua/menu.lua.8
Property | Old Value | New Value |
---|---|---|
svn:eol-style | null | native \ No newline at end of property |
svn:keywords | null | FreeBSD=%H \ No newline at end of property |
svn:mime-type | null | text/plain \ No newline at end of property |
.\" | |||||
.\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD | |||||
rpokala: Don't forget the SPDX tag. | |||||
.\" | |||||
.\" 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 20, 2018 | |||||
.Dt MENU.LUA 8 | |||||
.Os | |||||
.Sh NAME | |||||
.Nm menu.lua | |||||
.Nd FreeBSD dynamic menu boot module | |||||
Done Inline ActionsYou can drop this fragment; I think it's okay to just start with the name of the file. rpokala: You can drop this fragment; I think it's okay to just start with the name of the file. | |||||
.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 | |||||
Done Inline Actionsinfluenced by loader environment variables. As opposed to environment variables at build-time. That might be clear to most people, but make it explicit. rpokala: influenced by //loader// environment variables.
As opposed to environment variables at build… | |||||
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. | |||||
Done Inline ActionsSince "entries" starts with a vowel sound, this should be "contain an". rpokala: Since "entries" starts with a vowel sound, this should be "contain a//n//". | |||||
That table | |||||
.Sy must | |||||
contain an | |||||
.Va entries | |||||
key. | |||||
.Pp | |||||
Done Inline ActionsI think "If the value of the entries key is itself a table" reads a bit cleaner. rpokala: I think "If the value of the entries key is itself a table" reads a bit cleaner. | |||||
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. | |||||
Done Inline ActionsYou should define or describe "carousel". rpokala: You should define or describe "carousel". | |||||
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 | |||||
Done Inline Actions"A table (or a lambda that returns a table) of the possible choices for this carousel." I think that reads a little better. rpokala: "A table (or a lambda that returns a table) of the possible choices for this carousel."
I… | |||||
if this menu item should be visible and | |||||
.Dv false | |||||
if it should not be visible. | |||||
Done Inline ActionsSame. rpokala: Same. | |||||
.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_options -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. | |||||
.El | |||||
.Sh EXAMPLES | |||||
Done Inline ActionsI think the ".It Pa /boot/lua/menu.lua" and ".Nm" lines aren't meant to be here...? rpokala: I think the ".It Pa /boot/lua/menu.lua" and ".Nm" lines aren't meant to be here...? | |||||
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 = { | |||||
Not Done Inline ActionsMy eyes are rendering this as: The loader(8) /boot/lua/loader.lua loader(8) bootstrapping script. Which still doesn't look right. rpokala: My eyes are rendering this as:
```
The loader(8) /boot/lua/loader.lua loader(8) bootstrapping… | |||||
{ | |||||
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 . |
Don't forget the SPDX tag.