ceph/src/include/str_map.h

   1 // -*- mode:C++; tab-width:8; c-basic-offset:2; indent-tabs-mode:t -*-
   2 // vim: ts=8 sw=2 smarttab
   3 /*
   4  * Ceph - scalable distributed file system
   5  *
   6  * Copyright (C) 2013 Cloudwatt <libre.licensing@cloudwatt.com>
   7  *
   8  * Author: Loic Dachary <loic@dachary.org>
   9  *
  10  *  This library is free software; you can redistribute it and/or
  11  *  modify it under the terms of the GNU Lesser General Public
  12  *  License as published by the Free Software Foundation; either
  13  *  version 2.1 of the License, or (at your option) any later version.
  14  *
  15  */
  16
  17 #ifndef CEPH_STRMAP_H
  18 #define CEPH_STRMAP_H
  19
  20 #define CONST_DELIMS ",;\t\n "
  21
  22 #include <map>
  23 #include <string>
  24 #include <sstream>
  25
  26 /**
  27  * Parse **str** and set **str_map** with the key/value pairs read
  28  * from it. The format of **str** is either a well formed JSON object
  29  * or a custom key[=value] plain text format.
  30  *
  31  * JSON is tried first. If successfully parsed into a JSON object, it
  32  * is copied into **str_map** verbatim. If it is not a JSON object ( a
  33  * string, integer etc. ), -EINVAL is returned and **ss** is set to
  34  * a human readable error message.
  35  *
  36  * If **str** is no valid JSON and if **fallback_to_plain** is set to true
  37  * (default: true) it is assumed to be a string containing white space
  38  * separated key=value pairs. A white space is either space, tab or newline.
  39  * Function **get_str_map** will be leveraged to parse the plain-text
  40  * key/value pairs.
  41  *
  42  * @param [in] str JSON or plain text key/value pairs
  43  * @param [out] ss human readable message on error
  44  * @param [out] str_map key/value pairs read from str
  45  * @param [in] fallback_to_plain attempt parsing as plain-text if json fails
  46  * @return **0** on success or a -EINVAL on error.
  47  */
  48 extern int get_json_str_map(
  49     const std::string &str,
  50     std::ostream &ss,
  51     std::map<std::string,std::string> *str_map,
  52     bool fallback_to_plain = true);
  53
  54 /**
  55  * Parse **str** and set **str_map** with the key/value pairs read from
  56  * it.  The format of **str** is a number of custom key[=value] pairs in
  57  * plain text format.
  58  *
  59  * The string will be parsed taking **delims** as field delimiters for
  60  * key/values.  The value is optional resulting in an empty string when
  61  * not provided.  For example, using white space as delimiters:
  62  *
  63  *     insert your own=political/ideological    statement=here
  64  *
  65  * will be parsed into:
  66  *
  67  *     { "insert": "",
  68  *       "your": "",
  69  *       "own": "political/ideological",
  70  *       "statement": "here" }
  71  *
  72  * Alternative delimiters may be provided.  For instance, specifying
  73  * "white space and slash", for the above statement, would be parsed
  74  * into:
  75  *
  76  *     { "insert": "",
  77  *       "your": "",
  78  *       "own": "political",
  79  *       "ideological": "",
  80  *       "statement": "here" }
  81  *
  82  * See how adding '/' to the delimiters field will spawn a new key without
  83  * a set value.
  84  *
  85  * Always returns 0, as there is no condition for failure.
  86  *
  87  * @param [in] str plain text key/value pairs
  88  * @param [in] delims field delimiters to be used for parsing str
  89  * @param [out] str_map key/value pairs parsed from str
  90  * @return **0**
  91  */
  92 extern int get_str_map(
  93     const std::string &str,
  94     std::map<std::string,std::string> *str_map,
  95     const char *delims = CONST_DELIMS);
  96
  97 /**
  98  * Returns the value of **key** in **str_map** if available.
  99  *
 100  * If **key** is not available in **str_map**, and if **def_val** is
 101  * not-NULL then returns **def_val**. Otherwise checks if the value of
 102  * **key** is an empty string and if so will return **key**.
 103  * If the map contains **key**, the function returns the value of **key**.
 104  *
 105  * @param[in] str_map Map to obtain **key** from
 106  * @param[in] key The key to search for in the map
 107  * @param[in] def_val The value to return in case **key** is not present
 108  */
 109 extern std::string get_str_map_value(
 110     const std::map<std::string,std::string> &str_map,
 111     const std::string &key,
 112     const std::string *def_val = NULL);
 113
 114 /**
 115  * Returns the value of **key** in **str_map** if available.
 116  *
 117  * If **key** is available in **str_map** returns the value of **key**.
 118  *
 119  * If **key** is not available in **str_map**, and if **def_key**
 120  * is not-NULL and available in **str_map**, then returns the value
 121  * of **def_key**.
 122  *
 123  * Otherwise returns an empty string.
 124  *
 125  * @param[in] str_map Map to obtain **key** or **def_key** from
 126  * @param[in] key Key to obtain the value of from **str_map**
 127  * @param[in] def_key Key to fallback to if **key** is not present
 128  *                    in **str_map**
 129  */
 130 extern std::string get_str_map_key(
 131     const std::map<std::string,std::string> &str_map,
 132     const std::string &key,
 133     const std::string *fallback_key = NULL);
 134
 135
 136 // This function's only purpose is to check whether a given map has only
 137 // ONE key with an empty value (which would mean that 'get_str_map()' read
 138 // a map in the form of 'VALUE', without any KEY/VALUE pairs) and, in such
 139 // event, to assign said 'VALUE' to a given 'def_key', such that we end up
 140 // with a map of the form "m = { 'def_key' : 'VALUE' }" instead of the
 141 // original "m = { 'VALUE' : '' }".
 142 int get_conf_str_map_helper(
 143     const std::string &str,
 144     std::ostringstream &oss,
 145     std::map<std::string,std::string> *m,
 146     const std::string &def_key);
 147
 148 #endif