百科.dev
全部条目在线工具AI 编程趋势榜开源项目技术资讯提交条目
登录
< 返回工具列表
T

toml4j

> 编程语言
开源

一个 Java TOML 解析器

356 stars0 点赞0 次浏览
访问官网GitHub

工具介绍

一个 Java TOML 解析器

toml4j

toml4j is a TOML 0.4.0 parser for Java.

For the bleeding-edge version integrating the latest specs, see the work-in-progress branch.

Installation

Add the following dependency to your POM (or equivalent for other dependency managers):

xml

  com.moandjiezana.toml
  toml4j
  0.7.2

If you use gradle, you can use the following code :

gradle
repositories {
  mavenCentral()
}

dependencies {
  ...
  implementation 'com.moandjiezana.toml:toml4j:0.7.2'
}

Requires Java 1.6 or above.

Quick start

java
Toml toml = new Toml().read(getTomlFile());
String someValue = toml.getString("someKey");
Date someDate = toml.getDate("someTable.someDate");
MyClass myClass = toml.to(MyClass.class);

Usage

A com.moandjiezana.toml.Toml instance is populated by calling one of read(File), read(InputStream), read(Reader), read(String) or read(Toml).

java
Toml toml = new Toml().read("a=1");

An exception is thrown if the source is not valid TOML.

The data can then be accessed either by converting the Toml instance to your own class or by accessing tables and keys by name.

Maps

Toml#toMap() is a quick way to turn a Toml instance into a Map.

java
Map map = new Toml().read("a=1").toMap();

Custom classes

Toml#to(Class) maps a Toml instance to the given class.

toml
name = "Mwanji Ezana"

[address]
  street = "123 A Street"
  city = "AnyVille"
  
[contacts]
  "email address" = "[email protected]"
java
class Address {
  String street;
  String city;
}

class User {
  String name;
  Address address;
  Map contacts;
}
java
User user = new Toml().read(tomlFile).to(User.class);

assert user.name.equals("Mwanji Ezana");
assert user.address.street.equals("123 A Street");
assert user.contacts.get("\"email address\"").equals("[email protected]");

Any keys not found in both the TOML and the class are ignored. Fields may be private.

Quoted keys cannot be mapped directly to a Java object, but they can be used as keys within a Map.

TOML primitives can be mapped to a number of Java types:

TOML Java
Integer int, long (or wrapper), java.math.BigInteger
Float float, double (or wrapper), java.math.BigDecimal
String String, enum, java.net.URI, java.net.URL
One-letter String char, Character
Multiline and Literal Strings String
Array List, Set, array. The generic type can be anything that can be converted.
Table Custom class, Map

Custom classes, Maps and collections thereof can be nested to any level. See TomlToClassTest#should_convert_fruit_table_array() for an example.

Key names

Use the getters to retrieve the data:

  • getString(String)
  • getDate(String)
  • getBoolean(String)
  • getLong(String)
  • getDouble(String)
  • getList(String)
  • getTable(String) returns a new Toml instance containing only the keys in that table.
  • getTables(String), for table arrays, returns List.

You can also navigate values within a table with a compound key of the form table.key. Use a zero-based index such as tableArray[0].key to navigate table arrays.

Non-existent keys return null.

When retrieving quoted keys, the quotes must be used and the key must be spelled exactly the same way, including quotes and whitespace. The only exceptions are Unicode escapes: "\u00B1" = "value" would be retrieved with toml.getString("\"±\"").

toml
title = "TOML Example"
"sub title" = "Now with quoted keys"

[database]
  ports = [ 8001, 8001, 8002 ]
  enabled = true
  [database.credentials]
    password = "password"
    
[servers]
  cluster = "hyades"
  [servers.alpha]
  ip = "10.0.0.1"
  
[[networks]]
  name = "Level 1"
  [networks.status]
    bandwidth = 10

[[networks]]
  name = "Level 2"

[[networks]]
  name = "Level 3"
  [[networks.operators]]
    location = "Geneva"
  [[networks.operators]]
    location = "Paris"
…

Defaults

The constructor can be given a set of default values that will be used as fallbacks. For tables and table arrays, a shallow merge is performed.

Toml#read(Toml) is used to merge two Toml instances:

java
Toml toml1 = new Toml().read("a=1");
Toml toml2 = new Toml().read(getTomlFile());

Toml mergedToml = new Toml(toml1).read(toml2);

You can also call an overloaded version of the getters that take a default value. Note that the default value provided in the constructor take precedence over the one provided by the getter.

toml
# defaults
a = 2
b = 3

[table]
  c = 4
  d = 5
toml
a = 1

[table]
  c = 2
  
[[array]]
  d = 3
…

Reflection

Toml#entrySet() returns a Set of Map.Entry instances. Modifications to the returned Set are not reflected in the Toml instance. Note that Map.Entry#setValue() will throw an UnsupportedOperationException.

java
for (Map.Entry entry : myToml.entrySet()) {
  System.out.println(entry.getKey() + " " + entry.getValue());
}

Toml#contains(String) verifies that the instance contains a key of any type (primitive, table or array of tables) of the given name. Toml#containsPrimitive(String), Toml#containsTable(String) and Toml#containsTableArray(String) return true only if a key exists and is a primitive, table or array of tables, respectively. Compound keys can be used to check existence at any depth.

java
Toml toml = new Toml().read("a = 1");

toml.contains("a"); // true
toml.conatinsKey("a"); // true
toml.containsTable("a"); // false
toml.containsTableArray("a"); // false

Converting Objects To TOML

You can write Maps and custom objects to a TOML String, File, Writer, or OutputStream with a TomlWriter. Each TomlWriter instance is customisable, immutable and threadsafe, so it can be reused and passed around. Constants and transient fields are ignored.

To write a List of objects as a table array, put the list in a Map or in a custom object.

java
class AClass {
  int anInt = 1;
  int[] anArray = { 2, 3 };
}

TomlWriter tomlWriter = new TomlWriter();
AClass obj = new AClass();

Map map = new HashMap();
int[] intArray = { 2, 3 };
map.put("anInt", 1);
map.put("anArray", intArray);

String tomlString = tomlWriter.write(obj);
tomlString = tomlWriter.write(map);

tomlWriter.write(obj, new File("path/to/file"));
tomlWriter.write(obj, new ByteArrayOutputStream());
tomlWriter.write(obj, new OutputStreamWriter(anOutputStream));

/*
All methods output:

anInt = 1
anArray = [2, 3]
*/

You can customise formatting with a TomlWriter.Builder:

java
class BClass {
 Map aMap = new HashMap();
}

BClass obj = new BClass();
obj.aMap.put("item", 1);

TomlWriter tomlWriter = new TomlWriter.Builder()
 .indentValuesBy(2)
 .indentTablesBy(4)
 .padArrayDelimitersBy(3)
 .build();
   
String tomlString = tomlWriter.write(obj);

/*
Output:

[aMap]
 item = 1
 
   [aMap.a]
     anInt = 1
     anArray = [   2, 3   ]
*/

Threadsafety

TomlWriter is threadsafe, however the JDK's streams and Writer are not. Take care not to write to the same stream in parallel.

Limitations

Date precision is limited to milliseconds.

Changelog

Please see the changelog.

Contributing

Please see the contribution guidelines.

License

toml4j is copyright (c) 2013-2015 Moandji Ezana and is licensed under the MIT License

Issues· 0 开放

查看全部 Issues在 GitHub 打开

暂无开放 Issues,或尚未同步最近议题。

> 标签

Java

暂无评论,来聊聊你的看法吧

> 工具信息

发布日期2026年8月1日
最后更新2026年9月17日
分类编程语言
定价开源

> 相关工具

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言