JTamaro

JTamaro is a Java educational library designed for teaching problem decomposition using graphics.

JTamaro is a close cousin to the PyTamaro compositional graphics library for Python. Unlike PyTamaro, JTamaro also includes simple purely functional data structures (with types like Sequence, Option, and Pair), and functionality for developing purely-functional interactive applications (with a fluent API to configure and run an Interaction). JTamaro provides a minimal API, much smaller than the Java API surface covered in standard Java programming courses.

The library promotes purity, immutability, parametric polymorphism, subtyping polymorphism, and higher-order functions. It does this by focusing on interfaces, generics and modern features of the Java programming languages such as records, and by a design that encourages immutability and the composition of independent components.

It is featured in our textbook, Composition in Java.

Components

lib/data

Provides implementation for the following types:

• Function{0-4}: interfaces for function objects with up to 4 arguments
• Option: the Option(al) / Maybe monad. Used to handle errors
• Pair: tuple of two elements
• Sequence: ordered list of elements of a certain type

lib/graphic

import jtamaro.graphic.Graphic;
import jtamaro.graphic.Colors;
import jtamaro.graphic.Graphics;

public class Example {

  public static void example() {
    Graphic h = Graphics.rectangle(200, 60, Colors.WHITE);
    Graphic v = Graphics.rectangle(60, 200, Colors.WHITE);
    Graphic cross = Graphics.overlay(h, v);
  }
}

Using static imports, we can eliminate the need for mentioning class Graphics in each call:

import jtamaro.graphic.Graphic;

import static jtamaro.graphic.Colors.*;
import static jtamaro.graphic.Graphics.*;

public class Example {

  public static void example() {
    Graphic h = rectangle(200, 60, WHITE);
    Graphic v = rectangle(60, 200, WHITE);
    Graphic cross = overlay(h, v);
  }
}

lib/interaction

Interaction allows to develop an interactive application:

import jtamaro.data.Pair;
import jtamaro.graphic.Graphic;

import static jtamaro.graphic.Colors.*;
import static jtamaro.graphic.Fonts.*;
import static jtamaro.graphic.Graphics.*;
import static jtamaro.interaction.KeyboardKey.*;
import static jtamaro.io.IO.*;

public class Example {

  public static void example() {
    interact(0)
        .withKeyReleaseHandler((model, key) -> model + switch (key.keyCode()) {
          case UP -> 1;
          case DOWN -> -1;
          default -> 0;
        })
        .withRenderer(model -> text(String.valueOf(model),
            MONOSPACED, 100, BLACK))
        .run();
  }
}

lib/io

The colors and graphics are pure. Code that performs side effects (e.g., showing a graphic on the screen) is accessible through methods of class IO:

import static jtamaro.graphic.Colors.*;
import static jtamaro.graphic.Graphics.*;
import static jtamaro.io.IO.*;

public class Example {

  public static void example() {
    show(rectangle(200, 100, RED));
  }
}

Build

This project uses Gradle. It contains multiple subprojects:

• example - An application that shows how to use the features of the library.
• lib - Main jTamaro module. It includes the data structures, graphics, interaction and I/O.
• music - A midi-based music library that allows to play notes and chords.

To just the build library's jar file for usage in other projects:

./gradlew :lib:jar

To build everything and run the example app:

./gradlew :example:run

To run individual demos in the example app, run the corresponding classes with main methods in the example directory from within an IDE that understands gradle (e.g., VS Code) and thus will find (and if needed build) the library.

Requirements

The output will be in lib/build/libs/lib-*.jar

Note: The library is targeting Java 21, and it makes extensive use of the latest additions to the language (records, sealed classes, pattern matching...). Older Java versions are not supported.

Documentation

The documentation is published at this link, or it can be generated by running the following command (output at lib/build/docs/javadoc):

./gradlew :lib:javadoc