DOCSEARCHbyAlgolia
Submit Docs

Mordant Documentation

repository·master·Indexed 22 days ago

https://github.com/ajalt/mordant

A multiplatform library for rendering styled, colorful text and complex UI elements like tables, lists, and animations in the terminal. It features ANSI output with automatic capability detection, Markdown rendering via the mordant-markdown module, and various JVM-specific interface implementations including JNA, GraalVM Native Image FFI, and Java Foreign Function and Memory (FFM) APIs.

Tokens
8.2K
Snippets
33
Records
45
Agent score
78%

What's inside Mordant

  1. Overview of Mordant capabilities

    master

    Mordant is a multiplatform library for rendering styled text in the terminal. Key features include:

    • Colorful ANSI output: Easy styling with automatic detection of terminal capabilities.
    • Markdown rendering: Render Markdown directly to the terminal (requires mordant-markdown).
    • Layout Widgets: Tools for laying out terminal output, such as lists, tables, and panels.
    • Animations: Support for animating any widget, including progress bars and dashboards (requires mordant-coroutines for coroutine support).

  3. Use the TerminalInterface implementation for GraalVM Native Image

    master
    The mordant-jvm-graal-ffi module provides a TerminalInterface implementation that enables Mordant to function correctly when compiled via GraalVM Native Image. This is required because standard JVM terminal interactions may not behave as expected in a native image environment.

  4. Create a basic progress bar

    master

    You can create a progress bar using the progressBarLayout DSL. To run the animation, you can use animateOnThread (JVM only) or animateInCoroutine (available on all platforms via the mordant-coroutines module). Once started, use update to change the total value and advance to increment the completed amount.

    To ensure the final frame is rendered before the program exits when using threads, call .get() on the Future returned by execute().

    val progress = progressBarLayout {
    marquee(terminal.theme.warning("my-file-download.bin"), width = 15)
    percentage()
    progressBar()
    completed(style = terminal.theme.success)
    speed("B/s", style = terminal.theme.info)
    timeRemaining(style = magenta)
}.animateInCoroutine(terminal)

launch { progress.execute() }

// Update the progress as the download progresses
progress.update { total = 3_000_000_000 }
while (!progress.finished) {
    progress.advance(15_000_000)
    Thread.sleep(100)
}

  7. Configure Native Access for Mordant JVM FFM

    master

    Because this module uses the Java Foreign Functions and Memory (FFM) APIs, you must grant native access to the runtime. You can do this in one of two ways:

    1. Command Line: Add the flag --enable-native-access=ALL-UNNAMED to your java command line arguments.
    2. Executable JAR: Add Enable-Native-Access: ALL-UNNAMED to the manifest of your executable JAR.

  8. Use the Drawing sample to learn mouse input and screen drawing

    master
    The drawing sample demonstrates how to capture and read mouse input events to perform drawing operations on the screen. This is useful for understanding how to handle interactive input and render visual updates in response to user actions.

  9. Install the Mordant JVM GraalVM FFI module

    master

    To use Mordant with GraalVM Native Image, add the mordant-jvm-graal-ffi module to your dependencies. Note that this module is specifically designed for GraalVM Native Image and does not support regular JRE runtimes.

    implementation("com.github.ajalt.mordant:mordant-jvm-graal-ffi:$mordantVersion")

  10. Install Mordant JVM dependencies

    master

    Mordant is modular. You can either include all JVM interface modules at once or pick specific ones based on your requirements.

    All-in-one dependencies

    Use the main mordant module to include all JVM interface modules.

    Individual JVM dependencies

    • mordant-core: The base module. It does not include JVM interface modules. Without an interface module, features like raw mode and size detection will not work, though colors and styles will.
    • mordant-jvm-ffm: Uses Java Foreign Function and Memory API. Requires JDK 22+ and the --enable-native-access=ALL-UNNAMED JVM argument.
    • mordant-jvm-jna: Uses Java Native Access. Supports all Java versions but increases JAR size due to bundled native libraries.
    • mordant-jvm-graal-ffi: Uses GraalVM Native Image FFI. Only supports Graal Native Image.

    Optional Extensions

    • mordant-coroutines: For running animations with coroutines.
    • mordant-markdown: For rendering Markdown widgets.
    // All-in-one
implementation("com.github.ajalt.mordant:mordant:$mordantVersion")

// Individual
implementation("com.github.ajalt.mordant:mordant-core:$mordantVersion")
implementation("com.github.ajalt.mordant:mordant-jvm-ffm:$mordantVersion")
implementation("com.github.ajalt.mordant:mordant-jvm-jna:$mordantVersion")
implementation("com.github.ajalt.mordant:mordant-jvm-graal-ffi:$mordantVersion")

// Extensions
implementation("com.github.ajalt.mordant:mordant-coroutines:$mordantVersion")
implementation("com.github.ajalt.mordant:mordant-markdown:$mordantVersion")

  11. Install Mordant JVM FFM

    master

    To use the JVM-only module that provides a TerminalInterface implementation using Java Foreign Functions and Memory (FFM) APIs, add the following dependency to your project. Note that this module requires JDK 22 or newer.

    implementation("com.github.ajalt.mordant:mordant-jvm-ffm:$mordantVersion")

  12. Install Mordant via Gradle

    master

    Mordant is distributed through Maven Central. To use the core library and its optional extensions, add the following dependencies to your dependencies block in Gradle.

    Note: If you are using Maven instead of Gradle, use <artifactId>mordant-jvm</artifactId> for the core dependency.

    dependencies {
    implementation("com.github.ajalt.mordant:mordant:3.0.2")

    // optional extensions for running animations with coroutines
    implementation("com.github.ajalt.mordant:mordant-coroutines:3.0.2")

    // optional widget for rendering Markdown
    implementation("com.github.ajalt.mordant:mordant-markdown:3.0.2")
}