de.caff.io.json

## Class SimpleJsonWriter

- java.lang.Object
- - de.caff.io.json.SimpleJsonWriter

- All Implemented Interfaces:
    java.io.Closeable, java.lang.AutoCloseable

      public class SimpleJsonWriter
      extends java.lang.Object
      implements java.io.Closeable

  Simple JSON writer.
  Since:
    2022/04/22
  Author:
    Rammi

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `(package private) static class` | `SimpleJsonWriter.State` Internal state.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `SimpleJsonWriter(StringCollector stringCollector)` Constructor.
    `SimpleJsonWriter(StringCollector stringCollector, int basicIndent)` Constructor.
    `SimpleJsonWriter(StringCollector stringCollector, int basicIndent, boolean relaxed)` Constructor.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `SimpleJsonWriter` | `array(boolean... flags)` Convenience method for outputting a whole array of boolean flags.
    `SimpleJsonWriter` | `array(double... numbers)` Convenience method for outputting a whole array of double values.
    `SimpleJsonWriter` | `array(int... numbers)` Convenience method for outputting a whole array of integers.
    `SimpleJsonWriter` | `array(java.lang.Iterable<java.lang.String> elements)` Convenience method for outputting a whole array of strings.
    `SimpleJsonWriter` | `array(PrimitiveBooleanIterable flags)` Convenience method for outputting a whole array of boolean flags.
    `SimpleJsonWriter` | `array(PrimitiveDoubleIterable numbers)` Convenience method for outputting a whole array of double values.
    `SimpleJsonWriter` | `array(PrimitiveIntIterable numbers)` Convenience method for outputting a whole array of integers.
    `SimpleJsonWriter` | `array(java.lang.String... elements)` Convenience method for outputting a whole array of strings.
    `SimpleJsonWriter` | `beginArray()` Start outputting a JSON array.
    `SimpleJsonWriter` | `beginObject()` Start outputting a JSON object.
    `<T> SimpleJsonWriter` | `booleanArray(java.lang.Iterable<T> elements, java.util.function.Predicate<? super T> boolMapping)` Convenience method for outputting a whole array of boolean flags created from general elements.
    `void` | `close()` Close this writer.
    `SimpleJsonWriter` | `doubleArray(java.lang.Iterable<? extends java.lang.Number> numbers)` Convenience method for outputting a whole array of numbers as double values.
    `<T> SimpleJsonWriter` | `doubleArray(java.lang.Iterable<T> elements, java.util.function.ToDoubleFunction<? super T> doubleMapping)` Convenience method for outputting a whole array of double values created from general elements.
    `SimpleJsonWriter` | `endArray()` End outputting a JSON array.
    `SimpleJsonWriter` | `endObject()` End outputting a JSON object.
    `SimpleJsonWriter` | `intArray(java.lang.Iterable<? extends java.lang.Number> numbers)` Convenience method for outputting a whole array of numbers as integers.
    `<T> SimpleJsonWriter` | `intArray(java.lang.Iterable<T> elements, java.util.function.ToIntFunction<? super T> intMapping)` Convenience method for outputting a whole array of integers created from general elements.
    `SimpleJsonWriter` | `key(java.lang.String key)` Output the key of a key-value pair.
    `static void` | `main(java.lang.String[] args)` Test code
    `SimpleJsonWriter` | `nul()` Output a `null` value.
    `<T> SimpleJsonWriter` | `stringArray(java.lang.Iterable<T> elements, java.util.function.Function<? super T,java.lang.String> toStringFunction)` Convenience method for outputting a whole array of strings created from general elements.
    `SimpleJsonWriter` | `value(boolean value)` Output a boolean value.
    `SimpleJsonWriter` | `value(double value)` Output a double value.
    `SimpleJsonWriter` | `value(int value)` Output an integer value.
    `SimpleJsonWriter` | `value(java.lang.String value)` Output a string value.

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### SimpleJsonWriter

          public SimpleJsonWriter(@NotNull
                                  StringCollector stringCollector)

      Constructor. This writes without any superfluous white space.
      Parameters:
        `stringCollector` - string collector to write to

    - #### SimpleJsonWriter

          public SimpleJsonWriter(@NotNull
                                  StringCollector stringCollector,
                                  int basicIndent)

      Constructor.
      Parameters:
        `stringCollector` - string collector to write to
        `basicIndent` - basic indentation, use `-1` for optimal compactness w/o newlines, `0` for no indentation but newlines, or greater for newlines and indentation

    - #### SimpleJsonWriter

          public SimpleJsonWriter(@NotNull
                                  StringCollector stringCollector,
                                  int basicIndent,
                                  boolean relaxed)

      Constructor.
      Parameters:
        `stringCollector` - string collector to write to
        `basicIndent` - basic indentation, use `-1` for optimal compactness w/o newlines, `0` for no indentation but newlines, or greater for newlines and indentation
        `relaxed` - by default the writer expects to be started with a value, object, or array. If this parameter is `true` a key is also allowed.

  - ### Method Detail

    - #### key

          @NotNull
          public SimpleJsonWriter key(@NotNull
                                               java.lang.String key)

      Output the key of a key-value pair.
      Parameters:
        `key` - key to add
      Returns:
        JSON writer for chaining
      Throws:
        `java.lang.IllegalStateException` - if adding a key is currently not allowed

    - #### value

          @NotNull
          public SimpleJsonWriter value(@Nullable
                                                 java.lang.String value)

      Output a string value.

      A string value can appear after a key as part of a key-value pair, inside an array, or as single element.

      Parameters:
        `value` - string value
      Returns:
        JSON writer for chaining
      Throws:
        `java.lang.IllegalStateException` - if adding a value is currently not allowed

    - #### value

          @NotNull
          public SimpleJsonWriter value(int value)

      Output an integer value.

      A numeric value can appear after a key as part of a key-value pair, inside an array, or as single element. Please note that all numeric values in JSON are forwarded to 64bit double values, so this method is only for convenience.

      Parameters:
        `value` - integer value
      Returns:
        JSON writer for chaining
      Throws:
        `java.lang.IllegalStateException` - if adding a value is currently not allowed

    - #### value

          @NotNull
          public SimpleJsonWriter value(double value)

      Output a double value.

      A numeric value can appear after a key as part of a key-value pair, inside an array, or as single element. Please note that all numeric values in JSON are forwarded to 64bit double values, so if you call this with a `long` argument you might not be able to reread this value correctly.

      Parameters:
        `value` - double value
      Returns:
        JSON writer for chaining
      Throws:
        `java.lang.IllegalStateException` - if adding a value is currently not allowed

    - #### value

          @NotNull
          public SimpleJsonWriter value(boolean value)

      Output a boolean value.

      A boolean value can appear after a key as part of a key-value pair, inside an array, or as single element if this is enabled for this writer.

      Parameters:
        `value` - boolean value
      Returns:
        JSON writer for chaining
      Throws:
        `java.lang.IllegalStateException` - if adding a value is currently not allowed

    - #### nul

          @NotNull
          public SimpleJsonWriter nul()

      Output a `null` value.

      A null value can appear after a key as part of a key-value pair, inside an array, or as single element.

      Returns:
        JSON writer for chaining
      Throws:
        `java.lang.IllegalStateException` - if adding a value is currently not allowed

    - #### beginObject

          @NotNull
          public SimpleJsonWriter beginObject()

      Start outputting a JSON object.

      An object can appear as value of a key-value pair, as element of an array, or as root element.

      Returns:
        JSON writer for chaining
      Throws:
        `java.lang.IllegalStateException` - if adding an object is currently not allowed

    - #### endObject

          @NotNull
          public SimpleJsonWriter endObject()

      End outputting a JSON object.

      This will close the currently outputted object, and is only allowed at places where a key is also allowed.

      Returns:
        JSON writer for chaining
      Throws:
        `java.lang.IllegalStateException` - if no object is open, if this is called inside an array, or when the value of a key-value pair is not yet outputted

    - #### beginArray

          @NotNull
          public SimpleJsonWriter beginArray()

      Start outputting a JSON array.

      An array can appear as value of a key-value pair, as element of an array, or as root element.

      Returns:
        JSON writer for chaining
      Throws:
        `java.lang.IllegalStateException` - if adding an object is currently not allowed

    - #### endArray

          @NotNull
          public SimpleJsonWriter endArray()

      End outputting a JSON array.

      This will close the currently outputted array, and is only if currently inside an array.

      Returns:
        JSON writer for chaining
      Throws:
        `java.lang.IllegalStateException` - if no array is open, or if this is called inside an object

    - #### array

          @NotNull
          public SimpleJsonWriter array(@NotNull
                                                 java.lang.String... elements)

      Convenience method for outputting a whole array of strings.
      Parameters:
        `elements` - string elements
      Returns:
        JSON writer for chaining
      Throws:
        `java.lang.IllegalStateException` - if adding an array is not allowed

    - #### array

          @NotNull
          public SimpleJsonWriter array(@NotNull
                                                 java.lang.Iterable<java.lang.String> elements)

      Convenience method for outputting a whole array of strings.
      Parameters:
        `elements` - string elements
      Returns:
        JSON writer for chaining
      Throws:
        `java.lang.IllegalStateException` - if adding an array is not allowed

    - #### stringArray

          @NotNull
          public <T> SimpleJsonWriter stringArray(@NotNull
                                                           java.lang.Iterable<T> elements,
                                                           @NotNull
                                                           java.util.function.Function<? super T,java.lang.String> toStringFunction)

      Convenience method for outputting a whole array of strings created from general elements.
      Type Parameters:
        `T` - element type
      Parameters:
        `elements` - general elements
        `toStringFunction` - function which creates strings from the elements
      Returns:
        JSON writer for chaining
      Throws:
        `java.lang.IllegalStateException` - if adding an array is not allowed

    - #### array

          @NotNull
          public SimpleJsonWriter array(@NotNull
                                                 int... numbers)

      Convenience method for outputting a whole array of integers.
      Parameters:
        `numbers` - int elements
      Returns:
        JSON writer for chaining
      Throws:
        `java.lang.IllegalStateException` - if adding an array is not allowed

    - #### array

          @NotNull
          public SimpleJsonWriter array(@NotNull
                                                 PrimitiveIntIterable numbers)

      Convenience method for outputting a whole array of integers.
      Parameters:
        `numbers` - int elements
      Returns:
        JSON writer for chaining
      Throws:
        `java.lang.IllegalStateException` - if adding an array is not allowed

    - #### intArray

          @NotNull
          public SimpleJsonWriter intArray(@NotNull
                                                    java.lang.Iterable<? extends java.lang.Number> numbers)

      Convenience method for outputting a whole array of numbers as integers.
      Parameters:
        `numbers` - number elements
      Returns:
        JSON writer for chaining
      Throws:
        `java.lang.IllegalStateException` - if adding an array is not allowed

    - #### intArray

          @NotNull
          public <T> SimpleJsonWriter intArray(@NotNull
                                                        java.lang.Iterable<T> elements,
                                                        @NotNull
                                                        java.util.function.ToIntFunction<? super T> intMapping)

      Convenience method for outputting a whole array of integers created from general elements.
      Type Parameters:
        `T` - element type
      Parameters:
        `elements` - general elements
        `intMapping` - function which creates integers from the elements
      Returns:
        JSON writer for chaining
      Throws:
        `java.lang.IllegalStateException` - if adding an array is not allowed

    - #### array

          @NotNull
          public SimpleJsonWriter array(@NotNull
                                                 double... numbers)

      Convenience method for outputting a whole array of double values.
      Parameters:
        `numbers` - double elements
      Returns:
        JSON writer for chaining
      Throws:
        `java.lang.IllegalStateException` - if adding an array is not allowed

    - #### array

          @NotNull
          public SimpleJsonWriter array(@NotNull
                                                 PrimitiveDoubleIterable numbers)

      Convenience method for outputting a whole array of double values.
      Parameters:
        `numbers` - double elements
      Returns:
        JSON writer for chaining
      Throws:
        `java.lang.IllegalStateException` - if adding an array is not allowed

    - #### doubleArray

          @NotNull
          public SimpleJsonWriter doubleArray(@NotNull
                                                       java.lang.Iterable<? extends java.lang.Number> numbers)

      Convenience method for outputting a whole array of numbers as double values.
      Parameters:
        `numbers` - number elements
      Returns:
        JSON writer for chaining
      Throws:
        `java.lang.IllegalStateException` - if adding an array is not allowed

    - #### doubleArray

          @NotNull
          public <T> SimpleJsonWriter doubleArray(@NotNull
                                                           java.lang.Iterable<T> elements,
                                                           @NotNull
                                                           java.util.function.ToDoubleFunction<? super T> doubleMapping)

      Convenience method for outputting a whole array of double values created from general elements.
      Type Parameters:
        `T` - element type
      Parameters:
        `elements` - general elements
        `doubleMapping` - function which creates doubles from the elements
      Returns:
        JSON writer for chaining
      Throws:
        `java.lang.IllegalStateException` - if adding an array is not allowed

    - #### array

          @NotNull
          public SimpleJsonWriter array(@NotNull
                                                 boolean... flags)

      Convenience method for outputting a whole array of boolean flags.
      Parameters:
        `flags` - boolean elements
      Returns:
        JSON writer for chaining
      Throws:
        `java.lang.IllegalStateException` - if adding an array is not allowed

    - #### array

          @NotNull
          public SimpleJsonWriter array(@NotNull
                                                 PrimitiveBooleanIterable flags)

      Convenience method for outputting a whole array of boolean flags.
      Parameters:
        `flags` - boolean elements
      Returns:
        JSON writer for chaining
      Throws:
        `java.lang.IllegalStateException` - if adding an array is not allowed

    - #### booleanArray

          @NotNull
          public <T> SimpleJsonWriter booleanArray(@NotNull
                                                            java.lang.Iterable<T> elements,
                                                            @NotNull
                                                            java.util.function.Predicate<? super T> boolMapping)

      Convenience method for outputting a whole array of boolean flags created from general elements.
      Type Parameters:
        `T` - element type
      Parameters:
        `elements` - general elements
        `boolMapping` - function which creates booleans from the elements
      Returns:
        JSON writer for chaining
      Throws:
        `java.lang.IllegalStateException` - if adding an array is not allowed

    - #### close

          public void close()

      Close this writer.
      Specified by:
        `close` in interface `java.io.Closeable`
      Specified by:
        `close` in interface `java.lang.AutoCloseable`

    - #### main

          public static void main(java.lang.String[] args)
                           throws java.io.IOException

      Test code
      Parameters:
        `args` - ignored
      Throws:
        `java.io.IOException` - when writing fails