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