Skip to content

File wsh_shell_cmd.c

FileList > src > wsh_shell_cmd.c

Go to the source code of this file

  • #include "wsh_shell_cmd.h"

Public Functions

Type Name
WSH_SHELL_RET_STATE_t WshShellCmd_Attach (WshShellCmd_Table_t * pShellCommands, const WshShellCmd_t * pcCmdTable, WshShell_Size_t cmdNum)
Initializes the command table.
void WshShellCmd_DeAttach (WshShellCmd_Table_t * pShellCommands)
Frees or resets the command table.
const WshShellCmd_t * WshShellCmd_GetCmdByIndex (WshShellCmd_Table_t * pShellCommands, WshShell_Size_t idx)
Retrieves a command by index.
WshShell_Size_t WshShellCmd_GetCmdNum (WshShellCmd_Table_t * pShellCommands)
Returns the number of registered commands.
WSH_SHELL_RET_STATE_t WshShellCmd_GetOptValue (WshShellOption_Ctx_t * pOptCtx, WshShell_Size_t argc, const WshShell_Char_t * pArgv, WshShell_Size_t valueSize, void * pValue)
Retrieves the value associated with a parsed command option.
WshShellOption_Ctx_t WshShellCmd_ParseOpt (const WshShellCmd_t * pcCmd, WshShell_Size_t argc, const WshShell_Char_t * pArgv, WshShell_Size_t rights, WshShell_Size_t * pTokenPos)
Parses a command-line option for a given shell command.
void WshShellCmd_PrintOptionsOverview (const WshShellCmd_t * pcCmd)
Prints detailed information about a shell command and its options.
const WshShellCmd_t * WshShellCmd_SearchCmd (WshShellCmd_Table_t * pShellCommands, const WshShell_Char_t * pcCmdName)
Finds a command by its name.

Public Static Functions

Type Name
const WshShellOption_t * WshShellCmd_FindOpt (const WshShellCmd_t * pcCmd, const WshShell_Char_t * pcStr, WshShell_Size_t strLen)

Public Functions Documentation

function WshShellCmd_Attach

Initializes the command table. 

1
2
3
4
5
WSH_SHELL_RET_STATE_t WshShellCmd_Attach (
    WshShellCmd_Table_t * pShellCommands,
    const WshShellCmd_t * pcCmdTable,
    WshShell_Size_t cmdNum
)

Parameters:

  • pShellCommands Pointer to the shell command table.
  • pcCmdTable Pointer to the static list of commands.
  • cmdNum Number of commands in the list.

Returns:

WSH_SHELL_RET_STATE_SUCCESS on success.

function WshShellCmd_DeAttach

Frees or resets the command table. 

1
2
3
void WshShellCmd_DeAttach (
    WshShellCmd_Table_t * pShellCommands
)

Parameters:

  • pShellCommands Pointer to the command table.

function WshShellCmd_GetCmdByIndex

Retrieves a command by index. 

1
2
3
4
const WshShellCmd_t * WshShellCmd_GetCmdByIndex (
    WshShellCmd_Table_t * pShellCommands,
    WshShell_Size_t idx
)

Parameters:

  • pShellCommands Pointer to the command table.
  • idx Command index.

Returns:

Pointer to the command descriptor or NULL if out-of-bounds.

function WshShellCmd_GetCmdNum

Returns the number of registered commands. 

1
2
3
WshShell_Size_t WshShellCmd_GetCmdNum (
    WshShellCmd_Table_t * pShellCommands
)

Parameters:

  • pShellCommands Pointer to the command table.

Returns:

Number of commands.

function WshShellCmd_GetOptValue

Retrieves the value associated with a parsed command option. 

1
2
3
4
5
6
7
WSH_SHELL_RET_STATE_t WshShellCmd_GetOptValue (
    WshShellOption_Ctx_t * pOptCtx,
    WshShell_Size_t argc,
    const WshShell_Char_t * pArgv,
    WshShell_Size_t valueSize,
    void * pValue
)

This function extracts the value of a command-line option parsed by WshShellCmd_ParseOpt(), based on its type. Supported types include: * WSH_SHELL_OPTION_STR → copied to pValue as a string * WSH_SHELL_OPTION_INT → parsed as integer and written to pValue * WSH_SHELL_OPTION_FLOAT→ parsed as float and written to pValue

The function expects the option to be followed by its value in pArgv. All other option types return WSH_SHELL_RET_STATE_ERR_EMPTY.

Parameters:

  • pOptCtx Pointer to parsed option descriptor.
  • argc Argument count.
  • pArgv Argument vector (array of strings).
  • valueSize Maximum size of the output buffer (used for strings).
  • pValue Output buffer for value (string/int/float based on type).

Returns:

WSH_SHELL_RET_STATE_SUCCESS if value was successfully retrieved,

Returns:

WSH_SHELL_RET_STATE_ERR_PARAM if input parameters are invalid,

Returns:

WSH_SHELL_RET_STATE_ERR_EMPTY if the option doesn't accept a value,

Returns:

WSH_SHELL_RET_STATE_ERR_OVERFLOW if argument list is too short.

function WshShellCmd_ParseOpt

Parses a command-line option for a given shell command. 

1
2
3
4
5
6
7
WshShellOption_Ctx_t WshShellCmd_ParseOpt (
    const WshShellCmd_t * pcCmd,
    WshShell_Size_t argc,
    const WshShell_Char_t * pArgv,
    WshShell_Size_t rights,
    WshShell_Size_t * pTokenPos
)

This function analyzes the current token in the argument list and attempts to identify a valid option defined in the given command's option table. If a valid option is found, its descriptor is returned. The token position (*pTokenPos) is advanced accordingly depending on the number of arguments that the option consumes.

If only the command name is present (i.e., argc == 1), the function checks for an option of type WSH_SHELL_OPTION_NO (indicating the command may be executed without any parameters).

Parameters:

  • pcCmd Pointer to the shell command definition.
  • argc Number of arguments in the input array.
  • pArgv Array of argument strings.
  • pArgv User rights bitmask for access check.
  • pTokenPos Pointer to the current token position in pArgv. Will be updated to point past the parsed option.

Returns:

A filled option descriptor if a matching option is found, or an empty descriptor if not.

function WshShellCmd_PrintOptionsOverview

Prints detailed information about a shell command and its options. 

1
2
3
void WshShellCmd_PrintOptionsOverview (
    const WshShellCmd_t * pcCmd
)

This function outputs the help text and a formatted table describing each available option for the specified command. For each option, the following fields are printed: * Short name * Long name * Option type (e.g., INT, STR, FLOAT) * Access flags (read/write/etc.) * Description/help string

Options of type WSH_SHELL_OPTION_NO and WSH_SHELL_OPTION_WAITS_INPUT are skipped.

This is typically used for displaying help information when a user requests --help for a specific command.

Parameters:

  • pcCmd Pointer to the command descriptor whose options should be printed.

function WshShellCmd_SearchCmd

Finds a command by its name. 

1
2
3
4
const WshShellCmd_t * WshShellCmd_SearchCmd (
    WshShellCmd_Table_t * pShellCommands,
    const WshShell_Char_t * pcCmdName
)

Parameters:

  • pShellCommands Pointer to the command table.
  • pcCmdName Command name string.

Returns:

Pointer to the matching command descriptor or NULL if not found.

Public Static Functions Documentation

function WshShellCmd_FindOpt

1
2
3
4
5
static const WshShellOption_t * WshShellCmd_FindOpt (
    const WshShellCmd_t * pcCmd,
    const WshShell_Char_t * pcStr,
    WshShell_Size_t strLen
)

The documentation for this class was generated from the following file src/wsh_shell_cmd.c