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 #pragma once
  18
  19 #include <string>
  20 #include <map>
  21 #include <set>
  22 #include <vector>
  23 #include <unordered_map>
  24
  25 #include <boost/container/flat_set.hpp>
  26
  27 #include "hphp/neo/neo_hdf.h"
  28
  29 #include "hphp/util/exception.h"
  30 #include "hphp/util/functional.h"
  31 #include "hphp/util/hash-map.h"
  32 #include "hphp/util/hash-set.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   void configGet(hphp_fast_string_map<std::string> &values) const;
 154   void configGet(hphp_fast_string_imap<std::string> &values) const;
 155   void configGet(hphp_fast_string_set& values) const;
 156
 157   /**
 158    * Helper function to convert a config string value to bool.
 159    */
 160
 161   static bool convertRawConfigToBool(const char *v);
 162
 163
 164   /**
 165    * Set this node's value.
 166    */
 167   void set(const char *value);
 168   void set(const std::string &value) { set(value.c_str());}
 169   void set(bool   value) { set(value ? "1" : "0");}
 170   void set(char   value) { set((int64_t)value);}
 171   void set(unsigned char  value) { set((uint64_t)value);}
 172   void set(int16_t  value) { set((int64_t)value);}
 173   void set(uint16_t value) { set((uint64_t)value);}
 174   void set(int32_t  value) { set((int64_t)value);}
 175   void set(uint32_t value) { set((uint64_t)value);}
 176   void set(int64_t  value);
 177   void set(uint64_t value);
 178   void set(double value);
 179
 180   Hdf &operator=(const char *value) { set(value); return *this;}
 181   Hdf &operator=(const std::string &value) { set(value); return *this;}
 182   Hdf &operator=(bool   value) { set(value); return *this;}
 183   Hdf &operator=(char   value) { set(value); return *this;}
 184   Hdf &operator=(unsigned char  value) { set(value); return *this;}
 185   Hdf &operator=(int16_t  value) { set(value); return *this;}
 186   Hdf &operator=(uint16_t value) { set(value); return *this;}
 187   Hdf &operator=(int32_t  value) { set(value); return *this;}
 188   Hdf &operator=(uint32_t value) { set(value); return *this;}
 189   Hdf &operator=(int64_t  value) { set(value); return *this;}
 190   Hdf &operator=(uint64_t value) { set(value); return *this;}
 191   Hdf &operator=(double value) { set(value); return *this;}
 192   Hdf &operator=(const Hdf &hdf);
 193
 194   /**
 195    * Get this node's fully qualified path or just one-level node name.
 196    */
 197   std::string getFullPath() const;
 198   std::string getName(bool markVisited = true) const;
 199
 200   /**
 201    * Get this node's parent.
 202    */
 203   const Hdf parent() const;
 204   Hdf parent();
 205
 206   /**
 207    * Get a sub-node.
 208    */
 209   const Hdf operator[](int name) const;
 210   const Hdf operator[](const char *name) const;
 211   const Hdf operator[](const std::string &name) const;
 212   Hdf operator[](int name);
 213   Hdf operator[](const char *name);
 214   Hdf operator[](const std::string &name);
 215
 216   /**
 217    * Note that this is different than getting a boolean value. If "name" is
 218    * present, testing whether a subnode exists. Otherwise, testing myself is
 219    * present or not.
 220    */
 221   bool exists() const;
 222   bool exists(int name) const;
 223   bool exists(const char *name) const;
 224   bool exists(const std::string &name) const;
 225
 226   /**
 227    * Note that this is NOT testing existence, but reading a boolean value.
 228    */
 229   bool operator!() const { return !configGetBool();}
 230
 231   /**
 232    * Removes a sub-node from parent.
 233    */
 234   void remove(int name) const;
 235   void remove(const char *name) const;
 236   void remove(const std::string &name) const;
 237
 238   /**
 239    * Iterations. For example,
 240    *
 241    *   for (Hdf hdf = parent.firstChild(); hdf.exists(); hdf = hdf.next()) {
 242    *   }
 243    *
 244    * Please use "hdf.exists()" for testing than casting it to boolean.
 245    */
 246   Hdf firstChild(bool markVisited = true) const;
 247   Hdf next(bool markVisited = true) const;
 248
 249   /**
 250    * Comparisons
 251    */
 252   int compare(const char *v) const;
 253   int compare(const std::string &v) const;
 254   int compare(char   v) const;
 255   int compare(unsigned char  v) const;
 256   int compare(int16_t  v) const;
 257   int compare(uint16_t v) const;
 258   int compare(int32_t  v) const;
 259   int compare(uint32_t v) const;
 260   int compare(int64_t  v) const;
 261   int compare(uint64_t v) const;
 262   int compare(double v) const;
 263
 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   bool operator<=(const char *v) const { return compare(v) <= 0;}
 268   bool operator> (const char *v) const { return compare(v) >  0;}
 269   bool operator< (const char *v) const { return compare(v) <  0;}
 270
 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   bool operator<=(const std::string &v) const { return compare(v) <= 0;}
 275   bool operator> (const std::string &v) const { return compare(v) >  0;}
 276   bool operator< (const std::string &v) const { return compare(v) <  0;}
 277
 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   bool operator<=(char v) const { return compare(v) <= 0;}
 282   bool operator> (char v) const { return compare(v) >  0;}
 283   bool operator< (char v) const { return compare(v) <  0;}
 284
 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   bool operator<=(unsigned char v) const { return compare(v) <= 0;}
 289   bool operator> (unsigned char v) const { return compare(v) >  0;}
 290   bool operator< (unsigned char v) const { return compare(v) <  0;}
 291
 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   bool operator<=(int16_t v) const { return compare(v) <= 0;}
 296   bool operator> (int16_t v) const { return compare(v) >  0;}
 297   bool operator< (int16_t v) const { return compare(v) <  0;}
 298
 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   bool operator<=(uint16_t v) const { return compare(v) <= 0;}
 303   bool operator> (uint16_t v) const { return compare(v) >  0;}
 304   bool operator< (uint16_t v) const { return compare(v) <  0;}
 305
 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   bool operator<=(int32_t v) const { return compare(v) <= 0;}
 310   bool operator> (int32_t v) const { return compare(v) >  0;}
 311   bool operator< (int32_t v) const { return compare(v) <  0;}
 312
 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   bool operator<=(uint32_t v) const { return compare(v) <= 0;}
 317   bool operator> (uint32_t v) const { return compare(v) >  0;}
 318   bool operator< (uint32_t v) const { return compare(v) <  0;}
 319
 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   bool operator<=(int64_t v) const { return compare(v) <= 0;}
 324   bool operator> (int64_t v) const { return compare(v) >  0;}
 325   bool operator< (int64_t v) const { return compare(v) <  0;}
 326
 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   bool operator<=(uint64_t v) const { return compare(v) <= 0;}
 331   bool operator> (uint64_t v) const { return compare(v) >  0;}
 332   bool operator< (uint64_t v) const { return compare(v) <  0;}
 333
 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   bool operator<=(double v) const { return compare(v) <= 0;}
 338   bool operator> (double v) const { return compare(v) >  0;}
 339   bool operator< (double v) const { return compare(v) <  0;}
 340
 341   /**
 342    * Throw if there is an error from ClearSilver library.
 343    */
 344   static void CheckNeoError(NEOERR *err);
 345
 346 private:
 347   mutable HDF  *m_hdf ; // cached HDF pointer
 348   HdfRaw       *m_rawp; // raw pointer
 349   std::string   m_path; // parent path
 350   std::string   m_name; // my name
 351   mutable char *m_dump; // entire tree dump in HDF format
 352
 353   /**
 354    * There are only two different "modes" of an Hdf object: hdf_ being null or
 355    * non-null. First case is when we proactively constructed an Hdf object by
 356    * either opening a file or starting from scratch by calling Hdf(). Second
 357    * case is when we attach a raw HDF*, almost exclusively used by iterations.
 358    */
 359   HDF *getRaw() const;
 360
 361   /**
 362    * Parse value as a signed integer and check to make sure it's within
 363    * [-maxValue-1, maxValue]. If not, throw an HdfDataTypeException
 364    * with specified type string. If node is absent, return default value.
 365    */
 366   int64_t getInt(int64_t defValue, const char *type, int64_t maxValue) const;
 367
 368   /**
 369    * Parse value as a unsigned integer and check against mask to make sure
 370    * it's in the specified range. If not, throw an HdfDataTypeException
 371    * with specified type string. If node is absent, return default value.
 372    */
 373   uint64_t getUInt(uint64_t defValue, const char *type, uint64_t mask) const;
 374
 375   /**
 376    * Implementation of parent() calls.
 377    */
 378   Hdf parentImpl() const;
 379
 380   bool lintImpl(std::vector<std::string> &names,
 381                 const std::vector<std::string> &excludes, bool visited);
 382 };
 383
 384 /**
 385  * Base class of all exceptions Hdf class might throw.
 386  */
 387 struct HdfException : Exception {
 388   HdfException(ATTRIBUTE_PRINTF_STRING const char *fmt, ...)
 389     ATTRIBUTE_PRINTF(2,3);
 390   EXCEPTION_COMMON_IMPL(HdfException);
 391 };
 392
 393 /**
 394  * Trying to get a node's value, but it's not in the specified type.
 395  */
 396 struct HdfDataTypeException : HdfException {
 397   HdfDataTypeException(const Hdf *hdf, const char *type, const char *value)
 398     : HdfException("HDF node [%s]'s value \"%s\" is not %s",
 399                    hdf->getFullPath().c_str(), value, type) {
 400   }
 401   EXCEPTION_COMMON_IMPL(HdfDataTypeException);
 402 };
 403
 404 /**
 405  * A node's value is not expected.
 406  */
 407 struct HdfDataValueException : HdfException {
 408   explicit HdfDataValueException(const Hdf *hdf, const char *expected = "")
 409     : HdfException("HDF node [%s]'s value \"%s\" is not expected %s",
 410                    hdf->getFullPath().c_str(), hdf->configGet(""), expected) {
 411   }
 412   EXCEPTION_COMMON_IMPL(HdfDataValueException);
 413 };
 414
 415 /**
 416  * Calling a function in wrong context.
 417  */
 418 struct HdfInvalidOperation : HdfException {
 419   explicit HdfInvalidOperation(const char *operation)
 420     : HdfException("Invalid operation: %s", operation) {
 421   }
 422   EXCEPTION_COMMON_IMPL(HdfInvalidOperation);
 423 };
 424
 425 ///////////////////////////////////////////////////////////////////////////////
 426 }