module RemiLib::RSConf

Overview

RSConf is a data serialization format that's somewhere in-between JSON and hjson. It has a few more features than JSON that make it nicer for config files, such as comments, not needing commas, and unquoted strings. But it it's less strict and has fewer features than hjson to keep parsing simple.

It was created to fill a niche and scratch an itch for a nice, easy-to-use config format that doubles as a data serialization format. JSON is nice and (usually) easy to visually parse as a human, but is too strict with its syntax, and doesn't have comments. YAML is nice, but has far too many bells and whistles, leading to all sorts of strange edge cases, and a large space for possible security problems. TOML is just ugly and hard to visually parse once it gets complex. Hjson is nice, but has just a few too many unnecessary features, and is a bit too flexible. Thus, RSConf was born to fill the hole left by these other formats.

As a high-level overview, RSConf is like JSON, but:

• Keys don't need quoting if they do not contain spaces.
• Commas don't need to come after values/key-value pairs unless there are multiple values/key-value pairs on the same line.
• Toplevel braces ({ and }) can be omitted if the toplevel is an object.
• Integers and floats are differentiated.
• Integers can be in hex, octal, or binary. Floats can be in decimal or "scientific notation" (and accept either e or d for their character).
• The null value is called nil.
• Comments are allowed and use semicolons (;)
• Explicit minimum limits for integers and floats.
• Stricter whitespace.

It is also a lot like hsjon, except:

• All strings are multi-line strings; no separate syntax.
• No quoteless strings.
• Integers can be in hex, octal, or binary. Floats can be in decimal or "scientific notation" (and accept either e or d for their character).
• The null value is called nil.
• Comments are allowed and use semicolons (;)
• No multi-line comments.
• Explicit minimum limits for integers and floats.
• Slightly stricter whitespace.

The reference implementation for RSConf is in Common Lisp and is part of the sibling library to libremiliacr, CL-SDM. This is a direct port of that reference implementation, adapted to Crystal.

Some well-formatted example RSConf data:

;;;;
;;;; Example Document
;;;;

some-object: {
  values: [ 1, 2, 3] ;; Recommended syntax for short arrays

  ;; Better syntax for larger arrays, or ones with long values.
  values-2: [
    "foo"
    "bar"
    "baz"
  ]

  name: "test"
  sub-obj: {
    id: 1, ;; Comma here is optional
    enabled: false ;; or "true"
    something-else: nil ;; Null values are represented with "nil"
  }
}

Defined in:

remilib/rsconf.cr
remilib/rsconf/builder.cr
remilib/rsconf/common.cr
remilib/rsconf/parser.cr
remilib/rsconf/serializable.cr
remilib/rsconf/writer.cr