Package com.calebleavell.jatui.modules

Class TUIModule

java.lang.Object
com.calebleavell.jatui.modules.TUIModule
Direct Known Subclasses:
ApplicationModule, ContainerModule, FunctionModule, TextInputModule, TextModule
public abstract class TUIModule extends Object
The abstract class for all TUIModules.

A TUIModule is the basic runtime unit of a TUI that can have children and be run. It is immutable for structural properties (e.g, scanner, ansi, etc.), but mutable for runtime state (e.g., currentRunningChild).
Use TUIModule.Builder to construct a TUIModule (note: all concrete subclasses will have their own builder).

Use ContainerModule as the minimal implementation for this class.

TUIModule (and Jatui in general) is not thread-safe and is intended to be managed on a single thread.

  • Field Details

    • DEFAULT_SCANNER

      public static final Scanner DEFAULT_SCANNER
      Reads from System.in.

      It is strongly discouraged to close this Scanner, as it would close the scanner for all modules using it and potentially kill input for the entire TUI.

    • UNNAMED_ERROR

      public static final String UNNAMED_ERROR
      The standard message for when a module isn't named
      See Also:

    • logger

      protected static final org.slf4j.Logger logger
      The Logger for the module, provided by the slf4j facade

    • restart

      protected boolean restart
      Whether this module is flagged to restart.
      If restart is true while the module is running, it will run again after completion.

  • Constructor Details

  • Method Details

    • getName

      public String getName()
      Returns:
      name

    • getChildren

      public List<TUIModule.Builder<?>> getChildren()
      Returns:
      children

    • getChild

      public TUIModule.Builder<?> getChild(String name)
      Recursively searches for a child and returns it if it exists.
      Parameters:
      name - The name of the child to search for.
      Returns:
      The child, if it exists.

    • getChild

      public <T extends TUIModule.Builder<?>> T getChild(String name, Class<T> type)
      Recursively searches for a child and returns it as T, if it exists as type T.
      Type Parameters:
      T - The type of the child
      Parameters:
      name - The name of the child to search for.
      type - The type of the child to search for
      (e.g., ContainerModule.Builder.class)
      Returns:
      The child as T, if it exists.

    • start

      public void start()
      Runs this module as a "root", meaning a new scheduling stack is created. It will run all children from this module.
      For most use cases, only the top-level module will need to be run via this method (most likely an ApplicationModule). If you need to manually run a module that is a child of another module that will be running, use navigateTo(Builder) or ModuleFactory.run(String, TUIModule, String). This ensures a unified scheduler across all running modules.

    • doRunLogic

      public abstract void doRunLogic()
      The module-specific logic to run.
      Implementation Requirements:
      The children of this module are automatically run after this, so there is no need to implement logic that handles scheduling the behavior of children.

    • terminate

      public void terminate()
      Stop this module from running any more children.
      Recursively propagates the termination to its children.
      If a terminated module is run again, it will no longer be terminated.

    • terminateChild

      public void terminateChild(String moduleName)
      Terminates a currently running child of this module (see terminate()).
      All children higher up in the running branch will not be terminated.
      Parameters:
      moduleName - The name of the child to terminate.

    • restart

      public void restart()
      Terminates the running module and flags it to run again.
      Note: restarting a module that isn't running does nothing.

    • restartChild

      public void restartChild(String moduleName)
      Terminates the running child of this module and flags it to run again.
      Note: restarting a module that isn't running does nothing.

    • getCurrentRunningChild

      public TUIModule getCurrentRunningChild()
      Returns:
      The currentRunningChild. Will be null if there is no currently running child.

    • getCurrentRunningChild

      public TUIModule getCurrentRunningChild(String name)
      Searches for a child in the current running branch and returns it, if it exists.
      (see getCurrentRunningBranch())
      Parameters:
      name - The name of the child to search for
      Returns:
      The matching child in the current running branch, or null if not found.

    • getCurrentRunningBranch

      public List<TUIModule> getCurrentRunningBranch()
      When a module is running it runs its children, and its currently running child runs its children, and that child's currently running child runs its children, etc.
      This creates a "branch" of children that are currently running, stemming from this module to the leaf child at the very end.
      Note: the leaf child may also have children but simply isn't running them yet.
      Returns:
      The current running branch of modules stemming from this module.

    • getApplication

      public ApplicationModule getApplication()
      The ApplicationModule this module is tied to. An application module is primarily used for TUI input storage, as well as for providing a clean way to enter/exit the TUI.
      Returns:
      The ApplicationModule that this module is tied to.

    • getAnsi

      public org.fusesource.jansi.Ansi getAnsi()
      If this module displays text, this is the ansi that determines the text styling of that module (e.g., coloring, bolding, etc.). Ansi is provided by Jansi.
      Returns:
      The ansi stored in the module.

    • getScanner

      public Scanner getScanner()
      The Scanner that reads input from the defined source. It is set to System.in by default (provided by DEFAULT_SCANNER).
      Returns:
      The reference to the Scanner used by this module (Note that not every module will use the Scanner).

    • getPrintStream

      public PrintStream getPrintStream()
      PrintStream that outputs data to the defined location. It is set to System.in by default.
      Returns:
      The reference to the PrintStream used by this module (Note that not every module will use the PrintStream).

    • getAnsiEnabled

      public boolean getAnsiEnabled()
      Whether ansi is enabled applies to modules who may display text (e.g., TextModule). If ansi is disabled, only the raw text is displayed.
      Returns:
      Whether ansi is enabled for this module.

    • toString

      public String toString()
      Returns the name of this module. For a formatted string of the module hierarchy stemming from this module, see toTreeString().
      Overrides:
      toString in class Object
      Returns:
      The name of this module.

    • toTreeString

      public String toTreeString()
      Recursively generates toString with info for this scene and all children. Automatically caps recursion to 6 iterations.
      Returns:
      formatted string

    • toTreeString

      public String toTreeString(int maxDepth)
      Recursively generates toString with info for this scene and all children.
      Parameters:
      maxDepth - How deep to allow the recursion to go
      Returns:
      formatted string

    • structuralEquals

      public boolean structuralEquals(TUIModule other)

      Checks equality for properties given by the builder.

      For TUIModule, this includes:

      • name
      • application (Note: checks structural equality, not reference equality)
      • children
      • ansi
      • scanner
      • printStream
      • enableAnsi

      Note: Runtime properties (e.g., currentRunningChild, terminated), are not considered.

      Parameters:
      other - The TUIModule to compare
      Returns:
      true if this module equals other according to builder-provided properties
      Implementation Note:
      This method intentionally does not override Object.equals(Object) so that things like HashMaps still check by method reference. This method is merely for checking structural equality, which is generally only necessary for manual testing.

    • shallowStructuralEquals

      public static boolean shallowStructuralEquals(TUIModule first, TUIModule second)
      Performs a structural equality check on two modules. Does not check the equality of children.
      Checks equality of name, application, ansi, scanner, printStream, and enableAnsi. Structural equality, not reference equality, is checked for application.
      Parameters:
      first - The first TUIModule to check equality of.
      second - The second TUIModule to check equality of.
      Returns:
      Whether both modules are equal.