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