1 // Copyright 2012-2014 The Rust Project Developers. See the COPYRIGHT
2 // file at the top-level directory of this distribution and at
3 // http://rust-lang.org/COPYRIGHT.
4 //
5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
8 // option. This file may not be copied, modified, or distributed
9 // except according to those terms.
10 
11 //! JSON Builders
12 //!
13 //! This module provides Builders that simplify constructing complex `Value`s. This can be useful
14 //! when dynamically constructing a `Value`, or when it is inconvenient to write a custom
15 //! `Serialize` implementation or to use `#[derive(Serialize)]`.
16 //!
17 //! # Example
18 //!
19 //! ```rust
20 //! use serde_json::builder::ObjectBuilder;
21 //!
22 //! let value = ObjectBuilder::new()
23 //!     .insert("name", "point")
24 //!     .insert_array("points", |builder| {
25 //!         builder
26 //!             .push_object(|builder| {
27 //!                 builder.insert("x", 1).insert("y", 2)
28 //!             })
29 //!             .push_object(|builder| {
30 //!                 builder.insert("x", 3).insert("y", 4)
31 //!             })
32 //!     })
33 //!     .build();
34 //! ```
35 
36 use serde::ser;
37 
38 use value::{self, Map, Value};
39 
40 /// This structure provides a simple interface for constructing a JSON array.
41 #[derive(Default)]
42 pub struct ArrayBuilder {
43     array: Vec<Value>,
44 }
45 
46 impl ArrayBuilder {
47     /// Construct an `ObjectBuilder`.
new() -> ArrayBuilder48     pub fn new() -> ArrayBuilder {
49         ArrayBuilder::default()
50     }
51 
52     /// Return the constructed `Value`.
build(self) -> Value53     pub fn build(self) -> Value {
54         Value::Array(self.array)
55     }
56 
57     /// Insert a value into the array.
push<T: ser::Serialize>(mut self, v: T) -> ArrayBuilder58     pub fn push<T: ser::Serialize>(mut self, v: T) -> ArrayBuilder {
59         self.array.push(value::to_value(&v));
60         self
61     }
62 
63     /// Creates and passes an `ArrayBuilder` into a closure, then inserts the resulting array into
64     /// this array.
push_array<F>(mut self, f: F) -> ArrayBuilder where F: FnOnce(ArrayBuilder) -> ArrayBuilder,65     pub fn push_array<F>(mut self, f: F) -> ArrayBuilder
66         where F: FnOnce(ArrayBuilder) -> ArrayBuilder,
67     {
68         let builder = ArrayBuilder::new();
69         self.array.push(f(builder).build());
70         self
71     }
72 
73     /// Creates and passes an `ArrayBuilder` into a closure, then inserts the resulting object into
74     /// this array.
push_object<F>(mut self, f: F) -> ArrayBuilder where F: FnOnce(ObjectBuilder) -> ObjectBuilder,75     pub fn push_object<F>(mut self, f: F) -> ArrayBuilder
76         where F: FnOnce(ObjectBuilder) -> ObjectBuilder,
77     {
78         let builder = ObjectBuilder::new();
79         self.array.push(f(builder).build());
80         self
81     }
82 }
83 
84 /// This structure provides a simple interface for constructing a JSON object.
85 #[derive(Default)]
86 pub struct ObjectBuilder {
87     object: Map<String, Value>,
88 }
89 
90 impl ObjectBuilder {
91     /// Construct an `ObjectBuilder`.
new() -> ObjectBuilder92     pub fn new() -> ObjectBuilder {
93         ObjectBuilder::default()
94     }
95 
96     /// Return the constructed `Value`.
build(self) -> Value97     pub fn build(self) -> Value {
98         Value::Object(self.object)
99     }
100 
101     /// Insert a key-value pair into the object.
insert<S, V>(mut self, key: S, value: V) -> ObjectBuilder where S: Into<String>, V: ser::Serialize,102     pub fn insert<S, V>(mut self, key: S, value: V) -> ObjectBuilder
103         where S: Into<String>,
104               V: ser::Serialize,
105     {
106         self.object.insert(key.into(), value::to_value(&value));
107         self
108     }
109 
110     /// Creates and passes an `ObjectBuilder` into a closure, then inserts the resulting array into
111     /// this object.
insert_array<S, F>(mut self, key: S, f: F) -> ObjectBuilder where S: Into<String>, F: FnOnce(ArrayBuilder) -> ArrayBuilder,112     pub fn insert_array<S, F>(mut self, key: S, f: F) -> ObjectBuilder
113         where S: Into<String>,
114               F: FnOnce(ArrayBuilder) -> ArrayBuilder,
115     {
116         let builder = ArrayBuilder::new();
117         self.object.insert(key.into(), f(builder).build());
118         self
119     }
120 
121     /// Creates and passes an `ObjectBuilder` into a closure, then inserts the resulting object into
122     /// this object.
insert_object<S, F>(mut self, key: S, f: F) -> ObjectBuilder where S: Into<String>, F: FnOnce(ObjectBuilder) -> ObjectBuilder,123     pub fn insert_object<S, F>(mut self, key: S, f: F) -> ObjectBuilder
124         where S: Into<String>,
125               F: FnOnce(ObjectBuilder) -> ObjectBuilder,
126     {
127         let builder = ObjectBuilder::new();
128         self.object.insert(key.into(), f(builder).build());
129         self
130     }
131 }
132