org.stringtemplate.v4.STWriter Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of ST4 Show documentation

StringTemplate is a java template engine for generating source code, web pages, emails, or any other formatted text output. StringTemplate is particularly good at multi-targeted code generators, multiple site skins, and internationalization/localization. It evolved over years of effort developing jGuru.com. StringTemplate also powers the ANTLR 3 and 4 code generator. Its distinguishing characteristic is that unlike other engines, it strictly enforces model-view separation. Strict separation makes websites and code generators more flexible and maintainable; it also provides an excellent defense against malicious template authors.

There is a newer version: 4.3.4

Show newest version

/*
 * [The "BSD license"]
 *  Copyright (c) 2011 Terence Parr
 *  All rights reserved.
 *
 *  Redistribution and use in source and binary forms, with or without
 *  modification, are permitted provided that the following conditions
 *  are met:
 *  1. Redistributions of source code must retain the above copyright
 *     notice, this list of conditions and the following disclaimer.
 *  2. Redistributions in binary form must reproduce the above copyright
 *     notice, this list of conditions and the following disclaimer in the
 *     documentation and/or other materials provided with the distribution.
 *  3. The name of the author may not be used to endorse or promote products
 *     derived from this software without specific prior written permission.
 *
 *  THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
 *  IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
 *  OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
 *  IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
 *  INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
 *  NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 *  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 *  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 *  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
 *  THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
package org.stringtemplate.v4;

import org.stringtemplate.v4.compiler.Bytecode;

import java.io.IOException;

/** Generic StringTemplate output writer filter.
 * 
 *  Literals and the elements of expressions are emitted via {@link #write(String)}.
 *  Separators are emitted via {@link #writeSeparator(String)} because they must be
 *  handled specially when wrapping lines (we don't want to wrap
 *  in between an element and it's separator).
 */
public interface STWriter {
    int NO_WRAP = -1;

    void pushIndentation(String indent);

    String popIndentation();

    void pushAnchorPoint();

    void popAnchorPoint();

    void setLineWidth(int lineWidth);

    /** Write the string and return how many actual characters were written.
     *  With auto-indentation and wrapping, more chars than {@code str.length()}
     *  can be emitted.  No wrapping is done.
     */
    int write(String str) throws IOException;

    /** Same as write, but wrap lines using the indicated string as the
     *  wrap character (such as {@code "\n"}).
     */
    int write(String str, String wrap) throws IOException;

    /**
     * Because we evaluate ST instance by invoking
     * {@link Interpreter#exec(STWriter, InstanceScope)} again, we can't pass options in.
     * So the {@link Bytecode#INSTR_WRITE} instruction of an applied template
     * (such as when we wrap in between template applications like
     * {@code ]}; wrap>}) we need to write the {@code wrap} string
     * before calling {@link Interpreter#exec}. We expose just like for the
     * separator. See {@link Interpreter#writeObject} where it checks for ST
     * instance. If POJO, {@link Interpreter#writePOJO} passes {@code wrap} to
     * {@link STWriter#write(String str, String wrap)}. Can't pass to
     * {@link Interpreter#exec}.
     */
    int writeWrap(String wrap) throws IOException;

    /** Write a separator.  Same as {@link #write(String)} except that a {@code "\n"}
     *  cannot be inserted before emitting a separator.
     */
    int writeSeparator(String str) throws IOException;

    /** Return the absolute char index into the output of the char
     *  we're about to write.  Returns 0 if no char written yet.
     */
    int index();
}