Menu< T, H > Class Template Reference

A menu to execute commands with a specific target. More...

#include <Menu.h>

Inheritance diagram for Menu< T, H >:

Collaboration diagram for Menu< T, H >:

Classes
class	Line
	A command in the menu. More...

Public Types
using	TargetType = T
	the type of target this menu points to
using	TargetHandle = H
	the type of handle we use to access the target
using	SingleTargetCommand = std::function< void(TargetHandle)>
	type of function which does something with the target
using	MultipleTargetCommands = std::function< void(const std::string &, TargetHandle)>
	type of function which does one of several commands with target
using	RenderFuncType = std::function< void(TargetHandle)>
	The type of function used to "render" a menu. More...

Public Member Functions
Menu *	line (const char *name, const char *desc, SingleTargetCommand ex)
	declare a single target command with thei nput name and desc More...
Menu *	line (const char *name, const char *desc, MultipleTargetCommands ex)
	declare a single target command with the input name and desc More...
Menu *	submenu (const char *name, const char *desc, RenderFuncType f=0)
	declare a sub menu of us with input name and desc More...
void	render ()
	Go through and render each of the lines in this menu. More...
	Menu (const Menu &)=delete
	no copying
void	operator= (const Menu &)=delete
	no copying
	Menu (RenderFuncType f=0)
	Construct a menu with a rendering function.
void	steer (TargetHandle p_target) const
	give control over the target to this menu More...

Static Public Member Functions
static Menu *	root ()
	Retreve a pointer to the root menu.
static void	run (TargetHandle tgt)
	Call this function when ready to run. More...
static Menu *	menu (const char *name, const char *desc, RenderFuncType render_func=0)
	Construct a new menu with the root as parent and optional rendering. More...
Static Public Member Functions inherited from BaseMenu
static std::string	readline (const std::string &prompt, const std::string &defval, bool preserve_last_blank=false)
	Read in a parameter using the default value if nothing provided. More...
static std::string	readline_nosplit (const std::string &prompt, const std::string &defval)
	Get a raw input value without the additional splitting and modifications done in base readline. More...
static std::string	readline (const std::string &prompt)
	Read a string parameter without a default. More...
static std::string	readline (const std::string &prompt, const std::vector< std::string > &opts)
	Read a string parameter without a default but with the input list of options for tab-completion (and validation) More...
static int	readline_int (const std::string &prompt)
	Read an integer parameter without a default. More...
static int	readline_int (const std::string &prompt, int aval)
	Read an integer parameter with a default. More...
static double	readline_float (const std::string &prompt)
	Read a float parameter with a default. More...
static bool	readline_bool (const std::string &prompt, bool aval)
	Read a bool parameter with a default. More...
static std::string	readline_cmd ()
	Read a command from the menu. More...
static void	add_to_command_queue (const std::string &str)
	Add to the queue of commands to execute automatically. More...

Private Member Functions
virtual std::vector< std::string >	command_options () const
	Provide the list of command options. More...

Private Attributes
std::vector< Line >	lines_
	lines in this menu
RenderFuncType	render_func_
	function pointer to render the menu prompt

Additional Inherited Members
Protected Member Functions inherited from BaseMenu
void	add_to_history (const std::string &cmd) const
	Add a command to the history of commands that have been executed. More...
Static Protected Attributes inherited from BaseMenu
static std::list< std::string >	cmdTextQueue_
	the ordered list of commands to be executed from a script file
static std::vector< std::string >	cmd_options_
	the current command options (for interfacing with readline's tab completion)
static const std::vector< std::string > *	rl_comp_opts_ = &BaseMenu::cmd_options_
	a pointer to the list of options when attempting readline completion

Detailed Description

template<typename T, typename H = T*>
class Menu< T, H >

A menu to execute commands with a specific target.

Generally, it is a good idea to have a header defining the type of menu you wish to operate for your program. In it, you would have a line like

using pftool = Menu<PolarfireTarget>;

so that in the files where you are implementing menu commands the registration is less likely to be messed up.

// example registration using above alias
namespace {
auto sb = pftool::menu("SB","example empty submenu");
}

and running the menu takes on a more appealing form.

// tgt is a handle to the target of the menu
// i.e. it is of type pftool::TargetHandle
pftool::run(tgt);

Template Parameters

T	class to be passed to execution commands
H	a handle for T (defaults to T*)

Member Typedef Documentation

RenderFuncType

template<typename T , typename H = T*>

using Menu< T, H >::RenderFuncType = std::function<void(TargetHandle)>

The type of function used to "render" a menu.

"rendering" allows the user to have a handle for when the menu will be printed to the terminal prompt. Moreover, this can include necessary initiliazation procedures if need be.

Member Function Documentation

command_options()

template<typename T , typename H = T*>

virtual std::vector< std::string > Menu< T, H >::command_options ( ) const

inlineprivatevirtual

Provide the list of command options.

Returns

list of commands that could be run from this menu

line() [1/2]

template<typename T , typename H = T*>

Menu * Menu< T, H >::line ( const char *  name, const char *  desc, MultipleTargetCommands  ex  )

inline

declare a single target command with the input name and desc

MultipleTargetCommands functions have a string parameter which is given name when run.

appends this menu line to us and then returns a pointer to us

Parameters

[in]	name	Name of this line to use when running
[in]	desc	short description to print with menu
[in]	ex	function to execute when name is called

Returns

pointer to us

line() [2/2]

template<typename T , typename H = T*>

Menu * Menu< T, H >::line ( const char *  name, const char *  desc, SingleTargetCommand  ex  )

inline

declare a single target command with thei nput name and desc

appends this menu line to us and then returns a pointer to us

Parameters

[in]	name	Name of this line to use when running
[in]	desc	short description to print with menu
[in]	ex	function to execute when name is called

Returns

pointer to us

menu()

template<typename T , typename H = T*>

static Menu * Menu< T, H >::menu ( const char *  name, const char *  desc, RenderFuncType  render_func = 0  )

inlinestatic

Construct a new menu with the root as parent and optional rendering.

After using submenu to attach ourselves to the input parent, we return a pointer to the newly constructed menu. This is to allow chaining during the declaration of a menu, so that the declaration of a menu has a form similar to what the menu looks like at run time.

A simple example (actually using the shorter alias) is below. one_func and two_func are both functions accessible by this piece of code (either via a header or in this translation unit) and are void functions with take a handle to the target type. color_func is similarly accessible but it takes a string and the target handle. The string will be the command that is selected at runtime (e.g. "RED" if it is typed by the user)

namespace {
auto sb = Menu<T>::menu("SB","example submenu")
  ->line("ONE", "one command in this menu", one_func)
  ->line("TWO", "two command in this menu", two_func)
  ->line("RED", "can have multiple lines directed to the same func", color_func)
  ->line("BLUE", "see?" , color_func)
;
}

The anonymous namespace is used to force the variable within it to be static and therefore created at library linking time. The dummy variable is (unfortunately) necessary so that the sub menu can maintain existence throughout the runtime of the program.

See also

submenu for attaching to another menu directly

Parameters

[in]	name	Name of this sub menu for selection
[in]	desc	description of this sub menu
[in]	render_func	function to use to render this sub menu

Returns

pointer to newly created menu

render()

template<typename T , typename H = T*>

void Menu< T, H >::render ( )

inline

Go through and render each of the lines in this menu.

Note

No need to add EXIT/QUIT lines!

Afterwards, we append the "EXIT" line to us.

run()

template<typename T , typename H = T*>

static void Menu< T, H >::run ( TargetHandle  tgt )

inlinestatic

Call this function when ready to run.

Provide a TargetHandle to run over.

After rendering the menu, we give tgt to steer to start off.

Parameters

[in]

tgt

TargetHandle to run with

steer()

template<typename T , typename H = T*>

void Menu< T, H >::steer ( TargetHandle  p_target ) const

inline

give control over the target to this menu

We enter a do-while loop that continues until the user selects an empty line to execute. The contents of the do-while loop follow the procedure below.

1. If we have a render function set, we give the target to it.
2. If we aren't in batch mode, we print all of our lines and their descriptions.
3. Use the readline function to get the requested command from the user
   • We use the BaseMenu::command_matcher function to provide options given the user attempting <TAB> completion.
4. Loop through our lines to find all available matches.
5. Execute the line if there is a unique match; otherwise, print an error message.

Parameters

[in]

p_target

pointer to the target

submenu()

template<typename T , typename H = T*>

Menu * Menu< T, H >::submenu ( const char *  name, const char *  desc, RenderFuncType  f = 0  )

inline

declare a sub menu of us with input name and desc

appends this menu line to us and then returns a pointer to us

Note

Line takes ownership of Menus that are provided to it, so Menus should be dynamically created and not deleted. It is suggested to use the menu function to avoid complication.

This can be used if you already have a menu and you wish to add another submenu to it.

namespace {
auto mymain = Menu<T>::menu("MAIN","will be on the root menu");
auto sb = mymain->submenu("SB","A line in the MAIN menu");
}

Parameters

[in]	name	Name of this line to use when running
[in]	desc	short description to print with menu
[in]	ex	pointer to menu that we should append

Returns

pointer to the newly created submenu

---

The documentation for this class was generated from the following file:

• tool/Menu.h