搜索插件、代码仓与 APP 分类

插件详情v0.18.0

toml

TOML v1.0.0(Tom 的明显、最小语言)配置文件的解析器和编码器。

AndroidiOSWebmacOSWindowsLinux
近 30 天下载
44.7万
喜欢数
35
Pub 分数
160

安装插件

flutter pub add toml

插件介绍

基于插件公开信息、社区数据与项目使用情况整理的选型参考。

一个用于解析和编码 TOML(Tom 的明显、最小语言)配置文件的 Flutter/Dart 包,符合 TOML v1.0.0 标准。它可实现对结构化配置数据的无缝读写,格式易于人类阅读。适用于需要外部配置管理的应用程序,例如环境设置或应用偏好。该包支持所有主要平台,包括 Android、iOS、Web、macOS、Windows 和 Linux。轻量级且可通过 pub.dev 轻松集成。

适合场景

  • 读取应用程序配置文件
  • 以 TOML 格式编写配置数据
  • 存储环境特定的设置
  • 从 JSON/YAML 迁移到 TOML
  • 跨平台配置管理

主要特点

  • TOML v1.0.0 兼容性
  • 支持嵌套表格和数组
  • 易于使用的解析和编码方法
  • 平台无关的实现
  • 轻量且快速

适合对象

  • 需要结构化配置文件的应用程序
  • 偏好 TOML 而非 JSON/YAML 的开发者
  • 跨平台项目
  • 配置驱动的应用程序
  • CLI 工具需要配置

使用建议

  • 不适用于二进制数据存储
  • 仅限配置使用场景
  • 需要有效的 TOML 语法
  • 除了解析之外没有内置验证
  • 最好与静态或已知的架构配置一起使用

原始 README

以下为关联源码仓库的 README 原文快照,最新内容请访问源码仓库。

toml.dart

Dart CI Coverage Status Pub Package GitHub License

This package provides an implementation of a TOML parser and encoder for Dart.

It currently supports version 1.1.0 of the TOML specification.

Table of Contents

  1. Installation
  2. Usage
    1. Loading TOML
    2. Parsing TOML
    3. Decoding TOML
    4. Encoding TOML
  3. Data Structure
    1. Table and Inline Table
    2. Array and Array of Tables
    3. String
    4. Integer
    5. Float
    6. Boolean
    7. Offset Date-Time
    8. Local Date-Time
    9. Local Date
    10. Local Time
  4. Testing
  5. License

Installation

To get started add toml as a dependency to your pubspec.yaml and run the dart pub get or flutter pub get command.

dependencies:
  toml: "^0.18.0"

Usage

The toml.dart package can be used for loading, decoding and encoding TOML documents. To get started, just add the following import.

import 'package:toml/toml.dart';

The subsequent sections describe how to use the library in more detail. Additional examples can be found in the ./example directory.

Loading TOML

In order to load a TOML document, invoke the static TomlDocument.load method and pass the name of the configuration file to load. The method returns a Future of the loaded TomlDocument.

void main() async {
  var document = await TomlDocument.load('config.toml');
  // ...
}

When the code is running in the browser, package:web is used to fetch the configuration file via HTTP. When the code is running on the Dart VM or natively, the file is loaded from the local file system.

If the loaded TOML file contains a syntax error, a TomlParserException is thrown.

Full examples for loading a configuration file via HTTP and from a file can be found in ./example/http_config_loader and ./example/filesystem_config_loader, respectively.

Parsing TOML

Sometimes the two default mechanisms for loading TOML documents with TomlDocument.load are not sufficient. In those cases, you can simply load the contents of the configuration file yourself and parse them as a TOML document manually using the static TomlDocument.parse function.

void main() {
  var contents = '...';
  var document = TomlDocument.parse(contents);
  // ...
}

If the loaded TOML file contains a syntax error, a TomlParserException is thrown.

An example for writing a custom configuration file loader and parsing the loaded file manually can be found in ./example/toml_parser.

Decoding TOML

In the last two subsections we've learned how to load or parse a TomlDocument. Such a TomlDocument is an abstract representation of the syntax of a TOML document. In order to access the configuration options that are stored in the TOML document, we first have to convert it to a hash map with the TomlDocument.toMap method.

void main() {
  var config = TomlDocument.parse('...').toMap();
  // ...
}

If the TOML document is semantically invalid, a TomlException is thrown.

In the next section the type and structure of the generated hash map will be elaborated in more detail.

Encoding TOML

This package also includes a TOML encoder that can convert a hash map to a TOML document. Simply use the TomlDocument.fromMap factory constructor to convert the hash map into the internal representation. The resulting document can be converted to a TOML encoded string using the toString method.

var document = TomlDocument.fromMap({
  // ...
}).toString();

The type and structure of the hash map should match the format described in the next section. Additionally, the map may contain arbitrary keys and values that implement the TomlEncodableKey and TomlEncodableValue interfaces, respectively. Classes which implement those interfaces must define a toTomlKey or toTomlValue method, whose return value is either implements the interface itself or is natively encodable by TOML. If an object cannot be encoded as a TOML key or value, a TomlUnknownKeyTypeException or TomlUnknownValueTypeException is thrown by TomlDocument.fromMap.

An example for using the encoder and the TomlEncodableValue interface to encode a Map can be found in ./example/toml_encoder.

Data Structure

This section describes how the decoder (i.e., TomlDocument.toMap) maps TOML values to Dart values and which Dart values are accepted by the encoder (i.e., TomlDocument.fromMap).

Table and Inline Table

TOML documents and tables including inline tables are represented through nested Map objects whose keys are Strings and values dynamic representations of the corresponding TOML value or sub-table.

For example, given the following TOML document

[parent.table]
key = 'value'

the decoder produces the following Map.

<String, dynamic>{
  'parent': <String, dynamic>{
    'table': <String, dynamic>{'key': 'value'}
  }
}

The encoder does not require all keys to have the static type String. A map of type Map<MyKey, dynamic> can be encoded, provided that the class MyKey implements the TomlEncodableKey interface. The encoder never produces inline-tables or dotted keys at the moment.

Array and Array of Tables

The decoder produces List objects for all kinds of arrays including arrays of tables. For example, given the following TOML document

[[items]]
name = 'A'

[[items]]
name = 'B'

[[items]]
name = 'C'

the decoder produces the following List.

<String, dynamic>{
  'items': [
    <String, dynamic>{'name': 'A'},
    <String, dynamic>{'name': 'B'},
    <String, dynamic>{'name': 'C'},
  ]
}

The encoder accepts any Iterable.

String

All string variants produce regular dart Strings. For example, all strings in the listing below map to the Dart value 'Hello, World!'.

str1 = "Hello, World!"
str2 = 'Hello, World!'
str3 = """\
  Hello, \
  World!\
"""
str4 = '''
Hello, World!'''

The encoder preferably generates literal strings. If a string contains apostrophes or other characters that are not allowed in literal strings, a basic string is produced instead. Strings that contain newlines produce multiline strings. Whether a multiline literal or multiline basic string is generated depends on the remaining characters in the string. All produced multiline strings start with a trimmed newline and multiline basic strings never contain escaped whitespace.

If you need more control over the type of string that is produced by the encoder, you can wrap the value with a TomlLiteralString, TomlBasicString, TomlMultilineLiteralString or TomlMultilineBasicString.

Integer

Integers are represented by ints or BigInts.

The decoder produces an int only if the number can be represented losslessly by an int. Whether a number can be represented by an int is platform specific. When the code is running in the VM, numbers between -2^63 and 2^63 - 1 can be represented as an int. In JavaScript, only numbers in the range from -(2^53 - 1) to 2^53 - 1 are guaranteed to be converted to int but smaller or larger numbers may still produce an int if they can be represented without loss of precision.

The encoder accepts either representation and uses the decimal integer format by default. If you need more control over the format used by the encoder, the value has to be wrapped in a TomlInteger.

For example, the following map

<String, dynamic>{
  'decimal': 255,
  'hexadecimal': TomlInteger.hex(255)
}

is encoded as shown below.

decimal = 255
hexadecimal = 0xff
Float

Floating point numbers are represented as doubles. The special floating point values inf, -inf and nan are mapped to double.infinity, double.negativeInfinity and double.nan, respectively. The value -nan is also mapped to double.nan.

When compiled to JavaScript, a double without decimal places cannot be distinguished from an int. Thus, the encoder produces an integer for double values without decimal place. If you want to force a JavaScript number to be encoded as a float, it has to be wrapped in a TomlFloat.

Boolean

Boolean values are represented as values of type bool. The encoder produces the TOML values true and false.

Offset Date-Time

Offset Date-Time values are represented by the TomlOffsetDateTime class. They can be converted to a UTC DateTime object with the toUtcDateTime method.

The encoder accepts TomlOffsetDateTime as well as DateTime objects. A UTC DateTime is encoded as a offset date-time in the UTC time-zone. A local DateTime is encoded as a offset date0time in the local time-zone. For example, the following dates

<String, dynamic>{
  'utc': DateTime.utc(1969, 7, 20, 20, 17),
  'local': DateTime(1969, 7, 20, 20, 17),
}

are encoded as shown below when the code runs in the UTC+01:00 time-zone.

utc = 1969-07-20 20:17:00Z
local = 1969-07-20 20:17:00+01:00
Local Date-Time

Local Date-Time values are represented by the TomlLocalDateTime class. Before they can be converted to a DateTime, you must provide a time-zone information in which to interpret the date-time. For example, to interpret a local date-time in the time-zone the code is running in, type the following.

localDateTime.withOffset(TomlTimeZoneOffset.local()) // interpret in local time-zone

To interpret the local date-time value in a specific time-zone, write the following for example.

localDateTime.withOffset(TomlTimeZoneOffset.positive(1, 0)) // interpret in UTC+01:00

In both cases the result is a TomlOffsetDateTime that can be converted to a DateTime as described above. The encoder accepts TomlLocalDateTime objects only, i.e., a DateTime will never be encoded as a local date-time automatically.

Local Date

Local Date values are represented by the TomlLocalDate class. Before they can be converted to a DateTime, both a time and time-zone offset have to be provided. First add a time with the atTime method and use withOffset from the resulting TomlLocalDateTime to obtain a offset date-time that can then be converted to a DateTime.

localDate.atTime(time).withOffset(timeZoneOffset)
Local Time

Local Time values are represented by the TomlLocalTime class. Before they can be converted to a DateTime, both a date and time-zone offset have to be provided. First add a date with the atDate method and use withOffset from the resulting TomlLocalDateTime to obtain a offset date-time that can then be converted to a DateTime.

localTime.atDate(date).withOffset(timeZoneOffset)

Testing

To see whether everything is working correctly change into the root directory of this package and run the included tests as follows:

dart test

You may pass the --platform command line argument to test the package on other platforms than the VM. Run dart test --help for a list of all available platforms.

Additionally, the language-agnostic test suite toml-test is supported. To speedup the tests, it is recommended to compile the encoder and decoder scripts first.

mkdir -p build/bin
dart compile exe -o build/bin/decoder bin/decoder.dart
dart compile exe -o build/bin/encoder bin/encoder.dart

Then run the tests as follows.

toml-test build/bin/decoder
toml-test -encoder build/bin/encoder

License

toml.dart is licensed under the MIT license agreement. See the LICENSE file for details.

所属分类

依赖

依赖清单 4 项

源码仓库

使用此插件的项目