Package space.arim.dazzleconf.backend

Interface Printable

All Known Implementing Classes:
KeyPath, KeyPath.Immut, KeyPath.Mut, Printable.Abstract
public interface Printable
A displayable item, printed in one of multiple ways.

This interface exposes multiple printing methods, each named with "print." No matter the printing method used, the content generated by each method must be the same result. For example, the following assertion should pass: 

     
     Printable printable = ...;
     StringBuilder builder = new StringBuilder();
     printable.printTo(builder);
     assert printable.printString().equals(builder.toString());
Purpose

A Printable is typically passed to a method which expects to display information somewhere. The purpose is to provide late resolution and type-based concatenation of error messages, as opposed to eager construction of strings. Many error messages can be quite long, and might be better streamed.

Mutability

Mutability is left intentionally undefined. Instances of this type are not usually stored, but passed and consumed, which means that consumers will (usually) need to call one of the "print" methods at most once.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static class 
    Printable.Abstract
    A base implementation for Printable.

  • Method Summary

    Modifier and Type
    Method
    Description
    static @NonNull Printable
    join(@NonNull Printable @NonNull ... values)
    Joins multiple printable values, appending them one after the other.
    static @NonNull Printable
    preBuilt(@NonNull CharSequence content)
    Makes a simple implementation based on an existing string.
    @NonNull String
    printString()
    Gets the printed content as a string
    void
    printTo(@NonNull Appendable output)
    Prints to the given appendable
    void
    printTo(@NonNull StringBuilder output)
    Prints to the given builder
    @NonNull String
    toString()
    Gets a string representation.

  • Method Details

    • printString

      @NonNull String printString()
      Gets the printed content as a string
      Returns:
      printed string

    • printTo

      void printTo(@NonNull Appendable output) throws IOException
      Prints to the given appendable
      Parameters:
      output - where to place the message
      Throws:
      IOException - if the output threw this error, it is propagated

    • printTo

      void printTo(@NonNull StringBuilder output)
      Prints to the given builder
      Parameters:
      output - where to place the message

    • toString

      @NonNull String toString()
      Gets a string representation.

      Implementations are strongly encouraged (but not required) to return the same value as fo printString()

      Overrides:
      toString in class Object
      Returns:
      a string representation of this object

    • preBuilt

      static @NonNull Printable preBuilt(@NonNull CharSequence content)
      Makes a simple implementation based on an existing string. The argument will be yielded by each of the printing methods.
      Parameters:
      content - the prebuilt string or character sequence
      Returns:
      a printable using it

    • join

      static @NonNull Printable join(@NonNull Printable @NonNull ... values)
      Joins multiple printable values, appending them one after the other.

      This method creates a new Printable which combines the arguments in the sequence they are provided. If the returned result is printed, it will be identically to printing each of the arguments in a loop.

      If the caller modifies the values array after calling this function, it is not defined whether such modification will affect or not affect the returned Printable.

      Parameters:
      values - the values to join together
      Returns:
      a printable which prints each of the arguments, in sequence