Routes

(2min read) This page defines two possible route variations.

BoostedYAML uses "routes" (URI-like objects) to access and modify data. There are 2 different routes you can use:

• Route (objects) - any Java object as a key (beware of types)

• String routes (as in Spigot/BungeeCord API) - string keys only (all keys are converted to strings for type safety)

No matter which KeyFormat you choose, you can always use both string routes (only to the extent of their limitations) and route objects (overkill for KeyFormat.STRING though, their non-string keys will be internally converted).

Route objects

Route (objects) can contain anything as a key (except null) - are capable of accessing data at locations which contain non-string keys (e.g. integers). Use with KeyFormat.OBJECT (not a default, provide using GeneralSettings).

For example, name of the user with ID 2 in the following snippet is available under route ["users", 2, "name"], which can be created using Route.from("users", 2, "name").

users:
  1:
    name: "Peter"
  2:
    name: "James"

Recommended for documents whose syntax is strictly defined (e.g. protocol data transfer) and cannot be modified by a user.

To access user names from the snipped above, you'd need to use an integer as the key. However, if a user decides to add their own configuration and accidentally puts quotes around, the key will be interpreted as a string, therefore, cannot be accessed using a route with an integer. Read more below for BoostedYAML's solution to this problem.

String routes

String routes are represented by strings, which contain only string keys which are separated by the configured separator - just like file paths.

Assuming the snippet from above, you access anyone's name, because route to them contains an integer. That's when KeyFormat.STRING (already a default) comes into play: it converts are non-string keys to strings when the document is (re)loaded (irrevocable after saving). That means, the snippet would now look like this:

users:
  "1":
    name: "Peter"
  "2":
    name: "James"

Now, assuming default separator '.', name of the user with ID 1 in the following snippet is always conveniently available under route "users.1.name".

Recommended for configuration files due to the type safety, because all keys, no matter how specified, will be strings.