src/helper/nvp.h

   1 /* SPDX-License-Identifier: BSD-2-Clause-Views */
   2
   3 /*
   4  * Copyright 2005 Salvatore Sanfilippo <antirez@invece.org>
   5  * Copyright 2005 Clemens Hintze <c.hintze@gmx.net>
   6  * Copyright 2005 patthoyts - Pat Thoyts <patthoyts@users.sf.net>
   7  * Copyright 2008 oharboe - Øyvind Harboe - oyvind.harboe@zylin.com
   8  * Copyright 2008 Andrew Lunn <andrew@lunn.ch>
   9  * Copyright 2008 Duane Ellis <openocd@duaneellis.com>
  10  * Copyright 2008 Uwe Klein <uklein@klein-messgeraete.de>
  11  * Copyright 2008 Steve Bennett <steveb@workware.net.au>
  12  * Copyright 2009 Nico Coesel <ncoesel@dealogic.nl>
  13  * Copyright 2009 Zachary T Welch zw@superlucidity.net
  14  * Copyright 2009 David Brownell
  15  * Copyright (c) 2005-2011 Jim Tcl Project. All rights reserved.
  16  *
  17  * This file is extracted from jim-nvp.h, originally part of jim TCL code.
  18  */
  19
  20 #ifndef OPENOCD_HELPER_NVP_H
  21 #define OPENOCD_HELPER_NVP_H
  22
  23 #include <helper/compiler.h>
  24
  25 /** Name Value Pairs, aka: NVP
  26  *   -  Given a string - return the associated int.
  27  *   -  Given a number - return the associated string.
  28  *   .
  29  *
  30  * Very useful when the number is not a simple index into an array of
  31  * known string, or there may be multiple strings (aliases) that mean then same
  32  * thing.
  33  *
  34  * An NVP Table is terminated with ".name = NULL".
  35  *
  36  * During the 'name2value' operation, if no matching string is found
  37  * the pointer to the terminal element (with p->name == NULL) is returned.
  38  *
  39  * Example:
  40  * \code
  41  *      const struct nvp yn[] = {
  42  *          { "yes", 1 },
  43  *          { "no" , 0 },
  44  *          { "yep", 1 },
  45  *          { "nope", 0 },
  46  *          { NULL, -1 },
  47  *      };
  48  *
  49  *  struct nvp *result;
  50  *  result = nvp_name2value(yn, "yes");
  51  *         returns &yn[0];
  52  *  result = nvp_name2value(yn, "no");
  53  *         returns &yn[1];
  54  *  result = nvp_name2value(yn, "Blah");
  55  *         returns &yn[4];
  56  * \endcode
  57  *
  58  * During the number2name operation, the first matching value is returned.
  59  */
  60
  61 struct nvp {
  62         const char *name;
  63         int value;
  64 };
  65
  66 struct command_invocation;
  67
  68 /* Name Value Pairs Operations */
  69 const struct nvp *nvp_name2value(const struct nvp *nvp_table, const char *name)
  70         __returns_nonnull __nonnull((1));
  71 const struct nvp *nvp_value2name(const struct nvp *nvp_table, int v)
  72         __returns_nonnull __nonnull((1));
  73
  74 void nvp_unknown_command_print(struct command_invocation *cmd, const struct nvp *nvp,
  75         const char *param_name, const char *param_value);
  76
  77 #endif /* OPENOCD_HELPER_NVP_H */