src/librustc_serialize/json.rs

   1 // Rust JSON serialization library.
   2 // Copyright (c) 2011 Google Inc.
   3
   4 #![forbid(non_camel_case_types)]
   5 #![allow(missing_docs)]
   6
   7 //! JSON parsing and serialization
   8 //!
   9 //! # What is JSON?
  10 //!
  11 //! JSON (JavaScript Object Notation) is a way to write data in Javascript.
  12 //! Like XML, it allows to encode structured data in a text format that can be easily read by humans
  13 //! Its simple syntax and native compatibility with JavaScript have made it a widely used format.
  14 //!
  15 //! Data types that can be encoded are JavaScript types (see the `Json` enum for more details):
  16 //!
  17 //! * `Boolean`: equivalent to rust's `bool`
  18 //! * `Number`: equivalent to rust's `f64`
  19 //! * `String`: equivalent to rust's `String`
  20 //! * `Array`: equivalent to rust's `Vec<T>`, but also allowing objects of different types in the
  21 //!   same array
  22 //! * `Object`: equivalent to rust's `BTreeMap<String, json::Json>`
  23 //! * `Null`
  24 //!
  25 //! An object is a series of string keys mapping to values, in `"key": value` format.
  26 //! Arrays are enclosed in square brackets ([ ... ]) and objects in curly brackets ({ ... }).
  27 //! A simple JSON document encoding a person, their age, address and phone numbers could look like
  28 //!
  29 //! ```json
  30 //! {
  31 //!     "FirstName": "John",
  32 //!     "LastName": "Doe",
  33 //!     "Age": 43,
  34 //!     "Address": {
  35 //!         "Street": "Downing Street 10",
  36 //!         "City": "London",
  37 //!         "Country": "Great Britain"
  38 //!     },
  39 //!     "PhoneNumbers": [
  40 //!         "+44 1234567",
  41 //!         "+44 2345678"
  42 //!     ]
  43 //! }
  44 //! ```
  45 //!
  46 //! # Rust Type-based Encoding and Decoding
  47 //!
  48 //! Rust provides a mechanism for low boilerplate encoding & decoding of values to and from JSON via
  49 //! the serialization API.
  50 //! To be able to encode a piece of data, it must implement the `serialize::Encodable` trait.
  51 //! To be able to decode a piece of data, it must implement the `serialize::Decodable` trait.
  52 //! The Rust compiler provides an annotation to automatically generate the code for these traits:
  53 //! `#[derive(Decodable, Encodable)]`
  54 //!
  55 //! The JSON API provides an enum `json::Json` and a trait `ToJson` to encode objects.
  56 //! The `ToJson` trait provides a `to_json` method to convert an object into a `json::Json` value.
  57 //! A `json::Json` value can be encoded as a string or buffer using the functions described above.
  58 //! You can also use the `json::Encoder` object, which implements the `Encoder` trait.
  59 //!
  60 //! When using `ToJson` the `Encodable` trait implementation is not mandatory.
  61 //!
  62 //! # Examples of use
  63 //!
  64 //! ## Using Autoserialization
  65 //!
  66 //! Create a struct called `TestStruct` and serialize and deserialize it to and from JSON using the
  67 //! serialization API, using the derived serialization code.
  68 //!
  69 //! ```rust
  70 //! # #![feature(rustc_private)]
  71 //! use rustc_macros::{Decodable, Encodable};
  72 //! use rustc_serialize::json;
  73 //!
  74 //! // Automatically generate `Decodable` and `Encodable` trait implementations
  75 //! #[derive(Decodable, Encodable)]
  76 //! pub struct TestStruct  {
  77 //!     data_int: u8,
  78 //!     data_str: String,
  79 //!     data_vector: Vec<u8>,
  80 //! }
  81 //!
  82 //! let object = TestStruct {
  83 //!     data_int: 1,
  84 //!     data_str: "homura".to_string(),
  85 //!     data_vector: vec![2,3,4,5],
  86 //! };
  87 //!
  88 //! // Serialize using `json::encode`
  89 //! let encoded = json::encode(&object).unwrap();
  90 //!
  91 //! // Deserialize using `json::decode`
  92 //! let decoded: TestStruct = json::decode(&encoded[..]).unwrap();
  93 //! ```
  94 //!
  95 //! ## Using the `ToJson` trait
  96 //!
  97 //! The examples above use the `ToJson` trait to generate the JSON string, which is required
  98 //! for custom mappings.
  99 //!
 100 //! ### Simple example of `ToJson` usage
 101 //!
 102 //! ```rust
 103 //! # #![feature(rustc_private)]
 104 //! use rustc_macros::Encodable;
 105 //! use rustc_serialize::json::{self, ToJson, Json};
 106 //!
 107 //! // A custom data structure
 108 //! struct ComplexNum {
 109 //!     a: f64,
 110 //!     b: f64,
 111 //! }
 112 //!
 113 //! // JSON value representation
 114 //! impl ToJson for ComplexNum {
 115 //!     fn to_json(&self) -> Json {
 116 //!         Json::String(format!("{}+{}i", self.a, self.b))
 117 //!     }
 118 //! }
 119 //!
 120 //! // Only generate `Encodable` trait implementation
 121 //! #[derive(Encodable)]
 122 //! pub struct ComplexNumRecord {
 123 //!     uid: u8,
 124 //!     dsc: String,
 125 //!     val: Json,
 126 //! }
 127 //!
 128 //! let num = ComplexNum { a: 0.0001, b: 12.539 };
 129 //! let data: String = json::encode(&ComplexNumRecord{
 130 //!     uid: 1,
 131 //!     dsc: "test".to_string(),
 132 //!     val: num.to_json(),
 133 //! }).unwrap();
 134 //! println!("data: {}", data);
 135 //! // data: {"uid":1,"dsc":"test","val":"0.0001+12.539i"};
 136 //! ```
 137 //!
 138 //! ### Verbose example of `ToJson` usage
 139 //!
 140 //! ```rust
 141 //! # #![feature(rustc_private)]
 142 //! use rustc_macros::Decodable;
 143 //! use std::collections::BTreeMap;
 144 //! use rustc_serialize::json::{self, Json, ToJson};
 145 //!
 146 //! // Only generate `Decodable` trait implementation
 147 //! #[derive(Decodable)]
 148 //! pub struct TestStruct {
 149 //!     data_int: u8,
 150 //!     data_str: String,
 151 //!     data_vector: Vec<u8>,
 152 //! }
 153 //!
 154 //! // Specify encoding method manually
 155 //! impl ToJson for TestStruct {
 156 //!     fn to_json(&self) -> Json {
 157 //!         let mut d = BTreeMap::new();
 158 //!         // All standard types implement `to_json()`, so use it
 159 //!         d.insert("data_int".to_string(), self.data_int.to_json());
 160 //!         d.insert("data_str".to_string(), self.data_str.to_json());
 161 //!         d.insert("data_vector".to_string(), self.data_vector.to_json());
 162 //!         Json::Object(d)
 163 //!     }
 164 //! }
 165 //!
 166 //! // Serialize using `ToJson`
 167 //! let input_data = TestStruct {
 168 //!     data_int: 1,
 169 //!     data_str: "madoka".to_string(),
 170 //!     data_vector: vec![2,3,4,5],
 171 //! };
 172 //! let json_obj: Json = input_data.to_json();
 173 //! let json_str: String = json_obj.to_string();
 174 //!
 175 //! // Deserialize like before
 176 //! let decoded: TestStruct = json::decode(&json_str).unwrap();
 177 //! ```
 178
 179 use self::DecoderError::*;
 180 use self::ErrorCode::*;
 181 use self::InternalStackElement::*;
 182 use self::JsonEvent::*;
 183 use self::ParserError::*;
 184 use self::ParserState::*;
 185
 186 use std::borrow::Cow;
 187 use std::collections::{BTreeMap, HashMap};
 188 use std::io;
 189 use std::io::prelude::*;
 190 use std::mem::swap;
 191 use std::num::FpCategory as Fp;
 192 use std::ops::Index;
 193 use std::str::FromStr;
 194 use std::string;
 195 use std::{char, fmt, str};
 196
 197 use crate::Encodable;
 198
 199 /// Represents a json value
 200 #[derive(Clone, PartialEq, PartialOrd, Debug)]
 201 pub enum Json {
 202     I64(i64),
 203     U64(u64),
 204     F64(f64),
 205     String(string::String),
 206     Boolean(bool),
 207     Array(self::Array),
 208     Object(self::Object),
 209     Null,
 210 }
 211
 212 pub type Array = Vec<Json>;
 213 pub type Object = BTreeMap<string::String, Json>;
 214
 215 pub struct PrettyJson<'a> {
 216     inner: &'a Json,
 217 }
 218
 219 pub struct AsJson<'a, T> {
 220     inner: &'a T,
 221 }
 222 pub struct AsPrettyJson<'a, T> {
 223     inner: &'a T,
 224     indent: Option<usize>,
 225 }
 226
 227 /// The errors that can arise while parsing a JSON stream.
 228 #[derive(Clone, Copy, PartialEq, Debug)]
 229 pub enum ErrorCode {
 230     InvalidSyntax,
 231     InvalidNumber,
 232     EOFWhileParsingObject,
 233     EOFWhileParsingArray,
 234     EOFWhileParsingValue,
 235     EOFWhileParsingString,
 236     KeyMustBeAString,
 237     ExpectedColon,
 238     TrailingCharacters,
 239     TrailingComma,
 240     InvalidEscape,
 241     InvalidUnicodeCodePoint,
 242     LoneLeadingSurrogateInHexEscape,
 243     UnexpectedEndOfHexEscape,
 244     UnrecognizedHex,
 245     NotFourDigit,
 246     NotUtf8,
 247 }
 248
 249 #[derive(Clone, PartialEq, Debug)]
 250 pub enum ParserError {
 251     /// msg, line, col
 252     SyntaxError(ErrorCode, usize, usize),
 253     IoError(io::ErrorKind, String),
 254 }
 255
 256 // Builder and Parser have the same errors.
 257 pub type BuilderError = ParserError;
 258
 259 #[derive(Clone, PartialEq, Debug)]
 260 pub enum DecoderError {
 261     ParseError(ParserError),
 262     ExpectedError(string::String, string::String),
 263     MissingFieldError(string::String),
 264     UnknownVariantError(string::String),
 265     ApplicationError(string::String),
 266 }
 267
 268 #[derive(Copy, Clone, Debug)]
 269 pub enum EncoderError {
 270     FmtError(fmt::Error),
 271     BadHashmapKey,
 272 }
 273
 274 /// Returns a readable error string for a given error code.
 275 pub fn error_str(error: ErrorCode) -> &'static str {
 276     match error {
 277         InvalidSyntax => "invalid syntax",
 278         InvalidNumber => "invalid number",
 279         EOFWhileParsingObject => "EOF While parsing object",
 280         EOFWhileParsingArray => "EOF While parsing array",
 281         EOFWhileParsingValue => "EOF While parsing value",
 282         EOFWhileParsingString => "EOF While parsing string",
 283         KeyMustBeAString => "key must be a string",
 284         ExpectedColon => "expected `:`",
 285         TrailingCharacters => "trailing characters",
 286         TrailingComma => "trailing comma",
 287         InvalidEscape => "invalid escape",
 288         UnrecognizedHex => "invalid \\u{ esc}ape (unrecognized hex)",
 289         NotFourDigit => "invalid \\u{ esc}ape (not four digits)",
 290         NotUtf8 => "contents not utf-8",
 291         InvalidUnicodeCodePoint => "invalid Unicode code point",
 292         LoneLeadingSurrogateInHexEscape => "lone leading surrogate in hex escape",
 293         UnexpectedEndOfHexEscape => "unexpected end of hex escape",
 294     }
 295 }
 296
 297 /// Shortcut function to decode a JSON `&str` into an object
 298 pub fn decode<T: crate::Decodable<Decoder>>(s: &str) -> DecodeResult<T> {
 299     let json = match from_str(s) {
 300         Ok(x) => x,
 301         Err(e) => return Err(ParseError(e)),
 302     };
 303
 304     let mut decoder = Decoder::new(json);
 305     crate::Decodable::decode(&mut decoder)
 306 }
 307
 308 /// Shortcut function to encode a `T` into a JSON `String`
 309 pub fn encode<T: for<'r> crate::Encodable<Encoder<'r>>>(
 310     object: &T,
 311 ) -> Result<string::String, EncoderError> {
 312     let mut s = String::new();
 313     {
 314         let mut encoder = Encoder::new(&mut s);
 315         object.encode(&mut encoder)?;
 316     }
 317     Ok(s)
 318 }
 319
 320 impl fmt::Display for ErrorCode {
 321     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 322         error_str(*self).fmt(f)
 323     }
 324 }
 325
 326 fn io_error_to_error(io: io::Error) -> ParserError {
 327     IoError(io.kind(), io.to_string())
 328 }
 329
 330 impl fmt::Display for ParserError {
 331     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 332         // FIXME this should be a nicer error
 333         fmt::Debug::fmt(self, f)
 334     }
 335 }
 336
 337 impl fmt::Display for DecoderError {
 338     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 339         // FIXME this should be a nicer error
 340         fmt::Debug::fmt(self, f)
 341     }
 342 }
 343
 344 impl std::error::Error for DecoderError {}
 345
 346 impl fmt::Display for EncoderError {
 347     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 348         // FIXME this should be a nicer error
 349         fmt::Debug::fmt(self, f)
 350     }
 351 }
 352
 353 impl std::error::Error for EncoderError {}
 354
 355 impl From<fmt::Error> for EncoderError {
 356     /// Converts a [`fmt::Error`] into `EncoderError`
 357     ///
 358     /// This conversion does not allocate memory.
 359     fn from(err: fmt::Error) -> EncoderError {
 360         EncoderError::FmtError(err)
 361     }
 362 }
 363
 364 pub type EncodeResult = Result<(), EncoderError>;
 365 pub type DecodeResult<T> = Result<T, DecoderError>;
 366
 367 fn escape_str(wr: &mut dyn fmt::Write, v: &str) -> EncodeResult {
 368     wr.write_str("\"")?;
 369
 370     let mut start = 0;
 371
 372     for (i, byte) in v.bytes().enumerate() {
 373         let escaped = match byte {
 374             b'"' => "\\\"",
 375             b'\\' => "\\\\",
 376             b'\x00' => "\\u0000",
 377             b'\x01' => "\\u0001",
 378             b'\x02' => "\\u0002",
 379             b'\x03' => "\\u0003",
 380             b'\x04' => "\\u0004",
 381             b'\x05' => "\\u0005",
 382             b'\x06' => "\\u0006",
 383             b'\x07' => "\\u0007",
 384             b'\x08' => "\\b",
 385             b'\t' => "\\t",
 386             b'\n' => "\\n",
 387             b'\x0b' => "\\u000b",
 388             b'\x0c' => "\\f",
 389             b'\r' => "\\r",
 390             b'\x0e' => "\\u000e",
 391             b'\x0f' => "\\u000f",
 392             b'\x10' => "\\u0010",
 393             b'\x11' => "\\u0011",
 394             b'\x12' => "\\u0012",
 395             b'\x13' => "\\u0013",
 396             b'\x14' => "\\u0014",
 397             b'\x15' => "\\u0015",
 398             b'\x16' => "\\u0016",
 399             b'\x17' => "\\u0017",
 400             b'\x18' => "\\u0018",
 401             b'\x19' => "\\u0019",
 402             b'\x1a' => "\\u001a",
 403             b'\x1b' => "\\u001b",
 404             b'\x1c' => "\\u001c",
 405             b'\x1d' => "\\u001d",
 406             b'\x1e' => "\\u001e",
 407             b'\x1f' => "\\u001f",
 408             b'\x7f' => "\\u007f",
 409             _ => {
 410                 continue;
 411             }
 412         };
 413
 414         if start < i {
 415             wr.write_str(&v[start..i])?;
 416         }
 417
 418         wr.write_str(escaped)?;
 419
 420         start = i + 1;
 421     }
 422
 423     if start != v.len() {
 424         wr.write_str(&v[start..])?;
 425     }
 426
 427     wr.write_str("\"")?;
 428     Ok(())
 429 }
 430
 431 fn escape_char(writer: &mut dyn fmt::Write, v: char) -> EncodeResult {
 432     escape_str(writer, v.encode_utf8(&mut [0; 4]))
 433 }
 434
 435 fn spaces(wr: &mut dyn fmt::Write, mut n: usize) -> EncodeResult {
 436     const BUF: &str = "                ";
 437
 438     while n >= BUF.len() {
 439         wr.write_str(BUF)?;
 440         n -= BUF.len();
 441     }
 442
 443     if n > 0 {
 444         wr.write_str(&BUF[..n])?;
 445     }
 446     Ok(())
 447 }
 448
 449 fn fmt_number_or_null(v: f64) -> string::String {
 450     match v.classify() {
 451         Fp::Nan | Fp::Infinite => string::String::from("null"),
 452         _ if v.fract() != 0f64 => v.to_string(),
 453         _ => v.to_string() + ".0",
 454     }
 455 }
 456
 457 /// A structure for implementing serialization to JSON.
 458 pub struct Encoder<'a> {
 459     writer: &'a mut (dyn fmt::Write + 'a),
 460     is_emitting_map_key: bool,
 461 }
 462
 463 impl<'a> Encoder<'a> {
 464     /// Creates a new JSON encoder whose output will be written to the writer
 465     /// specified.
 466     pub fn new(writer: &'a mut dyn fmt::Write) -> Encoder<'a> {
 467         Encoder { writer, is_emitting_map_key: false }
 468     }
 469 }
 470
 471 macro_rules! emit_enquoted_if_mapkey {
 472     ($enc:ident,$e:expr) => {{
 473         if $enc.is_emitting_map_key {
 474             write!($enc.writer, "\"{}\"", $e)?;
 475         } else {
 476             write!($enc.writer, "{}", $e)?;
 477         }
 478         Ok(())
 479     }};
 480 }
 481
 482 impl<'a> crate::Encoder for Encoder<'a> {
 483     type Error = EncoderError;
 484
 485     fn emit_unit(&mut self) -> EncodeResult {
 486         if self.is_emitting_map_key {
 487             return Err(EncoderError::BadHashmapKey);
 488         }
 489         write!(self.writer, "null")?;
 490         Ok(())
 491     }
 492
 493     fn emit_usize(&mut self, v: usize) -> EncodeResult {
 494         emit_enquoted_if_mapkey!(self, v)
 495     }
 496     fn emit_u128(&mut self, v: u128) -> EncodeResult {
 497         emit_enquoted_if_mapkey!(self, v)
 498     }
 499     fn emit_u64(&mut self, v: u64) -> EncodeResult {
 500         emit_enquoted_if_mapkey!(self, v)
 501     }
 502     fn emit_u32(&mut self, v: u32) -> EncodeResult {
 503         emit_enquoted_if_mapkey!(self, v)
 504     }
 505     fn emit_u16(&mut self, v: u16) -> EncodeResult {
 506         emit_enquoted_if_mapkey!(self, v)
 507     }
 508     fn emit_u8(&mut self, v: u8) -> EncodeResult {
 509         emit_enquoted_if_mapkey!(self, v)
 510     }
 511
 512     fn emit_isize(&mut self, v: isize) -> EncodeResult {
 513         emit_enquoted_if_mapkey!(self, v)
 514     }
 515     fn emit_i128(&mut self, v: i128) -> EncodeResult {
 516         emit_enquoted_if_mapkey!(self, v)
 517     }
 518     fn emit_i64(&mut self, v: i64) -> EncodeResult {
 519         emit_enquoted_if_mapkey!(self, v)
 520     }
 521     fn emit_i32(&mut self, v: i32) -> EncodeResult {
 522         emit_enquoted_if_mapkey!(self, v)
 523     }
 524     fn emit_i16(&mut self, v: i16) -> EncodeResult {
 525         emit_enquoted_if_mapkey!(self, v)
 526     }
 527     fn emit_i8(&mut self, v: i8) -> EncodeResult {
 528         emit_enquoted_if_mapkey!(self, v)
 529     }
 530
 531     fn emit_bool(&mut self, v: bool) -> EncodeResult {
 532         if self.is_emitting_map_key {
 533             return Err(EncoderError::BadHashmapKey);
 534         }
 535         if v {
 536             write!(self.writer, "true")?;
 537         } else {
 538             write!(self.writer, "false")?;
 539         }
 540         Ok(())
 541     }
 542
 543     fn emit_f64(&mut self, v: f64) -> EncodeResult {
 544         emit_enquoted_if_mapkey!(self, fmt_number_or_null(v))
 545     }
 546     fn emit_f32(&mut self, v: f32) -> EncodeResult {
 547         self.emit_f64(f64::from(v))
 548     }
 549
 550     fn emit_char(&mut self, v: char) -> EncodeResult {
 551         escape_char(self.writer, v)
 552     }
 553     fn emit_str(&mut self, v: &str) -> EncodeResult {
 554         escape_str(self.writer, v)
 555     }
 556
 557     fn emit_enum<F>(&mut self, _name: &str, f: F) -> EncodeResult
 558     where
 559         F: FnOnce(&mut Encoder<'a>) -> EncodeResult,
 560     {
 561         f(self)
 562     }
 563
 564     fn emit_enum_variant<F>(&mut self, name: &str, _id: usize, cnt: usize, f: F) -> EncodeResult
 565     where
 566         F: FnOnce(&mut Encoder<'a>) -> EncodeResult,
 567     {
 568         // enums are encoded as strings or objects
 569         // Bunny => "Bunny"
 570         // Kangaroo(34,"William") => {"variant": "Kangaroo", "fields": [34,"William"]}
 571         if cnt == 0 {
 572             escape_str(self.writer, name)
 573         } else {
 574             if self.is_emitting_map_key {
 575                 return Err(EncoderError::BadHashmapKey);
 576             }
 577             write!(self.writer, "{{\"variant\":")?;
 578             escape_str(self.writer, name)?;
 579             write!(self.writer, ",\"fields\":[")?;
 580             f(self)?;
 581             write!(self.writer, "]}}")?;
 582             Ok(())
 583         }
 584     }
 585
 586     fn emit_enum_variant_arg<F>(&mut self, idx: usize, f: F) -> EncodeResult
 587     where
 588         F: FnOnce(&mut Encoder<'a>) -> EncodeResult,
 589     {
 590         if self.is_emitting_map_key {
 591             return Err(EncoderError::BadHashmapKey);
 592         }
 593         if idx != 0 {
 594             write!(self.writer, ",")?;
 595         }
 596         f(self)
 597     }
 598
 599     fn emit_enum_struct_variant<F>(
 600         &mut self,
 601         name: &str,
 602         id: usize,
 603         cnt: usize,
 604         f: F,
 605     ) -> EncodeResult
 606     where
 607         F: FnOnce(&mut Encoder<'a>) -> EncodeResult,
 608     {
 609         if self.is_emitting_map_key {
 610             return Err(EncoderError::BadHashmapKey);
 611         }
 612         self.emit_enum_variant(name, id, cnt, f)
 613     }
 614
 615     fn emit_enum_struct_variant_field<F>(&mut self, _: &str, idx: usize, f: F) -> EncodeResult
 616     where
 617         F: FnOnce(&mut Encoder<'a>) -> EncodeResult,
 618     {
 619         if self.is_emitting_map_key {
 620             return Err(EncoderError::BadHashmapKey);
 621         }
 622         self.emit_enum_variant_arg(idx, f)
 623     }
 624
 625     fn emit_struct<F>(&mut self, _: &str, _: usize, f: F) -> EncodeResult
 626     where
 627         F: FnOnce(&mut Encoder<'a>) -> EncodeResult,
 628     {
 629         if self.is_emitting_map_key {
 630             return Err(EncoderError::BadHashmapKey);
 631         }
 632         write!(self.writer, "{{")?;
 633         f(self)?;
 634         write!(self.writer, "}}")?;
 635         Ok(())
 636     }
 637
 638     fn emit_struct_field<F>(&mut self, name: &str, idx: usize, f: F) -> EncodeResult
 639     where
 640         F: FnOnce(&mut Encoder<'a>) -> EncodeResult,
 641     {
 642         if self.is_emitting_map_key {
 643             return Err(EncoderError::BadHashmapKey);
 644         }
 645         if idx != 0 {
 646             write!(self.writer, ",")?;
 647         }
 648         escape_str(self.writer, name)?;
 649         write!(self.writer, ":")?;
 650         f(self)
 651     }
 652
 653     fn emit_tuple<F>(&mut self, len: usize, f: F) -> EncodeResult
 654     where
 655         F: FnOnce(&mut Encoder<'a>) -> EncodeResult,
 656     {
 657         if self.is_emitting_map_key {
 658             return Err(EncoderError::BadHashmapKey);
 659         }
 660         self.emit_seq(len, f)
 661     }
 662     fn emit_tuple_arg<F>(&mut self, idx: usize, f: F) -> EncodeResult
 663     where
 664         F: FnOnce(&mut Encoder<'a>) -> EncodeResult,
 665     {
 666         if self.is_emitting_map_key {
 667             return Err(EncoderError::BadHashmapKey);
 668         }
 669         self.emit_seq_elt(idx, f)
 670     }
 671
 672     fn emit_tuple_struct<F>(&mut self, _name: &str, len: usize, f: F) -> EncodeResult
 673     where
 674         F: FnOnce(&mut Encoder<'a>) -> EncodeResult,
 675     {
 676         if self.is_emitting_map_key {
 677             return Err(EncoderError::BadHashmapKey);
 678         }
 679         self.emit_seq(len, f)
 680     }
 681     fn emit_tuple_struct_arg<F>(&mut self, idx: usize, f: F) -> EncodeResult
 682     where
 683         F: FnOnce(&mut Encoder<'a>) -> EncodeResult,
 684     {
 685         if self.is_emitting_map_key {
 686             return Err(EncoderError::BadHashmapKey);
 687         }
 688         self.emit_seq_elt(idx, f)
 689     }
 690
 691     fn emit_option<F>(&mut self, f: F) -> EncodeResult
 692     where
 693         F: FnOnce(&mut Encoder<'a>) -> EncodeResult,
 694     {
 695         if self.is_emitting_map_key {
 696             return Err(EncoderError::BadHashmapKey);
 697         }
 698         f(self)
 699     }
 700     fn emit_option_none(&mut self) -> EncodeResult {
 701         if self.is_emitting_map_key {
 702             return Err(EncoderError::BadHashmapKey);
 703         }
 704         self.emit_unit()
 705     }
 706     fn emit_option_some<F>(&mut self, f: F) -> EncodeResult
 707     where
 708         F: FnOnce(&mut Encoder<'a>) -> EncodeResult,
 709     {
 710         if self.is_emitting_map_key {
 711             return Err(EncoderError::BadHashmapKey);
 712         }
 713         f(self)
 714     }
 715
 716     fn emit_seq<F>(&mut self, _len: usize, f: F) -> EncodeResult
 717     where
 718         F: FnOnce(&mut Encoder<'a>) -> EncodeResult,
 719     {
 720         if self.is_emitting_map_key {
 721             return Err(EncoderError::BadHashmapKey);
 722         }
 723         write!(self.writer, "[")?;
 724         f(self)?;
 725         write!(self.writer, "]")?;
 726         Ok(())
 727     }
 728
 729     fn emit_seq_elt<F>(&mut self, idx: usize, f: F) -> EncodeResult
 730     where
 731         F: FnOnce(&mut Encoder<'a>) -> EncodeResult,
 732     {
 733         if self.is_emitting_map_key {
 734             return Err(EncoderError::BadHashmapKey);
 735         }
 736         if idx != 0 {
 737             write!(self.writer, ",")?;
 738         }
 739         f(self)
 740     }
 741
 742     fn emit_map<F>(&mut self, _len: usize, f: F) -> EncodeResult
 743     where
 744         F: FnOnce(&mut Encoder<'a>) -> EncodeResult,
 745     {
 746         if self.is_emitting_map_key {
 747             return Err(EncoderError::BadHashmapKey);
 748         }
 749         write!(self.writer, "{{")?;
 750         f(self)?;
 751         write!(self.writer, "}}")?;
 752         Ok(())
 753     }
 754
 755     fn emit_map_elt_key<F>(&mut self, idx: usize, f: F) -> EncodeResult
 756     where
 757         F: FnOnce(&mut Encoder<'a>) -> EncodeResult,
 758     {
 759         if self.is_emitting_map_key {
 760             return Err(EncoderError::BadHashmapKey);
 761         }
 762         if idx != 0 {
 763             write!(self.writer, ",")?
 764         }
 765         self.is_emitting_map_key = true;
 766         f(self)?;
 767         self.is_emitting_map_key = false;
 768         Ok(())
 769     }
 770
 771     fn emit_map_elt_val<F>(&mut self, _idx: usize, f: F) -> EncodeResult
 772     where
 773         F: FnOnce(&mut Encoder<'a>) -> EncodeResult,
 774     {
 775         if self.is_emitting_map_key {
 776             return Err(EncoderError::BadHashmapKey);
 777         }
 778         write!(self.writer, ":")?;
 779         f(self)
 780     }
 781 }
 782
 783 /// Another encoder for JSON, but prints out human-readable JSON instead of
 784 /// compact data
 785 pub struct PrettyEncoder<'a> {
 786     writer: &'a mut (dyn fmt::Write + 'a),
 787     curr_indent: usize,
 788     indent: usize,
 789     is_emitting_map_key: bool,
 790 }
 791
 792 impl<'a> PrettyEncoder<'a> {
 793     /// Creates a new encoder whose output will be written to the specified writer
 794     pub fn new(writer: &'a mut dyn fmt::Write) -> PrettyEncoder<'a> {
 795         PrettyEncoder { writer, curr_indent: 0, indent: 2, is_emitting_map_key: false }
 796     }
 797
 798     /// Sets the number of spaces to indent for each level.
 799     /// This is safe to set during encoding.
 800     pub fn set_indent(&mut self, indent: usize) {
 801         // self.indent very well could be 0 so we need to use checked division.
 802         let level = self.curr_indent.checked_div(self.indent).unwrap_or(0);
 803         self.indent = indent;
 804         self.curr_indent = level * self.indent;
 805     }
 806 }
 807
 808 impl<'a> crate::Encoder for PrettyEncoder<'a> {
 809     type Error = EncoderError;
 810
 811     fn emit_unit(&mut self) -> EncodeResult {
 812         if self.is_emitting_map_key {
 813             return Err(EncoderError::BadHashmapKey);
 814         }
 815         write!(self.writer, "null")?;
 816         Ok(())
 817     }
 818
 819     fn emit_usize(&mut self, v: usize) -> EncodeResult {
 820         emit_enquoted_if_mapkey!(self, v)
 821     }
 822     fn emit_u128(&mut self, v: u128) -> EncodeResult {
 823         emit_enquoted_if_mapkey!(self, v)
 824     }
 825     fn emit_u64(&mut self, v: u64) -> EncodeResult {
 826         emit_enquoted_if_mapkey!(self, v)
 827     }
 828     fn emit_u32(&mut self, v: u32) -> EncodeResult {
 829         emit_enquoted_if_mapkey!(self, v)
 830     }
 831     fn emit_u16(&mut self, v: u16) -> EncodeResult {
 832         emit_enquoted_if_mapkey!(self, v)
 833     }
 834     fn emit_u8(&mut self, v: u8) -> EncodeResult {
 835         emit_enquoted_if_mapkey!(self, v)
 836     }
 837
 838     fn emit_isize(&mut self, v: isize) -> EncodeResult {
 839         emit_enquoted_if_mapkey!(self, v)
 840     }
 841     fn emit_i128(&mut self, v: i128) -> EncodeResult {
 842         emit_enquoted_if_mapkey!(self, v)
 843     }
 844     fn emit_i64(&mut self, v: i64) -> EncodeResult {
 845         emit_enquoted_if_mapkey!(self, v)
 846     }
 847     fn emit_i32(&mut self, v: i32) -> EncodeResult {
 848         emit_enquoted_if_mapkey!(self, v)
 849     }
 850     fn emit_i16(&mut self, v: i16) -> EncodeResult {
 851         emit_enquoted_if_mapkey!(self, v)
 852     }
 853     fn emit_i8(&mut self, v: i8) -> EncodeResult {
 854         emit_enquoted_if_mapkey!(self, v)
 855     }
 856
 857     fn emit_bool(&mut self, v: bool) -> EncodeResult {
 858         if self.is_emitting_map_key {
 859             return Err(EncoderError::BadHashmapKey);
 860         }
 861         if v {
 862             write!(self.writer, "true")?;
 863         } else {
 864             write!(self.writer, "false")?;
 865         }
 866         Ok(())
 867     }
 868
 869     fn emit_f64(&mut self, v: f64) -> EncodeResult {
 870         emit_enquoted_if_mapkey!(self, fmt_number_or_null(v))
 871     }
 872     fn emit_f32(&mut self, v: f32) -> EncodeResult {
 873         self.emit_f64(f64::from(v))
 874     }
 875
 876     fn emit_char(&mut self, v: char) -> EncodeResult {
 877         escape_char(self.writer, v)
 878     }
 879     fn emit_str(&mut self, v: &str) -> EncodeResult {
 880         escape_str(self.writer, v)
 881     }
 882
 883     fn emit_enum<F>(&mut self, _name: &str, f: F) -> EncodeResult
 884     where
 885         F: FnOnce(&mut PrettyEncoder<'a>) -> EncodeResult,
 886     {
 887         f(self)
 888     }
 889
 890     fn emit_enum_variant<F>(&mut self, name: &str, _id: usize, cnt: usize, f: F) -> EncodeResult
 891     where
 892         F: FnOnce(&mut PrettyEncoder<'a>) -> EncodeResult,
 893     {
 894         if cnt == 0 {
 895             escape_str(self.writer, name)
 896         } else {
 897             if self.is_emitting_map_key {
 898                 return Err(EncoderError::BadHashmapKey);
 899             }
 900             writeln!(self.writer, "{{")?;
 901             self.curr_indent += self.indent;
 902             spaces(self.writer, self.curr_indent)?;
 903             write!(self.writer, "\"variant\": ")?;
 904             escape_str(self.writer, name)?;
 905             writeln!(self.writer, ",")?;
 906             spaces(self.writer, self.curr_indent)?;
 907             writeln!(self.writer, "\"fields\": [")?;
 908             self.curr_indent += self.indent;
 909             f(self)?;
 910             self.curr_indent -= self.indent;
 911             writeln!(self.writer)?;
 912             spaces(self.writer, self.curr_indent)?;
 913             self.curr_indent -= self.indent;
 914             writeln!(self.writer, "]")?;
 915             spaces(self.writer, self.curr_indent)?;
 916             write!(self.writer, "}}")?;
 917             Ok(())
 918         }
 919     }
 920
 921     fn emit_enum_variant_arg<F>(&mut self, idx: usize, f: F) -> EncodeResult
 922     where
 923         F: FnOnce(&mut PrettyEncoder<'a>) -> EncodeResult,
 924     {
 925         if self.is_emitting_map_key {
 926             return Err(EncoderError::BadHashmapKey);
 927         }
 928         if idx != 0 {
 929             writeln!(self.writer, ",")?;
 930         }
 931         spaces(self.writer, self.curr_indent)?;
 932         f(self)
 933     }
 934
 935     fn emit_enum_struct_variant<F>(
 936         &mut self,
 937         name: &str,
 938         id: usize,
 939         cnt: usize,
 940         f: F,
 941     ) -> EncodeResult
 942     where
 943         F: FnOnce(&mut PrettyEncoder<'a>) -> EncodeResult,
 944     {
 945         if self.is_emitting_map_key {
 946             return Err(EncoderError::BadHashmapKey);
 947         }
 948         self.emit_enum_variant(name, id, cnt, f)
 949     }
 950
 951     fn emit_enum_struct_variant_field<F>(&mut self, _: &str, idx: usize, f: F) -> EncodeResult
 952     where
 953         F: FnOnce(&mut PrettyEncoder<'a>) -> EncodeResult,
 954     {
 955         if self.is_emitting_map_key {
 956             return Err(EncoderError::BadHashmapKey);
 957         }
 958         self.emit_enum_variant_arg(idx, f)
 959     }
 960
 961     fn emit_struct<F>(&mut self, _: &str, len: usize, f: F) -> EncodeResult
 962     where
 963         F: FnOnce(&mut PrettyEncoder<'a>) -> EncodeResult,
 964     {
 965         if self.is_emitting_map_key {
 966             return Err(EncoderError::BadHashmapKey);
 967         }
 968         if len == 0 {
 969             write!(self.writer, "{{}}")?;
 970         } else {
 971             write!(self.writer, "{{")?;
 972             self.curr_indent += self.indent;
 973             f(self)?;
 974             self.curr_indent -= self.indent;
 975             writeln!(self.writer)?;
 976             spaces(self.writer, self.curr_indent)?;
 977             write!(self.writer, "}}")?;
 978         }
 979         Ok(())
 980     }
 981
 982     fn emit_struct_field<F>(&mut self, name: &str, idx: usize, f: F) -> EncodeResult
 983     where
 984         F: FnOnce(&mut PrettyEncoder<'a>) -> EncodeResult,
 985     {
 986         if self.is_emitting_map_key {
 987             return Err(EncoderError::BadHashmapKey);
 988         }
 989         if idx == 0 {
 990             writeln!(self.writer)?;
 991         } else {
 992             writeln!(self.writer, ",")?;
 993         }
 994         spaces(self.writer, self.curr_indent)?;
 995         escape_str(self.writer, name)?;
 996         write!(self.writer, ": ")?;
 997         f(self)
 998     }
 999
1000     fn emit_tuple<F>(&mut self, len: usize, f: F) -> EncodeResult
1001     where
1002         F: FnOnce(&mut PrettyEncoder<'a>) -> EncodeResult,
1003     {
1004         if self.is_emitting_map_key {
1005             return Err(EncoderError::BadHashmapKey);
1006         }
1007         self.emit_seq(len, f)
1008     }
1009     fn emit_tuple_arg<F>(&mut self, idx: usize, f: F) -> EncodeResult
1010     where
1011         F: FnOnce(&mut PrettyEncoder<'a>) -> EncodeResult,
1012     {
1013         if self.is_emitting_map_key {
1014             return Err(EncoderError::BadHashmapKey);
1015         }
1016         self.emit_seq_elt(idx, f)
1017     }
1018
1019     fn emit_tuple_struct<F>(&mut self, _: &str, len: usize, f: F) -> EncodeResult
1020     where
1021         F: FnOnce(&mut PrettyEncoder<'a>) -> EncodeResult,
1022     {
1023         if self.is_emitting_map_key {
1024             return Err(EncoderError::BadHashmapKey);
1025         }
1026         self.emit_seq(len, f)
1027     }
1028     fn emit_tuple_struct_arg<F>(&mut self, idx: usize, f: F) -> EncodeResult
1029     where
1030         F: FnOnce(&mut PrettyEncoder<'a>) -> EncodeResult,
1031     {
1032         if self.is_emitting_map_key {
1033             return Err(EncoderError::BadHashmapKey);
1034         }
1035         self.emit_seq_elt(idx, f)
1036     }
1037
1038     fn emit_option<F>(&mut self, f: F) -> EncodeResult
1039     where
1040         F: FnOnce(&mut PrettyEncoder<'a>) -> EncodeResult,
1041     {
1042         if self.is_emitting_map_key {
1043             return Err(EncoderError::BadHashmapKey);
1044         }
1045         f(self)
1046     }
1047     fn emit_option_none(&mut self) -> EncodeResult {
1048         if self.is_emitting_map_key {
1049             return Err(EncoderError::BadHashmapKey);
1050         }
1051         self.emit_unit()
1052     }
1053     fn emit_option_some<F>(&mut self, f: F) -> EncodeResult
1054     where
1055         F: FnOnce(&mut PrettyEncoder<'a>) -> EncodeResult,
1056     {
1057         if self.is_emitting_map_key {
1058             return Err(EncoderError::BadHashmapKey);
1059         }
1060         f(self)
1061     }
1062
1063     fn emit_seq<F>(&mut self, len: usize, f: F) -> EncodeResult
1064     where
1065         F: FnOnce(&mut PrettyEncoder<'a>) -> EncodeResult,
1066     {
1067         if self.is_emitting_map_key {
1068             return Err(EncoderError::BadHashmapKey);
1069         }
1070         if len == 0 {
1071             write!(self.writer, "[]")?;
1072         } else {
1073             write!(self.writer, "[")?;
1074             self.curr_indent += self.indent;
1075             f(self)?;
1076             self.curr_indent -= self.indent;
1077             writeln!(self.writer)?;
1078             spaces(self.writer, self.curr_indent)?;
1079             write!(self.writer, "]")?;
1080         }
1081         Ok(())
1082     }
1083
1084     fn emit_seq_elt<F>(&mut self, idx: usize, f: F) -> EncodeResult
1085     where
1086         F: FnOnce(&mut PrettyEncoder<'a>) -> EncodeResult,
1087     {
1088         if self.is_emitting_map_key {
1089             return Err(EncoderError::BadHashmapKey);
1090         }
1091         if idx == 0 {
1092             writeln!(self.writer)?;
1093         } else {
1094             writeln!(self.writer, ",")?;
1095         }
1096         spaces(self.writer, self.curr_indent)?;
1097         f(self)
1098     }
1099
1100     fn emit_map<F>(&mut self, len: usize, f: F) -> EncodeResult
1101     where
1102         F: FnOnce(&mut PrettyEncoder<'a>) -> EncodeResult,
1103     {
1104         if self.is_emitting_map_key {
1105             return Err(EncoderError::BadHashmapKey);
1106         }
1107         if len == 0 {
1108             write!(self.writer, "{{}}")?;
1109         } else {
1110             write!(self.writer, "{{")?;
1111             self.curr_indent += self.indent;
1112             f(self)?;
1113             self.curr_indent -= self.indent;
1114             writeln!(self.writer)?;
1115             spaces(self.writer, self.curr_indent)?;
1116             write!(self.writer, "}}")?;
1117         }
1118         Ok(())
1119     }
1120
1121     fn emit_map_elt_key<F>(&mut self, idx: usize, f: F) -> EncodeResult
1122     where
1123         F: FnOnce(&mut PrettyEncoder<'a>) -> EncodeResult,
1124     {
1125         if self.is_emitting_map_key {
1126             return Err(EncoderError::BadHashmapKey);
1127         }
1128         if idx == 0 {
1129             writeln!(self.writer)?;
1130         } else {
1131             writeln!(self.writer, ",")?;
1132         }
1133         spaces(self.writer, self.curr_indent)?;
1134         self.is_emitting_map_key = true;
1135         f(self)?;
1136         self.is_emitting_map_key = false;
1137         Ok(())
1138     }
1139
1140     fn emit_map_elt_val<F>(&mut self, _idx: usize, f: F) -> EncodeResult
1141     where
1142         F: FnOnce(&mut PrettyEncoder<'a>) -> EncodeResult,
1143     {
1144         if self.is_emitting_map_key {
1145             return Err(EncoderError::BadHashmapKey);
1146         }
1147         write!(self.writer, ": ")?;
1148         f(self)
1149     }
1150 }
1151
1152 impl<E: crate::Encoder> Encodable<E> for Json {
1153     fn encode(&self, e: &mut E) -> Result<(), E::Error> {
1154         match *self {
1155             Json::I64(v) => v.encode(e),
1156             Json::U64(v) => v.encode(e),
1157             Json::F64(v) => v.encode(e),
1158             Json::String(ref v) => v.encode(e),
1159             Json::Boolean(v) => v.encode(e),
1160             Json::Array(ref v) => v.encode(e),
1161             Json::Object(ref v) => v.encode(e),
1162             Json::Null => e.emit_unit(),
1163         }
1164     }
1165 }
1166
1167 /// Creates an `AsJson` wrapper which can be used to print a value as JSON
1168 /// on-the-fly via `write!`
1169 pub fn as_json<T>(t: &T) -> AsJson<'_, T> {
1170     AsJson { inner: t }
1171 }
1172
1173 /// Creates an `AsPrettyJson` wrapper which can be used to print a value as JSON
1174 /// on-the-fly via `write!`
1175 pub fn as_pretty_json<T>(t: &T) -> AsPrettyJson<'_, T> {
1176     AsPrettyJson { inner: t, indent: None }
1177 }
1178
1179 impl Json {
1180     /// Borrow this json object as a pretty object to generate a pretty
1181     /// representation for it via `Display`.
1182     pub fn pretty(&self) -> PrettyJson<'_> {
1183         PrettyJson { inner: self }
1184     }
1185
1186     /// If the Json value is an Object, returns the value associated with the provided key.
1187     /// Otherwise, returns None.
1188     pub fn find(&self, key: &str) -> Option<&Json> {
1189         match *self {
1190             Json::Object(ref map) => map.get(key),
1191             _ => None,
1192         }
1193     }
1194
1195     /// Attempts to get a nested Json Object for each key in `keys`.
1196     /// If any key is found not to exist, `find_path` will return `None`.
1197     /// Otherwise, it will return the Json value associated with the final key.
1198     pub fn find_path<'a>(&'a self, keys: &[&str]) -> Option<&'a Json> {
1199         let mut target = self;
1200         for key in keys {
1201             target = target.find(*key)?;
1202         }
1203         Some(target)
1204     }
1205
1206     /// If the Json value is an Object, performs a depth-first search until
1207     /// a value associated with the provided key is found. If no value is found
1208     /// or the Json value is not an Object, returns `None`.
1209     pub fn search(&self, key: &str) -> Option<&Json> {
1210         match *self {
1211             Json::Object(ref map) => match map.get(key) {
1212                 Some(json_value) => Some(json_value),
1213                 None => {
1214                     for v in map.values() {
1215                         match v.search(key) {
1216                             x if x.is_some() => return x,
1217                             _ => (),
1218                         }
1219                     }
1220                     None
1221                 }
1222             },
1223             _ => None,
1224         }
1225     }
1226
1227     /// Returns `true` if the Json value is an `Object`.
1228     pub fn is_object(&self) -> bool {
1229         self.as_object().is_some()
1230     }
1231
1232     /// If the Json value is an `Object`, returns the associated `BTreeMap`;
1233     /// returns `None` otherwise.
1234     pub fn as_object(&self) -> Option<&Object> {
1235         match *self {
1236             Json::Object(ref map) => Some(map),
1237             _ => None,
1238         }
1239     }
1240
1241     /// Returns `true` if the Json value is an `Array`.
1242     pub fn is_array(&self) -> bool {
1243         self.as_array().is_some()
1244     }
1245
1246     /// If the Json value is an `Array`, returns the associated vector;
1247     /// returns `None` otherwise.
1248     pub fn as_array(&self) -> Option<&Array> {
1249         match *self {
1250             Json::Array(ref array) => Some(&*array),
1251             _ => None,
1252         }
1253     }
1254
1255     /// Returns `true` if the Json value is a `String`.
1256     pub fn is_string(&self) -> bool {
1257         self.as_string().is_some()
1258     }
1259
1260     /// If the Json value is a `String`, returns the associated `str`;
1261     /// returns `None` otherwise.
1262     pub fn as_string(&self) -> Option<&str> {
1263         match *self {
1264             Json::String(ref s) => Some(&s[..]),
1265             _ => None,
1266         }
1267     }
1268
1269     /// Returns `true` if the Json value is a `Number`.
1270     pub fn is_number(&self) -> bool {
1271         matches!(*self, Json::I64(_) | Json::U64(_) | Json::F64(_))
1272     }
1273
1274     /// Returns `true` if the Json value is a `i64`.
1275     pub fn is_i64(&self) -> bool {
1276         matches!(*self, Json::I64(_))
1277     }
1278
1279     /// Returns `true` if the Json value is a `u64`.
1280     pub fn is_u64(&self) -> bool {
1281         matches!(*self, Json::U64(_))
1282     }
1283
1284     /// Returns `true` if the Json value is a `f64`.
1285     pub fn is_f64(&self) -> bool {
1286         matches!(*self, Json::F64(_))
1287     }
1288
1289     /// If the Json value is a number, returns or cast it to a `i64`;
1290     /// returns `None` otherwise.
1291     pub fn as_i64(&self) -> Option<i64> {
1292         match *self {
1293             Json::I64(n) => Some(n),
1294             Json::U64(n) => Some(n as i64),
1295             _ => None,
1296         }
1297     }
1298
1299     /// If the Json value is a number, returns or cast it to a `u64`;
1300     /// returns `None` otherwise.
1301     pub fn as_u64(&self) -> Option<u64> {
1302         match *self {
1303             Json::I64(n) => Some(n as u64),
1304             Json::U64(n) => Some(n),
1305             _ => None,
1306         }
1307     }
1308
1309     /// If the Json value is a number, returns or cast it to a `f64`;
1310     /// returns `None` otherwise.
1311     pub fn as_f64(&self) -> Option<f64> {
1312         match *self {
1313             Json::I64(n) => Some(n as f64),
1314             Json::U64(n) => Some(n as f64),
1315             Json::F64(n) => Some(n),
1316             _ => None,
1317         }
1318     }
1319
1320     /// Returns `true` if the Json value is a `Boolean`.
1321     pub fn is_boolean(&self) -> bool {
1322         self.as_boolean().is_some()
1323     }
1324
1325     /// If the Json value is a `Boolean`, returns the associated `bool`;
1326     /// returns `None` otherwise.
1327     pub fn as_boolean(&self) -> Option<bool> {
1328         match *self {
1329             Json::Boolean(b) => Some(b),
1330             _ => None,
1331         }
1332     }
1333
1334     /// Returns `true` if the Json value is a `Null`.
1335     pub fn is_null(&self) -> bool {
1336         self.as_null().is_some()
1337     }
1338
1339     /// If the Json value is a `Null`, returns `()`;
1340     /// returns `None` otherwise.
1341     pub fn as_null(&self) -> Option<()> {
1342         match *self {
1343             Json::Null => Some(()),
1344             _ => None,
1345         }
1346     }
1347 }
1348
1349 impl<'a> Index<&'a str> for Json {
1350     type Output = Json;
1351
1352     fn index(&self, idx: &'a str) -> &Json {
1353         self.find(idx).unwrap()
1354     }
1355 }
1356
1357 impl Index<usize> for Json {
1358     type Output = Json;
1359
1360     fn index(&self, idx: usize) -> &Json {
1361         match *self {
1362             Json::Array(ref v) => &v[idx],
1363             _ => panic!("can only index Json with usize if it is an array"),
1364         }
1365     }
1366 }
1367
1368 /// The output of the streaming parser.
1369 #[derive(PartialEq, Clone, Debug)]
1370 pub enum JsonEvent {
1371     ObjectStart,
1372     ObjectEnd,
1373     ArrayStart,
1374     ArrayEnd,
1375     BooleanValue(bool),
1376     I64Value(i64),
1377     U64Value(u64),
1378     F64Value(f64),
1379     StringValue(string::String),
1380     NullValue,
1381     Error(ParserError),
1382 }
1383
1384 #[derive(PartialEq, Debug)]
1385 enum ParserState {
1386     // Parse a value in an array, true means first element.
1387     ParseArray(bool),
1388     // Parse ',' or ']' after an element in an array.
1389     ParseArrayComma,
1390     // Parse a key:value in an object, true means first element.
1391     ParseObject(bool),
1392     // Parse ',' or ']' after an element in an object.
1393     ParseObjectComma,
1394     // Initial state.
1395     ParseStart,
1396     // Expecting the stream to end.
1397     ParseBeforeFinish,
1398     // Parsing can't continue.
1399     ParseFinished,
1400 }
1401
1402 /// A Stack represents the current position of the parser in the logical
1403 /// structure of the JSON stream.
1404 ///
1405 /// An example is `foo.bar[3].x`.
1406 #[derive(Default)]
1407 pub struct Stack {
1408     stack: Vec<InternalStackElement>,
1409     str_buffer: Vec<u8>,
1410 }
1411
1412 /// StackElements compose a Stack.
1413 ///
1414 /// As an example, `StackElement::Key("foo")`, `StackElement::Key("bar")`,
1415 /// `StackElement::Index(3)`, and `StackElement::Key("x")` are the
1416 /// StackElements composing the stack that represents `foo.bar[3].x`.
1417 #[derive(PartialEq, Clone, Debug)]
1418 pub enum StackElement<'l> {
1419     Index(u32),
1420     Key(&'l str),
1421 }
1422
1423 // Internally, Key elements are stored as indices in a buffer to avoid
1424 // allocating a string for every member of an object.
1425 #[derive(PartialEq, Clone, Debug)]
1426 enum InternalStackElement {
1427     InternalIndex(u32),
1428     InternalKey(u16, u16), // start, size
1429 }
1430
1431 impl Stack {
1432     pub fn new() -> Stack {
1433         Self::default()
1434     }
1435
1436     /// Returns The number of elements in the Stack.
1437     pub fn len(&self) -> usize {
1438         self.stack.len()
1439     }
1440
1441     /// Returns `true` if the stack is empty.
1442     pub fn is_empty(&self) -> bool {
1443         self.stack.is_empty()
1444     }
1445
1446     /// Provides access to the StackElement at a given index.
1447     /// lower indices are at the bottom of the stack while higher indices are
1448     /// at the top.
1449     pub fn get(&self, idx: usize) -> StackElement<'_> {
1450         match self.stack[idx] {
1451             InternalIndex(i) => StackElement::Index(i),
1452             InternalKey(start, size) => StackElement::Key(
1453                 str::from_utf8(&self.str_buffer[start as usize..start as usize + size as usize])
1454                     .unwrap(),
1455             ),
1456         }
1457     }
1458
1459     /// Compares this stack with an array of StackElement<'_>s.
1460     pub fn is_equal_to(&self, rhs: &[StackElement<'_>]) -> bool {
1461         if self.stack.len() != rhs.len() {
1462             return false;
1463         }
1464         for (i, r) in rhs.iter().enumerate() {
1465             if self.get(i) != *r {
1466                 return false;
1467             }
1468         }
1469         true
1470     }
1471
1472     /// Returns `true` if the bottom-most elements of this stack are the same as
1473     /// the ones passed as parameter.
1474     pub fn starts_with(&self, rhs: &[StackElement<'_>]) -> bool {
1475         if self.stack.len() < rhs.len() {
1476             return false;
1477         }
1478         for (i, r) in rhs.iter().enumerate() {
1479             if self.get(i) != *r {
1480                 return false;
1481             }
1482         }
1483         true
1484     }
1485
1486     /// Returns `true` if the top-most elements of this stack are the same as
1487     /// the ones passed as parameter.
1488     pub fn ends_with(&self, rhs: &[StackElement<'_>]) -> bool {
1489         if self.stack.len() < rhs.len() {
1490             return false;
1491         }
1492         let offset = self.stack.len() - rhs.len();
1493         for (i, r) in rhs.iter().enumerate() {
1494             if self.get(i + offset) != *r {
1495                 return false;
1496             }
1497         }
1498         true
1499     }
1500
1501     /// Returns the top-most element (if any).
1502     pub fn top(&self) -> Option<StackElement<'_>> {
1503         match self.stack.last() {
1504             None => None,
1505             Some(&InternalIndex(i)) => Some(StackElement::Index(i)),
1506             Some(&InternalKey(start, size)) => Some(StackElement::Key(
1507                 str::from_utf8(&self.str_buffer[start as usize..(start + size) as usize]).unwrap(),
1508             )),
1509         }
1510     }
1511
1512     // Used by Parser to insert StackElement::Key elements at the top of the stack.
1513     fn push_key(&mut self, key: string::String) {
1514         self.stack.push(InternalKey(self.str_buffer.len() as u16, key.len() as u16));
1515         self.str_buffer.extend(key.as_bytes());
1516     }
1517
1518     // Used by Parser to insert StackElement::Index elements at the top of the stack.
1519     fn push_index(&mut self, index: u32) {
1520         self.stack.push(InternalIndex(index));
1521     }
1522
1523     // Used by Parser to remove the top-most element of the stack.
1524     fn pop(&mut self) {
1525         assert!(!self.is_empty());
1526         match *self.stack.last().unwrap() {
1527             InternalKey(_, sz) => {
1528                 let new_size = self.str_buffer.len() - sz as usize;
1529                 self.str_buffer.truncate(new_size);
1530             }
1531             InternalIndex(_) => {}
1532         }
1533         self.stack.pop();
1534     }
1535
1536     // Used by Parser to test whether the top-most element is an index.
1537     fn last_is_index(&self) -> bool {
1538         matches!(self.stack.last(), Some(InternalIndex(_)))
1539     }
1540
1541     // Used by Parser to increment the index of the top-most element.
1542     fn bump_index(&mut self) {
1543         let len = self.stack.len();
1544         let idx = match *self.stack.last().unwrap() {
1545             InternalIndex(i) => i + 1,
1546             _ => {
1547                 panic!();
1548             }
1549         };
1550         self.stack[len - 1] = InternalIndex(idx);
1551     }
1552 }
1553
1554 /// A streaming JSON parser implemented as an iterator of JsonEvent, consuming
1555 /// an iterator of char.
1556 pub struct Parser<T> {
1557     rdr: T,
1558     ch: Option<char>,
1559     line: usize,
1560     col: usize,
1561     // We maintain a stack representing where we are in the logical structure
1562     // of the JSON stream.
1563     stack: Stack,
1564     // A state machine is kept to make it possible to interrupt and resume parsing.
1565     state: ParserState,
1566 }
1567
1568 impl<T: Iterator<Item = char>> Iterator for Parser<T> {
1569     type Item = JsonEvent;
1570
1571     fn next(&mut self) -> Option<JsonEvent> {
1572         if self.state == ParseFinished {
1573             return None;
1574         }
1575
1576         if self.state == ParseBeforeFinish {
1577             self.parse_whitespace();
1578             // Make sure there is no trailing characters.
1579             if self.eof() {
1580                 self.state = ParseFinished;
1581                 return None;
1582             } else {
1583                 return Some(self.error_event(TrailingCharacters));
1584             }
1585         }
1586
1587         Some(self.parse())
1588     }
1589 }
1590
1591 impl<T: Iterator<Item = char>> Parser<T> {
1592     /// Creates the JSON parser.
1593     pub fn new(rdr: T) -> Parser<T> {
1594         let mut p = Parser {
1595             rdr,
1596             ch: Some('\x00'),
1597             line: 1,
1598             col: 0,
1599             stack: Stack::new(),
1600             state: ParseStart,
1601         };
1602         p.bump();
1603         p
1604     }
1605
1606     /// Provides access to the current position in the logical structure of the
1607     /// JSON stream.
1608     pub fn stack(&self) -> &Stack {
1609         &self.stack
1610     }
1611
1612     fn eof(&self) -> bool {
1613         self.ch.is_none()
1614     }
1615     fn ch_or_null(&self) -> char {
1616         self.ch.unwrap_or('\x00')
1617     }
1618     fn bump(&mut self) {
1619         self.ch = self.rdr.next();
1620
1621         if self.ch_is('\n') {
1622             self.line += 1;
1623             self.col = 1;
1624         } else {
1625             self.col += 1;
1626         }
1627     }
1628
1629     fn next_char(&mut self) -> Option<char> {
1630         self.bump();
1631         self.ch
1632     }
1633     fn ch_is(&self, c: char) -> bool {
1634         self.ch == Some(c)
1635     }
1636
1637     fn error<U>(&self, reason: ErrorCode) -> Result<U, ParserError> {
1638         Err(SyntaxError(reason, self.line, self.col))
1639     }
1640
1641     fn parse_whitespace(&mut self) {
1642         while self.ch_is(' ') || self.ch_is('\n') || self.ch_is('\t') || self.ch_is('\r') {
1643             self.bump();
1644         }
1645     }
1646
1647     fn parse_number(&mut self) -> JsonEvent {
1648         let neg = if self.ch_is('-') {
1649             self.bump();
1650             true
1651         } else {
1652             false
1653         };
1654
1655         let res = match self.parse_u64() {
1656             Ok(res) => res,
1657             Err(e) => {
1658                 return Error(e);
1659             }
1660         };
1661
1662         if self.ch_is('.') || self.ch_is('e') || self.ch_is('E') {
1663             let mut res = res as f64;
1664
1665             if self.ch_is('.') {
1666                 res = match self.parse_decimal(res) {
1667                     Ok(res) => res,
1668                     Err(e) => {
1669                         return Error(e);
1670                     }
1671                 };
1672             }
1673
1674             if self.ch_is('e') || self.ch_is('E') {
1675                 res = match self.parse_exponent(res) {
1676                     Ok(res) => res,
1677                     Err(e) => {
1678                         return Error(e);
1679                     }
1680                 };
1681             }
1682
1683             if neg {
1684                 res *= -1.0;
1685             }
1686
1687             F64Value(res)
1688         } else if neg {
1689             let res = (res as i64).wrapping_neg();
1690
1691             // Make sure we didn't underflow.
1692             if res > 0 {
1693                 Error(SyntaxError(InvalidNumber, self.line, self.col))
1694             } else {
1695                 I64Value(res)
1696             }
1697         } else {
1698             U64Value(res)
1699         }
1700     }
1701
1702     fn parse_u64(&mut self) -> Result<u64, ParserError> {
1703         let mut accum = 0u64;
1704         let last_accum = 0; // necessary to detect overflow.
1705
1706         match self.ch_or_null() {
1707             '0' => {
1708                 self.bump();
1709
1710                 // A leading '0' must be the only digit before the decimal point.
1711                 if let '0'..='9' = self.ch_or_null() {
1712                     return self.error(InvalidNumber);
1713                 }
1714             }
1715             '1'..='9' => {
1716                 while !self.eof() {
1717                     match self.ch_or_null() {
1718                         c @ '0'..='9' => {
1719                             accum = accum.wrapping_mul(10);
1720                             accum = accum.wrapping_add((c as u64) - ('0' as u64));
1721
1722                             // Detect overflow by comparing to the last value.
1723                             if accum <= last_accum {
1724                                 return self.error(InvalidNumber);
1725                             }
1726
1727                             self.bump();
1728                         }
1729                         _ => break,
1730                     }
1731                 }
1732             }
1733             _ => return self.error(InvalidNumber),
1734         }
1735
1736         Ok(accum)
1737     }
1738
1739     fn parse_decimal(&mut self, mut res: f64) -> Result<f64, ParserError> {
1740         self.bump();
1741
1742         // Make sure a digit follows the decimal place.
1743         match self.ch_or_null() {
1744             '0'..='9' => (),
1745             _ => return self.error(InvalidNumber),
1746         }
1747
1748         let mut dec = 1.0;
1749         while !self.eof() {
1750             match self.ch_or_null() {
1751                 c @ '0'..='9' => {
1752                     dec /= 10.0;
1753                     res += (((c as isize) - ('0' as isize)) as f64) * dec;
1754                     self.bump();
1755                 }
1756                 _ => break,
1757             }
1758         }
1759
1760         Ok(res)
1761     }
1762
1763     fn parse_exponent(&mut self, mut res: f64) -> Result<f64, ParserError> {
1764         self.bump();
1765
1766         let mut exp = 0;
1767         let mut neg_exp = false;
1768
1769         if self.ch_is('+') {
1770             self.bump();
1771         } else if self.ch_is('-') {
1772             self.bump();
1773             neg_exp = true;
1774         }
1775
1776         // Make sure a digit follows the exponent place.
1777         match self.ch_or_null() {
1778             '0'..='9' => (),
1779             _ => return self.error(InvalidNumber),
1780         }
1781         while !self.eof() {
1782             match self.ch_or_null() {
1783                 c @ '0'..='9' => {
1784                     exp *= 10;
1785                     exp += (c as usize) - ('0' as usize);
1786
1787                     self.bump();
1788                 }
1789                 _ => break,
1790             }
1791         }
1792
1793         let exp = 10_f64.powi(exp as i32);
1794         if neg_exp {
1795             res /= exp;
1796         } else {
1797             res *= exp;
1798         }
1799
1800         Ok(res)
1801     }
1802
1803     fn decode_hex_escape(&mut self) -> Result<u16, ParserError> {
1804         let mut i = 0;
1805         let mut n = 0;
1806         while i < 4 && !self.eof() {
1807             self.bump();
1808             n = match self.ch_or_null() {
1809                 c @ '0'..='9' => n * 16 + ((c as u16) - ('0' as u16)),
1810                 'a' | 'A' => n * 16 + 10,
1811                 'b' | 'B' => n * 16 + 11,
1812                 'c' | 'C' => n * 16 + 12,
1813                 'd' | 'D' => n * 16 + 13,
1814                 'e' | 'E' => n * 16 + 14,
1815                 'f' | 'F' => n * 16 + 15,
1816                 _ => return self.error(InvalidEscape),
1817             };
1818
1819             i += 1;
1820         }
1821
1822         // Error out if we didn't parse 4 digits.
1823         if i != 4 {
1824             return self.error(InvalidEscape);
1825         }
1826
1827         Ok(n)
1828     }
1829
1830     fn parse_str(&mut self) -> Result<string::String, ParserError> {
1831         let mut escape = false;
1832         let mut res = string::String::new();
1833
1834         loop {
1835             self.bump();
1836             if self.eof() {
1837                 return self.error(EOFWhileParsingString);
1838             }
1839
1840             if escape {
1841                 match self.ch_or_null() {
1842                     '"' => res.push('"'),
1843                     '\\' => res.push('\\'),
1844                     '/' => res.push('/'),
1845                     'b' => res.push('\x08'),
1846                     'f' => res.push('\x0c'),
1847                     'n' => res.push('\n'),
1848                     'r' => res.push('\r'),
1849                     't' => res.push('\t'),
1850                     'u' => match self.decode_hex_escape()? {
1851                         0xDC00..=0xDFFF => return self.error(LoneLeadingSurrogateInHexEscape),
1852
1853                         // Non-BMP characters are encoded as a sequence of
1854                         // two hex escapes, representing UTF-16 surrogates.
1855                         n1 @ 0xD800..=0xDBFF => {
1856                             match (self.next_char(), self.next_char()) {
1857                                 (Some('\\'), Some('u')) => (),
1858                                 _ => return self.error(UnexpectedEndOfHexEscape),
1859                             }
1860
1861                             let n2 = self.decode_hex_escape()?;
1862                             if n2 < 0xDC00 || n2 > 0xDFFF {
1863                                 return self.error(LoneLeadingSurrogateInHexEscape);
1864                             }
1865                             let c =
1866                                 (u32::from(n1 - 0xD800) << 10 | u32::from(n2 - 0xDC00)) + 0x1_0000;
1867                             res.push(char::from_u32(c).unwrap());
1868                         }
1869
1870                         n => match char::from_u32(u32::from(n)) {
1871                             Some(c) => res.push(c),
1872                             None => return self.error(InvalidUnicodeCodePoint),
1873                         },
1874                     },
1875                     _ => return self.error(InvalidEscape),
1876                 }
1877                 escape = false;
1878             } else if self.ch_is('\\') {
1879                 escape = true;
1880             } else {
1881                 match self.ch {
1882                     Some('"') => {
1883                         self.bump();
1884                         return Ok(res);
1885                     }
1886                     Some(c) => res.push(c),
1887                     None => unreachable!(),
1888                 }
1889             }
1890         }
1891     }
1892
1893     // Invoked at each iteration, consumes the stream until it has enough
1894     // information to return a JsonEvent.
1895     // Manages an internal state so that parsing can be interrupted and resumed.
1896     // Also keeps track of the position in the logical structure of the json
1897     // stream isize the form of a stack that can be queried by the user using the
1898     // stack() method.
1899     fn parse(&mut self) -> JsonEvent {
1900         loop {
1901             // The only paths where the loop can spin a new iteration
1902             // are in the cases ParseArrayComma and ParseObjectComma if ','
1903             // is parsed. In these cases the state is set to (respectively)
1904             // ParseArray(false) and ParseObject(false), which always return,
1905             // so there is no risk of getting stuck in an infinite loop.
1906             // All other paths return before the end of the loop's iteration.
1907             self.parse_whitespace();
1908
1909             match self.state {
1910                 ParseStart => {
1911                     return self.parse_start();
1912                 }
1913                 ParseArray(first) => {
1914                     return self.parse_array(first);
1915                 }
1916                 ParseArrayComma => {
1917                     if let Some(evt) = self.parse_array_comma_or_end() {
1918                         return evt;
1919                     }
1920                 }
1921                 ParseObject(first) => {
1922                     return self.parse_object(first);
1923                 }
1924                 ParseObjectComma => {
1925                     self.stack.pop();
1926                     if self.ch_is(',') {
1927                         self.state = ParseObject(false);
1928                         self.bump();
1929                     } else {
1930                         return self.parse_object_end();
1931                     }
1932                 }
1933                 _ => {
1934                     return self.error_event(InvalidSyntax);
1935                 }
1936             }
1937         }
1938     }
1939
1940     fn parse_start(&mut self) -> JsonEvent {
1941         let val = self.parse_value();
1942         self.state = match val {
1943             Error(_) => ParseFinished,
1944             ArrayStart => ParseArray(true),
1945             ObjectStart => ParseObject(true),
1946             _ => ParseBeforeFinish,
1947         };
1948         val
1949     }
1950
1951     fn parse_array(&mut self, first: bool) -> JsonEvent {
1952         if self.ch_is(']') {
1953             if !first {
1954                 self.error_event(InvalidSyntax)
1955             } else {
1956                 self.state = if self.stack.is_empty() {
1957                     ParseBeforeFinish
1958                 } else if self.stack.last_is_index() {
1959                     ParseArrayComma
1960                 } else {
1961                     ParseObjectComma
1962                 };
1963                 self.bump();
1964                 ArrayEnd
1965             }
1966         } else {
1967             if first {
1968                 self.stack.push_index(0);
1969             }
1970             let val = self.parse_value();
1971             self.state = match val {
1972                 Error(_) => ParseFinished,
1973                 ArrayStart => ParseArray(true),
1974                 ObjectStart => ParseObject(true),
1975                 _ => ParseArrayComma,
1976             };
1977             val
1978         }
1979     }
1980
1981     fn parse_array_comma_or_end(&mut self) -> Option<JsonEvent> {
1982         if self.ch_is(',') {
1983             self.stack.bump_index();
1984             self.state = ParseArray(false);
1985             self.bump();
1986             None
1987         } else if self.ch_is(']') {
1988             self.stack.pop();
1989             self.state = if self.stack.is_empty() {
1990                 ParseBeforeFinish
1991             } else if self.stack.last_is_index() {
1992                 ParseArrayComma
1993             } else {
1994                 ParseObjectComma
1995             };
1996             self.bump();
1997             Some(ArrayEnd)
1998         } else if self.eof() {
1999             Some(self.error_event(EOFWhileParsingArray))
2000         } else {
2001             Some(self.error_event(InvalidSyntax))
2002         }
2003     }
2004
2005     fn parse_object(&mut self, first: bool) -> JsonEvent {
2006         if self.ch_is('}') {
2007             if !first {
2008                 if self.stack.is_empty() {
2009                     return self.error_event(TrailingComma);
2010                 } else {
2011                     self.stack.pop();
2012                 }
2013             }
2014             self.state = if self.stack.is_empty() {
2015                 ParseBeforeFinish
2016             } else if self.stack.last_is_index() {
2017                 ParseArrayComma
2018             } else {
2019                 ParseObjectComma
2020             };
2021             self.bump();
2022             return ObjectEnd;
2023         }
2024         if self.eof() {
2025             return self.error_event(EOFWhileParsingObject);
2026         }
2027         if !self.ch_is('"') {
2028             return self.error_event(KeyMustBeAString);
2029         }
2030         let s = match self.parse_str() {
2031             Ok(s) => s,
2032             Err(e) => {
2033                 self.state = ParseFinished;
2034                 return Error(e);
2035             }
2036         };
2037         self.parse_whitespace();
2038         if self.eof() {
2039             return self.error_event(EOFWhileParsingObject);
2040         } else if self.ch_or_null() != ':' {
2041             return self.error_event(ExpectedColon);
2042         }
2043         self.stack.push_key(s);
2044         self.bump();
2045         self.parse_whitespace();
2046
2047         let val = self.parse_value();
2048
2049         self.state = match val {
2050             Error(_) => ParseFinished,
2051             ArrayStart => ParseArray(true),
2052             ObjectStart => ParseObject(true),
2053             _ => ParseObjectComma,
2054         };
2055         val
2056     }
2057
2058     fn parse_object_end(&mut self) -> JsonEvent {
2059         if self.ch_is('}') {
2060             self.state = if self.stack.is_empty() {
2061                 ParseBeforeFinish
2062             } else if self.stack.last_is_index() {
2063                 ParseArrayComma
2064             } else {
2065                 ParseObjectComma
2066             };
2067             self.bump();
2068             ObjectEnd
2069         } else if self.eof() {
2070             self.error_event(EOFWhileParsingObject)
2071         } else {
2072             self.error_event(InvalidSyntax)
2073         }
2074     }
2075
2076     fn parse_value(&mut self) -> JsonEvent {
2077         if self.eof() {
2078             return self.error_event(EOFWhileParsingValue);
2079         }
2080         match self.ch_or_null() {
2081             'n' => self.parse_ident("ull", NullValue),
2082             't' => self.parse_ident("rue", BooleanValue(true)),
2083             'f' => self.parse_ident("alse", BooleanValue(false)),
2084             '0'..='9' | '-' => self.parse_number(),
2085             '"' => match self.parse_str() {
2086                 Ok(s) => StringValue(s),
2087                 Err(e) => Error(e),
2088             },
2089             '[' => {
2090                 self.bump();
2091                 ArrayStart
2092             }
2093             '{' => {
2094                 self.bump();
2095                 ObjectStart
2096             }
2097             _ => self.error_event(InvalidSyntax),
2098         }
2099     }
2100
2101     fn parse_ident(&mut self, ident: &str, value: JsonEvent) -> JsonEvent {
2102         if ident.chars().all(|c| Some(c) == self.next_char()) {
2103             self.bump();
2104             value
2105         } else {
2106             Error(SyntaxError(InvalidSyntax, self.line, self.col))
2107         }
2108     }
2109
2110     fn error_event(&mut self, reason: ErrorCode) -> JsonEvent {
2111         self.state = ParseFinished;
2112         Error(SyntaxError(reason, self.line, self.col))
2113     }
2114 }
2115
2116 /// A Builder consumes a json::Parser to create a generic Json structure.
2117 pub struct Builder<T> {
2118     parser: Parser<T>,
2119     token: Option<JsonEvent>,
2120 }
2121
2122 impl<T: Iterator<Item = char>> Builder<T> {
2123     /// Creates a JSON Builder.
2124     pub fn new(src: T) -> Builder<T> {
2125         Builder { parser: Parser::new(src), token: None }
2126     }
2127
2128     // Decode a Json value from a Parser.
2129     pub fn build(&mut self) -> Result<Json, BuilderError> {
2130         self.bump();
2131         let result = self.build_value();
2132         self.bump();
2133         match self.token {
2134             None => {}
2135             Some(Error(ref e)) => {
2136                 return Err(e.clone());
2137             }
2138             ref tok => {
2139                 panic!("unexpected token {:?}", tok.clone());
2140             }
2141         }
2142         result
2143     }
2144
2145     fn bump(&mut self) {
2146         self.token = self.parser.next();
2147     }
2148
2149     fn build_value(&mut self) -> Result<Json, BuilderError> {
2150         match self.token {
2151             Some(NullValue) => Ok(Json::Null),
2152             Some(I64Value(n)) => Ok(Json::I64(n)),
2153             Some(U64Value(n)) => Ok(Json::U64(n)),
2154             Some(F64Value(n)) => Ok(Json::F64(n)),
2155             Some(BooleanValue(b)) => Ok(Json::Boolean(b)),
2156             Some(StringValue(ref mut s)) => {
2157                 let mut temp = string::String::new();
2158                 swap(s, &mut temp);
2159                 Ok(Json::String(temp))
2160             }
2161             Some(Error(ref e)) => Err(e.clone()),
2162             Some(ArrayStart) => self.build_array(),
2163             Some(ObjectStart) => self.build_object(),
2164             Some(ObjectEnd) => self.parser.error(InvalidSyntax),
2165             Some(ArrayEnd) => self.parser.error(InvalidSyntax),
2166             None => self.parser.error(EOFWhileParsingValue),
2167         }
2168     }
2169
2170     fn build_array(&mut self) -> Result<Json, BuilderError> {
2171         self.bump();
2172         let mut values = Vec::new();
2173
2174         loop {
2175             if self.token == Some(ArrayEnd) {
2176                 return Ok(Json::Array(values.into_iter().collect()));
2177             }
2178             match self.build_value() {
2179                 Ok(v) => values.push(v),
2180                 Err(e) => return Err(e),
2181             }
2182             self.bump();
2183         }
2184     }
2185
2186     fn build_object(&mut self) -> Result<Json, BuilderError> {
2187         self.bump();
2188
2189         let mut values = BTreeMap::new();
2190
2191         loop {
2192             match self.token {
2193                 Some(ObjectEnd) => {
2194                     return Ok(Json::Object(values));
2195                 }
2196                 Some(Error(ref e)) => {
2197                     return Err(e.clone());
2198                 }
2199                 None => {
2200                     break;
2201                 }
2202                 _ => {}
2203             }
2204             let key = match self.parser.stack().top() {
2205                 Some(StackElement::Key(k)) => k.to_owned(),
2206                 _ => {
2207                     panic!("invalid state");
2208                 }
2209             };
2210             match self.build_value() {
2211                 Ok(value) => {
2212                     values.insert(key, value);
2213                 }
2214                 Err(e) => {
2215                     return Err(e);
2216                 }
2217             }
2218             self.bump();
2219         }
2220         self.parser.error(EOFWhileParsingObject)
2221     }
2222 }
2223
2224 /// Decodes a json value from an `&mut io::Read`
2225 pub fn from_reader(rdr: &mut dyn Read) -> Result<Json, BuilderError> {
2226     let mut contents = Vec::new();
2227     match rdr.read_to_end(&mut contents) {
2228         Ok(c) => c,
2229         Err(e) => return Err(io_error_to_error(e)),
2230     };
2231     let s = match str::from_utf8(&contents).ok() {
2232         Some(s) => s,
2233         _ => return Err(SyntaxError(NotUtf8, 0, 0)),
2234     };
2235     let mut builder = Builder::new(s.chars());
2236     builder.build()
2237 }
2238
2239 /// Decodes a json value from a string
2240 pub fn from_str(s: &str) -> Result<Json, BuilderError> {
2241     let mut builder = Builder::new(s.chars());
2242     builder.build()
2243 }
2244
2245 /// A structure to decode JSON to values in rust.
2246 pub struct Decoder {
2247     stack: Vec<Json>,
2248 }
2249
2250 impl Decoder {
2251     /// Creates a new decoder instance for decoding the specified JSON value.
2252     pub fn new(json: Json) -> Decoder {
2253         Decoder { stack: vec![json] }
2254     }
2255
2256     fn pop(&mut self) -> Json {
2257         self.stack.pop().unwrap()
2258     }
2259 }
2260
2261 macro_rules! expect {
2262     ($e:expr, Null) => {{
2263         match $e {
2264             Json::Null => Ok(()),
2265             other => Err(ExpectedError("Null".to_owned(), other.to_string())),
2266         }
2267     }};
2268     ($e:expr, $t:ident) => {{
2269         match $e {
2270             Json::$t(v) => Ok(v),
2271             other => Err(ExpectedError(stringify!($t).to_owned(), other.to_string())),
2272         }
2273     }};
2274 }
2275
2276 macro_rules! read_primitive {
2277     ($name:ident, $ty:ty) => {
2278         fn $name(&mut self) -> DecodeResult<$ty> {
2279             match self.pop() {
2280                 Json::I64(f) => Ok(f as $ty),
2281                 Json::U64(f) => Ok(f as $ty),
2282                 Json::F64(f) => Err(ExpectedError("Integer".to_owned(), f.to_string())),
2283                 // re: #12967.. a type w/ numeric keys (ie HashMap<usize, V> etc)
2284                 // is going to have a string here, as per JSON spec.
2285                 Json::String(s) => match s.parse().ok() {
2286                     Some(f) => Ok(f),
2287                     None => Err(ExpectedError("Number".to_owned(), s)),
2288                 },
2289                 value => Err(ExpectedError("Number".to_owned(), value.to_string())),
2290             }
2291         }
2292     };
2293 }
2294
2295 impl crate::Decoder for Decoder {
2296     type Error = DecoderError;
2297
2298     fn read_nil(&mut self) -> DecodeResult<()> {
2299         expect!(self.pop(), Null)
2300     }
2301
2302     read_primitive! { read_usize, usize }
2303     read_primitive! { read_u8, u8 }
2304     read_primitive! { read_u16, u16 }
2305     read_primitive! { read_u32, u32 }
2306     read_primitive! { read_u64, u64 }
2307     read_primitive! { read_u128, u128 }
2308     read_primitive! { read_isize, isize }
2309     read_primitive! { read_i8, i8 }
2310     read_primitive! { read_i16, i16 }
2311     read_primitive! { read_i32, i32 }
2312     read_primitive! { read_i64, i64 }
2313     read_primitive! { read_i128, i128 }
2314
2315     fn read_f32(&mut self) -> DecodeResult<f32> {
2316         self.read_f64().map(|x| x as f32)
2317     }
2318
2319     fn read_f64(&mut self) -> DecodeResult<f64> {
2320         match self.pop() {
2321             Json::I64(f) => Ok(f as f64),
2322             Json::U64(f) => Ok(f as f64),
2323             Json::F64(f) => Ok(f),
2324             Json::String(s) => {
2325                 // re: #12967.. a type w/ numeric keys (ie HashMap<usize, V> etc)
2326                 // is going to have a string here, as per JSON spec.
2327                 match s.parse().ok() {
2328                     Some(f) => Ok(f),
2329                     None => Err(ExpectedError("Number".to_owned(), s)),
2330                 }
2331             }
2332             Json::Null => Ok(f64::NAN),
2333             value => Err(ExpectedError("Number".to_owned(), value.to_string())),
2334         }
2335     }
2336
2337     fn read_bool(&mut self) -> DecodeResult<bool> {
2338         expect!(self.pop(), Boolean)
2339     }
2340
2341     fn read_char(&mut self) -> DecodeResult<char> {
2342         let s = self.read_str()?;
2343         {
2344             let mut it = s.chars();
2345             if let (Some(c), None) = (it.next(), it.next()) {
2346                 // exactly one character
2347                 return Ok(c);
2348             }
2349         }
2350         Err(ExpectedError("single character string".to_owned(), s.to_string()))
2351     }
2352
2353     fn read_str(&mut self) -> DecodeResult<Cow<'_, str>> {
2354         expect!(self.pop(), String).map(Cow::Owned)
2355     }
2356
2357     fn read_enum<T, F>(&mut self, _name: &str, f: F) -> DecodeResult<T>
2358     where
2359         F: FnOnce(&mut Decoder) -> DecodeResult<T>,
2360     {
2361         f(self)
2362     }
2363
2364     fn read_enum_variant<T, F>(&mut self, names: &[&str], mut f: F) -> DecodeResult<T>
2365     where
2366         F: FnMut(&mut Decoder, usize) -> DecodeResult<T>,
2367     {
2368         let name = match self.pop() {
2369             Json::String(s) => s,
2370             Json::Object(mut o) => {
2371                 let n = match o.remove(&"variant".to_owned()) {
2372                     Some(Json::String(s)) => s,
2373                     Some(val) => return Err(ExpectedError("String".to_owned(), val.to_string())),
2374                     None => return Err(MissingFieldError("variant".to_owned())),
2375                 };
2376                 match o.remove(&"fields".to_string()) {
2377                     Some(Json::Array(l)) => {
2378                         self.stack.extend(l.into_iter().rev());
2379                     }
2380                     Some(val) => return Err(ExpectedError("Array".to_owned(), val.to_string())),
2381                     None => return Err(MissingFieldError("fields".to_owned())),
2382                 }
2383                 n
2384             }
2385             json => return Err(ExpectedError("String or Object".to_owned(), json.to_string())),
2386         };
2387         let idx = match names.iter().position(|n| *n == &name[..]) {
2388             Some(idx) => idx,
2389             None => return Err(UnknownVariantError(name)),
2390         };
2391         f(self, idx)
2392     }
2393
2394     fn read_enum_variant_arg<T, F>(&mut self, _idx: usize, f: F) -> DecodeResult<T>
2395     where
2396         F: FnOnce(&mut Decoder) -> DecodeResult<T>,
2397     {
2398         f(self)
2399     }
2400
2401     fn read_enum_struct_variant<T, F>(&mut self, names: &[&str], f: F) -> DecodeResult<T>
2402     where
2403         F: FnMut(&mut Decoder, usize) -> DecodeResult<T>,
2404     {
2405         self.read_enum_variant(names, f)
2406     }
2407
2408     fn read_enum_struct_variant_field<T, F>(
2409         &mut self,
2410         _name: &str,
2411         idx: usize,
2412         f: F,
2413     ) -> DecodeResult<T>
2414     where
2415         F: FnOnce(&mut Decoder) -> DecodeResult<T>,
2416     {
2417         self.read_enum_variant_arg(idx, f)
2418     }
2419
2420     fn read_struct<T, F>(&mut self, _name: &str, _len: usize, f: F) -> DecodeResult<T>
2421     where
2422         F: FnOnce(&mut Decoder) -> DecodeResult<T>,
2423     {
2424         let value = f(self)?;
2425         self.pop();
2426         Ok(value)
2427     }
2428
2429     fn read_struct_field<T, F>(&mut self, name: &str, _idx: usize, f: F) -> DecodeResult<T>
2430     where
2431         F: FnOnce(&mut Decoder) -> DecodeResult<T>,
2432     {
2433         let mut obj = expect!(self.pop(), Object)?;
2434
2435         let value = match obj.remove(&name.to_string()) {
2436             None => {
2437                 // Add a Null and try to parse it as an Option<_>
2438                 // to get None as a default value.
2439                 self.stack.push(Json::Null);
2440                 match f(self) {
2441                     Ok(x) => x,
2442                     Err(_) => return Err(MissingFieldError(name.to_string())),
2443                 }
2444             }
2445             Some(json) => {
2446                 self.stack.push(json);
2447                 f(self)?
2448             }
2449         };
2450         self.stack.push(Json::Object(obj));
2451         Ok(value)
2452     }
2453
2454     fn read_tuple<T, F>(&mut self, tuple_len: usize, f: F) -> DecodeResult<T>
2455     where
2456         F: FnOnce(&mut Decoder) -> DecodeResult<T>,
2457     {
2458         self.read_seq(move |d, len| {
2459             if len == tuple_len {
2460                 f(d)
2461             } else {
2462                 Err(ExpectedError(format!("Tuple{}", tuple_len), format!("Tuple{}", len)))
2463             }
2464         })
2465     }
2466
2467     fn read_tuple_arg<T, F>(&mut self, idx: usize, f: F) -> DecodeResult<T>
2468     where
2469         F: FnOnce(&mut Decoder) -> DecodeResult<T>,
2470     {
2471         self.read_seq_elt(idx, f)
2472     }
2473
2474     fn read_tuple_struct<T, F>(&mut self, _name: &str, len: usize, f: F) -> DecodeResult<T>
2475     where
2476         F: FnOnce(&mut Decoder) -> DecodeResult<T>,
2477     {
2478         self.read_tuple(len, f)
2479     }
2480
2481     fn read_tuple_struct_arg<T, F>(&mut self, idx: usize, f: F) -> DecodeResult<T>
2482     where
2483         F: FnOnce(&mut Decoder) -> DecodeResult<T>,
2484     {
2485         self.read_tuple_arg(idx, f)
2486     }
2487
2488     fn read_option<T, F>(&mut self, mut f: F) -> DecodeResult<T>
2489     where
2490         F: FnMut(&mut Decoder, bool) -> DecodeResult<T>,
2491     {
2492         match self.pop() {
2493             Json::Null => f(self, false),
2494             value => {
2495                 self.stack.push(value);
2496                 f(self, true)
2497             }
2498         }
2499     }
2500
2501     fn read_seq<T, F>(&mut self, f: F) -> DecodeResult<T>
2502     where
2503         F: FnOnce(&mut Decoder, usize) -> DecodeResult<T>,
2504     {
2505         let array = expect!(self.pop(), Array)?;
2506         let len = array.len();
2507         self.stack.extend(array.into_iter().rev());
2508         f(self, len)
2509     }
2510
2511     fn read_seq_elt<T, F>(&mut self, _idx: usize, f: F) -> DecodeResult<T>
2512     where
2513         F: FnOnce(&mut Decoder) -> DecodeResult<T>,
2514     {
2515         f(self)
2516     }
2517
2518     fn read_map<T, F>(&mut self, f: F) -> DecodeResult<T>
2519     where
2520         F: FnOnce(&mut Decoder, usize) -> DecodeResult<T>,
2521     {
2522         let obj = expect!(self.pop(), Object)?;
2523         let len = obj.len();
2524         for (key, value) in obj {
2525             self.stack.push(value);
2526             self.stack.push(Json::String(key));
2527         }
2528         f(self, len)
2529     }
2530
2531     fn read_map_elt_key<T, F>(&mut self, _idx: usize, f: F) -> DecodeResult<T>
2532     where
2533         F: FnOnce(&mut Decoder) -> DecodeResult<T>,
2534     {
2535         f(self)
2536     }
2537
2538     fn read_map_elt_val<T, F>(&mut self, _idx: usize, f: F) -> DecodeResult<T>
2539     where
2540         F: FnOnce(&mut Decoder) -> DecodeResult<T>,
2541     {
2542         f(self)
2543     }
2544
2545     fn error(&mut self, err: &str) -> DecoderError {
2546         ApplicationError(err.to_string())
2547     }
2548 }
2549
2550 /// A trait for converting values to JSON
2551 pub trait ToJson {
2552     /// Converts the value of `self` to an instance of JSON
2553     fn to_json(&self) -> Json;
2554 }
2555
2556 macro_rules! to_json_impl_i64 {
2557     ($($t:ty), +) => (
2558         $(impl ToJson for $t {
2559             fn to_json(&self) -> Json {
2560                 Json::I64(*self as i64)
2561             }
2562         })+
2563     )
2564 }
2565
2566 to_json_impl_i64! { isize, i8, i16, i32, i64 }
2567
2568 macro_rules! to_json_impl_u64 {
2569     ($($t:ty), +) => (
2570         $(impl ToJson for $t {
2571             fn to_json(&self) -> Json {
2572                 Json::U64(*self as u64)
2573             }
2574         })+
2575     )
2576 }
2577
2578 to_json_impl_u64! { usize, u8, u16, u32, u64 }
2579
2580 impl ToJson for Json {
2581     fn to_json(&self) -> Json {
2582         self.clone()
2583     }
2584 }
2585
2586 impl ToJson for f32 {
2587     fn to_json(&self) -> Json {
2588         f64::from(*self).to_json()
2589     }
2590 }
2591
2592 impl ToJson for f64 {
2593     fn to_json(&self) -> Json {
2594         match self.classify() {
2595             Fp::Nan | Fp::Infinite => Json::Null,
2596             _ => Json::F64(*self),
2597         }
2598     }
2599 }
2600
2601 impl ToJson for () {
2602     fn to_json(&self) -> Json {
2603         Json::Null
2604     }
2605 }
2606
2607 impl ToJson for bool {
2608     fn to_json(&self) -> Json {
2609         Json::Boolean(*self)
2610     }
2611 }
2612
2613 impl ToJson for str {
2614     fn to_json(&self) -> Json {
2615         Json::String(self.to_string())
2616     }
2617 }
2618
2619 impl ToJson for string::String {
2620     fn to_json(&self) -> Json {
2621         Json::String((*self).clone())
2622     }
2623 }
2624
2625 macro_rules! tuple_impl {
2626     // use variables to indicate the arity of the tuple
2627     ($($tyvar:ident),* ) => {
2628         // the trailing commas are for the 1 tuple
2629         impl<
2630             $( $tyvar : ToJson ),*
2631             > ToJson for ( $( $tyvar ),* , ) {
2632
2633             #[inline]
2634             #[allow(non_snake_case)]
2635             fn to_json(&self) -> Json {
2636                 match *self {
2637                     ($(ref $tyvar),*,) => Json::Array(vec![$($tyvar.to_json()),*])
2638                 }
2639             }
2640         }
2641     }
2642 }
2643
2644 tuple_impl! {A}
2645 tuple_impl! {A, B}
2646 tuple_impl! {A, B, C}
2647 tuple_impl! {A, B, C, D}
2648 tuple_impl! {A, B, C, D, E}
2649 tuple_impl! {A, B, C, D, E, F}
2650 tuple_impl! {A, B, C, D, E, F, G}
2651 tuple_impl! {A, B, C, D, E, F, G, H}
2652 tuple_impl! {A, B, C, D, E, F, G, H, I}
2653 tuple_impl! {A, B, C, D, E, F, G, H, I, J}
2654 tuple_impl! {A, B, C, D, E, F, G, H, I, J, K}
2655 tuple_impl! {A, B, C, D, E, F, G, H, I, J, K, L}
2656
2657 impl<A: ToJson> ToJson for [A] {
2658     fn to_json(&self) -> Json {
2659         Json::Array(self.iter().map(|elt| elt.to_json()).collect())
2660     }
2661 }
2662
2663 impl<A: ToJson> ToJson for Vec<A> {
2664     fn to_json(&self) -> Json {
2665         Json::Array(self.iter().map(|elt| elt.to_json()).collect())
2666     }
2667 }
2668
2669 impl<T: ToString, A: ToJson> ToJson for BTreeMap<T, A> {
2670     fn to_json(&self) -> Json {
2671         let mut d = BTreeMap::new();
2672         for (key, value) in self {
2673             d.insert(key.to_string(), value.to_json());
2674         }
2675         Json::Object(d)
2676     }
2677 }
2678
2679 impl<A: ToJson> ToJson for HashMap<string::String, A> {
2680     fn to_json(&self) -> Json {
2681         let mut d = BTreeMap::new();
2682         for (key, value) in self {
2683             d.insert((*key).clone(), value.to_json());
2684         }
2685         Json::Object(d)
2686     }
2687 }
2688
2689 impl<A: ToJson> ToJson for Option<A> {
2690     fn to_json(&self) -> Json {
2691         match *self {
2692             None => Json::Null,
2693             Some(ref value) => value.to_json(),
2694         }
2695     }
2696 }
2697
2698 struct FormatShim<'a, 'b> {
2699     inner: &'a mut fmt::Formatter<'b>,
2700 }
2701
2702 impl<'a, 'b> fmt::Write for FormatShim<'a, 'b> {
2703     fn write_str(&mut self, s: &str) -> fmt::Result {
2704         match self.inner.write_str(s) {
2705             Ok(_) => Ok(()),
2706             Err(_) => Err(fmt::Error),
2707         }
2708     }
2709 }
2710
2711 impl fmt::Display for Json {
2712     /// Encodes a json value into a string
2713     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
2714         let mut shim = FormatShim { inner: f };
2715         let mut encoder = Encoder::new(&mut shim);
2716         match self.encode(&mut encoder) {
2717             Ok(_) => Ok(()),
2718             Err(_) => Err(fmt::Error),
2719         }
2720     }
2721 }
2722
2723 impl<'a> fmt::Display for PrettyJson<'a> {
2724     /// Encodes a json value into a string
2725     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
2726         let mut shim = FormatShim { inner: f };
2727         let mut encoder = PrettyEncoder::new(&mut shim);
2728         match self.inner.encode(&mut encoder) {
2729             Ok(_) => Ok(()),
2730             Err(_) => Err(fmt::Error),
2731         }
2732     }
2733 }
2734
2735 impl<'a, T: for<'r> Encodable<Encoder<'r>>> fmt::Display for AsJson<'a, T> {
2736     /// Encodes a json value into a string
2737     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
2738         let mut shim = FormatShim { inner: f };
2739         let mut encoder = Encoder::new(&mut shim);
2740         match self.inner.encode(&mut encoder) {
2741             Ok(_) => Ok(()),
2742             Err(_) => Err(fmt::Error),
2743         }
2744     }
2745 }
2746
2747 impl<'a, T> AsPrettyJson<'a, T> {
2748     /// Sets the indentation level for the emitted JSON
2749     pub fn indent(mut self, indent: usize) -> AsPrettyJson<'a, T> {
2750         self.indent = Some(indent);
2751         self
2752     }
2753 }
2754
2755 impl<'a, T: for<'x> Encodable<PrettyEncoder<'x>>> fmt::Display for AsPrettyJson<'a, T> {
2756     /// Encodes a json value into a string
2757     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
2758         let mut shim = FormatShim { inner: f };
2759         let mut encoder = PrettyEncoder::new(&mut shim);
2760         if let Some(n) = self.indent {
2761             encoder.set_indent(n);
2762         }
2763         match self.inner.encode(&mut encoder) {
2764             Ok(_) => Ok(()),
2765             Err(_) => Err(fmt::Error),
2766         }
2767     }
2768 }
2769
2770 impl FromStr for Json {
2771     type Err = BuilderError;
2772     fn from_str(s: &str) -> Result<Json, BuilderError> {
2773         from_str(s)
2774     }
2775 }
2776
2777 #[cfg(test)]
2778 mod tests;