khonsulabs / rsn

Rsn - Rusty Notation

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

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?

Other related projects

• 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.

rsn's Issues

link to Vim/Neovim plugin

https://github.com/ModProg/rsn.vim

Omit top level struct

This one I'm not sure about, but for a config file it feels quite nice:

1. Remove redundant information (90% of config files would be a struct anyway)
2. Remove unnecessary first indentation (granted, this could be achieved by making the default formatting:

{
a: {
    b: "hello"
}
}

but I'm not the biggest fan of that.)

Contra would be that this is a clear breakage to the rust like syntax, and it requires looking ahead till the first : to figure out, if the file root is a struct or a single value (thought the latter would be a single token AFAICT so probably not too bad to check).
Mainly the former is the reason though why I am a bit conflicted about this suggestion.

A “nondestructive” or modifying serializer

I was experimenting with this idea for TOML (https://play.rust-lang.org/?version=stable&mode=debug&edition=2021&gist=dbda15adfbdf58defcaf2c5707a3a033).
While obviously worse from a performance standpoint, I think having a Serializer that preserves whitespace and comments if possible and only updates modified values could be quite neat.

Json compatibility

Rsn is kindof a superset of json.

Not sure what the differences in encoding and string escaping are. But maybe we could have a json compatibility Output mode.

we could consider supporting `f*::Inf` and `f*::NaN`

In the positive case this would be no different from generic support for path::Ident but in the negative case this would require special handling. Feel free to ignore this, just crossed my mind.

would it make sense to have a `std` feature that enables `std::error::Error` implementations?

Add support for indexmap

It would be nice if rsn supported indexmap (through a feature flag) so it can be used for serializing when field order matters.

Raw strings shouldn't require a #

When I wrote rsn, I thought the minimal raw string in Rust was r#""#, but at some point Clippy started warning about unnecessary hashes. Apparently, r"" is the shortest raw string, but rsn currently errors when given a raw string with no hashes.