src/lib/shell/shell.h

   1 /*
   2  *
   3  *    Copyright (c) 2020 Project CHIP Authors
   4  *    Copyright (c) 2017 Google LLC
   5  *
   6  *    Licensed under the Apache License, Version 2.0 (the "License");
   7  *    you may not use this file except in compliance with the License.
   8  *    You may obtain a copy of the License at
   9  *
  10  *        http://www.apache.org/licenses/LICENSE-2.0
  11  *
  12  *    Unless required by applicable law or agreed to in writing, software
  13  *    distributed under the License is distributed on an "AS IS" BASIS,
  14  *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15  *    See the License for the specific language governing permissions and
  16  *    limitations under the License.
  17  */
  18
  19 /**
  20  *    @file
  21  *      Header that defines a generic shell API for CHIP examples
  22  */
  23
  24 #pragma once
  25
  26 #include "streamer.h"
  27
  28 #include <stdarg.h>
  29 #include <stddef.h>
  30
  31 #ifndef CHIP_SHELL_PROMPT
  32 #define CHIP_SHELL_PROMPT "> "
  33 #endif // CHIP_SHELL_PROMPT
  34
  35 #ifndef CHIP_SHELL_MAX_MODULES
  36 #define CHIP_SHELL_MAX_MODULES 10
  37 #endif // CHIP_SHELL_MAX_MODULES
  38
  39 #ifndef CHIP_SHELL_MAX_LINE_SIZE
  40 #define CHIP_SHELL_MAX_LINE_SIZE 256
  41 #endif // CHIP_SHELL_MAX_LINE_SIZE
  42
  43 #ifndef CHIP_SHELL_MAX_TOKENS
  44 #define CHIP_SHELL_MAX_TOKENS 10
  45 #endif // CHIP_SHELL_MAX_TOKENS
  46
  47 namespace chip {
  48 namespace Shell {
  49
  50 /**
  51  * Callback to execute an individual shell command.
  52  *
  53  * @param argc                  Number of arguments passed.
  54  * @param argv                  Array of option strings. The command name is not included.
  55  *
  56  * @return                      0 on success; CHIP_ERROR[...] on failure.
  57  */
  58 typedef int shell_command_fn(int argc, char * argv[]);
  59
  60 /**
  61  * Descriptor structure for a single command.
  62  *
  63  * Typically a set of commands are defined as an array of this structure
  64  * and passed to the `shell_register()` during application initialization.
  65  *
  66  * An example command set definition follows:
  67  *
  68  * static shell_command_t cmds[] = {
  69  *   { &cmd_echo, "echo", "Echo back provided inputs" },
  70  *   { &cmd_exit, "exit", "Exit the shell application" },
  71  *   { &cmd_help, "help", "List out all top level commands" },
  72  *   { &cmd_version, "version", "Output the software version" },
  73  * };
  74  */
  75 struct shell_command
  76 {
  77     shell_command_fn * cmd_func;
  78     const char * cmd_name;
  79     const char * cmd_help;
  80 };
  81
  82 typedef const struct shell_command shell_command_t;
  83
  84 /**
  85  * Execution callback for a shell command.
  86  *
  87  * @param command               The shell command being iterated.
  88  * @param arg                   A context variable passed to the iterator function.
  89  *
  90  * @return                      0 continue iteration; 1 break iteration.
  91  */
  92 typedef int shell_command_iterator_t(shell_command_t * command, void * arg);
  93
  94 class Shell
  95 {
  96 protected:
  97     static Shell theShellRoot;
  98
  99     shell_command_t * _commandSet[CHIP_SHELL_MAX_MODULES];
 100     unsigned _commandSetSize[CHIP_SHELL_MAX_MODULES];
 101     unsigned _commandSetCount;
 102
 103     /**
 104      * Registers a set of defaults commands (help) for all Shell and sub-Shell instances.
 105      *
 106      *    help      - list the top-level brief of all registered commands
 107      *    echo      - echo back all argument characters passed
 108      *    exit      - quit out of the shell
 109      *    version   - return the version of the CHIP library
 110      */
 111     void RegisterDefaultCommands();
 112
 113 public:
 114     Shell() {}
 115
 116     /** Return the root singleton for the Shell command hierarchy. */
 117     static Shell & Root() { return theShellRoot; }
 118
 119     /**
 120      * Execution callback for a shell command.
 121      *
 122      * @param on_command            An iterator callback to be called for each command.
 123      * @param arg                   A context variable to be passed to each command iterated.
 124      */
 125     void ForEachCommand(shell_command_iterator_t * on_command, void * arg);
 126
 127     /**
 128      * Dispatch and execute the command for the given argument list.
 129      *
 130      * @param argc                  Number of arguments in argv.
 131      * @param argv                  Array of arguments in the tokenized command line to execute.
 132      *
 133      * @return                      0 on success; CHIP_ERROR[...] on failure.
 134      */
 135     int ExecCommand(int argc, char * argv[]);
 136
 137     /**
 138      * Registers a command set, or array of commands with the shell.
 139      *
 140      * @param command_set           An array of commands to add to the shell.
 141      * @param count                 The number of commands in the command set array.
 142      */
 143     void RegisterCommands(shell_command_t * command_set, unsigned count);
 144
 145     /**
 146      * Utility function for converting a raw line typed into a shell into an array of words or tokens.
 147      *
 148      * @param buffer                String of the raw line typed into shell.
 149      * @param tokens                Array of words to be created by the tokenizer.
 150      *                              This array will point to the same memory as passed in
 151      *                              via buffer.  Spaces will be replaced with NULL characters.
 152      * @param max_tokens            Maximum size of token array.
 153      *
 154      * @return                      Number of tokens generated (argc).
 155      */
 156     static int TokenizeLine(char * buffer, char ** tokens, int max_tokens);
 157
 158     /**
 159      * Main loop for shell.
 160      *
 161      * @param arg                   Unused context block for shell task to comply with task function syntax.
 162      */
 163     static void TaskLoop(void * arg);
 164 };
 165
 166 /** Utility macro for running ForEachCommand on root shell. */
 167 static inline void shell_command_foreach(shell_command_iterator_t * on_command, void * arg)
 168 {
 169     return Shell::Root().ForEachCommand(on_command, arg);
 170 }
 171
 172 /** Utility macro for running ForEachCommand on Root shell. */
 173 static inline void shell_register(shell_command_t * command_set, unsigned count)
 174 {
 175     return Shell::Root().RegisterCommands(command_set, count);
 176 }
 177
 178 /** Utility macro for to tokenize an input line. */
 179 static inline int shell_line_tokenize(char * buffer, char ** tokens, int max_tokens)
 180 {
 181     return Shell::TokenizeLine(buffer, tokens, max_tokens);
 182 }
 183
 184 /** Utility macro to run main shell task loop. */
 185 static inline void shell_task(void * arg)
 186 {
 187     return Shell::TaskLoop(arg);
 188 }
 189
 190 } // namespace Shell
 191 } // namespace chip