diff --git a/docs/branding/images/experimental/logo_black_blue.png b/docs/branding/images/experimental/logo_black_blue.png deleted file mode 100644 index e2db8b369..000000000 Binary files a/docs/branding/images/experimental/logo_black_blue.png and /dev/null differ diff --git a/docs/branding/images/experimental/logo_black_red.png b/docs/branding/images/experimental/logo_black_red.png deleted file mode 100644 index d91ae2f75..000000000 Binary files a/docs/branding/images/experimental/logo_black_red.png and /dev/null differ diff --git a/docs/branding/images/logo_base.png b/docs/branding/images/logo_base.png deleted file mode 100644 index b49a8f067..000000000 Binary files a/docs/branding/images/logo_base.png and /dev/null differ diff --git a/docs/branding/images/logo_base_black_blue.png b/docs/branding/images/logo_base_black_blue.png deleted file mode 100644 index 3ea1e9c8c..000000000 Binary files a/docs/branding/images/logo_base_black_blue.png and /dev/null differ diff --git a/docs/branding/images/logo_base_black_blue2.png b/docs/branding/images/logo_base_black_blue2.png deleted file mode 100644 index 8c63510c2..000000000 Binary files a/docs/branding/images/logo_base_black_blue2.png and /dev/null differ diff --git a/docs/branding/images/logo_base_black_blue2_sq.png b/docs/branding/images/logo_base_black_blue2_sq.png deleted file mode 100644 index 79bcb7ea3..000000000 Binary files a/docs/branding/images/logo_base_black_blue2_sq.png and /dev/null differ diff --git a/docs/branding/images/logo_base_black_blue_512.png b/docs/branding/images/logo_base_black_blue_512.png deleted file mode 100644 index 5ce722db4..000000000 Binary files a/docs/branding/images/logo_base_black_blue_512.png and /dev/null differ diff --git a/docs/branding/images/logo_base_black_blue_square.png b/docs/branding/images/logo_base_black_blue_square.png deleted file mode 100644 index 6244dfcc9..000000000 Binary files a/docs/branding/images/logo_base_black_blue_square.png and /dev/null differ diff --git a/docs/cheatsheet.md_ b/docs/cheatsheet.md_ deleted file mode 100644 index 9f9f7455e..000000000 --- a/docs/cheatsheet.md_ +++ /dev/null @@ -1,648 +0,0 @@ ---- -layout: default ---- - -# Manifold Cheat Sheet - ->#### [IntelliJ IDEA](http://manifold.systems/docs.html#ide--intellij-idea) ->Manifold is best experienced in IntelliJ IDEA. The Manifold plugin provides comprehensive support for IntelliJ features -including code completion, navigation, usage searching, refactoring, incremental compilation, hotswap debugging, -full-featured ManTL template editing, and more. -> ->Install the plugin directly from IntelliJ: -> ->SettingsPluginsMarketplace ➜ search: `Manifold` - -## Sample Projects - -Clone the [Manifold sample project](https://github.com/manifold-systems/manifold-sample-project) to for a nice -breadthwise demonstration of features. - -Clone the [Manifold sample GraphQL project](https://github.com/manifold-systems/manifold-sample-graphql-app) to learn -more about application design with GraphQL using Manifold. - -Clone the [Manifold sample REST API project](https://github.com/manifold-systems/manifold-sample-rest-api) to quickly -begin experimenting with a JSON Schema REST API using Manifold. - -Clone the [Manifold sample Web App project](https://github.com/manifold-systems/manifold-sample-web-app) to get hooked -on ManTL templates with the Manifold IntelliJ plugin. - -Clone the [Manifold : _Gradle Example Project_](https://github.com/manifold-systems/manifold-simple-gradle-project) to -learn how to setup a Manifold project with Gradle. - -## Screencasts - -* [GraphQL](http://manifold.systems/images/graphql.mp4) -

- -

- -* [JSON Schema](http://manifold.systems/images/json.mp4) -

- -

- -* [Extension Methods](http://manifold.systems/images/ExtensionMethod.mp4) -

- -

- -* [Structural Typing](http://manifold.systems/images/structural%20typing.mp4) -

- -

- -* [Type-safe Reflection (**@Jailbreak**)](http://manifold.systems/images/jailbreak.mp4) -

- -

- -* [String Templates (aka Interpolation)](http://manifold.systems/images/string_interpolation.mp4) -

- -

- -* [Manifold Template Language (ManTL)](http://manifold.systems/images/mantl.mp4) -

- -

- -## [Metaprogramming](http://manifold.systems/docs.html) -Gain direct, **type-safe** access to *any* type of data. Remove the code gen step in your build process. - -### Resources -Put data files in your `resource path`. - -A typical Maven setup: -```text -src --- main ----- java ------- ----- resources ------- -``` - -### [JSON & JSON Schema](http://manifold.systems/docs.html#json-and-json-schema) - -You can use both sample JSON files and JSON Schema files. - -`resources/abc/Person.json` -```json -{ - "Name": "Joe Jayson", - "Age": 39, -... -} -``` -Use `Person.json` as a JSON-by-example schema: -```java -import abc.Person; -... -Person person = Person.fromJsonUrl(url); -person.setFirstName("Scott"); -``` -Or use JSON Schema files: -`resources/abc/Contact.json` -Here is a simple `User` type defined in `resources/abc/User.json` using JSON Schema: -```json -{ - "$schema": "http://json-schema.org/draft-07/schema#", - "$id": "http://example.com/schemas/User.json", - "type": "object", - "definitions": { - "Gender": { - "type": "string", - "enum": ["male", "female"] - } - }, - "properties": { - "name": { - "type": "string", - "description": "User's full name.", - "maxLength": 80 - }, - "email": { - "description": "User's email.", - "type": "string", - "format": "email" - }, - "date_of_birth": { - "type": "string", - "description": "Date of uses birth in the one and only date standard: ISO 8601.", - "format": "date" - }, - "gender": { - "$ref" : "#/definitions/Gender" - } - }, - "required": ["name", "email"] -} -``` -You can use this to create a new instance of the `User` type and then modify it using _setter_ methods to change -optional properties: -```java -import abc.User; -import abc.User.Gender; -import java.time.LocalDate; -... -User user = User.create("Scott McKinney", "scott@manifold.systems"); -user.setGender(Gender.male); -user.setDate_of_birth(LocalDate.of(1980, 7, 4)); -``` - -Alternatively, you can use `builder()` to fluently build a new instance: -```java -User user = User.builder("Scott McKinney", "scott@manifold.systems") - .withGender(Gender.male) - .withDate_of_birth(LocalDate.of(1980, 7, 4)) - .build(); -``` -You can load a `User` instance from a String: -```java -// From a YAML string -User user = User.load().fromYaml( - "name: Scott McKinney\n" + - "email: scott@manifold.systems\n" + - "gender: male\n" + - "date_of_birth: 1980-07-04" - ); -``` - -Load from a file: -```java -// From a JSON file -User user = User.load().fromJsonFile("/path/to/MyUser.json"); -``` - -You can invoke a REST API to fetch a `User` using HTTP GET: -```java -// Uses HTTP GET to invoke the API -User user = User.load().fromJsonUrl("http://api.example.com/users/$userId"); -``` - -#### Request REST API services -Use the `request()` static method to conveniently navigate an HTTP REST API with GET, POST, PUT, PATCH, & DELETE: -```java -String id = "scott"; -User user = User.request("http://api.example.com/users").getOne("/$id"); -``` -The `request()` method provides support for all basic REST API client usage: -```java -Requester req = User.request("http://api.example.com/users"); - -// Get all Users via HTTP GET -IJsonList users = req.getMany(); - -// Add a User with HTTP POST -User user = User.builder("scott", "mypassword", "Scott") - .withGender(male) - .build(); -req.postOne(user); - -// Get a User with HTTP GET -String id = user.getId(); -user = req.getOne("/$id"); - -// Update a User with HTTP PUT -user.setDob(LocalDate.of(1980, 7, 7)); -req.putOne("/$id", user); - -// Delete a User with HTTP DELETE -req.delete("/$id"); -``` -> Clone the [Manifold sample REST API project](https://github.com/manifold-systems/manifold-sample-rest-api) to quickly -begin experimenting with a JSON Schema REST API using Manifold. - -#### Writing JSON -An instance of a JSON API object can be written as formatted text with `write()`: -* `toJson()` - produces a JSON formatted String -* `toYaml()` - produces a YAML formatted String -* `toXml()` - produces an XML formatted String -* `toCsv()` - produces a CSV formatted String - -The following example produces a JSON formatted string: -```java -User user = User.builder("Scott McKinney", "scott@manifold.systems") - .withGender(Gender.male) - .withDate_of_birth(LocalDate.of(1980, 7, 4)) - .build(); - -String json = user.write().toJson(); -System.out.println(json); -``` -Output: -```json -{ - "name": "Scott McKinney", - "email": "scott@manifold.systems", - "gender": "male", - "date_of_birth": "1980-07-04" -} -``` - -### [YAML](http://manifold.systems/docs.html#json-and-json-schema) - -Manifold fully supports YAML 1.2. You can use YAML to build JSON Schema files as well. All that applies to JSON applie to YAML. - - -### [Properties](http://manifold.systems/docs.html#properties-files) -Avoid strings, access properties type-safely: - -`resources/abc/MyProperties.properties` -```properties -chocolate = Chocolate -chocolate.milk = Milk chocolate -chocolate.dark = Dark chocolate -``` -```java -String myMessage = MyProperties.chocolate.milk; -``` - -### [Images](http://manifold.systems/docs.html#image-files) -Gain direct type-safe access to all your project's images, efficiently cached: - -`resources/abc/images/companyLogo.png` -```java -import abc.images.*; -... -ImageIcon image = companyLogo_png.get(); -render(image); -``` - -### [JavaScript](http://manifold.systems/docs.html#javascript) - -`resources/abc/MyJsProgram.js`: -```javascript -var x = 1; - -function nextNumber() { - return x++; -} - -function doSomething(x) { - return x + " from Javascript"; -} -``` - -A JavaScript file and its members are directly accessible as a Java class: - -```java -import abc.MyJsProgram; -... -String hello = MyJsProgram.doSomething("Hello"); -System.out.println(hello); // prints 'Hello from JavaScript' - -double next = JsProgram.nextNumber(); -System.out.println(next); // prints '1' -``` - -## [String Templates](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-strings) (aka string interpolation) -### Enabling - -Enable the feature with the `manifold-strings` dependency: -```xml - - systems.manifold - manifold-strings - - 2024.1.29 - -``` - -### Using -A **String template** lets you use the `$` character to inline a Java expression within a String literal. You can -use `$` to inline a simple variable: -```java -int hour = 8; -String time = "It is $hour o'clock"; // prints "It is 8 o'clock" -``` -Or you can inline an expression of any complexity in curly braces: -```java -LocalTime localTime = LocalTime.now(); -String ltime = "It is ${localTime.getHour()}:${localTime.getMinute()}"; // prints "It is 8:39" -``` -Escape the `$` with `\$`. - -Use `@DisableStringLiteralTemplates` to turn string templates off at the class and method levels. - -## [Extensions](http://manifold.systems/docs.html#the-extension-manifold) - -### Basic -Add your own methods to any class e.g., `java.lang.String`: - -Make a class in a package named `extensions`. Create a sub-package using the full name of the class you want to extend, -in this case `java.lang.String`: - -```java -package abc.extensions.java.lang.String; - -import manifold.ext.api.*; - -@Extension -public class MyStringExtension { - - public static void print(@This String thiz) { - System.out.println(thiz); - } - - @Extension // required for static extension methods - public static String lineSeparator() { - return System.lineSeparator(); - } -} -``` -Now the methods are available directly from `String`: -```java -String hello = "hello"; -hello.print(); - -// static method -String.lineSeparator(); -``` - -### Generics -Here `map` is a generic extension method on `Collection` having type variable `R` and conveying `Collection`'s type -variable `E`. Extension methods must reflect the type variable names declared in the extended class. -```java -public static Stream map(@This Collection thiz, Function mapper) { - return thiz.stream().map(mapper); -} -``` - -## [@Structural - Structural Interfaces](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-ext#structural-interfaces-via-structural) -Unify disparate APIs. Bridge software components you do not control. Access maps through type-safe interfaces. -```java -@Structural -public interface Coordinate { - double getX(); - double getY(); -} -``` -Structural interface applied to `java.awt.Rectangle`: -```java -setLocation((Coordinate)new Rectangle(10, 10, 100, 100)); -... -void setLocation(Coordinate location) { - this.location = location; -} -``` -Structural interface applied to `java.util.HashMap` via `ICallHandler`: -```java -Map map = new HashMap<>(); -map.put("x", 10); -map.put("y", 10); - -Coordinate coord = (Coordinate)map; -double x = coord.getX(); -``` - -## [@Jailbreak - Type-safe Reflection](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-ext#type-safe-reflection-via-jailbreak) -Access private features with @Jailbreak to avoid the drudgery and vulnerability of Java reflection. -### Basic -```java -@Jailbreak Foo foo = new Foo(1); -foo.privateMethod(); -foo.privateMethod("hey"); -foo._privateField = 88; -``` -```java -public class Foo { - private final int _privateField; - - public Foo(int value) { - _privateField = value; - } - - private String privateMethod() { - return "hi"; - } - - private String privateMethod(String param) { - return param; - } -} -``` -### Static Members -```java -@Jailbreak MyClass myClass = null; // value is insignificant -myClass.staticMethod(); -myClass.Static_Field = "hi"; -``` -```java -public class MyClass { - private static String Static_Field = "hello"; - - private static void staticMethod() { - } -} -``` - -### Types and Constructors -```java -com.abc. @Jailbreak SecretClass secretClass = - new com.abc. @Jailbreak SecretClass("hi"); -secretClass._data = "hey"; -``` - -## [@Self - The Self Type](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-ext#the-self-type-via-self) - -Manifold supports the *Self* type via the `@Self` annotation. Use `@Self` with method return types, parameter types, and -field types to enforce `subtype of this` where suitable. Use `@Self` as a simpler, more versatile alternative to Java's -recursive generic types. - -### `equals()` - -You can use `@Self` to make methods like `equals()` type-safe: -```java -public class MyClass { - @Override - public boolean equals(@Self Object obj) { - ... - } -} -``` -Now your equals() method enforces `MyClass` as the parameter: -```java -myClass.equals("notMyClass"); // Compile Error. :) -``` - -### Builders - -A common use-case for the Self type involves fluent APIs like the *Builder* pattern: - -```java -public class VehicleBuilder { - private int _wheels; - - public VehicleBuilder withWheels(int wheels) { - _wheels = wheels; - return this; // returns THIS - } -} -``` - -This is fine until we subclass it: - -```java -public class AirplaneBuilder extends VehicleBuilder { - private int _wings; - - public AirplaneBuilder withWings(int wings) { - _wings = wings; - return this; // returns THIS - } -} - -... - -Airplane airplane = new AirplaneBuilder() - .withWheels(3) // returns VehicleBuilder :( - .withWings(1) // ERROR -``` - -`withWheels()` returns `VehicleBuilder`, not `AirplaneBuilder`. This is a classic example where we want to return the -*"the subtype of `this`"*. This is what the self type accomplishes: - -```java - public @Self VehicleBuilder withWheels(int wheels) { - _wheels = wheels; - return this; // returns THIS - } -``` - -Now with the return type annotated with `@Self` the example works as desired: - -```java -Airplane airplane = new AirplaneBuilder() - .withWheels(2) // returns AirplaneBuilder :) - .withWings(1) // GOOD! -``` - -Annotate with `@Self` to preserve the *"the subtype of `this`"* anywhere on or in a method return type, parameter type, -or field type. - -### Self + Generics - -You can also use `@Self` to annotate a _type argument_. A nice example of this involves a typical graph or tree -structure where the nodes in the structure are homogeneous: - -```java -public class Node { - private List children; - - public List<@Self Node> getChildren() { - return children; - } - - public void addChild(@Self Node child) { - children.add(child); - } -} - -public class MyNode extends Node { - ... -} -``` - -Here you can make the component type of `List` the Self type so you can use the `getChildren` method type-safely from -subtypes of node: - -```java -MyNode myNode = findMyNode(); -List = myNode.getChildren(); // wunderbar! -``` - -### Self + Extensions - -You can use `@Self` with [extension methods](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-ext#extension-classes-via-extension) -too. Here we make an extension method as a means to conveniently chain additions to `Map` while preserving its concrete -type: - -```java -public static @Self Map add(@This Map thiz, K key, V value) { - thiz.put(key, value); - return thiz; -} - -HashMap map = new HashMap<>() - .add("nick", "grouper") - .add("miles", "amberjack"); - .add("alec", "barracuda") -``` - -### Overriding Methods - -Using @Self in a method return type or parameter type has _no_ effect on the method's override characteristics or binary -signature: -```java -public class SinglyNode { - private @Self SinglyNode next; - - public void setNext(@Self SinglyNode next) { - this.next = next; - } -} - -public class DoublyNode extends SinglyNode { - private @Self DoublyNode prev; - - public void setNext(@Self SinglyNode next) { - if(next instanceof DoublyNode) { - super.setNext(next); - ((DoublyNode)next).prev = this; - } - else { - throw new IllegalArgumentException(); - } - } -} -``` - -## [Checked Exception Handling](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-exceptions) -Simply add the `manifold-exceptions` dependency to your project. Now checked exceptions behave like unchecked -exceptions! No more compiler errors, no more boilerplate `try`/`catch`/`wrap`/`rethrow` nonsense. -```java -List strings = ...; -List urls = list - .map(URL::new) // No need to handle the MalformedURLException! - .collect(Collectors.toList()); -``` - -To use Checked Exception handling you must add the `manifold-exceptions` dependency to your build configuration: -```xml - - systems.manifold - manifold-exceptions - - 2024.1.29 - -``` - -## [ManTL](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-templates) (Superfast **type-safe** templates, and a lot more) - -## [Libraries](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-ext#extension-libraries) -Leverage stock Manifold extension libraries for standard Java classes. Save time and reduce boilerplate code. -```java -File file = new File(path); -// Use refreshing extensions to File -String content = file.readText(); -``` -Use the `manifold-all` dependency to access all Manifold's provided extension libraries including I/O, Web, and -Collections. - -## [Learn More](http://manifold.systems/docs.html) diff --git a/docs/docs.md b/docs/docs.md deleted file mode 100644 index ea8c868a4..000000000 --- a/docs/docs.md +++ /dev/null @@ -1,417 +0,0 @@ ---- -layout: default ---- - -## Table of Contents -* [Overview](#overview) -* [Type-safe Metaprogramming (GraphQL, JSON, XML, etc.)](#type-safe-metaprogramming-with-type-manifolds) -* [Java Extensions with the _Extension_ Manifold](#the-extension-manifold) -* [Benefits](#benefits) -* [IDE Support](#ide-support) -* [Projects](#projects) -* [Platforms](#platforms) -* [**Setup**](#setup) -* [Download](#download) -* [License](#license) -* [Author](#author) -* [Forum](#forum) - -# Overview - -[Manifold](https://manifold.systems/) plugs directly into Java to supplement it with powerful features you can use -directly in your projects: - -* [**Type-safe Metaprogramming**](https://github.com/manifold-systems/manifold/tree/master/manifold-core-parent/manifold) -- _type-safe_ access to structured data. -Use [GraphQL](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-graphql), -[XML](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-xml), -[JSON](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-json), -[YAML](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-yaml), -[CSV](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-csv), -[JavaScript](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-js), -[Templates](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-templates), etc. -directly and type-safely from Java without a code generator in your build and with comprehensive IDE support. -* [**Java Extensions**](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-ext) -- -provides [extension methods](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-ext#extension-classes-via-extension), -[properties](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-props), -[operator overloading](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-ext#operator-overloading), -[unit expressions](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-ext#unit-expressions), -[structural typing](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-ext#structural-interfaces-via-structural), -[string interpolation](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-strings), -[type-safe reflection](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-collections#type-safe-reflection-via-jailbreak), -and a lot more. - - -# Type-safe Metaprogramming with Type Manifolds - -Bridging the worlds of data and code, a *type manifold* acts as an adapter to automatically connect data resources to -Java's type system. The core Manifold framework seamlessly plugs into the Java compiler enabling a type manifold to -transform structured data into data _types_ directly accessible in your Java code eliminating code generation build -steps otherwise required with conventional tools. Additionally, the [Manifold plugin](#ide-support) -provides comprehensive integration for type manifolds in both [IntelliJ IDEA](https://www.jetbrains.com/idea/download) -and [Android Studio](https://developer.android.com/studio). Types are always in sync; changes you make to resources are -immediately available in your code _without a compilation step_. Code completion, navigation, usage searching, -deterministic refactoring, incremental compilation, hotswap debugging -- all seamlessly integrated. With type manifolds -a data resource is a virtual data _type_. - -To illustrate, consider this simple properties resource file: - -`/abc/MyProperties.properties` -```properties -chocolate = Chocolate -chocolate.milk = Milk chocolate -chocolate.dark = Dark chocolate -``` - -Normally in Java you access a properties file like this: - -```java -Properties myProperties = new Properties(); -myProperties.load(getClass().getResourceAsStream("/abc/MyProperties.properties")); -String myMessage = myProperties.getProperty("chocolate.milk"); -``` - -As with any resource file a properties file is foreign to Java's type system -- there is no direct, type-safe access to -it. Instead you access it indirectly using boilerplate library code sprinkled with hard-coded strings. - -By contrast, with the Properties type manifold you access a properties file directly as a type: - -```java -String myMessage = MyProperties.chocolate.milk; -``` - -Concise and type-safe, with no additional build steps to engage. - -Any data resource is a potential type manifold, including file schemas, query languages, database definitions, -data services, templates, spreadsheets, and programming languages. - -Manifold provides type manifolds for: - -* [GraphQL](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-graphql) -* [JSON and JSON Schema](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-json) -* [XML](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-xml) -* [YAML](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-yaml) -* [CSV](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-csv) -* [Property files](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-properties) -* [Image files](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-image) -* [Dark Java](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-darkj) -* [JavaScript](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-js) -* [Java Templates](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-templates) - -# The Extension Manifold - -The extension manifold is a special kind of type manifold that lets you augment existing Java classes including Java's -own runtime classes such as `String`. You can add new methods, annotations, and interfaces to any type your project -uses. - -Let's say you want to make a new method on `String` so you can straightforwardly echo a String to the console. Normally -with Java you might write a "Util" library like this: - -```java -public class MyStringUtil { - public static void echo(String value) { - System.out.println(value); - } -} -``` - -And you'd use it like this: - -```java -MyStringUtil.echo("Java"); -``` - -Instead with Manifold you create an _**Extension Class**_: - -```java -@Extension -public class MyStringExtension { - public static void echo(@This String thiz) { - System.out.println(thiz); - } -} -``` - -Here we've added a new `echo()` method to `String`, so we use it like this: - -```java -"Java".echo(); -``` - -Extensions eliminate a lot of intermediate code such as "Util" and "Manager" libraries as well as Factory classes. As a -consequence extensions naturally promote higher levels of object-orientation, which result in more readable and -maintainable code. Additionally, with the Manifold IntelliJ plugin you can use code-completion which conveniently -presents all the extension methods available on an extended class: - -

- -

- -There's a lot more to the extension manifold including [operator overloading](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-ext#operator-overloading), -[unit expressions](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-ext#unit-expressions), -[structural interfaces](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-ext#structural-interfaces-via-structural), -which are similar to interfaces in the [Go](https://golang.org/) and [TypeScript](https://www.typescriptlang.org/docs/handbook/interfaces.html) -languages. See the [Java Extension Manifold](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-ext) -for full coverage of these features. - -> _**New!**_ -> * Finally, [_**Properties**_](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-props) for Java -> * Includes automatic property _inference_ for existing Java classes **😎** -> -> [Learn more](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-props). - - -# Benefits - -Manifold's core technology is a dramatic departure from conventional Java tooling. There are no code generation steps in -the build, no extra build target files to manage, no annotation processors, and no extra class loaders to engage at -runtime. - -Benefits of this approach include: - -* **Zero turnaround** -- direct, type-safe access to structured data -* **Lightweight** -- requires no special compilers, annotation processors, or runtime agents -* **Efficient** -- Manifold only produces types as they are needed -* **Simple, open API** -- use the Manifold API to build your own components and extensions -* **No code generation build step** -- integrates directly with the Java compiler -* **Incremental** -- only builds types that have changed -* **[IntelliJ IDEA](https://www.jetbrains.com/idea/download)** -- fully supported -* **[Android Studio](https://developer.android.com/studio)** -- fully supported - -Manifold is just a dependency you can drop into your existing project. You can begin using it incrementally without -having to rewrite classes or conform to a new way of doing things. - -# IDE Support - -Use Manifold to its fullest in **IntelliJ IDEA** and **Android Studio** using the [Manifold IDE plugin](https://plugins.jetbrains.com/plugin/10057-manifold). - -The plugin provides comprehensive support for IDE features including: -* Feature highlighting -* Error reporting -* Code completion -* Go to declaration -* Usage searching -* Rename/Move refactoring -* Quick navigation -* Operator overloading -* Unit expressions -* Structural typing -* Type-safe reflection with `@Jailbreak` -* Self type support with `@Self` -* Incremental compilation -* Hotswap debugging -* Preprocessor (conditional compilation) -* Professional template file editing - -Use code completion to discover and use type manifolds such as GraphQL and to access extension methods and structural -interfaces. Jump directly from usages of extension methods to their declarations. Jump directly from call sites to -resource elements and find usages of them in your code. Watch your GraphQL, JSON, XML, YAML, CSV, images, properties, -templates, and custom type manifolds come alive as types. Changes you make in resource files are instantly available in -your code, _without compiling_. - -Install the plugin directly from the IDE via: - -SettingsPluginsMarketplace ➜ search: `Manifold` - -Get the plugin from JetBrains Marketplace: - - - -# Projects - -The Manifold framework consists of the *core project* and a collection of *sub-projects* implementing SPIs provided -by the core. Each project represents a separate *dependency* you can use directly in your project. See details in each -projects' docs. - -### Core Framework -* [Manifold : _Core_](https://github.com/manifold-systems/manifold/tree/master/manifold-core-parent/manifold) - -### Resource Manifolds -* [Manifold : _GraphQL_](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-graphql) -* [Manifold : _JSON_](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-json) -* [Manifold : _XML_](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-xml) -* [Manifold : _CSV_](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-csv) -* [Manifold : _YAML_](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-yaml) -* [Manifold : _Property files_](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-properties) -* [Manifold : _Image files_](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-image) -* [Manifold : _Dark Java_](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-darkj) -* [Manifold : _JavaScript_](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-js) - -### Java Extension Manifold -* [Manifold : _Java Extension_](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-ext) - -### Java Properties -* [Manifold : _Java Properties_](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-props) - -### Java Templates Framework -* [Manifold : _Templates_](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-templates) - -### Java Compiler Extensions -* [Manifold : _String Templates_](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-strings) (string interpolation) -* [Manifold : _[Un]checked_](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-exceptions) - -### Java Preprocessor -* [Manifold : _Preprocessor_](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-preprocessor) - -### Java Science -* [Manifold : _Science_](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-science) - -### Java Extension Libraries -* [Manifold : _Collections_](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-collections) -* [Manifold : _I/0_](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-io) -* [Manifold : _Text_](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-text) - -### Sample Projects -* [Manifold sample project](https://github.com/manifold-systems/manifold-sample-project) -* [Manifold sample GraphQL App](https://github.com/manifold-systems/manifold-sample-graphql-app) -* [Manifold sample REST API App](https://github.com/manifold-systems/manifold-sample-rest-api) -* [Manifold sample Web App](https://github.com/manifold-systems/manifold-sample-web-app) -* [Manifold sample Gradle Project](https://github.com/manifold-systems/manifold-simple-gradle-project) -* [Manifold sample Kotlin App](https://github.com/manifold-systems/manifold-sample-kotlin-app) - -# Platforms - -Manifold supports: -* Java SE (8 - 21) -* [Android](http://manifold.systems/android.html) -* [Kotlin](http://manifold.systems/kotlin.html) (limited) - -Comprehensive IDE support is also available for IntelliJ IDEA and Android Studio. - -# Setup - -Manifold is designed to work with most build systems, including Maven and Gradle. - -The Manifold root project consists of several sub-projects you can include separately in your build, see [Projects](#projects) -above for a complete listing. If you're targeting Android using Android Studio, see [Using Manifold with Android Studio](http://manifold.systems/android.html) -for additional setup information. - -Setup instructions are consistent for each sub-project/dependency. Here are direct links: - -* Setup for [Manifold : _Core_](https://github.com/manifold-systems/manifold/tree/master/manifold-core-parent/manifold#setup) - -
- -* Setup for [Manifold : _GraphQL_](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-graphql#setup) -* Setup for [Manifold : _XML_](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-xml#setup) -* Setup for [Manifold : _JSON_](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-json#setup) -* Setup for [Manifold : _CSV_](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-csv#setup) -* Setup for [Manifold : _YAML_](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-yaml#setup) -* Setup for [Manifold : _Property Files_](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-properties#setup) -* Setup for [Manifold : _Image_](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-image#setup) -* Setup for [Manifold : _Dark Java_](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-darkj#setup) -* Setup for [Manifold : _JavaScript_](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-js#setup) - -
- -* Setup for [Manifold : _Java Extension_](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-ext#setup) - -
- -* Setup for [Manifold : _Java Properties_](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-props#setup) - -
- -* Setup for [Manifold : _Templates_](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-templates#setup) - -
- -* Setup for [Manifold : _String Templates_](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-strings#setup) -* Setup for [Manifold : _[Un]checked_](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-exceptions#setup) - -
- -* Setup for [Manifold : _Preprocessor_](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-preprocessor#setup) - -
- -* Setup for [Manifold : _Science_](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-science#setup) - -
- -* Setup for [Manifold : _Collections_](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-collections#setup) -* Setup for [Manifold : _I/0_](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-io#setup) -* Setup for [Manifold : _Text_](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-text#setup) - - -# Download - -For the convenience of non-maven/non-gradle users you can directly download latest release binaries below. - ->**WARNING** If you plan to build your project **without** Maven or Gradle using select binaries, your classpath ->**must** include the **transitive closure** of binaries in terms of the **dependencies** declared in corresponding ->project's POM file. Additionally, you will need to adapt your build to reflect the Maven or Gradle setup instructions ->from the list above. -> ->For instance, to use the *manifold-preprocessor* jar using **Ant** your project needs: ->* [manifold-preprocessor-2024.1.29.jar](https://repository.sonatype.org/service/local/artifact/maven/redirect?r=central-proxy&g=systems.manifold&a=manifold-preprocessor&v=RELEASE) ->* [manifold-2024.1.29.jar](https://repository.sonatype.org/service/local/artifact/maven/redirect?r=central-proxy&g=systems.manifold&a=manifold&v=RELEASE) ->* [manifold-util-2024.1.29.jar](https://repository.sonatype.org/service/local/artifact/maven/redirect?r=central-proxy&g=systems.manifold&a=manifold-util&v=RELEASE) -> ->As such your *javac* command line should include: ->```text ->javac -Xplugin:Manifold -classpath /manifold-preprocessor-2024.1.29.jar;/manifold-2024.1.29.jar;/manifold-util-2024.1.29.jar ->``` - -* Download [Manifold : _Core_](https://repository.sonatype.org/service/local/artifact/maven/redirect?r=central-proxy&g=systems.manifold&a=manifold&v=RELEASE) - -
- -* Download [Manifold : _GraphQL_](https://repository.sonatype.org/service/local/artifact/maven/redirect?r=central-proxy&g=systems.manifold&a=manifold-graphql&v=RELEASE) -* Download [Manifold : _XML_](https://repository.sonatype.org/service/local/artifact/maven/redirect?r=central-proxy&g=systems.manifold&a=manifold-xml&v=RELEASE) -* Download [Manifold : _JSON_](https://repository.sonatype.org/service/local/artifact/maven/redirect?r=central-proxy&g=systems.manifold&a=manifold-json&v=RELEASE) -* Download [Manifold : _CSV_](https://repository.sonatype.org/service/local/artifact/maven/redirect?r=central-proxy&g=systems.manifold&a=manifold-csv&v=RELEASE) -* Download [Manifold : _YAML_](https://repository.sonatype.org/service/local/artifact/maven/redirect?r=central-proxy&g=systems.manifold&a=manifold-yaml&v=RELEASE) -* Download [Manifold : _Properties_](https://repository.sonatype.org/service/local/artifact/maven/redirect?r=central-proxy&g=systems.manifold&a=manifold-properties&v=RELEASE) -* Download [Manifold : _Image_](https://repository.sonatype.org/service/local/artifact/maven/redirect?r=central-proxy&g=systems.manifold&a=manifold-image&v=RELEASE) -* Download [Manifold : _Dark Java_](https://repository.sonatype.org/service/local/artifact/maven/redirect?r=central-proxy&g=systems.manifold&a=manifold-darkj&v=RELEASE) -* Download [Manifold : _JavaScript_](https://repository.sonatype.org/service/local/artifact/maven/redirect?r=central-proxy&g=systems.manifold&a=manifold-js&v=RELEASE) - -
- -* Download [Manifold : _Java Extension_](https://repository.sonatype.org/service/local/artifact/maven/redirect?r=central-proxy&g=systems.manifold&a=manifold-ext&v=RELEASE) - -
- -* Download [Manifold : _Java Properties_](https://repository.sonatype.org/service/local/artifact/maven/redirect?r=central-proxy&g=systems.manifold&a=manifold-props&v=RELEASE) - -
- -* Download [Manifold : _Templates_](https://repository.sonatype.org/service/local/artifact/maven/redirect?r=central-proxy&g=systems.manifold&a=manifold-templates&v=RELEASE) - -
- -* Download [Manifold : _String Templates_](https://repository.sonatype.org/service/local/artifact/maven/redirect?r=central-proxy&g=systems.manifold&a=manifold-strings&v=RELEASE) -* Download [Manifold : _[Un]checked_](https://repository.sonatype.org/service/local/artifact/maven/redirect?r=central-proxy&g=systems.manifold&a=manifold-exceptions&v=RELEASE) - -
- -* Download [Manifold : _Preprocessor_](https://repository.sonatype.org/service/local/artifact/maven/redirect?r=central-proxy&g=systems.manifold&a=manifold-preprocessor&v=RELEASE) - -
- -* Download [Manifold : _Science_](https://repository.sonatype.org/service/local/artifact/maven/redirect?r=central-proxy&g=systems.manifold&a=manifold-science&v=RELEASE) - -
- -* Download [Manifold : _Collections_](https://repository.sonatype.org/service/local/artifact/maven/redirect?r=central-proxy&g=systems.manifold&a=manifold-collections&v=RELEASE) -* Download [Manifold : _I/0_](https://repository.sonatype.org/service/local/artifact/maven/redirect?r=central-proxy&g=systems.manifold&a=manifold-io&v=RELEASE) -* Download [Manifold : _Text_](https://repository.sonatype.org/service/local/artifact/maven/redirect?r=central-proxy&g=systems.manifold&a=manifold-text&v=RELEASE) - -
- -* Download [Manifold : Util](https://repository.sonatype.org/service/local/artifact/maven/redirect?r=central-proxy&g=systems.manifold&a=manifold-util&v=RELEASE) - -# License - -Manifold is open source and licensed under the [Apache 2.0](http://www.apache.org/licenses/LICENSE-2.0) license. - -# Author - -* [Scott McKinney](mailto:scott@manifold.systems) - -# Forum -Join our [Discord server](https://discord.gg/VYUpzA64) to start -a discussion, ask questions, provide feedback, etc. Someone is usually there to help. diff --git a/docs/licenses.md b/docs/licenses.md deleted file mode 100644 index 865b64b60..000000000 --- a/docs/licenses.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -layout: default ---- - -
- -# Licenses - -Manifold is open source and licensed under the [Apache 2.0](http://www.apache.org/licenses/LICENSE-2.0) license. - -## Plugin for IntelliJ IDEA and Android Studio - -The [Manifold Plugin](https://plugins.jetbrains.com/plugin/10057-manifold) is available separately via -the [JetBrains Marketplace](https://plugins.jetbrains.com/). \ No newline at end of file diff --git a/docs/manifold-js.md b/docs/manifold-js.md deleted file mode 100644 index 1127236d1..000000000 --- a/docs/manifold-js.md +++ /dev/null @@ -1,357 +0,0 @@ ---- -layout: default ---- -# The Javascript Manifold - -The Javascript Manifold (Manifold.js) is a [Manifold](http://manifold.systems/) extension library that allows for seamless interaction with javascript -resources from Java using the [Rhino](https://github.com/mozilla/rhino) project. - -The library supports the use of javascript programs from Java, the use of ES6-flavored javascript classes from -java, the use of Java classes from javascript, as well as the creation of type-safe javascript expressions for -use in Java as a scripting layer. - -## Javascript Program Support - -Manifold.js makes standard ES5-style Javascript programs available as types in Java. - -The entire javascript program is evaluated when the type is first accessed. Top level functions -are accessible as static methods on the program type. - -### Functions - -Here is an example top-level function found in `ExampleProgram.js`: - -```javascript - function hello(name) { - return "Hello " + name; - } -``` - -This function could be invoked from Java like so: - -```java - System.out.println( ExampleProgram.hello("Java Programmers") ) -``` - -### Parameter & Return Types - -The parameters and the return type of javascript functions are all of type `Object`. - -### Variables - -Top level variables in javascript programs are treated as global variables and will retain their values -between evaluation. Given this function: - -```javascript - var i = 0; - - function nextNum() { - return i++; - } -``` - -The following code - -```javascript - System.out.println( ExampleProgram.nextNum() ) - System.out.println( ExampleProgram.nextNum() ) -``` - -will print - - 0.0 - 1.0 - -### Typescript-Style Typing (Parameters & Return Types) - -In order to allow for greater control and readability in Java, Manifold.js allows you to specify the types parameters and return -types using Typescript syntax. - -Javascript: - -```javascript - import java.util.ArrayList; - class Sample { - constructor(a : String) { - this.foo = a; - } - - foo (bar: String, baz : Integer) : ArrayList { - var arrlist = new ArrayList(); - for(var i = 0 ; i < baz ; i ++) { - arrlist.add(bar); - } - return arrlist; - } - } -``` - -Java: - -```java - Sample sample = new Sample(); - System.out.println(foo("Hello", 5)) // ["Hello","Hello","Hello","Hello","Hello"] -``` - -### ES6-style Arrow Functions - -Manifold.js supports the use of ES6 Arrow Functions inside any Javascript program or class. - -Javascript: - -```javascript - //Arrow function expression - function filterEvens(list) { - return list.filter( a => a % 2 == 0); - } - - //Arrow function statements - function incrementList(list) { - return list.map( a => {return a + 1}); - } -``` - -## Experimental Features - -The following features are experimental. - -### Javascript Class Support - -Javascript classes are exposed as regular classes in Java. They have the same functionality as Java classes, -including constructors, methods, static methods, and properties. - -Javascript: foo.js - -```javascript - class Foo { - - //Constructor - constructor(a) { - this.foo = a; - this._bars = 5; - } - - //Methods - function bar() { - return this.foo * 2; - } - - function baz(a,b) { - return a+b + this.foo; - } - - //Static Methods - static hello() { - return "hello"; - } - - //Properties - get bars() { - return this._bars*2; - } - - set bars(a) { - this._bars = a; - } - - } -``` - -#### Constructor -The constructor is called when a new object is created. It initializes the properties within the object. - -Javascript: - -```javascript - class Foo { - constructor(a) { - this.bar = a; - } - } -``` - -Java: - -```java - Foo foo = new Foo(5); // Creates new Foo object and sets this.bar to a -``` - -#### Methods - -Methods are functions that are assigned to classes. They can interact with properties of the class and call other -internal methods. - -Javascript: - -```javascript - class Foo { - - constructor(a) { - this.foo = a; - } - - function bar() { - return this.foo * 2; - } - } -``` - -Java: - -```java - Foo foo = new Foo(21); - System.out.println(foo.bar); // prints 42 -``` -#### Static Methods - -Javascript: - -```javascript - class Foo { - constructor(a) { - this.foo = a; - this._bars = 5; - } - - static function staticFoo() { - return 42; - } - } -``` - -Java: - -```java - System.out.println(Foo.staticFoo()); // Prints 42 -``` - -#### Properties -Classes can have getter and setter properties which abstract the properties held within the class. - -Javascript: - -```javascript - class Foo { - constructor(a) { - this.foo = a; - this._bars = 5; - } - get bars() { - return this._bars*2; - } - - set bars(a) { - this._bars = a; - } - } -``` - -Java: - -```javascript - Foo foo = new Foo(); - foo.setBars(21); - System.out.println(foo.getBars()) // Prints 42 -``` - -### Javascript Template Support - -Javascript templates are supported as first class citizens. A Javascript String Template is a file that ends -in the .jst extension. - -Javascript Template: SampleJSTemplate.jst - - <%@ params(names) %> - - All Names: <%for (var i = 0; i < names.length; i++) { %> - ${names[i]} - <% } %> - -The template declares the parameters using the `<%@ params() %>` directive, and can import Java classes using -the <%@ import %> directive. - -Javascript statements can be added between the `<%` and `%>` punctuators, which are evaluated as Javascript but -added directly to the generated string. - -Javascript expressions can be added either between the `${` and `}` punctuators or the `<%=` and `%>` punctuators, -and are evaluated and added to the generated string. - -Javascript templates can then be rendered from Java like so: - -Java: - -```java - - String str = SampleJSTemplate.renderToString({"Carson", "Kyle", "Lucca"}); - System.out.println(str) - -``` - -### Accessing Javascript Classes from Java - -Javascript classes can be accessed using the same syntax as Java classes. - -Java: - -```java - Foo foo = new Foo(10); - System.out.println(foo.bar()); // 20 - System.out.println(foo.getBars()); // 5 - - foo.setBars(20); - System.out.println(foo.getBars()) // 40 - System.out.println(Foo.hello()) // Hello -``` - -#### Accessing Java Classes from Javascript - -The (non-standard javascript) import statement is used to extend Java classes with javascript methods. - -Here is some example javascript: hello.js - -```javascript - import java.util.ArrayList; - - function hello() { - var arrlist = new ArrayList(); - arrlist.add(1); - arrlist.add(2); - arrlist.add(3); - System.out.println(arrlist.toArray(new Integer[arrlist.size()])); - } -``` - -This can be invoked from Java like so: - -```java - hello.hello(); //prints [1,2,3] -``` - -NB: The import statement in Manifold.js acts like the java import statement, not the (unsupported) javascript version. - -#### Extending Java Classes from Javascript - -Java classes can be extended using javascript, allowing for the creation of modified classes. One -known limitation is that the constructor of the superclass cannot be overwritten. - -Javascript: - -```javascript - import java.util.ArrayList; - - class SizePrints extends ArrayList { - printSize() { - System.out.println(super.size()); - } - } -``` - -Java: - -```java - SizePrints demo = new sizePrints(); - demo.add(1); - demo.add(2); - demo.add(3); - demo.printSize(); // Prints 3 -``` diff --git a/docs/manifold-templates.md b/docs/manifold-templates.md deleted file mode 100644 index ebb85d39a..000000000 --- a/docs/manifold-templates.md +++ /dev/null @@ -1,682 +0,0 @@ ---- -layout: default ---- - -# ManTL (Manifold Template Language) - -ManTL is a lightweight & *type-safe* template engine directly integrated with the Java compiler using [Manifold](http://manifold.systems/). -It supports the full Java language, type-safe arguments to templates, type-safe inclusion of other templates, -shared layouts for templates and custom base classes for application-specific logic, among other features. - -Templates compile directly in your build as if Java source files _without a separate code generation build step_, therefore -your Java source code can reference and use your template files by name directly as _Java classes_. This level of -integration and type-safety promotes higher levels of integrity and performance. It also enables tooling like the [Manifold IntelliJ plugin](https://plugins.jetbrains.com/plugin/10057-manifold) -to provide deterministic code completion, navigation, usage searching, and refactoring. Additionally the IntelliJ plugin -enables incremental compilation and hot swap debugging, allowing you to make template changes in a running application. - -> Clone the [Manifold sample Web App project](https://github.com/manifold-systems/manifold-sample-web-app) to quickly -begin experimenting with ManTL templates using the Manifold IntelliJ plugin. - -## Table of Contents -* [Installing](#installing) -* [Usage](#usage) -* [Syntax](#basic-syntax) - * [Statements](#statements) - * [Expressions](#expressions) - * [Comments](#comments) - * [Directives](#directives) - * [`import`](#-import-) - * [`extends`](#-extends-) - * [`params`](#-params-) - * [`include`](#-include-) - * [`section`](#-section-) - * [`layout`](#-layout-) - * [`content`](#-layout-) -* [Whitespace](#whitespace) -* [**Spark** Java Support](#spark) - * [Hello World!](#spark-hello-world) - * [Tracing](#tracing) - * [Template Base Class](#spark-template) - * [Sample Application](#demo) - - - -# Installing - -Use ManTL in your project simply by adding the `manifold-template` dependency. - -Maven: -```xml - - systems.manifold - manifold-templates - - 0.71-alpha - -``` - -Gradle: -```groovy - compile group: 'systems.manifold', name: 'manifold-templates', version: 'RELEASE' -``` - -> Note [prebuilt binaries](http://manifold.systems/docs.html#binaries) are also available for non-Maven/Gradle projects. - -# Usage - -Once you have installed ManTL, you can begin using it by placing a new file with the `mtl` extension in your _resources_ -directory (nb: not in your source directory). The file can have any sort of string content, as well as [dynamic content](#basic-syntax) -and [directives](#directives) that change how the template behaves. - -> Note it is helpful, but not required, to include the file extension of the target content in the template file name. -For instance, a template that produces HTML as output is named *MyTemplate.html.mtl* - -Consider the following template named `HelloWorld.txt.mtl`, located in the `resources/templates` directory: - -```jsp -Hello World! -``` -This template can be used directly from your Java code: - -```java -import templates.HelloWorld; -public class Demo { - public static void main(String[] args) { - System.out.println(HelloWorld.render()); - } -} -``` - -This prints `Hello World` to your console. - -If you want to add a parameter to the template, you can change the template to use the [`params`](#-params-) directive: - -```jsp -<%@ params(String name) %> -Hello ${name}! -``` - ->Note you can make changes to your templates in IntelliJ while debugging your application. The Manifold plugin for -IntelliJ hot swaps incremental compilation changes into your running application. - -You can call this parameterized template with a `String` argument: - -```java -import templates.HelloWorld; -public class Demo { - public static void main(String[] args) { - System.out.println(HelloWorld.render("ManTL")); - } -} -``` - -Which prints `Hello ManTL!` to your console. - -If you do not wish to materialize the template as a string, you can use the `renderInto()` method to render templates -into any `Appendable` object. The `renderInto()` method is similar to `render()` but defines an additional `Appendable` -parameter and returns `void`. - - - -# Syntax - -As with most template languages, a ManTL template consists of regular textual content interspersed with language -constructs such as statements, expressions, comments, and directives. - - - -## Statements - -ManTL lets you control output of a template with Java language statements. You inline statements or statement fragments -in a template using this syntax: - -```jsp -<% java-statement-parts %> -``` - -ManTL supports all Java language statements including variable and method declarations and control structures. For -example, the `if` statement: - -```jsp -<% if(total >= 90) { %> -Grade: A -<% } %> -``` -results in the following output if `total` is `90` or greater: -```text -Grade: A -``` -otherwise, the statement has no effect on the output. - -Notice the statement is fragmented between two sets of `<% %>` delimiters. You can leverage many of Java's -statements in this way to control the output, including `if-else`, `switch`, `for`, `while`, and `do-while`. - -This example demonstrates how a simple `for` statement can repeat a section of the template's content: -```jsp -<% for(String brand: Arrays.asList("Maserati", "Alfa Romeo", "Abarth") { %> - Fiat brand: ${brand} -<% } %> -``` -Renders as: -```text - Fiat brand: Maserati - Fiat brand: Alfa Romeo - Fiat brand: Abarth -``` - -You can achieve the same result using a Java lambda expression: -```jsp -<% Arrays.asList("Maserati", "Alfa Romeo", "Abarth").forEach(brand -> { %> - Fiat brand: ${brand} -<% }); %> -``` - - - -## Expressions - -A ManTL expression contains a Java language expression, it is evaluated, coerced to a `String`, and -inserted where the expression appears in the ManTL file. - -Use expressions with this syntax: -```jsp -<%= java-expression %> -``` - -Additionally, the following shorthand syntax is also valid: -```jsp -${ java-expression } -``` - -For example, this template: -```jsp - - Expression Example - - <% int y = 10; %> -

The font size of this paragraph is ${y}.

- - -``` - -generates the following HTML: - -```html - - Expression Example - -

The font size of this paragraph is 10.

- - -``` - -Note the statement declaring the `y` variable does not directly contribute to the resulting content. This is because a -statement does not produce a value to display, instead a statement *controls* what displays. By contrast an expression -produces a value, thus it directly renders as part of the template's resulting content, hence both `${y}` expressions -render `10` in the output. - - - -## Comments -Comments are blocks that delimit areas of the template the compiler ignores; they do not contribute to the template's -output. Use them to make comments and to temporarily mask off sections of a template as you like. - ->Note template comments in no way affect the generated Java code, they are exclusively template file comments. - -The syntax of a comment is as follows: -```jsp -<%-- This is a comment --%> -``` - - - -## Directives - -Directives are commands you use to control the compilation and resulting structure of a template. - -Directives have the following syntax: - -```jsp -<%@ directive-name [options] %> -``` - -Here is a summary of all the ManTL directives. More detailed descriptions follow. - -| Directive     | Syntax | Description | -|----------------|---------------------------------------------|-------------------------------------------------------------------------------------| -| import | `<%@ import type-name %>` | Imports Java types for use in template directives, statements, and expressions | -| extends | `<%@ extends class-name %>` | Extends a base class having features suitable for the template file | -| params | `<%@ params(parameter-list) %>` | Parameters for the template, arguments passed via the `render(arg-list)`method | -| include | `<%@ include template-name[(parameter-list)] [if ]%>` | Include a separate template in the template | -| section | `<%@ section section-name(parameter-list) %>` | Creates a sub-template within the template, that can be called from other templates | -| layout | `<%@ layout template-name %>` | Specifies the template in which the declaring template nests its content | -| content | `<%@ content %>` | Used in a `layout` template, denotes where the content of a nested template renders | - - - - -### `import` -Use the `import` directive as you would a Java `import` statement so you can use Java classes without -having to qualify them with package names. - -The syntax of the `import` directive: -```jsp -<%@ import type-name %> -``` - -This example imports the `java.util.HashSet` class and uses it to declare the `myHashSet` variable: -```jsp - -<%@ import java.util.HashSet %> - Import Example - - <% int y = 10; - HashSet myHashSet = new HashSet<>(); - myHashSet.add(y); - myHashSet.add(15); - for(Integer a: myHashSet) { %> -

myHashSet contains ${a}.

- <% } %> - - -``` -The above template produces the following HTML: -```html - - Import Example - -

myHashSet contains 10.

-

myHashSet contains 15.

- - -``` - ->Note `import` directives must precede all other directives in your template. - - - -### `extends` -Use the `extends` directive to make a template extend a custom base class, which you can use to provide -additional application specific functionality e.g., `Request` and `Response` objects in a web application. - -A practical example of the `extends` directive: -```java -package demo; - -import model.Contact; -import manifold.templates.rt.runtime.BaseTemplate; - -public class ExampleTemplate extends BaseTemplate { - - public String displayContact(Contact c) { - if(c.hasName()) { - return c.getName(); - } else { - return c.getEmail(); - } - } - -} -``` - -This allows the developer to render a clean template: - -```jsp -<%@ import model.Contact %> -<%@ extends demo.ExampleTemplate %> -<%@ params(Contact c)%> - -
-
- Contact -
-
- ${displayContact(c)} -
-
-``` - -And easily callable: -```jsp - get("/contact/:id", (req, resp) -> ShowContact.render(Contact.find(req.getParam("id"))); -``` - - - -### `params` - -Use the `params` directive to declare parameters in a template, similar to declaring parameters for a method. - -The syntax of the `params` directive is as follows: -```jsp -<%@ params(parameter-list) %> -``` - -For example, you can create the template `NameDisplay.html.mtl` as the following: - -```jsp -<%@ params(String name) %> -

Your name is: ${myName}

-``` - -You can then include it in another template as follows: - -```jsp - - PARAMS Example - - <%@ include NameDisplay("Robert") %> - <%@ include NameDisplay("Scott") %> - - -``` - -Then, the following HTML will be generated: -```html - - PARAMS Example - -

Your name is: Robert

-

Your name is: Scott

- - -``` - - - -### `include` - -The `include` directive allows users to insert other templates inside of the given template in a type -safe manner. - -The syntax looks like this: -```jsp -<%@ include [template-name] %> -``` - -For example, consider the following template, `MyTemplate.html.mtl`: -```jsp -<% int fontSize = 0; %> - - WHILE LOOP Example - - <% while (fontSize <= 3) { %> - - ManTL Tutorial -
- <%fontSize++;%> - <%}%> - - -``` -We can then include it from another template as such: -```jsp -<%@ include MyTemplate %> -``` - -Both statements will result in the following HTML code: -```html - - WHILE LOOP Example - - - ManTL Tutorial - < - - ManTL Tutorial -
- - ManTL Tutorial -
- - ManTL Tutorial -
- - -``` - -#### Conditional Include -ManTL supports shorthand for conditional inclusion of templates. The following syntax: -```jsp -<% if (condition) { %> - <%@ include MyTemplate %> -<% } %> -``` -Can be condensed to the following: -```jsp -<%@ include MyTemplate if(condition) %> -``` -(Note: In the above, parentheses are optional.) - - - - -### `section` - -The `section` directive creates a subsection of the current template that can be added using the `include` directive in -other templates. - -The syntax of a `section` block: -```jsp -<%@ section section-name[(symbols-used-in-section)] %> - SECTION CONTENT HERE -<%@ end section %> -``` -Note the corresponding `<%@ end section %>` directive must be used to complete the section, otherwise -a compile error results. - -For example, you can create the template `NestedImport.html.mtl` as the following: -```jsp -<%@ import java.util.* %> -

Defines a section

-<%@ section mySection %> - <% HashSet myHashSet = new HashSet<>(); - myHashSet.add(1); - myHashSet.add(2); - myHashSet.add(3); - for(Integer a: myHashSet) { %> -

Font size: ${a}

- <% } %> -<%@ end section %> -

The End

-``` - -The above code will generate the following HTML: -```html -

Defines a section

-

Font size: 1

-

Font size: 2

-

Font size: 3

-

The End

-``` - -Then, you can include `mySection` in a separate template: -```jsp - <%@ include NestedImport.mySection %> -``` - -Which will result in the following HTML: -```html -

Font size: 1

-

Font size: 2

-

Font size: 3

-``` - - - - -### `layout` - -Layouts can be made and used with the `content` and `layout` directives respectively. - -The `content` directive splits the current template into the header and footer of a layout. - -The `layout` directive makes the header and footer of the layout frame the current template. -The current template renders at the location of the `content` directive. - -Both the `content` directive and `layout` directive are only valid in the outermost class -(not within sections) and can only appear once in a template. - -The `params` directive is not yet supported for a template that contains the `content` directive. - -The syntax of a layout template is as follows: -```jsp -HEADER CONTENT HERE -<%@ content %> -FOOTER CONTENT HERE -``` - -For example, you can create the template `LayoutEx.html.mtl`: -```jsp - - - <%@ content %> - - -``` - -And use the layout in the following template: -```jsp -<%@ layout LayoutEx %> -

This is a template that uses a layout.

-

The layout directive can appear anywhere in the template.

-``` - - -The above code will generate the following HTML: -```html - - -

This is a template that uses a layout.

-

The directive can appear anywhere in the template.

- - -``` - -#### Default Layouts - -ManTL also supports the ability to set default layouts for templates in a given package via the -`ManifoldTemplates.java` configuration class: - -```java - // Sets default template for all templates - ManifoldTemplates.setDefaultLayout(MyLayout.asLayout()); - - // Sets default templates for all templates in "some.package" - ManifoldTemplates.setDefaultLayout("some.package", AnotherLayout.asLayout()); -``` - -By default, more specific layout declarations take precedence over less specific ones. For example, templates with a -declared layout (using the `layout` directive) override the default layout. - -Note the generated `asLayout()` static method on layout template classes. This is useful when you override -layouts, as specified below. - - - -#### Layout Overrides - -Sometimes you may want to manually override the layout of a given template in code, -or render a template with no layout. ManTL classes include two fluent helper methods: -`withoutLayout()` and `withLayout(ILayout)` to assist in these cases: - -```java - // Renders the template with no layout, regardless of the configuration - MyTemplate.withoutLayout().render(); - - // Renders MyTemplate with the MyLayout layout, regardless of other configuration - MyTemplate.withLayout(MyLayout.asLayout()).render(); -``` - - - -# Whitespace - -ManTL language constructs are silent with respect to the template's output. That is to say, contiguous whitespace -characters leading and trailing a language construct are omitted from the template's generated content. Whitespace -characters include spaces, tabs, and new lines. -```jsp - <%@ import java.util.ArrayList %> - <% if(true) { <%> -Hi - <% } %> -``` -The above template renders just one line of text consisting of the two characters in the word `Hi`; none of the -whitespace immediately preceding or following the language constructs are included. - - - -# Spark Java Support - -ManTL is designed with web frameworks like [Spark](http://sparkjava.com/) in mind. - - - -## Hello World! -A simple "Hello World!" Spark application making use of ManTL: - -```java -package app; - -import manifold.templates.rt.ManifoldTemplates; -import views.Index; -import views.layout.DefaultLayout; - -import static spark.Spark.*; - -public class WebApp { - public static void main(String[] args) { - // Set up the default layout for the application - ManifoldTemplates.setDefaultLayout(DefaultLayout.asLayout()); - - // Enable tracing - ManifoldTemplates.trace(); - - // Render the Index template - get("/", (req, resp) -> Index.render("Hello World!")); - } -} -``` - -There are two templates in the `resources` directory: `views/Index.html.mtl` and `views/layouts/DefaultLayout.html.mtl`. -Here the code references the `Index` template directly as a Java class. This is a powerful aspect of ManTL -- the -compiler verifies your links are never broken and you can fully leverage the strength of IntelliJ for deterministic -code completion, usage searching, refactoring, navigation, incremental compilation, and hot swap. - -> Note the code takes advantage of the _type-safe_ parameters available in ManTL and no Spark "TemplateEngine" is needed. - - - -### SparkTemplate Base Class - -Manifold provides base class `manifold.templates.rt.sparkjava.SparkTemplate` for use with the `extends` directive -in your templates (or, more commonly, you extend this class and add more of your own application functionality). This -class provides various convenience methods to get the HTTP `Request`, `Response`, etc. and it also automatically escapes -all string content for HTML, to help prevent malicious user input from causing a security issue in your application. - -If you wish, you can output raw HTML in a template that extends `manifold.templates.rt.sparkjava.SparkTemplate` using the -`raw()` function: - -```jsp - ${raw("

Some Raw HTML

")} -``` - - -### Tracing - -ManTL supports performance tracing with the following syntax: -```java - ManifoldTemplates.trace(); -``` -After invoking the `trace()` method, every following `render()` call prints the following to the console: -``` - - Template template-name rendered in time-to-render ms -``` - - - -### Sample Application - -A sample Spark application is available here: - -[https://github.com/manifold-systems/manifold-sample-web-app](https://github.com/manifold-systems/manifold-sample-web-app) diff --git a/docs/news.md b/docs/news.md deleted file mode 100644 index a5d34ff61..000000000 --- a/docs/news.md +++ /dev/null @@ -1,593 +0,0 @@ ---- -layout: default ---- - -# News -

- -## New article at Jaxenter (16 August 2019): - - - - - - -
-

a

-
-

Say Goodbye to Checked Exceptions

-

Modern languages don’t do checked exceptions. But you don’t have to jump ship to share the experience. In this - article Scott McKinney shows you how to stick with Java and completely neutralize checked exceptions with a simple - new addition to the Manifold framework.

-

jaxenter.com

-
-

- - - -## Manifold 2019.1.11 released (12 August 2019) - -Some API and structural cleanup and documentation improvements -* Refined project readme.md files, standardized them, and overall shifted documentation focus more toward Manifold’s -individual projects and away from the current monolithic docs -* JPMS related changes: - * All manifold projects are defined as "automatic" modules now, with explicit names via "Automatic-Module-Name" - * API changes - * renamed 'manifold' package 'manifold.util' to 'manifold.api.util' - * renamed 'manifold.ext' package 'manifold.util' to 'manifold.ext.api' -* Removed 'bootstrap' plugin -* Manifold JavacPlugin is now a self registered Plugin service -* DEPRECATED: '-Xplugin:Manifold' arguments: 'strings' and 'exceptions' - * replaced with new dependencies: 'manifold-strings' and 'manifold.exceptions' - * renamed package 'manifold.api.templ' to 'manifold.strings.api' -* Sample application improvements - * where applicable restructure projects to use only the manifold component frameworks needed (instead of 'manifold-all') - -Bug fixes: -* Fix incremental compilation - * fixes problem where types corresponding with resource files appeared to recompile (or not) randomly in IJ during an incremental build - * fixes problem where manifold fragments would also appear to randomly recompile (or not) during an incremental build -* Fix -processorpath v. --processor-module-path involving JPMS named module(s) in a project -* Fix preprocessor issue where a Java file would not display preprocessor directives correctly in the presence of manifold fragments -* Fix preprocessor JAVA_N_OR_LATER behavior - -Manifold version 2019.1.11 is available for download on [Maven Central](https://search.maven.org/artifact/systems.manifold/manifold-all/2019.1.11/jar). -

- - - -## New article at Jaxenter (5 August 2019): - - - - - - -
-

a

-
-

A Preprocessor for Java

-

Discover how to build multiple targets from a single Java codebase using the new preprocessor from the Manifold - project. In this article Scott McKinney explains how the preprocessor plugs directly into Java’s compiler to - provide seamless conditional compilation using familiar directives.

-

jaxenter.com

-
-

- - - -## Neuer Artikel bei Jaxenter (5. August 2019): - - - - - - -
-

a

-
-

Manifold: Typsicherer Reflexionscode mit @Jailbreak

-

Fällt Euch die Arbeit mit Reflexionscode schwer? Der Reflexionscode an sich ist nicht typsicher, weshalb es später - zu Problemen kommen kann. Doch keine Panik, es gibt eine Alternative! Mit @Jailbreak aus dem Manifold-Projekt kann - man die Typsicherheit bewahren und sich der Effizienz seines Codes sicher sein.

-

jaxenter.de

-
-

- - - -## A Preprocessor for Java (23 July 2019) - -Manifold now provides a fully integrated Java Preprocessor. -

-The Java Preprocessor is designed exclusively for conditional compilation of Java source code. It is directly -integrated into the Java compiler via the Javac Plugin API. Unlike conventional preprocessors it does not incur -separate build steps or additional file I/O, instead it directly contributes to the compilation pipeline.
-
-

echo method

-
-The preprocessor offers a simple and convenient way to support multiple build targets with a single codebase. It -provides advanced features such as tiered symbol definition via `build.properties` files, `-Akey[=value]` compiler -arguments, and environmental symbols such as `JAVA_9_OR_LATER` and `JPMS_NAMED`. The preprocessor is also fully -integrated into IntelliJ IDEA using the Manifold plugin: - -
-

- -

-
- -

-Learn More -

-

- - - -## Manifold 2019.1.8 released (23 July 2019) -New Feature -* the [Java Preprocessor](https://github.com/manifold-systems/manifold/blob/master/manifold-deps-parent/manifold-preprocessor/readme.md), a fully integrated preprocessor for Java -* minor fixes and improvements - -Manifold version 2019.1.8 is available for download on [Maven Central](https://search.maven.org/artifact/systems.manifold/manifold-all/2019.1.8/jar). -

- - - -## Manifold 2019.1.7 released (8 July 2019) - -Manifold **core** changes -* support a **file fragment** as an r-value inlined in a Java String literal [a la F# type provider](https://fsharp.github.io/FSharp.Data/library/JsonProvider.html) -* support Manifold fragments values in Java 13 **text blocks** -* this change is part of the broader [file fragment](http://manifold.systems/docs.html#inlining-with-fragments) set of -changes supporting fragments in comments as type declarations and in String literals as values, to bring type-safe -resources closer to your code - -Manifold **JSON** changes -* add `fromSource()` method for JSON/YAML types to enable quick usage of by-example JSON/YAML resource **data** e.g., - -```java -// Conveniently access the *data* in Preson.json directly and type-safely -Person person = Person.fromSource(); -``` -* enable JSON/YAML **fragments** e.g, as type-safe inlined comments, use `fromSource()` to gain type-safe access to resource data - -Manifold **Javascript** changes -* replace the deprecated nashorn dependency with latest **rhino** -* remove ScriptEngine usage, instead go straight to rhino -* using a shared global scope per thread to avoid expensive js initialization -* each program/class/template has its own scope which in turn delegates to the shared scope -* support javascript type-safely inlined as a string literal via file **fragments** e.g., -`int value = (int) "[.js/] 3 + 4 + 5";` -* this is more a **proof of concept** to demonstrate: -1. the relative simplicity to enable any manifold resource for literal inlining -2. GraphQL is not the only manifold that can be inlined in a literal -3. to prepare for more languages such a **R** -4. to get the general feature in place and ready for java 13 where **text blocks** facilitate multiline scripts (intellij's **injection editing** makes this quite attractive) - -Bug **fixes**: -* Fix [#102](https://github.com/manifold-systems/manifold/issues/102) -* other minor fixes and improvements - -
- ->Manifold release *2019.1.7* is available for download on [Maven Central](https://search.maven.org/artifact/systems.manifold/manifold-all/2019.1.7/jar). -> ->Manifold plugin for Intellij IDEA update *2019.1.7* available at [JetBrains Marketplace](https://plugins.jetbrains.com/plugin/10057-manifold). - -

- - - -## Manifold is "Trick #1" (5 July 2019) -
-Catch [Marco Behler's _**Five Minute Friday**_](https://www.youtube.com/watch?v=-x0QuhWJg-8) coverage of Manifold. -

- -

-

- - -## JetBrains Marketplace is LIVE with Manifold (25 June 2019): -
-JetBrains Marketplace is [LIVE](https://blog.jetbrains.com/platform/2019/06/jetbrains-marketplace-is-live/) today along -with [Manifold IntelliJ plugin release 2019.1.5](https://plugins.jetbrains.com/plugin/10057-manifold). -

-The Manifold IntelliJ IDEA plugin version `2019.1.5` is available directly from your IDE or visit the -[JetBrains Plugins Repository](https://plugins.jetbrains.com/plugin/10057-manifold). -

- - -## Neuer Artikel bei Jaxenter (8. Juni 2019): -
- - - - - -
-

a

-
-

REST API Vision mit Manifold

-

Manifold ist eine einzigartige Open-Source-Technologie, die man in jedem Java-Projekt verwenden kann, um innovative - Sprachfunktionen wie typsichere Metaprogrammierung, Erweiterungsmethoden, Templating und strukturelle Typisierung - nutzen zu können. Im dritten Teil unserer Artikelserie zeigt Scott McKinney, wie man Manifold einsetzen kann, um - JSON Schema als REST API Single Source of Truth (SSoT) festzulegen. Er geht dabei auch darauf ein, wie das Framework - JSON-Schema- und YAML-Ressourcen auf direktem Wege mit Java verbindet, ohne dabei auf Code-Generatoren, kommentierte - POJOs oder andere Zwischenlösungen angewiesen zu sein.

-

jaxenter.de

-
-

- - -## New article at Jaxenter (6 June 2019): -
- - - - - -
-

a

-
-

Type-safe reflection code with `@Jailbreak`

-

Ever overexpose fields and methods just so they can be accessed from tests? Ever write reflection code in order to - access private class members? You can stop doing that now. Maintain integrity and type-safety with @Jailbreak from - the Manifold project.

-

jaxenter.com

-
-

- - -## Manifold 2019.1 is released! (5 June 2019): -
-Announcing Manifold's first official release -- 2019.1 is available! From *Type-safe Metaprogramming*, -*Structural Interfaces*, and *Extension Classes* to *GraphQL*, *JSON Schema*, and *Templates* and everything in between. -All ready for your imagination! - -Manifold version `2019.1.2` is available for download on [Maven Central](https://search.maven.org/artifact/systems.manifold/manifold-all/2019.1.2/jar). -The Manifold IntelliJ IDEA plugin version `2019.1.2` is available directly from your IDE or visit the -[JetBrains Plugins Repository](https://plugins.jetbrains.com/plugin/10057-manifold). -

- - -## A new screencast showcasing Manifold's new GraphQL support (24 May 2019): -
-

- -

-
-Clone the [GraphQL sample application](https://github.com/manifold-systems/manifold-sample-graphql-app) to experiment -with type-safe GraphQL. Don't forget to add the [Manifold plugin](https://plugins.jetbrains.com/plugin/10057-manifold), -and while you're at it add the [JS GraphQL plugin](https://plugins.jetbrains.com/plugin/8097-js-graphql) too; it pairs -extremely well with the Manifold plugin when developing with GraphQL. -

- - -## Manifold 0.71-alpha released (22 May 2019) - -Bug fixes and improvements -* [#90](https://github.com/manifold-systems/manifold/issues/90): improve identifier encoding, fix JSON create/build parameter coercion -* Fix JPS compiler plugin bug involving projects without manifold dependencies -* Add Copier/Copy API support for GraphQL types and operations -* Fix race condition in IJ plugin involving internal caching -* Several minor GraphQL related fixes - -Manifold version 0.71-alpha is available for download on [Maven Central](https://search.maven.org/artifact/systems.manifold/manifold-all/0.71-alpha/jar). -

- - - -## Manifold 0.68-alpha released (16 May 2019) - -Bug fixes and improvements -* [#87](https://github.com/manifold-systems/manifold/issues/87): handle case where a jar file has both a file entry and a directory entry as siblings with the same exact name -* [#88](https://github.com/manifold-systems/manifold/issues/88): extension classes fix -* [#89](https://github.com/manifold-systems/manifold/issues/89): support `graphqls` extension -* fix NPEs related to recent changes involving manifold plugin dormancy when a project is not using manifold dependencies - -Manifold version 0.68-alpha is available for download on [Maven Central](https://search.maven.org/artifact/systems.manifold/manifold-all/0.68-alpha/jar). -

- - - -## Manifold 0.66-alpha released (14 May 2019) - -Bug fixes and improvements -* [#62](https://github.com/manifold-systems/manifold/issues/62): fix "never accessed" warnings for string interpolation -* [#80](https://github.com/manifold-systems/manifold/issues/80), [#81](https://github.com/manifold-systems/manifold/issues/81): fix static ext methods re IJ usage searching, rename, etc. -* [#84](https://github.com/manifold-systems/manifold/issues/84): manifold plugin extensions are "dumb" when project has no dependencies on manifold : they have no side effects when called -* [#85](https://github.com/manifold-systems/manifold/issues/85): fix incremental compile/hotswap of manifold types -* For a project with no manifold dependencies, invoking UI action to create an extension class or ManTL file produces a warning message indicating the dependencies must be added - -Manifold version 0.66-alpha is available for download on [Maven Central](https://search.maven.org/artifact/systems.manifold/manifold-all/0.66-alpha/jar). -

- - - -## Manifold 0.65-alpha released (8 May 2019) - -Bug fixes and improvements -* Improved java source viewer on manifold resources (a debugging aid for type manifold impls in IJ) -* [#75](https://github.com/manifold-systems/manifold/issues/75): Fix stack overflow involving element refs -* [#76](https://github.com/manifold-systems/manifold/issues/76): Define a new [ManTL](http://manifold.systems/manifold-templates.html) directive: `nest`. Behaves exactly like `include` but retains and distributes the indentation whitespace immediately preceding the `nest` directive, and retains whitespace immediately following the directive. The indentation is applied to each line in the resulting `nest`ed template or section. This behavior facilitates the code generation use-case where whitespace formatting, esp. indentation, is significant. -* [#74](https://github.com/manifold-systems/manifold/issues/74): Handle a missed use-case for checked exception suppression -* [#64](https://github.com/manifold-systems/manifold/issues/64): Provide a compile-time error indicating a method reference is not supported on a structural interface method, instead a lambda expression must be used. -* [#63](https://github.com/manifold-systems/manifold/issues/63): Fully support relative JSON refs -* Other minor changes - -Manifold version 0.65-alpha is available for download on [Maven Central](https://search.maven.org/artifact/systems.manifold/manifold-all/0.65-alpha/jar). -

- - - -## Manifold 0.63-alpha released (1 May 2019) - -Manifold 0.63-alpha introduces _schema-first_ **GraphQL** support! - -With the GraphQL Manifold framework `.graphql` (SDL) files come to life in your Java project -- the entire GraphQL type -system is at your fingertips in your Java code. Build and execute queries **type-safely**, make changes to GraphQL schema -files and automatically see and use the changes in your code _without recompiling!_ And **no code generation** steps in -your build. - -Highlights -* **Schema-first** tooling for Java: `*.graphql` schema files are first-class Java types -* True centralized **single source of truth** development, *ZERO* code generation steps in your build -* **Comprehensive** schema support: queries, mutations, types, inputs, interfaces, unions, scalars, & extensions -* Simple, **type-safe** query building and execution -* Excellent **IntelliJ** support via Manifold plugin - -Manifold 0.63-alpha is available for download on [Maven Central](https://search.maven.org/artifact/systems.manifold/manifold-all/0.63-alpha/jar). -

- - - -## Manifold 0.59-alpha released (8 April 2019) - -Bug fixes -* fix jps plugin so that a source root suc as 'target/generated-sources/annotations' exists on disk before we handle incremental compilation -* fix [#60](https://github.com/manifold-systems/manifold/issues/60): regression on primitive JSON list types, ensure component type is boxed regardless of nullability -* other minor fixes - -Manifold 0.59-alpha is available for download on [Maven Central](https://search.maven.org/artifact/systems.manifold/manifold-all/0.59-alpha/jar). -

- - - -## Manifold 0.56-alpha released (2 April 2019) - -Bug fixes -* fix regression involving extension classes where a class in the same project, but a in different module may not work -* fix compilation with module that does not have a dependency on manifold (don't attempt to perform manifold incremental compilation on it) -* only warn about manifold being out of date if the project is already using manifold but is using an older version than the plugin, otherwise no warning -* other minor changes - -Manifold 0.59-alpha is available for download on [Maven Central](https://search.maven.org/artifact/systems.manifold/manifold-all/0.59-alpha/jar). -

- - - -## Manifold 0.55-alpha released (31 March 2019) - -Manifold provides a new option to **Turn Off Checked Exceptions!** - -Highlights -* Simply add the `exceptions` plugin argument e.g., `-Xplugin:Manifold strings exceptions` - * Now checked exceptions behave like unchecked exceptions! No more compiler errors, no more boilerplate try/catch, no more nonsense. - -Bug fixes -* [#55](https://github.com/manifold-systems/manifold/issues/55), don't display warning message re manifold jars for a project without manifold dependencies -* other minor fixes -

- - - -## Manifold 0.53-alpha released (28 March 2019) - -Highlights -* **Support Java 12** -* Fix issues with "Create Extension Method Class" dialog -* Some performance improvements esp. faster manifold resource compilation with larger projects -* Other minor improvements and fixes -

- - - -## Manifold 0.50-alpha released (14 March 2019) - -Highlights -* Provide means to satisfy a structural interface dynamically via registered IProxyFactory service, major perf improvement -* Self type improvements - -Bug fixes -* Fix regression where annotation processing libraries could cause problems with self types, structural types, etc. -* Fix completion issue. A project with multiple unrelated modules can now access extension methods from shared jar files such as Manifold's builtin extensions for String etc. -

- - - -## Manifold 0.48-alpha released (12 March 2019) - -Highlights -* Rewrite @Self implementation to provide comprehensive 'self' type support. Essentially, @Self is suitable as a simpler alternative to recursive generic types. -* @Self can be applied to: - * instance method return type - * instance method parameter type - * instance field type -* You can override methods having @Self in a parameter and maintain the super type's signature, but also have your subclass type enforced, no bridge methods or other shenanigans otherwise present with recursive generics -* @Self is fully supported in *extension methods* ->Note the completion of @Self facilitates [#47](https://github.com/manifold-systems/manifold/issues/47) -- use @Self instead of generic methods and recursive generic types. -

- - - -## Manifold 0.45-alpha released (17 February 2019) - -Structural Interface improvements -* Structural interface improvements - * Provide a solution to eliminate the first-time load/cast overhead for a structural interface. Enable a structural interface to provide its own proxy factory via new optional parameters to @Structural(factoryClass, baseClass) - -JSON Schema improvements -* JSON array types are now concrete types and define a component type named Item - * Thus a JSON array declared as "Users" has type "Users" and, if not a $ref, its nested component type is named "UsersItem" - * The "Users" type is an interface and extends IJsonList, which in extends List -* Added `request(URL)` static method on all JSON API interfaces - * Use to conveniently navigate an HTTP REST API with GET, POST, PUT, PATCH, & DELETE -* IJsonParser no longer wraps lists in bindings with single "value" property -- returns JSON List as-is now -* Fixed bug dealing with not preserving insertion order of oneOf/anyOf union types -* Several other bug fixes along the way -

- - - -## Manifold 0.43-alpha released (7 February 2019) - -Manifold core changes -* Support dynamic compilation/loading of resources in other dependency modules in a multi-module Java 11 (JPMS) project -* Eliminate "built-in" type manifolds, move them all out into separate modules: - * `manifold-properties` - * `manifold-image` - * `manifold-darkj` ->Note although all built-in type manifolds are now registered and loaded separately as services, they are all still included in the `manifold-all` jar - -Manifold JSON changes: -* Support $ref paths of any kind: -``` -$ref: "#someId/foo" -$ref: "#/definitions/raw.name" -etc. -``` -* Support `/properties` in a $ref path -* Support non-standard JSON Schema type names with proper-case, `String`, `Object`, `Array` and also support `double` as an alias for `number`. -* Fix a bug where an errant Json list type has a null component type -* Fix a bug where a $ref to a oneOf type did not add union methods to the ref'ing type -

- - - -## Manifold 0.42-alpha released (2 February 2019) - -New **YAML** support with the new YAML Type Manifold. - -Highlights -* Use JSON Schema and YAML interchangeably -* New JSON Schema fluent API -* Performance optimizations relating to very large scale IntelliJ projects such as IJ CE EAP -* Enhancements to @Precompile -* Manifold works with Lombok (edge release) -* Very large scale projects supported -

- - - -## Manifold 0.37-alpha (17 January 2019) - -Manifold JSON changes -* Support JSON Schema's many curious ways of saying a type is "nullable": - * The type array: `"type": ["", "null"]` - * The union type: `"oneOf": [ ..., {"type": "null"}]` - * The enum type: `"enum": [..., null]` - * OpenAPI's sane way: `"nullable"` - -* Support OpenAPI formats: - * `byte`, `binary` with backing classes: `Base64Encoding` and `OctetEncoding` - * `int64` with `Long`/`long` - * note `int32`, `float`, and `double` formats are naturally accounted for with default backing types Integer/int, Double/double, no need for special formats - -* Support `readOnly` and `writeOnly` -* Support `additionalProperties` and `patternProperties` - * both of these control whether or not a type can be treated as a general map, has methods get(key) and put(key, value) -* Support json schema cycles stemming from `oneOf` i.e., interface Foo extends Foo.InnerClass - * such a cycle is short-circuited by directly incorporating the super interface's property methods in the extending type - * Foo.InnerClass remains an inner class of Foo and Foo remains structurally assignable to Foo.InnerClass (JSON interfaces are structural interfaces) -* Add Builders having withXxx() methods - * a json schema interface now has a static builder(...) method with parameters matching the create(...) method (required properties) - * returns inner class Builder instance having withXxx(x) matching all non-required properties -* Much refactoring to better accommodate the additional `readOnly`, `additionProperties`, etc. attributes - -* support nested `definitions` for JSON Schema -

- - - -## Manifold 0.34-alpha (4 January 2019) - -Manifold Templates (ManTL) changes -* support static imports in the `import` directive -* change template generation to support very large template files esp. content chunks larger than 64k -* several other template related fixes/refactors/changes - -Manifold JSON changes -* Remove overhead of JSON dynamic proxy by removing it in favor of improving the interface API to provide its own implementation - * Usage of a JSON interface no longer involves a runtime delay the first time it is used -* Type-safe support for JSON Schema `enum` types, generate Java enum to correspond with any JSON `enum` including non-string values -* Type-safe, pluggable support for JSON Schema `format` types like `date-time` etc. - * The JSON type manifold supplies a Java service provider API with `IJsonFormatTypeResolver` - * Implement `IJsonFormatTypeResolver` to map Java types to your own formats - * Manifold supports standard JSON Schema formats including `date-time`, `date`, `time` using `java.time.LocalDateTime`, `LocalDate`, and `LocalTime` - * Manifold supports some non-standard formats too including `utc-millisec` with `java.time.Instant` - * Additionally Manifold provides new (non-standard) formats such as `big-integer` and `big-decimal` -* Support `default` value and `required` properties type-safely by adding parameters to the JSON interface's static create() method where each parameter corresponds with a `required` property that does not have a `default` value -* Support `const` as a single value enum type (as described in the JSON Schema) -* Support `allOf`, `anyOf`, `oneOf` where all the component types are enums such that regardless of the all/any/one operation the resulting type is a single enum composed of all the constants in all the component enum types -

- - - -## Manifold 0.33-alpha released (22 December 2018) - -Manifold ext changes -* `@Jailbreak` supports using members of a class to which the JPMS otherwise prohibits access e.g., call a method on a class in a package that is not exported or open to the module of the call site -* small perf improvement on structural proxy generation, test for ICallHandler statically as well as via extension and cache the result -Manifold Templates (ManTL) changes -* fix `section` support involving params -* support lambda usage where the statement block of the lambda is used for generating content -* filter leading spaces associated with some non-content template constructs -

- - - -## Manifold 0.32-alpha (11 December 2018) - -* Fix some issues introduced with Jailbreak (from ver 0.30-alpha) - * Rename `@JailBreak` to proper spelling '@Jailbreak` (doh!) - * Fix problems related to compile error reporting from javac - * Prohibit use of @Jailbreak in compound assignment expressions and increment/decrement expressions; it's better to use direct assignment with '=' - * Resolve https://github.com/manifold-systems/manifold/issues/33 -

- - - -## Manifold 0.30-alpha (7 December 2018) - -New `@JailBreak` feature. - -Gain direct, type-safe access to otherwise inaccessible classes/methods/fields. Use `@JailBreak` to avoid the drudgery and vulnerability of Java reflection: -```java -@JailBreak Foo foo = getFoo(); -foo.privateMethodOnFoo(); -foo.privateFieldOnFoo = value; -``` -Added `jailbreak()` extension method to Object. Use it like `@JailBreak` but directly in an expression: -```java -foo.jailbreak().privateMethodOnFoo() -``` -Bug fixes -* Fixed [#31](https://github.com/manifold-systems/manifold/issues/31) -

- - - -## Manifold 0.28-alpha released (22 November 2018) - -Highlights -* Support the [Self type](http://manifold.systems/docs.html#the-self-type) via the new `@Self` feature -* Fix modifier code gen where public was used instead of the original modifier -* Fix ReflectUtil method invocation to unwrap InvocationTargetException and rethrow original exception -* Other minor changes -

- diff --git a/docs/projects.md b/docs/projects.md deleted file mode 100644 index ccb07844e..000000000 --- a/docs/projects.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -layout: default ---- - -# Projects Quick Reference - -The Manifold project consists of the core Manifold framework and a collection of sub-projects implementing SPIs provided -by the core framework. This document serves as a quick reference to these projects. - -## Core Framework -* [Manifold : _Core_](https://github.com/manifold-systems/manifold/tree/master/manifold-core-parent/manifold) - -## Resource Manifolds -* [Manifold : _GraphQL_](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-graphql) -* [Manifold : _XML_](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-xml) -* [Manifold : _JSON_](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-json) -* [Manifold : _CSV_](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-csv) -* [Manifold : _YAML_](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-yaml) -* [Manifold : _Property Files_](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-properties) -* [Manifold : _Image_](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-image) -* [Manifold : _Dark Java_](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-darkj) -* [Manifold : _JavaScript_](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-js) - -## Java Extension Manifold -* [Manifold : _Java Extension_](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-ext) - -## Java Templates Framework -* [Manifold : _Templates_](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-templates) - -## Java Compiler Extensions -* [Manifold : _Properties_](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-props) -* [Manifold : _Delegation_](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-delegation) -* [Manifold : _Tuples_](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-tuple) -* [Manifold : _String Templates_](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-strings) (string interpolation) -* [Manifold : _[Un]checked_](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-exceptions) - -## Java Preprocessor -* [Manifold : _Preprocessor_](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-preprocessor) - -## Java Science -* [Manifold : _Science_](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-science) - -## Java Extension Libraries -* [Manifold : _Collections_](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-collections) -* [Manifold : _I/0_](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-io) -* [Manifold : _Text_](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-text) - -## Sample Projects -* [Manifold sample project](https://github.com/manifold-systems/manifold-sample-project) -* [Manifold sample GraphQL project](https://github.com/manifold-systems/manifold-sample-graphql-app) -* [Manifold sample REST API project](https://github.com/manifold-systems/manifold-sample-rest-api) -* [Manifold sample Web App project](https://github.com/manifold-systems/manifold-sample-web-app) -* [Manifold sample Kotlin App project](https://github.com/manifold-systems/manifold-sample-kotlin-app) -* [Manifold sample Gradle Project](https://github.com/manifold-systems/manifold-simple-gradle-project) \ No newline at end of file diff --git a/docs/roadmap.md b/docs/roadmap.md deleted file mode 100644 index dd2da5593..000000000 --- a/docs/roadmap.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -layout: default ---- - -# Roadmap - -![roadmap](http://manifold.systems/images/roadmap.jpg) - -Recently completed: -* [tuple expressions](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-tuple) -* [`auto` type inference](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-ext#type-inference-with-auto) -* [multiple return values](https://github.com/manifold-systems/manifold/tree/master/manifold-deps-parent/manifold-ext#multiple-return-values) - -Working on:
-* IntelliJ plugin bugs