OVER

OVER: the best data format.

Table of Contents

OVER
- About
- Usage
- Examples
- Types
  - Null
  - Bool
  - Int
  - Frac
  - Char
  - Str
  - Arr
  - Tup
  - Obj
- What's wrong with JSON?
- What about YAML/others?
- Copyright

About

OVER is a general-purpose data format like XML or JSON, but much better. Here are some of its key features:

OVER is designed to be intuitive for humans to read and write without sacrificing flexibility.
It is powerful, with concepts such as variables, file includes, and object parents.
It has an elegant and versatile type system which can safely represent all common data.
It is resilient to errors by design and has no weird behavior or syntax like YAML or TOML.

Usage

Add OVER to your Cargo.toml:

toml [dependencies] over = "0.1.0"

Example Rust code reading the first example ("The Basics") from this README:

```rust extern crate fraction;

[macro_use]

extern crate over;

use fraction::Fraction; use over::obj::Obj;

[test]

fn example() { let obj = Obj::fromfile("tests/testfiles/example.over").unwrap();

assert_eq!(obj.get("receipt").unwrap(), "Oz-Ware Purchase Invoice");
assert_eq!(obj.get("date").unwrap(), "2012-08-06");
assert_eq!(
    obj.get("customer").unwrap(),
    obj_map!{"first_name" => "Dorothy",
             "family_name" => "Gale"}
);

assert_eq!(
    obj.get("items").unwrap(),
    arr_vec![
        obj_map!{"part_no" => "A4786",
                 "descrip" => "Water Bucket (Filled)",
                 "price" => Fraction::new(147u8, 100u8),
                 "quantity" => 4},
        obj_map!{"part_no" => "E1628",
                 "descrip" => "High Heeled \"Ruby\" Slippers",
                 "size" => 8,
                 "price" => Fraction::new(1337u16, 10u8),
                 "quantity" => 1},
    ]
);

assert_eq!(
    obj.get("bill_to").unwrap(),
    obj_map!{"street" => "123 Tornado Alley\nSuite 16",
             "city" => "East Centerville",
             "state" => "KS",
    }
);

assert_eq!(obj.get("ship_to").unwrap(), obj.get("bill_to").unwrap());

assert_eq!(
    obj.get("specialDelivery").unwrap(),
    "Follow the Yellow Brick Road to the Emerald City. \
     Pay no attention to the man behind the curtain."
);

} ```

Currently OVER has only been implemented for Rust; more languages may be supported in the future.

Examples

The Basics

A basic usage of OVER as a data format might look like this:

``` receipt: "Oz-Ware Purchase Invoice" date: "2012-08-06" customer: { firstname: "Dorothy" familyname: "Gale" }

items: [{ partno: "A4786" descrip: "Water Bucket (Filled)" price: 01.47 quantity: 4 } { partno: "E1628" descrip: "High Heeled \"Ruby\" Slippers" size: 8 price: 133.70 quantity: 1 } ]

bill_to: { street: # A multi-line string. Can also be written as "123 Tornado Alley\nSuite16" "123 Tornado Alley Suite 16" city: "East Centerville" state: "KS" }

shipto: billto

specialDelivery: "Follow the Yellow Brick Road to the Emerald City. Pay no attention to the man behind the curtain." ```

This basic example already demonstrates a lot of nice features about OVER:

You can immediately tell what kind of data each field contains.
Multi-line strings require no special syntax; see bill_to.street.
Variables; see ship_to.
Comments (sounds simple, but JSON doesn't have them).

Containers

OVER has three container types: * An [array] where all elements must be of the same type of data (enforced by the parser). * A (tuple) which can hold elements of different types. * {Objects}.

The following is a valid array, as each sub-tuple is the same type:

[ ("Alex" 10) ("Alice" 12) ]

The following is not a valid array. Can you see why?

[ ("Morgan" 13) ("Alan" 15 16) ]

Variables

Fields defined in an object can be referenced later, but only in the same scope of the object:

``` var: 2

number: var

obj: { number: var # Invalid! } ```

You can also define global variables. These are private and do not appear as fields in the final data:

``` @var: 2

number: @var

obj: { number: @var # Valid! } ```

Parents

An object can inherit the fields of another object. In the following example we define a template object called @default and define it to be the parent of foo and bar using the ^ field:

``` @default: { a: 1 b: 2 }

foo: { ^: @default b: 5 # Override the value of "b" inherited from "@default". # foo.a == 1 }

bar: { ^: @default a: 5 # Override the value of "a" inherited from "@default". # bar.b == 2 } ```

File Includes

Coming in the next release!

Arithmetic on Values and Variables

Coming soon!

String Substitutions

Coming soon!

Types

Null

A simple null value, represented by null.

Bool

true, or false. Take your pick.

Int

A 64-bit signed integer type. Any token beginning with -, +, or a numeral will be either an Int or a Frac (see below).

Examples: 1, -2, +4

Frac

A sane representation of decimal values. Forget about float types and use fractions instead.

Examples: -1/3, -5,1/4, +2,1/2, 42,6/1

Fracs can also be written as decimals, which get converted automatically to fraction representation.

Examples: 2.5, -.0

Char

A type representing a single, unicode character.

Examples: 'q', ' '

Str

A unicode string type.

Examples: "smörgåsbord", "A string with \"quotes\""

Multi-line strings are trivial:

"You don't need any special syntax for multi-line strings; newlines are captured automatically."

Arr

An array container which can hold an arbitrary number of elements of a single type.

Examples: [], [1 2 3], [(1 2) (3 4)]

Tup

A tuple container which can hold elements of different types.

Examples: (), (1 "John") ( ('x' 1/2) [1 2 3] )

Obj

The godfather of all types, the object. A hashmap of keys to values, where values can be any type, including other objects.

Examples: { id: 4 field: { field: "Objects can be nested and each has their own scope." } }

What's wrong with JSON?

I started this project because I wanted an alternative to JSON. Why?

The last element in a list cannot have a trailing comma.
What's with the opening/closing braces?
Floating-point numeric type.
Arrays where different types are allowed.
Field names have to be in quotes, e.g. "name": "Johnny" instead of name: "Johnny". It's verbose and not ergonomic.
Finally, no support for comments is a dealbreaker. Some JSON implementations allow them, but it's not standard.

JSON and other options are also lacking many of the features that I'm interested in, such as the ability to define variables and the concept of object parents.

What about YAML/others?

Let's compare the first example in this README ("The Basics") with the YAML version of the same data, taken from Wikipedia:

```yaml

receipt: Oz-Ware Purchase Invoice date: 2012-08-06 customer: firstname: Dorothy familyname: Gale

items: - part_no: A4786 descrip: Water Bucket (Filled) price: 1.47 quantity: 4

- part_no:   E1628
  descrip:   High Heeled "Ruby" Slippers
  size:      8
  price:     133.7
  quantity:  1

bill-to: &id001 street: | 123 Tornado Alley Suite 16 city: East Centerville state: KS

ship-to: *id001

specialDelivery: > Follow the Yellow Brick Road to the Emerald City. Pay no attention to the man behind the curtain. ... ```

As you can see, OVER is much more understandable, even if you're not at all familiar with it. The YAML version has strange syntax in some places (such as &id001 and *id001; plus, what in the world are > and | supposed to be?) and a lack of useful syntax in others (every value looks like a string). Is the "data" field a number or a string? YAML is certainly more pleasing on a superficial level, which I suspect is the only reason it entered into general use, but it fails to stand up to light scrutiny.

Look at this answer on StackExchange for an example of how unintuitive YAML is. Trust me, that's not even the worst of it; there is a shocking amount of weirdness in the official spec. This design disaster also makes it impossible to write an efficient parser for it.

Finally, as seen throughout this README, OVER manages to be more powerful than YAML while being much simpler! This may strike you as a paradox, but it is just a consequence of the thoughtless design of YAML and company (don't think I've forgotten about TOML). There are options such as StrictYAML but they are, in my opinion, just bandaids on a broken solution.