API Cheat Sheet

API Cheat Sheet

A one-page reference. See the linked pages for detail.

Open / lifecycle — Lifecycle, Reload & Watching

Config cfg = Config.open(path, codec);   // ABSENT / EMPTY / PARSE_FAILED_BACKED_UP / OK
cfg.save();  cfg.saveIfDirty();  cfg.saveAsync();
cfg.reload();                            // OK / ABSENT / PARSE_FAILED_KEPT
cfg.onReload(runnable).withAutoReload(Duration.ofSeconds(2));  cfg.stopAutoReload();
cfg.close();                             // AutoCloseable
cfg.lastLoadStatus();  cfg.isDivergedFromDisk();  cfg.getLastModified();  cfg.hasBeenModified();

Set / remove — The Dynamic API

cfg.setValue(path, value);               // null value deletes; auto-vivifies objects
cfg.setValue(path, value, comment);
cfg.removeValue(path);  cfg.clear(path); // boolean

Typed getters

getString  getInt  getLong  getDouble  getBoolean  getStringList  getList  getUUID   // + (path, default) forms
getValue(path)        // unwrapped scalar / node
getNode(path)         // raw JsonNode or null

Keys / sections

cfg.contains(path);
cfg.getKeys();  cfg.getKeys(path);  cfg.getKeys(path, true /*deep*/);
cfg.getConfigSection(path);          // always a view
cfg.getConfigurationSection(path);   // null if absent / not an object
cfg.getRoot();                       // live ObjectNode escape hatch

Defaults & comments — Default Values & Comments

cfg.getOrSetDefaultValue(path, def);
cfg.getOrSetDefaultValue(path, def, comment);   // seeds comment if absent
cfg.setComment(path, text);                     // authoritative (CommentType.BLOCK default)
cfg.setDefaultComment(path, text);              // set-if-absent
cfg.getComment(path);  cfg.getComment(path, CommentType.SIDE);
cfg.migrateKey(oldPath, newPath);

Binding — Entity Binding

T pojo = cfg.loadAs(Type.class, codec);                 // bind + @PostInject
EntityBinder<T> b = cfg.bind(Type.class, codec, opts);  // b.bind(); b.lastLoadIssues();
cfg.mergeFrom(pojo, codec);                             // merge into the tree

BindOptions.defaults()
    .withCoercion(BindOptions.Coercion.STRICT)          // or LENIENT (default)
    .withObsoletePolicy(BindOptions.ObsoletePolicy.REMOVE);  // or PRESERVE (default)

@Id collections — @Id Collections

cfg.writeIdCollection(path, collection, codec);
List<T> back = cfg.readIdCollection(path, Type.class, codec);
cfg.lastIdCollectionIssues();

Annotations — Annotations

@Key(value, transformCase)   @Comment(value, mode)   @Section("a.b")   @Id   @PostInject
KeyTransformCase.{NONE, KEBAB_CASE, SNAKE_CASE, CAMEL_CASE, UPPER_CAMEL_CASE}
CommentMode.{OVERRIDE, SET_IF_ABSENT}

Codecs — Codecs & Formats

new YamlCodec()   // LOSSLESS   yml, yaml
new JsonCodec()   // NONE       json
new TomlCodec()   // LOSSLESS   toml   (no null)
new JsoncCodec()  // LOSSY      jsonc

CodecRegistry.defaults().forFile("a.toml");   // resolve by extension