Package net.frozenblock.lib.config.api.instance.xjs

Class XjsUtils

java.lang.Object
net.frozenblock.lib.config.api.instance.xjs.XjsUtils
public class XjsUtils extends Object
A collection of convenience methods for interacting with XJS objects. Unlike the original methods inside of JsonObject, most of the utilities in this class return values wrapped in Optional, instead of null.

In a future version of this library (via Exjson/xjs-core), JSON objects will support returning Optional out of the box, as well as the options to flatten arrays, support additional data types, and more. As a result, most of these utilities will eventually be deprecated.

  • Constructor Summary

    Constructors
    Constructor
    Description
    XjsUtils()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    static xjs.data.JsonObject
    addToArray(xjs.data.JsonObject json, String field, xjs.data.JsonValue value)
    Adds a value to an array by name.
    static xjs.data.JsonObject
    filter(xjs.data.JsonObject json, Collection<JsonPath> paths)
    Filters values from the given JSON object according to a list of expected paths.
    static xjs.data.JsonObject
    filter(xjs.data.JsonObject json, Collection<JsonPath> paths, boolean blacklist)
    Filters values from the given JSON object according to a list of expected paths.
    static JsonPath
    getClosestMatch(xjs.data.JsonObject json, JsonPath path)
    Attempts to resolve the closest matching path in the given JSON data.
    static int
    getLastAvailable(xjs.data.JsonObject json, JsonPath path)
    Gets the index of the last available element in this path, or else -1.
    static xjs.data.JsonContainer
    getLastContainer(xjs.data.JsonObject json, JsonPath path)
    Retrieves the last JsonObject or JsonArray represented by this path.
    static List<xjs.data.JsonObject>
    getObjectArray(xjs.data.JsonObject json, String field)
    Returns a list of JsonObjects from the given source.
    static xjs.data.JsonArray
    getOrCreateArray(xjs.data.JsonObject json, String field)
    Gets an array for the given key, or else adds a new array into the object and returns it.
    static xjs.data.JsonObject
    getOrCreateObject(xjs.data.JsonObject json, String field)
    Gets and object for the given key, or else adds a new object into the container and returns it.
    static List<String>
    getPaths(xjs.data.JsonObject json, JsonPath path)
    Retrieves a list of paths adjacent to the input path.
    static List<xjs.data.JsonObject>
    getRegularObjects(xjs.data.JsonObject json, String field)
    Variant of getObjectArray(xjs.data.JsonObject, java.lang.String) which does not coerce values into objects.
    static Optional<xjs.data.JsonValue>
    getValueFromPath(xjs.data.JsonObject json, JsonPath path)
    Gets a single value in a JSON object based on a full, dotted path.
    static xjs.data.serialization.writer.JsonWriterOptions
    noCr()
    Gets the default formatting options, guaranteed to never print a `\r` character, which Minecraft does not print correctly in-game.
    static Optional<xjs.data.JsonObject>
    readJson(File file)
    Reads a JsonObject from the given file.
    static Optional<xjs.data.JsonObject>
    readJson(InputStream is)
    Reads a JsonObject from the given input stream.
    static <T> Optional<T>
    readOptional(com.mojang.serialization.Codec<T> codec, xjs.data.JsonValue value)
    Reads an object from the given data when provided a codec.
    static Optional<xjs.data.JsonObject>
    readSuppressing(File file)
    Variant of readJson(File) which ignores syntax errors and simply returns Optional.empty() if any error occurs.
    static Optional<xjs.data.JsonObject>
    readSuppressing(InputStream is)
    Variant of readSuppressing(File) which reads directly from an InputStream.
    static <T> T
    readThrowing(com.mojang.serialization.Codec<T> codec, xjs.data.JsonValue value)
    Reads an object from the given data, or else throws an exception.
    static personthecat.fresult.Result<xjs.data.JsonValue,xjs.data.exception.SyntaxException>
    readValue(String contents)
    Reads any JSON data from the given string contents.
    static xjs.data.JsonArray
    setOrAdd(xjs.data.JsonArray array, int index, xjs.data.JsonValue value)
    Sets the value at the given index, or else if index == array.size(), adds it.
    static void
    setValueFromPath(xjs.data.JsonObject json, JsonPath path, @Nullable xjs.data.JsonValue value)
    Updates a single value in a JSON object based on a full, dotted path.
    static xjs.data.JsonArray
    skip(xjs.data.JsonArray json, boolean used)
    Generates a new JsonArray containing only the values that were or were not used in the original.
    static xjs.data.JsonObject
    skip(xjs.data.JsonObject json, boolean used)
    Generates a new JsonObject containing only the values that were or were not used in the original.
    static personthecat.fresult.Result<personthecat.fresult.Void,IOException>
    updateJson(File file, Consumer<xjs.data.JsonObject> f)
    Reads a file from the disk and updates it.
    static personthecat.fresult.Result<personthecat.fresult.Void,IOException>
    writeJson(xjs.data.JsonObject json, File file)
    Writes a regular JsonObject to the disk.
    static <A> Optional<xjs.data.JsonValue>
    writeSuppressing(com.mojang.serialization.Codec<A> codec, A a)
    Writes the input value as JSON, returning Optional.empty() if any errors occur in the process.
    static <A> xjs.data.JsonValue
    writeThrowing(com.mojang.serialization.Codec<A> codec, A a)
    Writes the input value as JSON, or else throwing an exception if any errors occur in the process.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • XjsUtils

      public XjsUtils()

  • Method Details

    • readJson

      public static Optional<xjs.data.JsonObject> readJson(File file)
      Reads a JsonObject from the given file.
      Parameters:
      file - The file containing the serialized JSON object.
      Returns:
      The deserialized object, or else Optional.empty().

    • readJson

      public static Optional<xjs.data.JsonObject> readJson(InputStream is)
      Reads a JsonObject from the given input stream.
      Parameters:
      is - The stream containing the serialized JSON object.
      Returns:
      The deserialized object, or else Optional.empty().

    • readSuppressing

      public static Optional<xjs.data.JsonObject> readSuppressing(File file)
      Variant of readJson(File) which ignores syntax errors and simply returns Optional.empty() if any error occurs.
      Parameters:
      file - The file containing the serialized JSON object.
      Returns:
      The deserialized object, or else Optional.empty().

    • readSuppressing

      public static Optional<xjs.data.JsonObject> readSuppressing(InputStream is)
      Variant of readSuppressing(File) which reads directly from an InputStream.
      Parameters:
      is - The data containing the serialized JSON object.
      Returns:
      The deserialized object, or else Optional.empty().

    • readValue

      public static personthecat.fresult.Result<xjs.data.JsonValue,xjs.data.exception.SyntaxException> readValue(String contents)
      Reads any JSON data from the given string contents.
      Parameters:
      contents - The raw JSON data being parsed.
      Returns:
      The parsed JSON data, or else Result.err(E) containing the exception.

    • readOptional

      public static <T> Optional<T> readOptional(com.mojang.serialization.Codec<T> codec, xjs.data.JsonValue value)
      Reads an object from the given data when provided a codec.
      Type Parameters:
      T - The type of object being returned.
      Parameters:
      codec - Instructions for deserializing the data.
      value - The actual data being deserialized.
      Returns:
      The deserialized object, or else Optional.empty().

    • readThrowing

      public static <T> T readThrowing(com.mojang.serialization.Codec<T> codec, xjs.data.JsonValue value)
      Reads an object from the given data, or else throws an exception.
      Type Parameters:
      T - The type of object being returned.
      Parameters:
      codec - Instructions for deserializing the data.
      value - The actual data being deserialized.
      Returns:
      The deserialized object.

    • writeJson

      public static personthecat.fresult.Result<personthecat.fresult.Void,IOException> writeJson(xjs.data.JsonObject json, File file)
      Writes a regular JsonObject to the disk. The format of this output file is automatically determined by its extension.

      Any file extended with .json will be written in regular JSON format. All other extensions will implicitly be treated as XJS.

      No IOExceptions will be thrown by this method. Instead, they will be logged and simply returned for the caller to optionally throw.

      All other exceptions will be thrown by this method.

      Parameters:
      json - The JSON data being serialized.
      file - The destination file containing these data.
      Returns:
      A result which potentially contains an error.

    • writeSuppressing

      public static <A> Optional<xjs.data.JsonValue> writeSuppressing(com.mojang.serialization.Codec<A> codec, @Nullable A a)
      Writes the input value as JSON, returning Optional.empty() if any errors occur in the process.
      Type Parameters:
      A - The type of data being serialized.
      Parameters:
      codec - The codec responsible for the serialization.
      a - The data being serialized.
      Returns:
      The serialized data, or else Optional.empty().

    • writeThrowing

      public static <A> xjs.data.JsonValue writeThrowing(com.mojang.serialization.Codec<A> codec, @Nullable A a)
      Writes the input value as JSON, or else throwing an exception if any errors occur in the process.
      Type Parameters:
      A - The type of data being serialized.
      Parameters:
      codec - The codec responsible for the serialization.
      a - The data being serialized.
      Returns:
      The serialized data.

    • updateJson

      @CheckReturnValue public static personthecat.fresult.Result<personthecat.fresult.Void,IOException> updateJson(File file, Consumer<xjs.data.JsonObject> f)
      Reads a file from the disk and updates it.

      For example, 

      
   XJSTools.updateJson(file, json -> {
      json.set("hello", "world");
   });

      The output of this expression will be applied to the original file.

      Parameters:
      file - the file containing JSON data.
      f - Instructions for updating the JSON data.
      Returns:
      A result which potentially contains an error.

    • noCr

      public static xjs.data.serialization.writer.JsonWriterOptions noCr()
      Gets the default formatting options, guaranteed to never print a `\r` character, which Minecraft does not print correctly in-game.
      Returns:
      The default formatting options without \r.

    • setValueFromPath

      public static void setValueFromPath(xjs.data.JsonObject json, JsonPath path, @Nullable @Nullable xjs.data.JsonValue value)
      Updates a single value in a JSON object based on a full, dotted path.

      For example, 

         /update my_json path.to.field true
      Parameters:
      json - The JSON object containing this path.
      value - The updated value to set at this path.

    • getValueFromPath

      public static Optional<xjs.data.JsonValue> getValueFromPath(xjs.data.JsonObject json, JsonPath path)
      Gets a single value in a JSON object based on a full, dotted path.
      Parameters:
      json - The JSON object containing this path.
      path - The JSON path.
      Returns:
      The value at this location, or else Optional.empty().

    • getLastContainer

      public static xjs.data.JsonContainer getLastContainer(xjs.data.JsonObject json, JsonPath path)
      Retrieves the last JsonObject or JsonArray represented by this path.

      For example, a path of 

         object1.array2.object3.value4

      will return object3 when passed into this method.

      If no object or array exists at this location, a new container will be created at this location and returned by the method.

      Parameters:
      json - The JSON object containing this path.
      path - The JSON path.
      Returns:
      The value at this location, the original json, or else a new container.

    • getLastAvailable

      public static int getLastAvailable(xjs.data.JsonObject json, JsonPath path)
      Gets the index of the last available element in this path, or else -1.

      For example, when given the following JSON object:

         a:{b:[]}

      And the following path:

         a.b[0].c

      An index of 1 (pointing to b) will be returned.

      Parameters:
      json - The JSON object containing the data being inspected.
      path - The path to the expected data, which may or may not exist.
      Returns:
      The index to the last matching element, or else -1.

    • getClosestMatch

      public static JsonPath getClosestMatch(xjs.data.JsonObject json, JsonPath path)
      Attempts to resolve the closest matching path in the given JSON data.

      Essentially, this method accepts the canonicalized path of an expected value for the data being represented. It will account for the possibility that object arrays may be expressed as singletons and return the actual path, should any be used.

      Parameters:
      json - The object being inspected.
      path - The canonicalized path to the expected value
      Returns:
      The actual path to the value, or else the canonical path.

    • filter

      public static xjs.data.JsonObject filter(xjs.data.JsonObject json, Collection<JsonPath> paths)
      Filters values from the given JSON object according to a list of expected paths.
      Parameters:
      json - The JSON object and source being transformed.
      paths - The paths expected to stay in the output.
      Returns:
      A transformed object containing only the expected paths.

    • filter

      public static xjs.data.JsonObject filter(xjs.data.JsonObject json, Collection<JsonPath> paths, boolean blacklist)
      Filters values from the given JSON object according to a list of expected paths.
      Parameters:
      json - The JSON object and source being transformed.
      paths - The paths expected to stay in the output.
      blacklist - Whether to optionally blacklist these paths.
      Returns:
      A transformed object containing only the expected paths.

    • skip

      public static xjs.data.JsonObject skip(xjs.data.JsonObject json, boolean used)
      Generates a new JsonObject containing only the values that were or were not used in the original.
      Parameters:
      json - The original JSON object being transformed.
      used - true to skip used values, false to skip unused.
      Returns:
      A new JSON object with these values trimmed out.

    • skip

      public static xjs.data.JsonArray skip(xjs.data.JsonArray json, boolean used)
      Generates a new JsonArray containing only the values that were or were not used in the original.
      Parameters:
      json - The original JSON array being transformed.
      used - true to skip used values, false to skip unused.
      Returns:
      A new JSON array with these values trimmed out.

    • getPaths

      public static List<String> getPaths(xjs.data.JsonObject json, JsonPath path)
      Retrieves a list of paths adjacent to the input path. This can be used to provide command suggestions as the user is walking through this container.

      For example, when given the following JSON object: 

         a: [
     {
       b: { b1: true }
       c: { c1: false }
     }
   ]

      and the following incomplete command: 

         /update my_json a[0]

      the following paths will be returned:

      • a[0].b
      • a[0].c
      Parameters:
      json - The JSON data containing these paths.
      path - The JSON path.
      Returns:
      A list of all adjacent paths.

    • addToArray

      public static xjs.data.JsonObject addToArray(xjs.data.JsonObject json, String field, xjs.data.JsonValue value)
      Adds a value to an array by name. The value will be coerced into an array, if needed.

      For example, when adding a string to the following JSON field: 

         field: hello

      the field will be updated as follows: 

         field: [
     hello
     world
   ]
      Parameters:
      json - The JSON object containing these data.
      field - The key for updating an array.
      value - The value being added to the array.
      Returns:
      The original json passed in.

    • setOrAdd

      public static xjs.data.JsonArray setOrAdd(xjs.data.JsonArray array, int index, xjs.data.JsonValue value)
      Sets the value at the given index, or else if index == array.size(), adds it.
      Parameters:
      array - The array being added into.
      index - The index of the value being set.
      value - The value being set.
      Returns:
      array, for method chaining.
      Throws:
      IndexOutOfBoundsException - If index < 0 || index > size

    • getObjectArray

      public static List<xjs.data.JsonObject> getObjectArray(xjs.data.JsonObject json, String field)
      Returns a list of JsonObjects from the given source.

      Note that the values in this array will be coerced into JsonObjects.

      These objects can be stored in any number of dimensions, but will be coerced into a single dimensional array. For example, each of the following values will yield single dimensional object arrays:

      • array: [{},{},{}]
      • array: [[{}],[[{}]]]
      • array: {}
      Parameters:
      json - The JSON parent containing the array.
      field - The field where this array is stored.
      Returns:
      The JSON array in the form of a regular list.

    • getRegularObjects

      public static List<xjs.data.JsonObject> getRegularObjects(xjs.data.JsonObject json, String field)
      Variant of getObjectArray(xjs.data.JsonObject, java.lang.String) which does not coerce values into objects.

      Note that any non-object values in this array will not be returned.

      For example, when given the following JSON array: 

         array: [{},{},true,[[{}]]]

      This array will be returned: 

         [{},{},{}]
      Parameters:
      json - The JSON object containing the array.
      field - The key where this array is stored.
      Returns:
      A list of all JsonObjects at this location.

    • getOrCreateArray

      public static xjs.data.JsonArray getOrCreateArray(xjs.data.JsonObject json, String field)
      Gets an array for the given key, or else adds a new array into the object and returns it.
      Parameters:
      json - The JSON object being inspected.
      field - The name of the array being queried.
      Returns:
      The existing or new array.

    • getOrCreateObject

      public static xjs.data.JsonObject getOrCreateObject(xjs.data.JsonObject json, String field)
      Gets and object for the given key, or else adds a new object into the container and returns it.
      Parameters:
      json - The JSON object being inspected.
      field - The name of the object being queried.
      Returns:
      The existing or new object.