Manifold Documentation

Manifold is a static metaprogramming framework for the Java compiler (javac). It allows developers to add new types and modify existing types at compile-time without separate build steps or runtime agents.

Key capabilities include:

• Type Manifolds: Integrating structured resources (like GraphQL, JSON, XML, or JavaScript) directly into the Java type system. You can treat these files as if they were native Java types.
• Extension Manifolds: Adding new methods, interfaces, and annotations to existing Java types that cannot otherwise be modified.
• Language Extensions: Experimental features that extend the Java language itself, such as operator overloading, properties, tuples, and structural typing.

Manifold is designed to be fully IDE-integrated (specifically IntelliJ) and supports incremental compilation.

Manifold: Javascript provides direct, type-safe access to JavaScript files as if they were Java files. It allows you to treat JavaScript programs, classes, and templates as native Java entities.

Key capabilities:

• JavaScript Programs: Access functions and variables from .js files as static members of a Java class.
• JavaScript Classes: Access JS classes directly as Java classes, including support for getters, setters, and constructors.
• JavaScript Templates: Create type-safe templates using .jst files (similar to JSP syntax) and render them in Java using renderToString().

The Manifold Preprocessor is a javac plugin that enables seamless conditional compilation in Java. It integrates directly into the Java compiler, meaning no intermediate build steps or source generation are required.

Key characteristics:

• No Macros: Unlike C/C++ preprocessors, it is designed exclusively for conditional compilation. #define symbols are always boolean (true if defined, false if not) and cannot be assigned values within the source code.
• Flexible Placement: Directives can be placed anywhere in a class, including around import statements, class definitions, methods, and fields.
• High Performance: Because it is a javac plugin, it runs as part of the standard compilation process.
• IDE Support: The Manifold IntelliJ IDEA plugin allows you to visualize how code reacts to directives and toggle the feature in settings.

Manifold is a Java compiler plugin designed to supplement Java projects with highly productive features. It provides two main categories of enhancements:

1. Metaprogramming: Type-safely integrates data, metadata, or DSLs directly into Java. Supported formats include:

   • SQL (Type-safe native SQL)
   • GraphQL
   • JSON & JSON Schema
   • YAML
   • XML
   • CSV
   • JavaScript

2. Language Enhancements: Improves developer productivity by adding features like:

   • Extension methods
   • True delegation
   • Properties
   • Optional parameters
   • Tuple expressions
   • Operator overloading
   • Unit expressions
   • Java template engine
   • Preprocessor

Each feature is available as a separate dependency. You can add only the Manifold dependencies you need to your existing project.

Manifold Core is a framework that plugs directly into the Java compiler via the Javac plugin API. It acts as a universal type adapter, allowing developers to supply types and features that are otherwise inaccessible to the standard Java type system.

Key capabilities include:

• Type Manifolds: Implementing the SPI to dynamically resolve type names and project Java source code into the type system on demand (e.g., mapping JSON, XML, or GraphQL to Java types).
• Type Augmentation: Supplementing existing Java types with additional methods, properties, interfaces, or annotations.
• Just-in-Time Code Generation: Unlike traditional code generators, Manifold operates on a 'pull' model, generating code incrementally as the compiler requests types. This eliminates the need for separate build steps and ensures code is always in sync with underlying resources.

In Manifold, Properties and Java Records are orthogonal concepts that solve different problems:

• Properties are an abstraction of state. They encapsulate state that can be optionally mutable, lazily initialized, observable, or delegated. They eliminate getter/setter boilerplate at both the declaration site and the use site by allowing direct access via name (l-values).
• Records are concrete terminal types. They are essentially immutable data classes that provide shorthand for constructors, equals(), hashCode(), and toString(). They are containers of raw state, not abstractions.

Properties can be used to implement records to make them more capable.

The Manifold project is composed of a core framework and various sub-projects that implement specific Service Provider Interfaces (SPIs). You can add these as individual dependencies to your project based on your requirements.

Key sub-projects include:

• Core: The base Manifold framework.
• Extensions: Extension methods, operator overloading, and unit expressions.
• Data Formats: Support for SQL, GraphQL, JSON, XML, YAML, CSV, Property Files, and Image formats.
• Language Enhancements: Optional parameters & named arguments, Tuples, String Interpolation, (Un)checked Exceptions, and Preprocessor.
• Collections & Science: Specialized collections, science-related utilities, and I/O/Text enhancements.
• Specialized Languages: Dark Java and JavaScript support.

Manifold provides two distinct API surfaces depending on whether you want to manipulate types or extend the language itself:

1. Type Manifolds: An API for Just-in-time type projection. This allows you to override the standard javac type system by claiming or ignoring type names. You can project types from various sources such as resources or URLs. Types in this system are treated as lazy virtual source files, meaning they do not require actual file I/O.

2. Compiler Components: An API for language enhancements. This allows you to add new language constructs (via Parser modifications and AST modifications) or augment existing language features (via AST modifications).