Skip to content

Getting Started

Jump to bottom
GroundbreakingMC edited this page Oct 3, 2025 · 1 revision

Getting Started

This guide will help you start using TOMLy in your project.

Your First TOML Parse

The simplest way to use TOMLy is parsing a string:

import com.github.groundbreakingmc.tomly.Tomly;
import com.github.groundbreakingmc.tomly.nodes.TomlDocument;
import com.github.groundbreakingmc.tomly.options.PreserveOptions;

String toml = """
    name = "MyApp"
    version = "1.0.0"
    debug = true
    """;

TomlDocument doc = Tomly.parse(toml, false, PreserveOptions.defaultOptions());

The parse method takes three parameters:

  • toml - the TOML content as a String
  • debug - whether to enable debug mode (comment preservation)
  • options - preservation options for parsing

Accessing Values

Use type-safe getters to access values:

// Simple values
String name = doc.getStr("name");        // "MyApp"
String version = doc.getStr("version");  // "1.0.0"
Boolean debug = doc.getBool("debug");    // true

With Default Values

Provide defaults for missing keys:

String name = doc.getStr("name", "DefaultApp");
int timeout = doc.getInt("timeout", 30);
boolean debug = doc.getBool("debug", false);

Nullable vs Non-Nullable

Methods without defaults return nullable types:

String name = doc.getStr("name");  // Returns null if missing
Integer port = doc.getInt("port"); // Returns null if missing

Methods with defaults return non-nullable primitives:

int port = doc.getInt("port", 8080);         // Returns 8080 if missing
boolean debug = doc.getBool("debug", false); // Returns false if missing

Parsing from File

For configuration files, parse directly from a Path:

import java.nio.file.Path;

Path configPath = Path.of("config.toml");
TomlDocument config = Tomly.parse(configPath, false, PreserveOptions.defaultOptions());

Example config.toml:

# Application Configuration
app_name = "MyApp"
version = "1.0.0"

[server]
host = "localhost"
port = 8080

[database]
url = "jdbc:postgresql://localhost:5432/mydb"
username = "admin"
password = "secret"

Accessing Nested Values

Using Dot Notation

The simplest way to access nested values:

String host = doc.getStr("server.host");     // "localhost"
int port = doc.getInt("server.port", 8080);  // 8080
String dbUrl = doc.getStr("database.url");   // "jdbc:postgresql://..."

Navigating to Sections

For multiple accesses to the same section, navigate once:

// Less efficient - parses path multiple times
String host = doc.getStr("server.host");
int port = doc.getInt("server.port");
int timeout = doc.getInt("server.timeout");

// More efficient - navigate once
TomlDocument server = doc.getSection("server");
String host = server.getStr("host");
int port = server.getInt("port");
int timeout = server.getInt("timeout");

Working with Different Types

Numbers

String toml = """
    count = 42
    price = 19.99
    large = 9223372036854775807
    """;

TomlDocument doc = Tomly.parse(toml, false, PreserveOptions.defaultOptions());

Integer count = doc.getInt("count");   // 42
Double price = doc.getDbl("price");    // 19.99
Long large = doc.getLong("large");     // 9223372036854775807

Lists

String toml = """
    ports = [8080, 8081, 8082]
    hosts = ["localhost", "127.0.0.1"]
    enabled = [true, false, true]
    """;

TomlDocument doc = Tomly.parse(toml, false, PreserveOptions.defaultOptions());

IntList ports = doc.getIntList("ports");          // [8080, 8081, 8082]
List<String> hosts = doc.getStrList("hosts");     // ["localhost", "127.0.0.1"]
BooleanList enabled = doc.getBoolList("enabled"); // [true, false, true]

Date and Time

String toml = """
    release_date = 2025-10-01
    start_time = 09:30:00
    created_at = 2025-10-01T09:30:00
    updated_at = 2025-10-01T09:30:00+02:00
    """;

TomlDocument doc = Tomly.parse(toml, false, PreserveOptions.defaultOptions());

LocalDate release = doc.getLocalDate("release_date");
LocalTime start = doc.getLocalTime("start_time");
LocalDateTime created = doc.getLocalDateTime("created_at");
OffsetDateTime updated = doc.getOffsetDateTime("updated_at");

Complete Example

Here's a complete application configuration example:

import com.github.groundbreakingmc.tomly.Tomly;
import com.github.groundbreakingmc.tomly.nodes.TomlDocument;
import com.github.groundbreakingmc.tomly.options.PreserveOptions;

import java.nio.file.Path;

public class ConfigLoader {

    public static class AppConfig {
        public final String name;
        public final String version;
        public final ServerConfig server;
        public final DatabaseConfig database;
        
        public AppConfig(TomlDocument doc) {
            this.name = doc.getStr("app_name", "MyApp");
            this.version = doc.getStr("version", "1.0.0");
            
            TomlDocument serverDoc = doc.getSection("server");
            this.server = new ServerConfig(serverDoc);
            
            TomlDocument dbDoc = doc.getSection("database");
            this.database = new DatabaseConfig(dbDoc);
        }
    }
    
    public static class ServerConfig {
        public final String host;
        public final int port;
        
        public ServerConfig(TomlDocument doc) {
            this.host = doc.getStr("host", "localhost");
            this.port = doc.getInt("port", 8080);
        }
    }
    
    public static class DatabaseConfig {
        public final String url;
        public final String username;
        public final String password;
        
        public DatabaseConfig(TomlDocument doc) {
            this.url = doc.getStr("url", "jdbc:postgresql://localhost:5432/mydb");
            this.username = doc.getStr("username", "admin");
            this.password = doc.getStr("password", "");
        }
    }
    
    public static void main(String[] args) {
        Path configPath = Path.of("config.toml");
        TomlDocument doc = Tomly.parse(configPath, false, PreserveOptions.defaultOptions());
        
        AppConfig config = new AppConfig(doc);
        
        System.out.println("Application: " + config.name);
        System.out.println("Version: " + config.version);
        System.out.println("Server: " + config.server.host + ":" + config.server.port);
        System.out.println("Database: " + config.database.url);
    }
}

Next Steps

Clone this wiki locally