xpcom/base/nsINIParser.h

   1 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* vim: set ts=8 sts=2 et sw=2 tw=80: */
   3 /* This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
   6
   7 // This file was shamelessly copied from mozilla/xpinstall/wizard/unix/src2
   8
   9 #ifndef nsINIParser_h__
  10 #define nsINIParser_h__
  11
  12 #ifdef MOZILLA_INTERNAL_API
  13 #  define nsINIParser nsINIParser_internal
  14 #endif
  15
  16 #include "nscore.h"
  17 #include "nsClassHashtable.h"
  18 #include "mozilla/UniquePtr.h"
  19
  20 #include <stdio.h>
  21
  22 class nsIFile;
  23
  24 class nsINIParser {
  25  public:
  26   nsINIParser() {}
  27   ~nsINIParser() = default;
  28
  29   /**
  30    * Initialize the INIParser with a nsIFile. If this method fails, no
  31    * other methods should be called. This method reads and parses the file,
  32    * the class does not hold a file handle open. An instance must only be
  33    * initialized once.
  34    */
  35   nsresult Init(nsIFile* aFile);
  36
  37   nsresult InitFromString(const nsCString& aStr);
  38
  39   /**
  40    * Enumerate the sections within the INI file.
  41    *
  42    * The callback takes the section name as an argument, and can can return
  43    * false to stop enumeration.
  44    */
  45   nsresult GetSections(std::function<bool(const char*)>&& aCallback);
  46
  47   /**
  48    * Enumerate the strings within a section. If the section does not exist, this
  49    * function will silently return.
  50    *
  51    * The callback takes the key and value strings as arguments, and can return
  52    * false to stop enumeration.
  53    */
  54   nsresult GetStrings(
  55       const char* aSection,
  56       std::function<bool(const char*, const char*)>&& aCallback);
  57
  58   /**
  59    * Get the value of the specified key in the specified section
  60    * of the INI file represented by this instance.
  61    *
  62    * @param aSection      section name
  63    * @param aKey          key name
  64    * @param aResult       the value found
  65    * @throws NS_ERROR_FAILURE if the specified section/key could not be
  66    *                          found.
  67    */
  68   nsresult GetString(const char* aSection, const char* aKey,
  69                      nsACString& aResult);
  70
  71   /**
  72    * Alternate signature of GetString that uses a pre-allocated buffer
  73    * instead of a nsACString (for use in the standalone glue before
  74    * the glue is initialized).
  75    *
  76    * @throws NS_ERROR_LOSS_OF_SIGNIFICANT_DATA if the aResult buffer is not
  77    *         large enough for the data. aResult will be filled with as
  78    *         much data as possible.
  79    *
  80    * @see GetString [1]
  81    */
  82   nsresult GetString(const char* aSection, const char* aKey, char* aResult,
  83                      uint32_t aResultLen);
  84
  85   /**
  86    * Sets the value of the specified key in the specified section. The section
  87    * is created if it does not already exist.
  88    *
  89    * @oaram aSection      section name
  90    * @param aKey          key name
  91    * @param aValue        the value to set
  92    */
  93   nsresult SetString(const char* aSection, const char* aKey,
  94                      const char* aValue);
  95
  96   /**
  97    * Deletes the value of the specified key in the specified section.
  98    *
  99    * @param aSection      section name
 100    * @param aKey          key name
 101    *
 102    * @throws NS_ERROR_FAILURE if the string was not set.
 103    */
 104   nsresult DeleteString(const char* aSection, const char* aKey);
 105
 106   /**
 107    * Deletes the specified section.
 108    *
 109    * @param aSection      section name
 110    *
 111    * @throws NS_ERROR_FAILURE if the section did not exist.
 112    */
 113   nsresult DeleteSection(const char* aSection);
 114
 115   /**
 116    * Renames the specified section.
 117    *
 118    * @param aSection      section name
 119    * @param aNewName      new section name
 120    *
 121    * @throws NS_ERROR_FAILURE if the section did not exist.
 122    * @throws NS_ERROR_ILLEGAL_VALUE if the new section name already exists.
 123    */
 124   nsresult RenameSection(const char* aSection, const char* aNewName);
 125
 126   /**
 127    * Writes the ini data to disk.
 128    * @param aFile         the file to write to
 129    * @throws NS_ERROR_FAILURE on failure.
 130    */
 131   nsresult WriteToFile(nsIFile* aFile);
 132
 133   void WriteToString(nsACString& aOutput);
 134
 135  private:
 136   struct INIValue {
 137     INIValue(const char* aKey, const char* aValue)
 138         : key(strdup(aKey)), value(strdup(aValue)) {}
 139
 140     ~INIValue() {
 141       delete key;
 142       delete value;
 143     }
 144
 145     void SetValue(const char* aValue) {
 146       delete value;
 147       value = strdup(aValue);
 148     }
 149
 150     const char* key;
 151     const char* value;
 152     mozilla::UniquePtr<INIValue> next;
 153   };
 154
 155   nsClassHashtable<nsCharPtrHashKey, INIValue> mSections;
 156
 157   bool IsValidSection(const char* aSection);
 158   bool IsValidKey(const char* aKey);
 159   bool IsValidValue(const char* aValue);
 160 };
 161
 162 #endif /* nsINIParser_h__ */