michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: shell: update according to new help usage

Browse source 
Updated documentation according to recent changes:
1. Removed options from the shell.
2. Simplified help usage.

Signed-off-by: Jakub Rzeszutko <jakub.rzeszutko@nordicsemi.no>
This commit is contained in:
Jakub Rzeszutko 2018-11-26 22:39:43 +01:00 • committed by Carles Cufí
commit 9e958b405c
2 changed files with 28 additions and 132 deletions
Download patch file Download diff file Expand all files Collapse all files

147
doc/subsystems/shell/shell.rst
View file

@ -236,127 +236,23 @@ Simple command handler implementation:
} }
.. warning:: .. warning::
Do not use function :cpp:func:`shell_fprintf` outside of the command Do not use function :cpp:func:`shell_fprintf` or shell print macros:
handler because this might lead to incorrect text display on the :c:macro:`shell_print`, :c:macro:`shell_info`, :c:macro:`shell_warn`,
screen. If any text should be displayed outside of the command context, :c:macro:`shell_error` outside of the command handler because this
then use the :ref:`logger`. might lead to incorrect text display on the screen. If any text should
be displayed outside of the command context, then use the
:ref:`logger` or `printk` function.
Command help Command help
------------ ------------
Every user-defined command, subcommand, or option can have its own help Every user-defined command or subcommand can have its own help description.
description. The help for commands and subcommands can be created with The help for commands and subcommands can be created with respective macros:
respective macros: :c:macro:`SHELL_CMD_REGISTER` and :c:macro:`SHELL_CMD`. :c:macro:`SHELL_CMD_REGISTER`, :c:macro:`SHELL_CMD_ARG_REGISTER`,
In addition, you can define options for commands or subcommands using the :c:macro:`SHELL_CMD`, and :c:macro:`SHELL_CMD_ARG`.
macro :c:macro:`SHELL_OPT`. By default, each and every command or subcommand
has these two options implemented: ``-h`` and ``--help``.
In order to add help functionality to a command or subcommand, you must Shell prints this help message when you call a command
implement the help handler by either calling :cpp:func:`shell_cmd_precheck` or subcommand with ``-h`` or ``--help`` parameter.
or pair of functions :cpp:func:`shell_help_requested` and
:cpp:func:`shell_help_print`. The former is more convenient as it also
checks for valid arguments count.
.. code-block:: c
static int cmd_dummy_1(const struct shell *shell, size_t argc,
char **argv)
{
ARG_UNUSED(argv);
/* Function shell_cmd_precheck will do one of below actions:
* 1. print help if command called with -h or --help
* 2. print error message if argc > 2
*
* Each of these actions can be deactivated in Kconfig.
*/
int err = shell_cmd_precheck(shell, (argc <= 2), NULL, 0);
if (err) {
return err;
}
shell_fprintf(shell, SHELL_NORMAL,
"Command called with no -h or --help option."
"\n");
return 0;
}
static int cmd_dummy_2(const struct shell *shell, size_t argc,
char **argv)
{
ARG_UNUSED(argc);
ARG_UNUSED(argv);
if (shell_help_requested(shell) {
shell_help_print(shell);
} else {
shell_fprintf(shell, SHELL_NORMAL,
"Command called with no -h or --help option."
"\n");
}
return 0;
}
Command options
---------------
When possible, use subcommands instead of options. Options apply mainly in the
case when an argument with ``-`` or ``--`` is requested. The main benefit of
using subcommands is that they can be prompted or completed with the :kbd:`Tab`
key. In addition, subcommands can have their own handler, which limits the
usage of ``if - else if`` statements combination with the ``strcmp`` function
in command handler.
.. code-block:: c
static int cmd_with_options(const struct shell *shell, size_t argc,
char **argv)
{
int err;
/* Dummy options showing options usage */
static const struct shell_getopt_option opt[] = {
SHELL_OPT(
"--test",
"-t",
"test option help string"
),
SHELL_OPT(
"--dummy",
"-d",
"dummy option help string"
)
};
/* If command will be called with -h or --help option
* all declared options will be listed in the help message
*/
err = shell_cmd_precheck(shell, (argc <= 2), opt,
sizeof(opt)/sizeof(opt[1]));
if (err) {
return err;
}
/* checking if command was called with test option */
if (!strcmp(argv[1], "-t") || !strcmp(argv[1], "--test")) {
shell_fprintf(shell, SHELL_NORMAL, "Command called with -t"
" or --test option.\n");
return 0;
}
/* checking if command was called with dummy option */
if (!strcmp(argv[1], "-d") || !strcmp(argv[1], "--dummy")) {
shell_fprintf(shell, SHELL_NORMAL, "Command called with -d"
" or --dummy option.\n");
return 0;
}
shell_fprintf(shell, SHELL_WARNING,
"Command called with no valid option.\n");
return 0;
}
Parent commands Parent commands
--------------- ---------------
@ -367,7 +263,7 @@ commands or the parent commands, depending on how you index ``argv``.
* When indexing ``argv`` with positive numbers, you can access the parameters. * When indexing ``argv`` with positive numbers, you can access the parameters.
* When indexing ``argv`` with negative numbers, you can access the parent * When indexing ``argv`` with negative numbers, you can access the parent
commands. commands.
* The subcommand to which the handler belongs has the ``argv`` value of 0. * The subcommand to which the handler belongs has the ``argv`` index of 0.
.. code-block:: c .. code-block:: c
@ -379,18 +275,14 @@ commands or the parent commands, depending on how you index ``argv``.
/* If it is a subcommand handler parent command syntax /* If it is a subcommand handler parent command syntax
* can be found using argv[-1]. * can be found using argv[-1].
*/ */
shell_fprintf(shell, SHELL_NORMAL, shell_print(shell, "This command has a parent command: %s",
"This command has a parent command: %s\n",
argv[-1]); argv[-1]);
/* Print this command syntax */ /* Print this command syntax */
shell_fprintf(shell, SHELL_NORMAL, shell_print(shell, "This command syntax is: %s", argv[0]);
"This command syntax is: %s\n",
argv[0]);
/* Print first argument */ /* Print first argument */
shell_fprintf(shell, SHELL_NORMAL, shell_print(shell, "%s", argv[1]);
argv[1]);
return 0; return 0;
} }
@ -480,7 +372,7 @@ The following code shows a simple use case of this library:
ARG_UNUSED(argc); ARG_UNUSED(argc);
ARG_UNUSED(argv); ARG_UNUSED(argv);
shell_fprintf(shell, SHELL_NORMAL, "pong\n"); shell_print(shell, "pong");
return 0; return 0;
} }
@ -489,10 +381,9 @@ The following code shows a simple use case of this library:
{ {
int cnt; int cnt;
shell_fprintf(shell, SHELL_NORMAL, "argc = %d\n", argc); shell_print(shell, "argc = %d", argc);
for (cnt = 0; cnt < argc; cnt++) { for (cnt = 0; cnt < argc; cnt++) {
shell_fprintf(shell, SHELL_NORMAL, shell_print(shell, " argv[%d] = %s", cnt, argv[cnt]);
" argv[%d] = %s\n", cnt, argv[cnt]);
} }
return 0; return 0;
} }

13
include/shell/shell.h
View file

@ -105,10 +105,12 @@ struct shell_static_entry {
}; };
/** /**
* @brief Macro for defining and adding a root command (level 0) with * @brief Macro for defining and adding a root command (level 0) with required
* arguments. * number of arguments.
* *
* @note Each root command shall have unique syntax. * @note Each root command shall have unique syntax. If a command will be called
* with wrong number of arguments shell will print an error message and command
* handler will not be called.
* *
* @param[in] syntax Command syntax (for example: history). * @param[in] syntax Command syntax (for example: history).
* @param[in] subcmd Pointer to a subcommands array. * @param[in] subcmd Pointer to a subcommands array.
@ -184,7 +186,10 @@ struct shell_static_entry {
} }
/** /**
* @brief Initializes a shell command with arguments * @brief Initializes a shell command with arguments.
*
* @note If a command will be called with wrong number of arguments shell will
* print an error message and command handler will not be called.
* *
* @param[in] _syntax Command syntax (for example: history). * @param[in] _syntax Command syntax (for example: history).
* @param[in] _subcmd Pointer to a subcommands array. * @param[in] _subcmd Pointer to a subcommands array.