Topics for the JSON chapter

[japaric]

This is what I have in mind at the moment (but we should try to reduce the number of topics by merging some of them)

• Custom Encoding/Decoding (to Structs)
• Decoding from &str
• Default Decoding/Encoding #[deriving(Encodable,Decodable)]
• Encoding to String
• Error handling (DecoderError, ParserError, etc)
• Streaming (which is not documented)
• The Json intermediate struct
• ToJson
• How JSON types match to Rust types: null <-> None, [] <-> Vec, "" <-> String, Object <-> TreeMap<String, T>/HashMap<String, T>

Feedback is welcome!

Order-wise, this chapter should be after the "hashmap"/"treemap" chapters.

The structure of the chapter should look like this (some topics are still missing):

.
|-- `Json` -> The `Json` enum and its variants
|   |-- Decoding -> `json::from_str` + `BuilderError`
|   |-- `ToJson`` -> struct -> `Json`
|   `-- Stringify??? -> `Json` -> `String`
|-- `Decoder` -> `Json` -> `Decoder` -> `T` - where `T` = `Vec`, `String`, `HashMap`, etc
|-- `Decodable` -> `#[deriving(Decodable)]`
|   `-- Custom??? -> Manually implement `Decodable`
`-- `Encodable` -> `#[deriving(Encodable)]`, `str_encode`
    `-- Custom??? -> Manually implement `Encodable`

---

@vojtechkral is working on this

[vojtechkral]

@japaric I'm not quite clear on some of these. What does "Custom Encoding/Decoding (to Structs)" mean? Is that de/encoding without Decodable, Encodable & ToJson? I'm not sure about the last one either.

Also, what should be in the chapter root/intro (the top level chapter on JSON)?

[japaric]

What does "Custom Encoding/Decoding (to Structs)" mean?

I mean manually implementing the traits, rather that using [deriving(Encodable)]. Like the impl ToJson example in the docs.

I'm not sure about the last one either

Explain how the JSON types map to Rust types.

Also, what should be in the chapter root/intro (the top level chapter on JSON)?

Either an overview about JSON serialization, or the simplest possible example about JSON.

[vojtechkral]

@japaric Ok, I think I have a code covering topics 2, 3 & 4. I reckon I should wait until #80 is sorted out, though...

Either an overview about JSON serialization, or the simplest possible example about JSON.

How about something as simple as this:

extern crate serialize;

use serialize::json;

fn main() {
    let numbers = vec![1, 2, 3];
    let encoded_str: String = json::Encoder::str_encode(&numbers);
    println!("{}", encoded_str);
}

The chapter intro might also mention that all the json stuff is in the serialize crate.

[japaric]

Ok, I think I have a code covering topics 2, 3 & 4.

\o/

I reckon I should wait until #80 is sorted out, though...

#80 is done, you can send PRs to master now, I won't do any more heavy refactoring for now.

How about something as simple as this:

We can postpone thinking about the intro until we have all the other section of the chapter done. In other words, it's ok if it's not clear what the intro should be at the moment. Finishing the other sections makes sure we don't explain a concept twice in the intro. Plus, it's not necessary for the intro to have a runnable example.

tl;dr I will like to see what examples you have done first :-)

The chapter intro might also mention that all the json stuff is in the serialize crate.

nods We should also mention that Rust provides other serialization formats.

[vojtechkral]

@japaric Ok, see #99

[japaric]

@vojtechkral See this reddit post for a clue about how to manually implement the Decodable trait.

TIL The rustc --pretty expanded command reveals the magic behind the #[deriving(...)] attribute.

[vojtechkral]

@japaric I've actually had code for manual implentation of both Decodable and Encodable for some time now, I just didn't get to bring it to PR-able shape yet :-/

[vojtechkral]

@japaric Also, I've just found out str_encode() has been deprecated, apparently it's replaced by json::encode(). I'm gonna have to update the code...

[japaric]

Also, I've just found out str_encode() has been deprecated, apparently it's replaced by json::encode(). I'm gonna have to update the code...

json::encode is a drop-in replacement for str::Encoder::str_encode. (Just a shorter name)

[mdinger]

JSON is gone so this should be closed for now.