src/lib/support/CHIPArgParser.hpp

   1 /*
   2  *
   3  *    Copyright (c) 2020 Project CHIP Authors
   4  *    Copyright (c) 2017 Nest Labs, Inc.
   5  *    All rights reserved.
   6  *
   7  *    Licensed under the Apache License, Version 2.0 (the "License");
   8  *    you may not use this file except in compliance with the License.
   9  *    You may obtain a copy of the License at
  10  *
  11  *        http://www.apache.org/licenses/LICENSE-2.0
  12  *
  13  *    Unless required by applicable law or agreed to in writing, software
  14  *    distributed under the License is distributed on an "AS IS" BASIS,
  15  *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16  *    See the License for the specific language governing permissions and
  17  *    limitations under the License.
  18  */
  19
  20 /**
  21  *    @file
  22  *      Support functions for parsing command-line arguments.
  23  *
  24  */
  25
  26 #pragma once
  27
  28 #include <core/CHIPCore.h>
  29
  30 #if CHIP_CONFIG_ENABLE_ARG_PARSER
  31
  32 #include <stdio.h>
  33 #include <stdlib.h>
  34
  35 namespace chip {
  36 namespace ArgParser {
  37
  38 struct OptionSet;
  39
  40 /**
  41  * A function that can be called to handle a set of command line options.
  42  */
  43 typedef bool (*OptionHandlerFunct)(const char * progName, OptionSet * optSet, int id, const char * name, const char * arg);
  44
  45 /**
  46  * A function that can be called to handle any remaining, non-option command line arguments.
  47  */
  48 typedef bool (*NonOptionArgHandlerFunct)(const char * progName, int argc, char * argv[]);
  49
  50 /**
  51  * Defines the argument requirements for a command line option.
  52  */
  53 enum OptionArgumentType
  54 {
  55     kNoArgument       = 0,
  56     kArgumentRequired = 1,
  57     kArgumentOptional = 2,
  58 };
  59
  60 /**
  61  * Defines a command line option.
  62  */
  63 struct OptionDef
  64 {
  65     const char * Name;          /**< Long name for the option */
  66     OptionArgumentType ArgType; /**< An enumerated value specifying whether the option takes an argument */
  67     uint16_t Id;                /**< An integer id for the option.  If the value falls in the range of
  68                                      graphical ASCII characters the value is also used as the short name
  69                                      for the option. */
  70 };
  71
  72 /**
  73  * Defines a group of logically-related and reusable command line options.
  74  */
  75 struct OptionSet
  76 {
  77     OptionHandlerFunct OptionHandler; /**< Pointer to function for processing individual options */
  78     OptionDef * OptionDefs;           /**< NULL terminated list of option definitions structures. */
  79     const char * HelpGroupName;       /**< Group name under which options appear in help output */
  80     const char * OptionHelp;          /**< Help text describing options */
  81 };
  82
  83 /**
  84  * An OptionSet where the handler is a virtual function.
  85  */
  86 class OptionSetBase : public OptionSet
  87 {
  88 public:
  89     OptionSetBase();
  90     virtual ~OptionSetBase() {}
  91     virtual bool HandleOption(const char * progName, OptionSet * optSet, int id, const char * name, const char * arg) = 0;
  92
  93 private:
  94     static bool CallHandleFunct(const char * progName, OptionSet * optSet, int id, const char * name, const char * arg);
  95 };
  96
  97 bool ParseArgs(const char * progName, int argc, char * argv[], OptionSet * optSets[]);
  98 bool ParseArgs(const char * progName, int argc, char * argv[], OptionSet * optSets[], NonOptionArgHandlerFunct nonOptArgHandler);
  99 bool ParseArgs(const char * progName, int argc, char * argv[], OptionSet * optSets[], NonOptionArgHandlerFunct nonOptArgHandler,
 100                bool ignoreUnknown);
 101
 102 bool ParseArgsFromString(const char * progName, const char * argStr, OptionSet * optSets[]);
 103 bool ParseArgsFromString(const char * progName, const char * argStr, OptionSet * optSets[],
 104                          NonOptionArgHandlerFunct nonOptArgHandler);
 105 bool ParseArgsFromString(const char * progName, const char * argStr, OptionSet * optSets[],
 106                          NonOptionArgHandlerFunct nonOptArgHandler, bool ignoreUnknown);
 107
 108 bool ParseArgsFromEnvVar(const char * progName, const char * varName, OptionSet * optSets[]);
 109 bool ParseArgsFromEnvVar(const char * progName, const char * varName, OptionSet * optSets[],
 110                          NonOptionArgHandlerFunct nonOptArgHandler);
 111 bool ParseArgsFromEnvVar(const char * progName, const char * varName, OptionSet * optSets[],
 112                          NonOptionArgHandlerFunct nonOptArgHandler, bool ignoreUnknown);
 113
 114 void PrintOptionHelp(OptionSet * optionSets[], FILE * s);
 115
 116 extern void (*PrintArgError)(const char * msg, ...);
 117 void DefaultPrintArgError(const char * msg, ...);
 118
 119 // Utility functions for parsing common argument value types.
 120 bool ParseBoolean(const char * str, bool & output);
 121 bool ParseInt(const char * str, uint8_t & output);
 122 bool ParseInt(const char * str, uint16_t & output);
 123 bool ParseInt(const char * str, int32_t & output);
 124 bool ParseInt(const char * str, uint32_t & output);
 125 bool ParseInt(const char * str, uint64_t & output);
 126 bool ParseInt(const char * str, int32_t & output, int base);
 127 bool ParseInt(const char * str, uint32_t & output, int base);
 128 bool ParseInt(const char * str, uint64_t & output, int base);
 129 bool ParseNodeId(const char * str, uint64_t & nodeId);
 130 bool ParseFabricId(const char * str, uint64_t & fabricId, bool allowReserved = false);
 131 bool ParseSubnetId(const char * str, uint16_t & subnetId);
 132 bool ParseHexString(const char * hexStr, uint32_t strLen, uint8_t * outBuf, uint32_t outBufSize, uint32_t & outDataLen);
 133
 134 extern OptionSet ** gActiveOptionSets;
 135
 136 /**
 137  * Common OptionSet for handling informational options (--help, --version).
 138  *
 139  */
 140 class HelpOptions : public OptionSetBase
 141 {
 142 public:
 143     const char * AppName;  /**< The name of the command-line application. */
 144     const char * AppUsage; /**< A short string depicting the application's command-line syntax. */
 145     const char * AppVersion;
 146     const char * AppDesc; /**< A description of the application's purpose/behavior. */
 147
 148     HelpOptions(const char * appName, const char * appUsage, const char * appVersion);
 149     HelpOptions(const char * appName, const char * appUsage, const char * appVersion, const char * appDesc);
 150
 151     void PrintBriefUsage(FILE * s);
 152     void PrintLongUsage(OptionSet * optSets[], FILE * s);
 153     void PrintVersion(FILE * s);
 154
 155     bool HandleOption(const char * progName, OptionSet * optSet, int id, const char * name, const char * arg) override;
 156 };
 157
 158 } // namespace ArgParser
 159 } // namespace chip
 160
 161 #endif // CHIP_CONFIG_ENABLE_ARG_PARSER