stand/lua/menu.lua.8

   1 .\"
   2 .\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD
   3 .\"
   4 .\" Copyright (c) 2018 Kyle Evans <kevans@FreeBSD.org>
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  16 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  17 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  18 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  19 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  20 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  21 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  22 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  25 .\" SUCH DAMAGE.
  26 .\"
  27 .\" $FreeBSD$
  28 .\"
  29 .Dd February 23, 2018
  30 .Dt MENU.LUA 8
  31 .Os
  32 .Sh NAME
  33 .Nm menu.lua
  34 .Nd FreeBSD dynamic menu boot module
  35 .Sh DESCRIPTION
  36 .Nm
  37 contains the main functionality required to build a dynamic menu system.
  38 It also contains definitions for the built-in menus, some of which are
  39 influenced by
  40 .Xr loader 8
  41 environment variables.
  42 .Pp
  43 Before hooking into the functionality provided by
  44 .Nm ,
  45 it must be included with a statement such as the following:
  46 .Pp
  47 .Dl local menu = require("menu")
  48 .Ss MENU DEFINITIONS
  49 Menus are represented in
  50 .Nm
  51 as a table.
  52 That table
  53 .Sy must
  54 contain an
  55 .Va entries
  56 key.
  57 .Pp
  58 If the value of the
  59 .Va entries
  60 key is itself a table, then each value in this table defines a single entry in
  61 this menu.
  62 See
  63 .Sx MENU ITEM DEFINITIONS
  64 for the structure of each entry.
  65 .Pp
  66 .Va entries
  67 may also be a function.
  68 This function must return a table, each value of which defines a single entry
  69 in this menu.
  70 See
  71 .Sx MENU ITEM DEFINITIONS .
  72 .Ss MENU ITEM DEFINITIONS
  73 The following keys may be defined for a menu item:
  74 .Bl -tag -width disable-module_module -offset indent
  75 .It Ic entry_type
  76 The type of this menu entry.
  77 See
  78 .Sx MENU ITEM TYPES .
  79 .It Ic carousel_id
  80 A unique string id for this carousel.
  81 A carousel is a menu entry that rotates through a selection of items.
  82 Used for storage of the carousel's current setting.
  83 .It Ic visible
  84 A lambda that returns
  85 .Dv true
  86 if this menu item should be visible and
  87 .Dv false
  88 if it should not be visible.
  89 .It Ic items
  90 A table (or a lambda that returns a table) of the possible choices for this
  91 carousel.
  92 .It Ic name
  93 A string (or a lambda that returns a string) containing the current name of this
  94 item.
  95 .It Ic func
  96 The function executed when this entry is selected.
  97 Every type except for
  98 .Ic core.MENU_SEPARATOR
  99 may have a
 100 .Ic func .
 101 .It Ic submenu
 102 The submenu menu definition to draw when this entry is selected.
 103 .It Ic alias
 104 A table of case-sensitive aliases for this menu entry.
 105 All menu entries that can be selected may have any number of
 106 .Ic alias
 107 entries.
 108 .El
 109 .Pp
 110 .Ic entry_type
 111 is the only required key for every entry type.
 112 .Ic name
 113 is required for all entry types except for
 114 .Ic core.MENU_SEPARATOR .
 115 .Ss MENU ITEM TYPES
 116 The menu item type constants are defined in
 117 .Xr core.lua 8 .
 118 The following types are available:
 119 .Bl -tag -width core.MENU_CAROUSEL_ENTRY -offset indent
 120 .It Ic core.MENU_RETURN
 121 Return to the parent menu.
 122 If the current menu is the default menu,
 123 .Nm
 124 will exit the menu and begin the autoboot sequence (if applicable).
 125 This type of menu entry may execute
 126 .Ic func ,
 127 when selected, and has a
 128 .Ic name .
 129 .It Ic core.MENU_ENTRY
 130 A normal menu entry that executes
 131 .Ic func
 132 when selected, and has a
 133 .Ic name .
 134 .It Ic core.MENU_SEPARATOR
 135 A menu entry that serves as a separator.
 136 It may have a
 137 .Ic name .
 138 .It Ic core.MENU_SUBMENU
 139 A menu entry that opens
 140 .Ic submenu
 141 when selected.
 142 It may have a
 143 .Ic name .
 144 .It Ic core.MENU_CAROUSEL_ENTRY
 145 A menu entry that rotates through
 146 .Ic items
 147 like a carousel.
 148 .Ic func
 149 is executed when selected, and the callback is passed the choice index, name of
 150 the current choice, and the table of choices.
 151 .El
 152 .Ss EXPORTED MENUS
 153 The following menus are exported by
 154 .Nm :
 155 .Bl -tag -width menu.boot_environments -offset indent
 156 .It Ic menu.default
 157 The default menu to draw.
 158 Set to
 159 .Ic menu.welcome
 160 by default.
 161 .It Ic menu.welcome
 162 The welcome menu.
 163 Contains single and multi user boot options, as well as entries to access other
 164 menus.
 165 .It Ic menu.boot_options
 166 The "Boot Options" menu.
 167 .It Ic menu.boot_environments
 168 The "Boot Environments" menu.
 169 This menu is only visible if the system is booted on a ZFS partition and more
 170 than one boot environment was detected at boot.
 171 .El
 172 .Sh EXAMPLES
 173 To replace the default boot menu with a simple boot menu:
 174 .Pp
 175 .Bd -literal -offset indent -compact
 176 local core = require("core")
 177 local menu = require("menu")
 178
 179 menu.default = {
 180         entries = {
 181                 {
 182                         entry_type = core.MENU_ENTRY,
 183                         name = "Boot",
 184                         func = core.boot,
 185                 },
 186                 {
 187                         entry_type = core.MENU_CAROUSEL_ENTRY,
 188                         carousel_id = "unique_boot_entry_name",
 189                         items = {"NO", "YES"},
 190                         name = function(_, choice, _)
 191                                 return "Option: " .. choice
 192                         end,
 193                         func = function(_, _, _)
 194                                 loader.setenv("some_envvar", "some_value")
 195                         end,
 196                 },
 197         },
 198 }
 199 .Ed
 200 .Pp
 201 To add another option to the welcome menu:
 202 .Pp
 203 .Bd -literal -offset indent -compact
 204 local core = require("core")
 205 local menu = require("menu")
 206
 207 local welcome_entries = menu.welcome.all_entries
 208 welcome_entries[#welcome_entries + 1] = {
 209         entry_type = core.MENU_CAROUSEL_ENTRY,
 210         carousel_id = "unique_boot_entry_name",
 211         items = {"NO", "YES"},
 212         name = function(_, choice, _)
 213                 return "Option: " .. choice
 214         end,
 215         func = function(_, _, _)
 216                 loader.setenv("some_envvar", "some_value")
 217         end,
 218 }
 219 .Ed
 220 .Sh SEE ALSO
 221 .Xr loader.conf 5 ,
 222 .Xr core.lua 8 ,
 223 .Xr loader 8
 224 .Sh HISTORY
 225 The
 226 .Nm
 227 file first appeared in
 228 .Fx 12.0 .
 229 .Sh AUTHORS
 230 The
 231 .Nm
 232 file was originally written by
 233 .An Pedro Souza Aq Mt pedrosouza@FreeBSD.org .
 234 Later work and this manual page was done by
 235 .An Kyle Evans Aq Mt kevans@FreeBSD.org .