#include "steam/control/command.hpp"

Description

Handle object representing a single Command instance to be used by client code.

Commands are accessed through a symbolic ID ; there needs to be a CommandDef somewhere to specify the actual operation and to define, how the effect of the command can be undone. Moreover, the command's definition refers to a HandlingPattern, which describes how the command is actually to be executed (the default is scheduling it within the SteamDispatcher)

Client code usually just

creates a command instance by referring to a command ID
maybe binds to concrete arguments (e.g. a target object)
triggers command execution through operator()
maybe checks the return value for errors

Remarks: lightweight implementation as smart-ptr

Definition at line 115 of file command.hpp.

Static Public Member Functions
static Command	get (Symbol cmdID)
	Access existing command for use.

static bool	remove (Symbol cmdID)

static Command	maybeGetNewInstance (Symbol cmdID)
	try to access an existing command definition and immediately create a new clone copy by calling newInstance()

static size_t	definition_count ()

static size_t	instance_count ()

static bool	defined (Symbol cmdID)

static bool	canExec (Symbol cmdID)

static bool	canUndo (Symbol cmdID)

Public Member Functions
Command	storeDef (Symbol newCmdID) const
	create a clone definition

Command	newInstance () const
	create independent (anonymous) clone copy of this command

	Command (Symbol cmdID)

	Command ()
	undefined command

	~Command ()

	Command (Command &&)=default

	Command (Command const &)=default

Command &	operator= (Command &&)=default

Command &	operator= (Command const &)=default

template<typename... TYPES>
Command &	bindArg (std::tuple< TYPES... > const &)

Command &	bindArg (lib::diff::Rec const &)

Command &	unbind ()
	discard any argument data previously bound.

ExecResult	operator() ()

ExecResult	exec ()

ExecResult	undo ()

ExecResult	exec (HandlingPattern const &execPattern)
	core operation: invoke the command

ExecResult	exec (HandlingPattern::ID)

ExecResult	undo (HandlingPattern const &execPattern)

ExecResult	undo (HandlingPattern::ID)

ExecResult	execSync ()
	invoke using a default "synchronous" execution pattern

HandlingPattern::ID	getDefaultHandlingPattern () const

HandlingPattern::ID	setHandlingPattern (HandlingPattern::ID)
	define a handling pattern to be used by default

bool	canExec () const

bool	canUndo () const

void	duplicate_detected (Symbol) const

Symbol	getID () const noexcept

bool	isAnonymous () const

	operator string () const
	diagnostics: shows the commandID, if any, and the degree of definition of this command

Public Member Functions inherited from AcceptAnyBind< TAR, BA, RET >
RET	bind ()
	Accept dummy binding (0 Arg)

template<typename... ARGS>
RET	bind (ARGS &&...args)
	mix in `bind` function to create binding of arbitrary arguments

Friends
class	CommandDef

bool	operator== (Command const &, Command const &)

bool	operator< (Command const &, Command const &)
	allow for sets and associative containers

Protected Member Functions
void	activate (shared_ptr< CommandImpl > &&, Symbol cmdID=0)

Static Protected Member Functions
static Command	fetchDef (Symbol cmdID)

Private Types
using	_Handle = lib::Handle< CommandImpl >

Private Member Functions
void	setArguments (Arguments &)

void	setArguments (lib::diff::Rec const &)

Constructor & Destructor Documentation

◆ Command() [1/4]

Command ( Symbol cmdID )

inline

Definition at line 135 of file command.hpp.

References Command::get().

Here is the call graph for this function:

◆ Command() [2/4]

Command ( )

inline

undefined command

Definition at line 136 of file command.hpp.

◆ ~Command()

~Command ( )

Definition at line 106 of file command.cpp.

◆ Command() [3/4]

Command ( Command && )

default

◆ Command() [4/4]

Command ( Command const & )

default

Member Typedef Documentation

◆ _Handle

using _Handle = lib::Handle<CommandImpl>

private

Definition at line 121 of file command.hpp.

Member Function Documentation

◆ get()

Command get ( Symbol cmdID )

static

Access existing command for use.

Exceptions

error::Invalid if command not registered or incompletely defined.

Remarks: this function deliberately returns by-value. Returning a reference into the global CommandRegistry would be dangerous under concurrent access.

Definition at line 120 of file command.cpp.

References CommandRegistry::instance, and LERR_.

Referenced by Command::Command(), CommandUse1_test::allInOneStep(), CommandUse2_test::check_defaultHandlingPattern(), CommandUse2_test::check_ThrowOnError(), CommandUse1_test::definePrototype(), CommandInstanceManager::getInstance(), steam::control::invoke(), AbstractTangible_test::invokeCommand(), WrappedStandardExeBuilder::invokeOriginalBuilder(), CommandInstanceManager::newInstance(), stage::model::test::anonymous_namespace{abstract-tangible-test.cpp}::processCommandInvocation(), CommandBasic_test::run(), CommandEquality_test::run(), CommandMessageBinding_test::run(), CommandUse1_test::standardUse(), CommandUse1_test::statePredicates(), CommandUse1_test::stringRepresentation(), CommandUse1_test::undef(), CommandUse1_test::usePrototype(), CommandInstanceManager_test::verify_fallback(), and CommandBinding_test::zeroArgumentCommand().

Here is the caller graph for this function:

◆ remove()

bool remove ( Symbol cmdID )

static

Definition at line 241 of file command.cpp.

References CommandRegistry::instance.

Referenced by CommandDef::~CommandDef(), CommandQueue_test::~CommandQueue_test(), SessionCommandFunction_test::~SessionCommandFunction_test(), CommandBinding_test::run(), CommandRegistry_test::run(), CommandUse2_test::run(), CommandUse3_test::run(), CommandUse1_test::statePredicates(), CommandUse1_test::undef(), and CommandSetup_test::verify_standardUsage().

Here is the caller graph for this function:

◆ storeDef()

Command storeDef ( Symbol newCmdID ) const

create a clone definition

create an independent clone copy of this command and register it as new command definition under a different ID

Definition at line 183 of file command.cpp.

References Command::activate(), CommandRegistry::createCloneImpl(), Command::duplicate_detected(), CommandRegistry::instance, and CommandRegistry::queryIndex().

Referenced by SessionCommandFunction_test::SessionCommandFunction_test(), CommandUse2_test::check_ThrowOnError(), CommandRegistry_test::checkRegistration(), SessionCommandFunction_test::perform_massivelyParallel(), and CommandSetup_test::verify_standardUsage().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ newInstance()

Command newInstance ( ) const

create independent (anonymous) clone copy of this command

Definition at line 200 of file command.cpp.

References Command::activate(), CommandRegistry::createCloneImpl(), and CommandRegistry::instance.

Referenced by CommandUse1_test::usePrototype(), CommandQueue_test::verifyBasics(), CommandQueue_test::verifyExecutabilityCheck(), and CommandBinding_test::zeroArgumentCommand().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ maybeGetNewInstance()

Command maybeGetNewInstance ( Symbol cmdID )

static

try to access an existing command definition and immediately create a new clone copy by calling newInstance()

Returns: when search for this ID was successful, a new anonymous command instance based on the same definition, but not registered in the global CommandRegistry. Otherwise, when search fails, an empty Command instance (as can be tested with bool conversion

Definition at line 140 of file command.cpp.

References CommandRegistry::instance.

Referenced by CommandInstanceManager::getCloneOrInstance().

Here is the caller graph for this function:

◆ operator=() [1/2]

Command & operator= ( Command && )

default

◆ operator=() [2/2]

Command & operator= ( Command const & )

default

◆ bindArg() [1/2]

template<typename... TYPES>

Command & bindArg ( std::tuple< TYPES... > const & tuple )

inline

Definition at line 243 of file command.hpp.

References Command::setArguments().

Referenced by SimulatedCommandHandler::SimulatedCommandHandler(), SessionCommandService::bindArg(), CompletedDefinition< SIG >::bindArg(), CommandInvoker< SIG >::bindArg(), CompletedDefinition< SIG >::maybeArm_if_zero_parameters(), and SessionCommandService::trigger().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ bindArg() [2/2]

Command & bindArg ( lib::diff::Rec const & paramData )

inline

Definition at line 252 of file command.hpp.

References Command::setArguments().

Here is the call graph for this function:

◆ unbind()

Command & unbind ( )

discard any argument data previously bound.

Remarks: this returns the command into pristine state, just holding the definition but not any further argument data or UNDO state. Contrast this to an defalut constructed Command, which is inactive and not bound to any definition at all.

Definition at line 279 of file command.cpp.

References Handle< CommandImpl >::impl().

Referenced by CommandUse1_test::statePredicates().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ operator()()

ExecResult operator() ( )

inline

Definition at line 223 of file command.hpp.

References Command::exec(), and Command::getDefaultHandlingPattern().

Here is the call graph for this function:

◆ exec() [1/3]

ExecResult exec ( )

inline

Definition at line 229 of file command.hpp.

References Command::exec(), and Command::getDefaultHandlingPattern().

Referenced by SimulatedCommandHandler::SimulatedCommandHandler(), CommandUse2_test::check_ThrowOnError(), Command::exec(), Command::exec(), Command::execSync(), and Command::operator()().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ undo() [1/3]

ExecResult undo ( )

inline

Definition at line 235 of file command.hpp.

References Command::getDefaultHandlingPattern(), and Command::undo().

Referenced by CommandUse1_test::allInOneStep(), CommandUse2_test::check_defaultHandlingPattern(), CommandEquality_test::execCommand(), AbstractTangible_test::invokeCommand(), CommandUse1_test::standardUse(), CommandUse1_test::statePredicates(), CommandUse1_test::stringRepresentation(), Command::undo(), Command::undo(), and CommandBinding_test::zeroArgumentCommand().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ exec() [2/3]

ExecResult exec ( HandlingPattern const & execPattern )

core operation: invoke the command

Parameters

execPattern describes the individual steps necessary to get this command invoked properly

Definition at line 412 of file command.cpp.

References Handle< CommandImpl >::impl().

Here is the call graph for this function:

◆ exec() [3/3]

ExecResult exec ( HandlingPattern::ID pattID )

Definition at line 436 of file command.cpp.

References Command::exec(), and HandlingPattern::get().

Here is the call graph for this function:

◆ undo() [2/3]

ExecResult undo ( HandlingPattern const & execPattern )

Definition at line 424 of file command.cpp.

References Handle< CommandImpl >::impl().

Here is the call graph for this function:

◆ undo() [3/3]

ExecResult undo ( HandlingPattern::ID pattID )

Definition at line 443 of file command.cpp.

References HandlingPattern::get(), and Command::undo().

Here is the call graph for this function:

◆ execSync()

ExecResult execSync ( )

invoke using a default "synchronous" execution pattern

Definition at line 450 of file command.cpp.

References HandlingPattern::DUMMY, Command::exec(), and HandlingPattern::get().

Here is the call graph for this function:

◆ getDefaultHandlingPattern()

HandlingPattern::ID getDefaultHandlingPattern ( ) const

Returns: ID of the execution pattern used by operator()

Definition at line 457 of file command.cpp.

Referenced by Command::exec(), Command::operator()(), and Command::undo().

Here is the caller graph for this function:

◆ setHandlingPattern()

HandlingPattern::ID setHandlingPattern ( HandlingPattern::ID pattID )

define a handling pattern to be used by default

Returns: ID of the currently defined default pattern

Definition at line 465 of file command.cpp.

Referenced by CommandUse2_test::check_ThrowOnError(), and CompletedDefinition< SIG >::setHandlingPattern().

Here is the caller graph for this function:

◆ definition_count()

size_t definition_count ( )

static

Returns: the number of command definitions currently registered

Definition at line 289 of file command.cpp.

References CommandRegistry::instance.

Referenced by CommandBinding_test::run(), CommandUse1_test::run(), CommandUse2_test::run(), and CommandUse3_test::run().

Here is the caller graph for this function:

◆ instance_count()

size_t instance_count ( )

static

Returns: number of distinguishable registered command instances

Definition at line 298 of file command.cpp.

References CommandRegistry::instance.

Referenced by CommandBinding_test::run(), CommandUse1_test::run(), CommandUse2_test::run(), and CommandUse3_test::run().

Here is the caller graph for this function:

◆ canExec() [1/2]

bool canExec ( ) const

Definition at line 350 of file command.cpp.

Referenced by steam::control::anonymous_namespace{command.cpp}::___check_isBound(), CommandInvoker< SIG >::bindArg(), Command::canExec(), BusTerm_test::commandInvocation(), SessionCommandFunction_test::perform_messageInvocation(), CommandUse1_test::standardUse(), CommandUse1_test::statePredicates(), CommandSetup_test::verify_standardUsage(), and CommandBinding_test::zeroArgumentCommand().

Here is the caller graph for this function:

◆ canUndo() [1/2]

bool canUndo ( ) const

Definition at line 358 of file command.cpp.

Referenced by steam::control::anonymous_namespace{command.cpp}::___check_canUndo(), Command::canUndo(), CommandUse1_test::standardUse(), and CommandUse1_test::statePredicates().

Here is the caller graph for this function:

◆ defined()

bool defined ( Symbol cmdID )

inlinestatic

Definition at line 264 of file command.hpp.

References Command::fetchDef().

Referenced by CommandUse1_test::statePredicates(), CommandSetup_test::verify_DefinitionRegistration(), and CommandSetup_test::verify_standardUsage().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ canExec() [2/2]

bool canExec ( Symbol cmdID )

inlinestatic

Definition at line 283 of file command.hpp.

References _FAILSAFE_COMMAND_QUERY, and Command::canExec().

Here is the call graph for this function:

◆ canUndo() [2/2]

bool canUndo ( Symbol cmdID )

inlinestatic

Definition at line 290 of file command.hpp.

References _FAILSAFE_COMMAND_QUERY, and Command::canUndo().

Here is the call graph for this function:

◆ duplicate_detected()

void duplicate_detected ( Symbol newCmdID ) const

Definition at line 230 of file command.cpp.

References LERR_.

Referenced by Command::activate(), and Command::storeDef().

Here is the caller graph for this function:

◆ getID()

Symbol getID ( ) const

noexcept

Definition at line 366 of file command.cpp.

References Symbol::FAILURE.

Referenced by SimulatedCommandHandler::SimulatedCommandHandler(), and Nexus::prepareMockCmd().

Here is the caller graph for this function:

◆ isAnonymous()

bool isAnonymous ( ) const

Returns: true when this command (front-end) was never registered with the CommandRegistry; typically this is the case with instances created from a prototype, when calling Command::newInstance instead of invoking Command::storeDef(Symbol).

Definition at line 379 of file command.cpp.

References CommandRegistry::instance.

◆ operator string()

operator string ( ) const

diagnostics: shows the commandID, if any, and the degree of definition of this command

Definition at line 389 of file command.cpp.

◆ fetchDef()

Command fetchDef ( Symbol cmdID )

staticprotected

just query an existing instance, if any.

Definition at line 150 of file command.cpp.

References CommandRegistry::instance.

Referenced by Command::defined().

Here is the caller graph for this function:

◆ activate()

void activate	(	shared_ptr< CommandImpl > &&	implFrame,
		Symbol	cmdID = `0`
	)

protected

make a command ready for use. Typically to be invoked through CommandDef during the definition stage, but also used for activating (anonymous) clone instances.

Parameters

cmdID new ID for creating a separate command registration when provided

Exceptions

error::Logic when this is already activated.

Definition at line 162 of file command.cpp.

References Handle< CommandImpl >::activate(), cStr(), Command::duplicate_detected(), and CommandRegistry::instance.

Referenced by CommandDef::activate(), Command::newInstance(), and Command::storeDef().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ setArguments() [1/2]

void setArguments ( Arguments & args )

private

pass a new argument tuple to the CommandImpl without exposing implementation.

Definition at line 251 of file command.cpp.

References Handle< CommandImpl >::impl().

Referenced by Command::bindArg(), and Command::bindArg().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ setArguments() [2/2]

void setArguments ( lib::diff::Rec const & paramData )

private

forward a Record<GenNode>, which was typically received via UI-Bus, down to the CommandImpl.

Remarks: this is how command arguments are actually passed from UI to the Session core

Definition at line 264 of file command.cpp.

References Handle< CommandImpl >::impl().

Here is the call graph for this function:

Friends And Related Symbol Documentation

◆ CommandDef

friend class CommandDef

friend

Definition at line 210 of file command.hpp.

◆ operator==

bool operator==	(	Command const &	c1,
		Command const &	c2
	)

friend

Definition at line 301 of file command.hpp.

◆ operator<

bool operator<	(	Command const &	c1,
		Command const &	c2
	)

friend

allow for sets and associative containers

Definition at line 314 of file command.hpp.

Inheritance diagram for Command:

Collaboration diagram for Command:

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

Description

Static Public Member Functions

Public Member Functions

Friends

Protected Member Functions

Static Protected Member Functions

Private Types

Private Member Functions

Constructor & Destructor Documentation

◆ Command() [1/4]

◆ Command() [2/4]

◆ ~Command()

◆ Command() [3/4]

◆ Command() [4/4]

Member Typedef Documentation

◆ _Handle

Member Function Documentation

◆ get()

◆ remove()

◆ storeDef()

◆ newInstance()

◆ maybeGetNewInstance()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ bindArg() [1/2]

◆ bindArg() [2/2]

◆ unbind()

◆ operator()()

◆ exec() [1/3]

◆ undo() [1/3]

◆ exec() [2/3]

◆ exec() [3/3]

◆ undo() [2/3]

◆ undo() [3/3]

◆ execSync()

◆ getDefaultHandlingPattern()

◆ setHandlingPattern()

◆ definition_count()

◆ instance_count()

◆ canExec() [1/2]

◆ canUndo() [1/2]

◆ defined()

◆ canExec() [2/2]

◆ canUndo() [2/2]

◆ duplicate_detected()

◆ getID()

◆ isAnonymous()

◆ operator string()

◆ fetchDef()

◆ activate()

◆ setArguments() [1/2]

◆ setArguments() [2/2]

Friends And Related Symbol Documentation

◆ CommandDef

◆ operator==

◆ operator<