hphp/util/hdf.h

   1 /*
   2    +----------------------------------------------------------------------+
   3    | HipHop for PHP                                                       |
   4    +----------------------------------------------------------------------+
   5    | Copyright (c) 2010-present Facebook, Inc. (http://www.facebook.com)  |
   6    +----------------------------------------------------------------------+
   7    | This source file is subject to version 3.01 of the PHP license,      |
   8    | that is bundled with this package in the file LICENSE, and is        |
   9    | available through the world-wide-web at the following url:           |
  10    | http://www.php.net/license/3_01.txt                                  |
  11    | If you did not receive a copy of the PHP license and are unable to   |
  12    | obtain it through the world-wide-web, please send a note to          |
  13    | license@php.net so we can mail you a copy immediately.               |
  14    +----------------------------------------------------------------------+
  15 */
  16
  17 #ifndef incl_HPHP_CONFIG_HDF_H_
  18 #define incl_HPHP_CONFIG_HDF_H_
  19
  20 #include <string>
  21 #include <map>
  22 #include <set>
  23 #include <vector>
  24 #include <unordered_map>
  25
  26 #include <boost/container/flat_set.hpp>
  27
  28 #include "hphp/neo/neo_hdf.h"
  29
  30 #include "hphp/util/exception.h"
  31 #include "hphp/util/functional.h"
  32 #include "hphp/util/hash-map.h"
  33
  34 namespace HPHP {
  35 ///////////////////////////////////////////////////////////////////////////////
  36
  37 /**
  38  * A super-fast hierarchical data structure, wrapped around ClearSilver's HDF
  39  * data format: http://www.clearsilver.net/docs/man_hdf.hdf
  40  *
  41  * HDF is a serialization format that emphasizes cleanness and simplicity when
  42  * representing hierarchical data. It's designed to be fast parsing and
  43  * accessing. One example is,
  44  *
  45  *   Server {
  46  *     Name = MyTestServer
  47  *     IP.1 = 192.168.100.100
  48  *     IP.2 = 192.168.100.101
  49  *   }
  50  */
  51 struct HdfRaw; // reference counting HDF* raw pointer, implmented in .cpp file
  52 struct Hdf {
  53   /**
  54    * Constructors.
  55    */
  56   Hdf();                                          // create an empty HDF tree
  57   explicit Hdf(const char *filename);             // open the specified file
  58   explicit Hdf(const std::string &filename);      // open the specified file
  59   explicit Hdf(const Hdf *hdf, const char *name); // constructing a sub-node
  60            Hdf(const Hdf &hdf);                   // make a copy by reference
  61   explicit Hdf(HDF *hdf);                         // attaching a raw pointer
  62   ~Hdf();
  63
  64   /**
  65    * Is this an empty Hdf?
  66    */
  67   bool isEmpty() const;
  68
  69   /**
  70    * Close current and make a copy of the specified.
  71    */
  72   void assign(const Hdf &hdf);
  73
  74   /**
  75    * Copy specified without closing current.
  76    */
  77   void copy(const Hdf &hdf);
  78
  79   /**
  80    * Either close current file and open a new file, or append a file's content.
  81    */
  82   void open(const char *filename);
  83   void open(const std::string &filename) { open(filename.c_str());}
  84   void append(const char *filename);
  85   void append(const std::string &filename) { append(filename.c_str());}
  86   void close();
  87
  88   /**
  89    * Get a list of node names that are visited or not visited. Great for lint
  90    * purpose, finding nodes that are invalid for configurations, for example.
  91    * Use exclusion to skip checking certain node names. For example,
  92    *
  93    *   LintExcludePatterns {
  94    *     * = FutureConfigName
  95    *     * = *endwith
  96    *     * = startwith*
  97    *     * = *containing*
  98    *   }
  99    *
 100    * The pattern is NOT a full regex, but only the simple 3 as above.
 101    *
 102    * When visited = true, return a list of nodes that are visited.
 103    */
 104   void lint(std::vector<std::string> &names,
 105             const char *excludePatternNode = "LintExcludePatterns",
 106             bool visited = false);
 107   void setVisited(bool visited = true);
 108
 109   /**
 110    * Read or dump this entire tree in HDF format.
 111    */
 112   void fromString(const char *input);
 113   const char *toString() const;
 114   void write(const char *filename) const;
 115   void write(const std::string &filename) const { write(filename.c_str());}
 116
 117   /**
 118    * Get this node's value. When node is not present or node's value is not
 119    * parsable, return default value "defValue" instead.
 120    *
 121    * Boolean "false" is defined as one of these values and anything else is
 122    * "true" (except absent node will take default value):
 123    *   1. empty string
 124    *   2. 0 (note: string "00" or longer are not "false").
 125    *   3. string "false", "no" or "off" case-insensitively
 126    *
 127    * Numbers can also be specified in hex (0x prefix) or octal (0 prefix). For
 128    * any values that are not entirely parsable to be a number, it will return
 129    * default value instead.
 130    */
 131   bool configGetBool(bool defValue = false) const;
 132   const char *configGet(const char *defValue = nullptr) const;
 133   std::string configGetString(const std::string &defValue = "") const;
 134   char configGetByte(char defValue = 0) const;
 135   unsigned char configGetUByte (unsigned char defValue = 0) const;
 136   int16_t configGetInt16(int16_t  defValue = 0) const;
 137   uint16_t configGetUInt16(uint16_t defValue = 0) const;
 138   int32_t configGetInt32(int32_t  defValue = 0) const;
 139   uint32_t configGetUInt32(uint32_t defValue = 0) const;
 140   int64_t configGetInt64(int64_t  defValue = 0) const;
 141   uint64_t configGetUInt64(uint64_t defValue = 0) const;
 142   double configGetDouble(double defValue = 0) const;
 143
 144   void configGet(std::vector<uint32_t> &values) const;
 145   void configGet(std::vector<std::string> &values) const;
 146   void configGet(std::set<std::string> &values) const;
 147   void configGet(std::set<std::string, stdltistr> &values) const;
 148   void configGet(boost::container::flat_set<std::string> &values) const;
 149   void configGet(std::unordered_map<std::string, int> &values) const;
 150   void configGet(std::map<std::string, std::string> &values) const;
 151   void configGet(std::map<std::string, std::string, stdltistr> &values) const;
 152   void configGet(hphp_string_imap<std::string> &values) const;
 153
 154   /**
 155    * Helper function to convert a config string value to bool.
 156    */
 157
 158   static bool convertRawConfigToBool(const char *v);
 159
 160
 161   /**
 162    * Set this node's value.
 163    */
 164   void set(const char *value);
 165   void set(const std::string &value) { set(value.c_str());}
 166   void set(bool   value) { set(value ? "1" : "0");}
 167   void set(char   value) { set((int64_t)value);}
 168   void set(unsigned char  value) { set((uint64_t)value);}
 169   void set(int16_t  value) { set((int64_t)value);}
 170   void set(uint16_t value) { set((uint64_t)value);}
 171   void set(int32_t  value) { set((int64_t)value);}
 172   void set(uint32_t value) { set((uint64_t)value);}
 173   void set(int64_t  value);
 174   void set(uint64_t value);
 175   void set(double value);
 176
 177   Hdf &operator=(const char *value) { set(value); return *this;}
 178   Hdf &operator=(const std::string &value) { set(value); return *this;}
 179   Hdf &operator=(bool   value) { set(value); return *this;}
 180   Hdf &operator=(char   value) { set(value); return *this;}
 181   Hdf &operator=(unsigned char  value) { set(value); return *this;}
 182   Hdf &operator=(int16_t  value) { set(value); return *this;}
 183   Hdf &operator=(uint16_t value) { set(value); return *this;}
 184   Hdf &operator=(int32_t  value) { set(value); return *this;}
 185   Hdf &operator=(uint32_t value) { set(value); return *this;}
 186   Hdf &operator=(int64_t  value) { set(value); return *this;}
 187   Hdf &operator=(uint64_t value) { set(value); return *this;}
 188   Hdf &operator=(double value) { set(value); return *this;}
 189   Hdf &operator=(const Hdf &hdf);
 190
 191   /**
 192    * Get this node's fully qualified path or just one-level node name.
 193    */
 194   std::string getFullPath() const;
 195   std::string getName(bool markVisited = true) const;
 196
 197   /**
 198    * Get this node's parent.
 199    */
 200   const Hdf parent() const;
 201   Hdf parent();
 202
 203   /**
 204    * Get a sub-node.
 205    */
 206   const Hdf operator[](int name) const;
 207   const Hdf operator[](const char *name) const;
 208   const Hdf operator[](const std::string &name) const;
 209   Hdf operator[](int name);
 210   Hdf operator[](const char *name);
 211   Hdf operator[](const std::string &name);
 212
 213   /**
 214    * Note that this is different than getting a boolean value. If "name" is
 215    * present, testing whether a subnode exists. Otherwise, testing myself is
 216    * present or not.
 217    */
 218   bool exists() const;
 219   bool exists(int name) const;
 220   bool exists(const char *name) const;
 221   bool exists(const std::string &name) const;
 222
 223   /**
 224    * Note that this is NOT testing existence, but reading a boolean value.
 225    */
 226   bool operator!() const { return !configGetBool();}
 227
 228   /**
 229    * Removes a sub-node from parent.
 230    */
 231   void remove(int name) const;
 232   void remove(const char *name) const;
 233   void remove(const std::string &name) const;
 234
 235   /**
 236    * Iterations. For example,
 237    *
 238    *   for (Hdf hdf = parent.firstChild(); hdf.exists(); hdf = hdf.next()) {
 239    *   }
 240    *
 241    * Please use "hdf.exists()" for testing than casting it to boolean.
 242    */
 243   Hdf firstChild(bool markVisited = true) const;
 244   Hdf next(bool markVisited = true) const;
 245
 246   /**
 247    * Comparisons
 248    */
 249   int compare(const char *v) const;
 250   int compare(const std::string &v) const;
 251   int compare(char   v) const;
 252   int compare(unsigned char  v) const;
 253   int compare(int16_t  v) const;
 254   int compare(uint16_t v) const;
 255   int compare(int32_t  v) const;
 256   int compare(uint32_t v) const;
 257   int compare(int64_t  v) const;
 258   int compare(uint64_t v) const;
 259   int compare(double v) const;
 260
 261   bool operator==(const char *v) const { return compare(v) == 0;}
 262   bool operator!=(const char *v) const { return compare(v) != 0;}
 263   bool operator>=(const char *v) const { return compare(v) >= 0;}
 264   bool operator<=(const char *v) const { return compare(v) <= 0;}
 265   bool operator> (const char *v) const { return compare(v) >  0;}
 266   bool operator< (const char *v) const { return compare(v) <  0;}
 267
 268   bool operator==(const std::string &v) const { return compare(v) == 0;}
 269   bool operator!=(const std::string &v) const { return compare(v) != 0;}
 270   bool operator>=(const std::string &v) const { return compare(v) >= 0;}
 271   bool operator<=(const std::string &v) const { return compare(v) <= 0;}
 272   bool operator> (const std::string &v) const { return compare(v) >  0;}
 273   bool operator< (const std::string &v) const { return compare(v) <  0;}
 274
 275   bool operator==(char v) const { return compare(v) == 0;}
 276   bool operator!=(char v) const { return compare(v) != 0;}
 277   bool operator>=(char v) const { return compare(v) >= 0;}
 278   bool operator<=(char v) const { return compare(v) <= 0;}
 279   bool operator> (char v) const { return compare(v) >  0;}
 280   bool operator< (char v) const { return compare(v) <  0;}
 281
 282   bool operator==(unsigned char v) const { return compare(v) == 0;}
 283   bool operator!=(unsigned char v) const { return compare(v) != 0;}
 284   bool operator>=(unsigned char v) const { return compare(v) >= 0;}
 285   bool operator<=(unsigned char v) const { return compare(v) <= 0;}
 286   bool operator> (unsigned char v) const { return compare(v) >  0;}
 287   bool operator< (unsigned char v) const { return compare(v) <  0;}
 288
 289   bool operator==(int16_t v) const { return compare(v) == 0;}
 290   bool operator!=(int16_t v) const { return compare(v) != 0;}
 291   bool operator>=(int16_t v) const { return compare(v) >= 0;}
 292   bool operator<=(int16_t v) const { return compare(v) <= 0;}
 293   bool operator> (int16_t v) const { return compare(v) >  0;}
 294   bool operator< (int16_t v) const { return compare(v) <  0;}
 295
 296   bool operator==(uint16_t v) const { return compare(v) == 0;}
 297   bool operator!=(uint16_t v) const { return compare(v) != 0;}
 298   bool operator>=(uint16_t v) const { return compare(v) >= 0;}
 299   bool operator<=(uint16_t v) const { return compare(v) <= 0;}
 300   bool operator> (uint16_t v) const { return compare(v) >  0;}
 301   bool operator< (uint16_t v) const { return compare(v) <  0;}
 302
 303   bool operator==(int32_t v) const { return compare(v) == 0;}
 304   bool operator!=(int32_t v) const { return compare(v) != 0;}
 305   bool operator>=(int32_t v) const { return compare(v) >= 0;}
 306   bool operator<=(int32_t v) const { return compare(v) <= 0;}
 307   bool operator> (int32_t v) const { return compare(v) >  0;}
 308   bool operator< (int32_t v) const { return compare(v) <  0;}
 309
 310   bool operator==(uint32_t v) const { return compare(v) == 0;}
 311   bool operator!=(uint32_t v) const { return compare(v) != 0;}
 312   bool operator>=(uint32_t v) const { return compare(v) >= 0;}
 313   bool operator<=(uint32_t v) const { return compare(v) <= 0;}
 314   bool operator> (uint32_t v) const { return compare(v) >  0;}
 315   bool operator< (uint32_t v) const { return compare(v) <  0;}
 316
 317   bool operator==(int64_t v) const { return compare(v) == 0;}
 318   bool operator!=(int64_t v) const { return compare(v) != 0;}
 319   bool operator>=(int64_t v) const { return compare(v) >= 0;}
 320   bool operator<=(int64_t v) const { return compare(v) <= 0;}
 321   bool operator> (int64_t v) const { return compare(v) >  0;}
 322   bool operator< (int64_t v) const { return compare(v) <  0;}
 323
 324   bool operator==(uint64_t v) const { return compare(v) == 0;}
 325   bool operator!=(uint64_t v) const { return compare(v) != 0;}
 326   bool operator>=(uint64_t v) const { return compare(v) >= 0;}
 327   bool operator<=(uint64_t v) const { return compare(v) <= 0;}
 328   bool operator> (uint64_t v) const { return compare(v) >  0;}
 329   bool operator< (uint64_t v) const { return compare(v) <  0;}
 330
 331   bool operator==(double v) const { return compare(v) == 0;}
 332   bool operator!=(double v) const { return compare(v) != 0;}
 333   bool operator>=(double v) const { return compare(v) >= 0;}
 334   bool operator<=(double v) const { return compare(v) <= 0;}
 335   bool operator> (double v) const { return compare(v) >  0;}
 336   bool operator< (double v) const { return compare(v) <  0;}
 337
 338   /**
 339    * Throw if there is an error from ClearSilver library.
 340    */
 341   static void CheckNeoError(NEOERR *err);
 342
 343 private:
 344   mutable HDF  *m_hdf ; // cached HDF pointer
 345   HdfRaw       *m_rawp; // raw pointer
 346   std::string   m_path; // parent path
 347   std::string   m_name; // my name
 348   mutable char *m_dump; // entire tree dump in HDF format
 349
 350   /**
 351    * There are only two different "modes" of an Hdf object: hdf_ being null or
 352    * non-null. First case is when we proactively constructed an Hdf object by
 353    * either opening a file or starting from scratch by calling Hdf(). Second
 354    * case is when we attach a raw HDF*, almost exclusively used by iterations.
 355    */
 356   HDF *getRaw() const;
 357
 358   /**
 359    * Parse value as a signed integer and check to make sure it's within
 360    * [-maxValue-1, maxValue]. If not, throw an HdfDataTypeException
 361    * with specified type string. If node is absent, return default value.
 362    */
 363   int64_t getInt(int64_t defValue, const char *type, int64_t maxValue) const;
 364
 365   /**
 366    * Parse value as a unsigned integer and check against mask to make sure
 367    * it's in the specified range. If not, throw an HdfDataTypeException
 368    * with specified type string. If node is absent, return default value.
 369    */
 370   uint64_t getUInt(uint64_t defValue, const char *type, uint64_t mask) const;
 371
 372   /**
 373    * Implementation of parent() calls.
 374    */
 375   Hdf parentImpl() const;
 376
 377   bool lintImpl(std::vector<std::string> &names,
 378                 const std::vector<std::string> &excludes, bool visited);
 379 };
 380
 381 /**
 382  * Base class of all exceptions Hdf class might throw.
 383  */
 384 struct HdfException : Exception {
 385   HdfException(ATTRIBUTE_PRINTF_STRING const char *fmt, ...)
 386     ATTRIBUTE_PRINTF(2,3);
 387   EXCEPTION_COMMON_IMPL(HdfException);
 388 };
 389
 390 /**
 391  * Trying to get a node's value, but it's not in the specified type.
 392  */
 393 struct HdfDataTypeException : HdfException {
 394   HdfDataTypeException(const Hdf *hdf, const char *type, const char *value)
 395     : HdfException("HDF node [%s]'s value \"%s\" is not %s",
 396                    hdf->getFullPath().c_str(), value, type) {
 397   }
 398   EXCEPTION_COMMON_IMPL(HdfDataTypeException);
 399 };
 400
 401 /**
 402  * A node's value is not expected.
 403  */
 404 struct HdfDataValueException : HdfException {
 405   explicit HdfDataValueException(const Hdf *hdf, const char *expected = "")
 406     : HdfException("HDF node [%s]'s value \"%s\" is not expected %s",
 407                    hdf->getFullPath().c_str(), hdf->configGet(""), expected) {
 408   }
 409   EXCEPTION_COMMON_IMPL(HdfDataValueException);
 410 };
 411
 412 /**
 413  * Calling a function in wrong context.
 414  */
 415 struct HdfInvalidOperation : HdfException {
 416   explicit HdfInvalidOperation(const char *operation)
 417     : HdfException("Invalid operation: %s", operation) {
 418   }
 419   EXCEPTION_COMMON_IMPL(HdfInvalidOperation);
 420 };
 421
 422 ///////////////////////////////////////////////////////////////////////////////
 423 }
 424
 425 #endif // incl_HPHP_CONFIG_HDF_H_