Crate rsn

Source
Expand description

§Rsn - Rusty Notation

This crate is very early in development. Please report any issues on our GitHub.

rsn forbids unsafe code rsn is considered alpha crate version Live Build Status HTML Coverage Report for main Documentation for main

A UTF-8 based text format that looks very similar to valid Rust code. This format adheres closely to Rust’s lexical rules

§no_std support

This crate supports no_std targets that support the alloc crate.

§Data Types

ExampleStruct {
  integers: [42, 0xFF, 0o77, 0b101],
  floats: [42., 3.14, 1e10],
  bools: [true, false],
  chars: ['a', '\''],
  string: "Hello, World!",
  raw_string: r#"I said, "Hello, World!""#,
  bytes: [b'a', b'\''],
  byte_string: b"Hello, World!",
  raw_byte_string: br#"I said, "Hello, World!""#,
  named_map: StructLike {
    field: 42,
  },
  named_tuple: TupleLike(42),
  r#raw_identifiers: true,
  array: [1, 2, 3],
  tuple: (1, 2, 3),
  map: {
    "a": 1,
    "b": 2,
  },
}

  • Integers (42, 0xFF, 0o77, 0b101)

  • Floats (42., 3.14)

  • Bool (true, false)

  • Character ('a', '\'')

  • Byte (b'a', b'\'')

  • String ("hello, world")

  • Raw Strings (r#"They said, "Hello World!""#)

  • Byte Strings (b"hello, world")

  • Named

    • Ident or Raw Ident (r#foo)
    • Map or Tuple

  • Map

    • List of <Value>: <Value> pairs, delimited by comma
    • Trailing comma is optional

  • Tuple (empty tuple = Unit)

    • List of <Value>s, delimited by comma
    • Trailing comma is optional

  • Array

    • List of <Value>s, delimited by comma
    • Trailing comma is optional

  • Comments // and /* */

  • Potential Extensions via #[] syntax

    • Semi-strict comma-delimited list
    • #[foo(...), bar = ...,]
    • All braces/brackets/parens must be paired correctly?
  • rsn-fmt: A formatter project for rsn.
  • rsn.vim: A plugin for Vim/NeoVim.

§Why not Ron?

Ron is a great format. There were a few design decisions that led to this very-similar-yet-not-the-same format being invented:

  • ron differentiates between Tuples and Lists, while rsn treats all sequences the same.
  • ron uses a different syntax for structures and maps. rsn uses the same syntax for both concepts.
  • ron has special support for Option<T>. rsn treats Option<T> like any other enum.
  • ron’s parsing rules are close but not the same as Rust, while rsn attempts to match implementations:
    • Unicode white space and idents (added in ron-rs/ron#444)
    • Rust allows _ in float literals
    • Rust allows for raw line endings to be escaped in string literals.
    • Rust supports byte strings and byte literals, while Ron elected to use base64 encoded strings for byte values.

§Differences between Rust syntax and Rsn

The syntax differs from valid Rust code for:

  • Map literals. Rust has no syntax for map literals.
  • Enum Variants being used without the type name – Red vs Color::Red
    • This is technically valid Rust syntax if use Color::* is present.
  • Infinity and Not-A-Number floats are represented as +inf/-inf/+NaN/-NaN.
    • For compatibility with Rust syntax, support for f64::INFINITY is being considered.

The rules for parsing literals should match Rust’s rules as closely as possible.

Modules§

de
Serde deserialization support.
parser
Parse data or a reader into a sequence of Rsn events.
ser
Serde serialization support.
tokenizer
Parse data or a reader into a sequence of tokens.
value
Types for generically representing the parsed value from an Rsn document.
writer
Types for writing Rsn.

Functions§

from_reader
Deserializes D from reader using the default Rsn Config.
from_slice
Deserializes D from slice using the default Rsn Config.
from_str
Deserializes D from source using the default Rsn Config.
to_string
Serializes value into a String using the default Rsn Config.
to_string_pretty
Serializes value into a String using Config::pretty().
to_vec
Serializes value into a Vec<u8> using the default Rsn Config.
to_writer
Serializes value into a writer using the default Rsn Config.