org.stekikun.dolmen.codegen

Class CodeBuilder

java.lang.Object

org.stekikun.dolmen.codegen.CodeBuilder

public final class CodeBuilder
extends Object

An instance of this utility class manages a string buffer with a current indentation level, which allows for convenient declarative generation of user-readable code.

It can also be used to track the origins of some of the regions of the generated code, typically in order to keep track of pieces of code that are copied verbatim from some other source file into the code builder (see withTracker(String, int)).

Author:

Stéphane Lescuyer

Field Summary

Fields

Modifier and Type	Field and Description
static int	PER_LEVEL Amount of indentation per level

Constructor Summary

Constructors

Constructor and Description
CodeBuilder(int level) Returns a fresh code builder starting with the given indentation level, and using a fresh instance of StringBuilder as the internal target of emitted code

Method Summary

Modifier and Type	Method and Description
CodeBuilder	closeBlock() Closes a curly-braced block with decremented indentation, i.e. is equivalent to: decrIndent(); newline(); emit("}"); newline();
CodeBuilder	closeBlock0() Closes a curly-braced block with decremented indentation and without breaking the line after the closing brace, i.e. is equivalent to: decrIndent(); newline(); emit("}"); It is useful when closing several blocks in a row to avoid empty lines.
String	contents() Returns the current contents of this code builder buffer
CodeBuilder	decrIndent() Decrements the indentation level by 1 (and the indentation amount by PER_LEVEL
CodeBuilder	emit(char c) Appends the given character, which should not be a newline characters unless indentation is not required
CodeBuilder	emit(CharSequence code) Appends the given characters, which should not contain newline characters unless indentation of the given piece of code is not required
CodeBuilder	emitIf(boolean cond, String code) Appends the given code, which should not contain newline characters, provided the condition cond holds
CodeBuilder	emitln(String line) Appends the given line of code and emits a terminal newline()
CodeBuilder	emitlnIf(boolean cond, String line) Appends the given line of code and emits a terminal newline(), provided the condition cond holds
CodeBuilder	emitTracked(CExtent extent) Convenient helper which emits the content of some verbatim piece of code described by the given extent, and maps it to the extent's original position.
CodeBuilder	emitTrackedIf(boolean cond, CExtent extent) Same as emitTracked(CExtent) but is only performed if the given condition holds.
CodeBuilder	endTrackedRange(@Nullable CExtent extent) Closes the currently tracked region and maps it to the source position given in the corresponding call to startTrackedRange(LexBuffer.Position).
int	getCurrentLevel()
SourceMapping	getSourceMapping()
CodeBuilder	incrIndent() Increments the indentation level by 1 (and the indentation amount by PER_LEVEL)
CodeBuilder	newline() Starts a new line with the current indentation amount
CodeBuilder	openBlock() Opens a new curly-braced block with incremented indentation, i.e. is equivalent to: emit(" {"); incrIndent(); newline();
void	print(Appendable appendable) Prints all code emitted thus far in this code builder into the provided appendable
CodeBuilder	startTrackedRange(LexBuffer.Position pos) Starts tracking a new region from the current position in the emitted code.
void	withTracker(String generated, int offset) Configures this CodeBuilder to be ready to start tracking some regions of the emitted code.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

PER_LEVEL

public static final int PER_LEVEL

Amount of indentation per level

See Also:

Constant Field Values

Constructor Detail

CodeBuilder

public CodeBuilder(int level)

Returns a fresh code builder starting with the given indentation level, and using a fresh instance of StringBuilder as the internal target of emitted code

Parameters:

level -

Method Detail

getCurrentLevel

public int getCurrentLevel()

Returns:

the current indentation level (not the number of spaces, but the number of nested blocks, starting at 0)

incrIndent

public CodeBuilder incrIndent()

Increments the indentation level by 1 (and the indentation amount by PER_LEVEL)

newline

public CodeBuilder newline()

Starts a new line with the current indentation amount

decrIndent

public CodeBuilder decrIndent()

Decrements the indentation level by 1 (and the indentation amount by PER_LEVEL

emit

public CodeBuilder emit(CharSequence code)

Appends the given characters, which should not contain newline characters unless indentation of the given piece of code is not required

Parameters:

code -

emit

public CodeBuilder emit(char c)

Appends the given character, which should not be a newline characters unless indentation is not required

Parameters:

c -

emitln

public CodeBuilder emitln(String line)

Appends the given line of code and emits a terminal newline()

Parameters:

line - should not contain newline characters

emitIf

public CodeBuilder emitIf(boolean cond,
                          String code)

Appends the given code, which should not contain newline characters, provided the condition cond holds

Parameters:

cond -

code -

emitlnIf

public CodeBuilder emitlnIf(boolean cond,
                            String line)

Appends the given line of code and emits a terminal newline(), provided the condition cond holds

Parameters:

cond -

line - should not contain newline characters

openBlock

public CodeBuilder openBlock()

Opens a new curly-braced block with incremented indentation, i.e. is equivalent to:

        emit(" {");
  incrIndent();
  newline();
 

closeBlock0

public CodeBuilder closeBlock0()

Closes a curly-braced block with decremented indentation and without breaking the line after the closing brace, i.e. is equivalent to:

  decrIndent();
        newline();
  emit("}");
 

It is useful when closing several blocks in a row to avoid empty lines.

closeBlock

public CodeBuilder closeBlock()

Closes a curly-braced block with decremented indentation, i.e. is equivalent to:

  decrIndent();
  newline();
        emit("}");
  newline();
 

contents

public String contents()

Returns the current contents of this code builder buffer

print

public void print(Appendable appendable)
           throws IOException

Prints all code emitted thus far in this code builder into the provided appendable

Parameters:

appendable -

Throws:

IOException

withTracker

public void withTracker(String generated,
                        int offset)

Configures this CodeBuilder to be ready to start tracking some regions of the emitted code. Should only be called once: extra calls will be ignored.

Once this instance is configured, the various methods that take advantage of region tracking can be used:

• getSourceMapping()
• startTrackedRange(LexBuffer.Position)
• endTrackedRange(CExtent)
• emitTracked(CExtent)
• emitTrackedIf(boolean, CExtent)

The tracked regions will refer to their positions in the emitted code relative to the current amount of code already emitted when this method is called, plus the given offset.

Parameters:

generated - the name describing the code being generated

offset - a non-negative offset describing where this code is going to be emitted in the actual generated file

getSourceMapping

public SourceMapping getSourceMapping()

Returns:

the current source mappings representing the regions that have already been tracked

Throws:

IllegalArgumentException - if tracking has not been enabled with withTracker(String, int)

startTrackedRange

public CodeBuilder startTrackedRange(LexBuffer.Position pos)

Starts tracking a new region from the current position in the emitted code. The region will be mapped with the corresponding region at the given position pos in the source file.

Only one region can be tracked at any given time. Successive calls to startTrackedRange(LexBuffer.Position) without any calls to endTrackedRange(CExtent) will be ignored.

Parameters:

pos -

Throws:

IllegalArgumentException - if tracking has not been enabled with withTracker(String, int)

See Also:

endTrackedRange(CExtent)

endTrackedRange

public CodeBuilder endTrackedRange(@Nullable CExtent extent)

Closes the currently tracked region and maps it to the source position given in the corresponding call to startTrackedRange(LexBuffer.Position). It will now be registered into the source mappings.

If no region was being tracked, this call is ignored.

Parameters:

extent - if non-null, describes how the emitted contents were obtained by instantiating placeholders in the corresponding source region

Throws:

IllegalArgumentException - if tracking has not been enabled with withTracker(String, int)

emitTracked

public CodeBuilder emitTracked(CExtent extent)

Convenient helper which emits the content of some verbatim piece of code described by the given extent, and maps it to the extent's original position. There should be no currently tracked region or the results will be unexpected.

Parameters:

extent -

Throws:

IllegalArgumentException - if tracking has not been enabled with withTracker(String, int)

emitTrackedIf

public CodeBuilder emitTrackedIf(boolean cond,
                                 CExtent extent)

Same as emitTracked(CExtent) but is only performed if the given condition holds. Convenient for conditional output based on preferences/debug/etc.

Parameters:

cond -

extent -