Simple Config

文档

一种为人类设计的非自描述配置语言。

Simple Config 不特定于 Rust 或 serde，但已知的唯一实现同时使用这两者。

为什么使用 Simple Config？

Simple config 基于这样的概念：您不需要能够从配置文件中形成模式。这已经非常常见，但形式更为随意，例如，您可能使用 JSON 字符串来存储日期，如 "1990-02-14"。Simple Config 利用这一点提供更丰富的类型和更少的转义。例如，多行字符串不需要额外的标记，模式表明它是字符串，因此不会尝试将其解析为字典。同样，您不会遇到类型错误，因为 false 或 no 被解析为布尔值，您也不必担心带数字开头的字符串的引号。

为什么不使用 Simple Config？

• 没有模式不能解析。（注意：可以跳过未知项，但不能进行语义解析。）
• 不支持代码重用。Simple Config 适用于相对简单的配置文件，其中不需要重用。
• 目前不支持序列化。

示例

这是一个小型示例，展示了模式（作为 Rust 代码）和配置（作为字符串字面量）。有关完整说明，请参阅下文。

#[derive(Debug,PartialEq,serde::Deserialize)]
enum Country {
	CA,
	US,
	NO,
}

#[derive(Debug,PartialEq,serde::Deserialize)]
#[serde(rename_all="kebab-case")]
enum Contact {
	Email(String),
	Matrix(String),
	Phone{
		number: u64,
		#[serde(default)]
		extension: Option<u64>,
	},
}

#[derive(Debug,PartialEq,serde::Deserialize)]
#[serde(rename_all="kebab-case")]
struct Contestant {
	contact: Vec<Contact>,
	country: Country,

	#[serde(with = "humantime_serde")]
	personal_best: std::time::Duration,

	#[serde(with = "humantime_serde")]
	last_seen: std::time::SystemTime,
}

let t: std::collections::BTreeMap<String, Contestant> = simple_config::from_bytes("

kevincox:
	contact:
		:
			email: [email protected]

		:
			phone:
				number: 18005551234
	country: CA
	personal-best: 1h 13min
	last-seen: 2021-06-08 00:00:00Z
sarah:
	contact:
		:
			matrix: @me:matrix.example
	country: NO
	personal-best: 73min
	last-seen: 2019-06-30 07:24:30Z

").unwrap();

assert_eq!(t, std::array::IntoIter::new([
	("kevincox".to_owned(), Contestant {
		contact: vec![
			Contact::Email("[email protected]".into()),
			Contact::Phone{number: 18005551234, extension: None},
		],
		country: Country::CA,
		personal_best: std::time::Duration::from_secs(1*3600 + 13*60),
		last_seen: std::time::UNIX_EPOCH + std::time::Duration::from_secs(1623110400),
	}),
	("sarah".to_owned(), Contestant {
		contact: vec![
			Contact::Matrix("@me:matrix.example".into()),
		],
		country: Country::NO,
		personal_best: std::time::Duration::from_secs(73*60),
		last_seen: std::time::UNIX_EPOCH + std::time::Duration::from_secs(1561879470),
	}),
]).collect());

有关更多示例，请参阅 示例目录。请注意，此目录中的一些示例是对现有数据结构的重新实现，可能包含与先前配置语言的兼容性黑客，导致 Simple Config 中的呈现不佳。

参考

字典

key: value

字典是将键映射到值的映射。键始终是单行值，不包含冒号后的冒号，然而确切的解析取决于类型。

# The type of the key depends on the schema, but these examples can be parsed as the specified type.
true: boolean key
123: integer key
hello: string key

值可以是任意类型。指定值有两种方式。这些值如何解析取决于类型。

key: inline value
key:
	multi
	line
	value

有关解析的完整参考，请参阅值的类型文档。

嵌套

当嵌套时，值必须指定为多行值。

vehicle:
	type: Car
	engine:
		capacity_cc: 200
		mass_g: 60k
	wheels:
		diameter_m: 550m

列表

列表包含多个值。根据模式，顺序可能重要或不重要。

strings:
	string one
	string two
	string three
numbers:
	1
	1k
	1M

默认情况下，列表项是单行长的。要将多行项放入列表中，您必须使用:字符打开一个新级别的缩进。可以混合单行和多行项。请注意，字典必须是多行的。

strings:
	single line string
	:
		multi
		line
		string
	another single line string
dicts:
	:
		species: Cat
		cuteness: 0.99
	:
		species: Dog
		cuteness: 0.8

字符串

字符串可以是单行或多行。目前不允许或必要进行转义，字符串在换行符或注释（#）之前结束，哪个先出现。然而，以双引号"开始的单行字符串是为将来的转义功能保留的。多行字符串将删除前导缩进。请注意，多行字符串中没有特殊字符，包括注释。如果您想在多行字符串中放入注释，则需要使用目标注释格式。

inline: a string # This comment is not part of the string.
out-of-line:
	a string
multi-line: # This comment is not part of the string.
	this
		is
	a
		string
no-comments:
	# This comment is a part of the string.

警告：目前无法指定第一行缩进的字符串。

# WARNING: This example is invalid.
doesnt-work:
		indented first line
	non-indented line

数字

数字可以像预期的那样指定。此外，支持许多后缀以缩放数字。对于相关类型，整数超出范围是错误的。浮点值将是可表示的最近值。

simple-int: 123
simple-float: 3.14

base2: 0b01001011
base8: 0o664
base16: 0xCC

# Currently arbitrary exponents are only supported for base10.
exponents:
	6.022e1023 # 6.022 ⨉ 10^1023
	2.5e-11 # 2.5 ⨉ 10^-11

si-suffixes:
	1E
	1P
	1T
	1G
	1M
	1k # K is also accepted for consistency.
	1m
	1u
	1µ
	1n
	1p
	1f
	1a

iec-sufixes:
	1Ei
	1Pi
	1Ti
	1Gi
	1Mi
	1ki # Ki is also accepted for consistency.
	1mi
	1ui
	1µi
	1ni
	1pi
	1fi
	1ai

布尔值

布尔值指定为true或false。

字节

目前不支持字节。https://gitlab.com/kevincox/simple-config-rs/-/issues/1

可选值

可以指定为空值。

注意：目前无法为Option<String>指定空字符串，它始终表示None。

maybe_none:
maybe_some: 17

# comment
a-number: # comment
	5
another-number: 5 # comment

a-string: # comment
	hi
multi-line-string: # comment
	hi # NOT COMMENT
	# NOT COMMENT
# comment

list: # comment
	1 # comment
	# comment
	2

# comment