패키지, 저장소 및 앱 카테고리 검색

패키지 상세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 호환성
  • 중첩 테이블 및 배열 지원
  • 사용이 간편한 파싱 및 인코딩 메서드
  • 플랫폼에 관계없는 구현
  • 경량이고 빠름

적합한 대상

  • 구조화된 구성 파일이 필요한 앱
  • JSON/YAML 대신 TOML을 선호하는 개발자
  • 크로스 플랫폼 프로젝트
  • 구성 기반 애플리케이션
  • 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 개

소스 저장소

이 패키지를 사용하는 프로젝트