Repository files navigation

RON is a simple readable data serialization format that looks similar to Rust syntax.It's designed to support all ofSerde's data model, sostructs, enums, tuples, arrays, generic maps, and primitive values.

GameConfig(// optional struct namewindow_size: (800,600),window_title:"PAC-MAN",fullscreen:false,mouse_sensitivity:1.4,key_bindings: {"up":Up,"down":Down,"left":Left,"right":Right,// Uncomment to enable WASD controls/*        "W": Up,        "S": Down,        "A": Left,        "D": Right,        */    },difficulty_options: (start_difficulty:Easy,adaptive:false,    ),)

• Numbers:42,3.14,0xFF,0b0110
• Strings:"Hello","with\\escapes\n",r#"raw string, great for regex\."#
• Byte Strings:b"Hello",b"with \x65\x73\x63\x61\x70\x65\x73\n",br#"raw, too"#
• Booleans:true,false
• Chars:'e','\n'
• Optionals:Some("string"),Some(Some(1.34)),None
• Tuples:("abc", 1.23, true),()
• Lists:["abc", "def"]
• Structs:( foo: 1.0, bar: ( baz: "I'm nested" ) )
• Maps:{ "arbitrary": "keys", "are": "allowed" }

Note: Serde's data model represents fixed-size Rust arrays as tuple (instead of as list)

RON also supports several extensions, which are documentedhere.

RON's formal and complete grammar is availablehere.

There also is a very basic, work in progress specification available onthe wiki page.

{"materials": {"metal": {"reflectivity":1.0        },"plastic": {"reflectivity":0.5        }   },"entities": [        {"name":"hero","material":"metal"        },        {"name":"monster","material":"plastic"        }   ]}

Scene(// class name is optionalmaterials: {// this is a map"metal": (reflectivity:1.0,        ),"plastic": (reflectivity:0.5,        ),    },entities: [// this is an array        (name:"hero",material:"metal",        ),        (name:"monster",material:"plastic",        ),    ],)

Note the following advantages of RON over JSON:

• trailing commas allowed
• single- and multi-line comments
• field names aren't quoted, so it's less verbose
• optional struct names improve readability
• enums are supported (and less verbose than their JSON representation)

[dependencies]ron ="0.8"serde = {version ="1",features = ["derive"] }

use serde::{Deserialize,Serialize};#[derive(Debug,Deserialize,Serialize)]structMyStruct{boolean:bool,float:f32,}fnmain(){let x:MyStruct = ron::from_str("(boolean: true, float: 1.23)").unwrap();println!("RON: {}", ron::to_string(&x).unwrap());println!("Pretty RON: {}", ron::ser::to_string_pretty(&x, ron::ser::PrettyConfig::default()).unwrap(),);}

RON is not designed to be a fully self-describing format (unlike JSON) and is thus not guaranteed to work whendeserialize_any is used instead of its typed alternatives. In particular, the following Serde attributes only have limited support:

• #[serde(tag = "tag")], i.e. internally tagged enums¹
• #[serde(tag = "tag", content = "content")], i.e. adjacently tagged enums¹
• #[serde(untagged)], i.e. untagged enums¹
• #[serde(flatten)], i.e. flattening of structs into maps²

While data structures with any of these attributes should generally roundtrip through RON, some restrictions apply³ and their textual representation may not always match your expectation:

• ron only supports string keys inside maps flattened into structs
• internally (or adjacently) tagged or untagged enum variants or#[serde(flatten)]ed fields must not contain:
  • struct names, e.g. by enabling the#[enable(explicit_struct_names)] extension or thePrettyConfig::struct_names setting
  • newtypes
  • zero-length arrays / tuples / tuple structs / structs / tuple variants / struct variants
    • Options with#[enable(implicit_some)] must not contain any of these or a unit, unit struct, or an untagged unit variant
  • externally tagged tuple variants with just one field (that are not newtype variants)
  • tuples or arrays or tuple structs with just one element are not supported inside newtype variants with#[enable(unwrap_variant_newtypes)] (includingSome)
  • aron::value::RawValue
• untagged tuple / struct variants with no fields are not supported
• untagged tuple variants with just one field (that are not newtype variants) are not supported when the#![enable(unwrap_variant_newtypes)] extension is enabled
• serializing aron::value::RawValue using aPrettyConfig may add leading and trailing whitespace and comments, which theron::value::RawValue absorbs upon deserialization

Furthermore, serde imposes the following restrictions for data to roundtrip:

• structs or struct variants that contain a#[serde(flatten)]ed field:
  • are only serialised as maps and deserialised from maps
  • must not contain duplicate fields / keys, e.g. where an inner-struct field matches an outer-struct or inner-struct field
  • must not contain more than one (within the super-struct of all flattened structs)#[serde(flatten)]ed map field, which collects all unknown fields
  • if they contain a#[serde(flatten)]ed map, they must not contain:
    • a struct that is not flattened itself but contains some flattened fields and is flattened into the outer struct (variant)
    • an untagged struct variant that contains some flattened fields
    • a flattened externally tagged newtype, tuple, or struct variant, flattened internally tagged unit, newtype, or struct variant, or any flattened adjacently tagged variant
    • a flattened tagged struct
• internally (or adjacently) tagged or untagged enum variants or#[serde(flatten)]ed fields must not contain:
  • i128 oru128 values
• internally tagged newtype variants and#[serde(flatten)]ed fields must not contain:
  • a unit or a unit struct inside an untagged newtype variant
  • an untagged unit variant
• internally tagged newtype variants, which are#[serde(flatten)]ed together with other fields, must not contain:
  • a unit or unit struct or an untagged unit variant

Please file anew issue if you come across a use case which is not listed among the above restrictions but still breaks.

While RON guarantees roundtrips like Rust -> RON -> Rust for Rust types using non-deserialize_any-based implementations, RON does not yet make any guarantees about roundtrips throughron::Value. For instance, even when RON -> Rust works, RON ->ron::Value -> Rust, or RON ->ron::Value -> RON -> Rust may not work. We plan on improvingron::Value in an upcoming version of RON, though this work is partially blocked onserde#1183.

RON is dual-licensed under Apache-2.0 and MIT.

Any contribution intentionally submitted for inclusion in the work must be provided under the same dual-license terms.