结束

结束：最佳数据格式。

目录

• 结束
  • 关于
  • 示例
  • 用法
  • 特性
    • 容器
    • 变量
    • 父类
    • 对象字段访问
    • 值和变量的算术运算
    • 文件包含
    • 字符串替换
  • 类型
    • 空值
    • 布尔值
    • 整数
    • 分数
    • 字符
    • 字符串
    • 数组
    • 元组
    • 对象
  • 待办事项
  • JSON 的问题是什么？
  • YAML/其他呢？
  • 变更日志
  • 版权

关于

结束是一个类似于 XML 或 JSON 的一般用途数据格式，但要好得多。以下是它的一些关键特性

• 结束被设计成既直观又灵活，便于人类阅读和编写。
• 它功能强大，具有变量、文件包含和对象父类等概念。
• 它有一个优雅且通用的类型系统，可以安全地表示所有常见的数据。
• 它设计上具有容错性，没有像 YAML 或 TOML 那样的奇怪行为或语法。

示例

作为数据格式的基本用法可能看起来像这样

receipt: "Oz-Ware Purchase Invoice"
date:    "2012-08-06"
customer: {
    first_name:  "Dorothy"
    family_name: "Gale"
}

items: [
        {
         part_no:  "A4786"
         descrip:  "Water Bucket (Filled)"
         price:    01.47
         quantity: 4
        }
        {
         part_no:  "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"
}

ship_to: bill_to

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

这个基本示例已经展示了结束的许多优点

• 您可以立即了解每个字段包含的数据类型。
• 多行字符串不需要特殊语法；请参阅 bill_to.street。
• 变量；请参阅 ship_to。
• 注释（听起来很简单，但 JSON 没有注释）。

用法

将结束添加到您的 Cargo.toml

[dependencies]
over = "*"

Rust 代码读取上述示例数据

#[macro_use]
extern crate over;

use over::obj::Obj;

#[test]
fn example() {
    let obj = Obj::from_file("tests/test_files/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!{"first_name" => "Dorothy",
             "family_name" => "Gale"}
    );

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

    assert_eq!(
        obj.get("bill_to").unwrap(),
        obj!{"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."
    );
}

目前结束仅实现了 Rust；将来可能支持更多语言。

特性

容器

结束有三个容器类型

• 一个 [数组]，其中所有元素必须具有相同的数据类型（由解析器强制执行）。
• 一个 (元组)，可以包含不同类型的元素。
• {对象}，包含字段到不同类型值的映射。

以下是一个有效的数组，因为每个子元组都是同一类型

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

以下不是一个有效的数组。你能看出为什么吗？

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

变量

在对象中定义的字段可以在后面引用，但只能在对象的作用域内

var: 2

number: var

obj: {
    number: var # Invalid!
}

您还可以定义全局变量。这些是私有的，不会出现在最终数据中的字段中

@var: 2

number: @var

obj: {
    number: @var # Valid!
}

父类

一个对象可以继承另一个对象的字段。在以下示例中，我们定义了一个名为 @default 的模板对象，并将其定义为 foo 和 bar 的父对象，使用 ^ 字段

@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
}

对象字段访问

可以使用点符号访问对象的字段。只要相关的对象在作用域内且字段存在，则此操作有效。示例

obj: {
    sub_obj: {
        secret_value: 0
    }
}

value: obj.sub_obj.secret_value

这允许一些很好的命名空间可能性

@colors: {
    red:   "#FF0000"
    green: "#00FF00"
    blue:  "#0000FF"
}

obj: {
    name: "Red monster"
    color: @colors.red
}

数组与元组也可以使用点符号进行索引。

tup: ("test" 0)

zero: tup.1
test: tup.zero

值和变量的算术运算

值和变量可以进行基本算术运算。可用的运算符有 +、-、*、/ 和 %，但并非所有运算符都可以应用于所有类型。运算符 *、/ 和 % 的优先级高于 + 和 -。

请注意，运算符和它们的操作数之间不能有空格。语言的语义是，值后的空格表示该值的结束。

以下是一个示例：

grid: 16
x: 18 y: 20
width: 4
height: 6

rectangle: (x-x%grid y-y%grid width*grid height*grid)

文件包含

为了体现模块化的精神，OVER 提供了一种分割文件的功能。通过示例可以最好地说明这一功能。

假设我们有两个对象，我们希望分别放在两个不同的文件中：

includes/obj1.over:

a: 1
b: 2
c: 3

includes/obj2.over:

a: 2
b: 3
c: 1

我们可以拥有一个类似于“主”文件的文件，其中包含两个子对象文件

main.over:

obj1: <"includes/obj1.over">
obj2: <"includes/obj2.over">

includes 的主要好处是方便和组织。我们还可以将数组和元组放入单独的文件中，这使得自动生成的空白分隔的值很容易包含进来。最后，字符串也可以放在它们自己的文件中，在这种情况下，它们将被逐字解析；不进行字符转义。这对于长字符串来说是一个非常方便的选项。

以下是一个演示包含 Str、Arr 和 Tup 的示例

main.over:

str: <Str "includes/str.over">
arr: <Arr "includes/arr.over">
tup: <Tup "includes/tup.over">

includes/str.over:

Multi-line string
which should be included verbatim
in another file. "Quotes" and $$$
don't need to be escaped.

includes/arr.over:

1 2 3 4 5

includes/tup.over:

1
'a'
3
'b'
5

关于文件包含的一些说明

• 全局变量在文件之间无效。
• 文件不能以循环方式包含；例如，如果文件 main 包含 sub-obj，那么 sub-obj 不能包含 main。
• 您可以多次包含相同的文件。文件包含只会在第一次遇到时进行处理。
• 包含仅对 Obj、Str、Arr 和 Tup 有效。当包含对象文件时，Obj 关键字是可选的。

字符串替换

即将推出！

类型

空值

一个简单的空值，表示为 null。

布尔值

true 或 false。任选其一。

整数

任意长度的有符号整数类型。任何以 -、+ 或数字开头的标记要么是 Int，要么是 Frac（见下文）。

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

---
receipt:     Oz-Ware Purchase Invoice
date:        2012-08-06
customer:
    first_name:   Dorothy
    family_name:  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.
...