extensions/common/value_builder.h

   1 // Copyright 2013 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 // This file provides a builders for DictionaryValue and ListValue.  These
   6 // aren't specific to extensions and could move up to base/ if there's interest
   7 // from other sub-projects.
   8 //
   9 // The general pattern is to write:
  10 //
  11 //  scoped_ptr<BuiltType> result(FooBuilder()
  12 //                               .Set(args)
  13 //                               .Set(args)
  14 //                               .Build());
  15 //
  16 // For methods that take other built types, you can pass the builder directly
  17 // to the setter without calling Build():
  18 //
  19 // DictionaryBuilder().Set("key", ListBuilder()
  20 //                         .Append("foo").Append("bar") /* No .Build() */);
  21 //
  22 // Because of limitations in C++03, and to avoid extra copies, you can't pass a
  23 // just-constructed Builder into another Builder's method directly. Use the
  24 // Pass() method.
  25 //
  26 // The Build() method invalidates its builder, and returns ownership of the
  27 // built value.
  28 //
  29 // These objects are intended to be used as temporaries rather than stored
  30 // anywhere, so the use of non-const reference parameters is likely to cause
  31 // less confusion than usual.
  32
  33 #ifndef EXTENSIONS_COMMON_VALUE_BUILDER_H_
  34 #define EXTENSIONS_COMMON_VALUE_BUILDER_H_
  35
  36 #include <string>
  37
  38 #include "base/memory/scoped_ptr.h"
  39 #include "base/strings/string16.h"
  40 #include "base/values.h"
  41
  42 namespace extensions {
  43
  44 class ListBuilder;
  45
  46 class DictionaryBuilder {
  47  public:
  48   DictionaryBuilder();
  49   explicit DictionaryBuilder(const base::DictionaryValue& init);
  50   ~DictionaryBuilder();
  51
  52   // Workaround to allow you to pass rvalue ExtensionBuilders by reference to
  53   // other functions.
  54   DictionaryBuilder& Pass() { return *this; }
  55
  56   // Can only be called once, after which it's invalid to use the builder.
  57   scoped_ptr<base::DictionaryValue> Build() { return dict_.Pass(); }
  58
  59   // Immediately serializes the current state to JSON. Can be called as many
  60   // times as you like.
  61   std::string ToJSON() const;
  62
  63   DictionaryBuilder& Set(const std::string& path, int in_value);
  64   DictionaryBuilder& Set(const std::string& path, double in_value);
  65   DictionaryBuilder& Set(const std::string& path, const std::string& in_value);
  66   DictionaryBuilder& Set(const std::string& path,
  67                          const base::string16& in_value);
  68   DictionaryBuilder& Set(const std::string& path, DictionaryBuilder& in_value);
  69   DictionaryBuilder& Set(const std::string& path, ListBuilder& in_value);
  70   DictionaryBuilder& Set(const std::string& path,
  71                          scoped_ptr<base::Value> in_value);
  72
  73   // Named differently because overload resolution is too eager to
  74   // convert implicitly to bool.
  75   DictionaryBuilder& SetBoolean(const std::string& path, bool in_value);
  76
  77  private:
  78   scoped_ptr<base::DictionaryValue> dict_;
  79 };
  80
  81 class ListBuilder {
  82  public:
  83   ListBuilder();
  84   explicit ListBuilder(const base::ListValue& init);
  85   ~ListBuilder();
  86
  87   // Workaround to allow you to pass rvalue ExtensionBuilders by reference to
  88   // other functions.
  89   ListBuilder& Pass() { return *this; }
  90
  91   // Can only be called once, after which it's invalid to use the builder.
  92   scoped_ptr<base::ListValue> Build() { return list_.Pass(); }
  93
  94   ListBuilder& Append(int in_value);
  95   ListBuilder& Append(double in_value);
  96   ListBuilder& Append(const std::string& in_value);
  97   ListBuilder& Append(const base::string16& in_value);
  98   ListBuilder& Append(DictionaryBuilder& in_value);
  99   ListBuilder& Append(ListBuilder& in_value);
 100
 101   // Named differently because overload resolution is too eager to
 102   // convert implicitly to bool.
 103   ListBuilder& AppendBoolean(bool in_value);
 104
 105  private:
 106   scoped_ptr<base::ListValue> list_;
 107 };
 108
 109 }  // namespace extensions
 110
 111 #endif  // EXTENSIONS_COMMON_VALUE_BUILDER_H_