Introduction

Unlike other "Model-to-Text" engines (JSP, Velocity and the like), there is no need for external template files. Dynamic code and static content are both contained in the same Java file.

Writing Sugar4j code should resemble most what programmers would write in plain Java. There exists only a few special 'higher-level-constructs' to learn (like var, method or call). All other code just looks like Java. A Java programmer is quickly able to 'read behind' the Sugar4j code and identify the relevant Java code parts of the template.

Sugar4j's naming scheme is quite special.
Using a fluent interface, the obvious name for a method to output the public keyword would be public(). But that's not possible. So what name then closest looks like public? The answer is: publicc
But why?

Arcicondg to a reheeasrcr at an Eligsnh uvitneirsy, it deson't meattr in what oderr the ltetres in a word are, the only irmapontt tinhg is that frsit and last leettr is at the rghit pacle. The rest can be a ttaol mess and you can siltl read it whotuit pbloerm. This is baucsee we do not read eervy leettr by it self but the word as a wolhe.

More on this topic can be found here. You can even try it out yourself here.

So according to this amazing study, the ideal name is publicc. Except for the last character, everything is the same. If you want public in the output, just start writing public.

For every Java keyword, there exists a method with the same name but it's last character appended. new becomes neww(), class becomes classs(), throws becomes throwss().
The same naming scheme is applied to primitive types and literals: intt, booleann, doublee, truee, falsee, nulll. For a complete list see Javadoc sugar4j.lang.JavaLang.

Another unique pattern of Sugar4j is to make extensive use of the Java 5.0 varargs feature. Where appropriate, the varargs array elements are treated as Pairs. In a method declaration, for instance, the method parameters are expected to occur in type-name pairs: The name "Sugar4j" originated from asking the question: What other stuff does one need for a cup of Java? You have the jar, you have the beans...and I personally don't like my coffee without sugar. A second meaning comes from the terms "adding syntactical sugar" or "...is only syntactical sugar". To be precise: Sugar4j is rather syntactical salt, but I just don't like salt in my coffee :)

These are the main advantages of Sugar4j:

• Having only one source file means maintaining only one source file, only one programming language to learn/understand, only one editor: the one you use the most because it is the best.
• Parameter documentation. At some point you must access your dynamic data within your template. Without such a feature, the whole thing does not make sense. This data is made available mostly using prefixed identifiers such as #className or $member. Where are those parameters documented? Are they even used anymore? In Sugar4j you use Java and Javadoc.
• Reference analysis and refactoring. External text templates behave contrarily to a source file's life cycle. 80% of a source file's life cycle is spent in maintaining it. Only 20% for it's initial creation. A template is created very fast. Take some sample class, replace all occurences of "XXX" to "<%= className %>", put a loop around it, save it as "MyClass.jsp" and your done. But later you must add new features to it, the String list is'nt sufficent anymore. You must introduce a new class. Which code is affected? Who needs that variable again? I better copy and paste that code. So in 80% of the time it is hard to program. Only if 20% of the time it is cool. Creating a Sugar4j class is (relative) hard in 20% of the time, and cool in 80% of the time! It's seems hard to write 'begin()' instead of '{'. Yes, but you get used to it. With some routine your eye simply identify 'begin()' as being '{'. There's no need to read it. The more imporant thing is the indent level, which precisely shows the structure of your program. Thanks to your one and only code formatter.

import sugar4j.Sugar4j;
import sugar4j.lang.JavaIo;

public class MyIoSugar extends Sugar4j<MyIoSugar> implements JavaIo {
  public MyIoSugar() {
    super("tutorial.MyIo");
  }

  public void doCreate() {
    publicc().classs().begin();
    {
      publicc().method(Reader, "createReader").begin();
      {
        var(Reader, "reader").assign().neww(FileReader, "/myfile.txt").eos();
        returnn("reader").eos();
      }
      end();
    }
    end();
  }
}

import sugar4j.Sugar4j;
import static sugar4j.lang.JavaIo.Reader;
import static sugar4j.lang.JavaIo.FileReader;

public class MyIoSugar extends Sugar4j<MyIoSugar> {
  public MyIoSugar() {
    super("tutorial.MyIo");
  }

  public void doCreate() {
    publicc().classs().begin();
    {
      publicc().method(Reader, "createReader").begin();
      {
        var(Reader, "reader").assign().neww(FileReader, "/myfile.txt").eos();
        returnn("reader").eos();
      }
      end();
    }
    end();
  }
}