'Transformized' grammar seems hard to read, because it's
packed and powerfull.
If good source code standards are used, it is consistent and easy to change.
Jjdoc-generated html grammar tree is used for orientation in whole grammar.
add(Object), conc(Object),toString() is
indented by depth of their level
and newline character(s) are replaced by system newline character(s).
toString() and saved to file, written from servlet to TCP packet...
this ret.add( "//Assignment on next line" ).preadd(..), preconc(..) should be used with care and not very
often, otherwise they decrease readability. 'Local root' container
of unshifted subcontainers is used for more complicated compositions.
toString(),equals(Object) checks whether parameter is Trans and has
equal text represenation. Because result of toString() is uncachable, this
shouldn't be used often.
Trans empty(), unshifted(), error(String), unfinished;Trans.empty()... or subclassing Trans. So it's left up to user.
Trans(int) is used to specify offset other than default.
Trans(Object) is used to specify first Object, String or Trans item.
void.
Trans ret= new Trans(). Constructor for retret
always from end of production. Even if translation result is
finally known before getting to end, where next optional
statements are 'not important' or actual statement can be
repeated more time, result must be returned after parsing those parts. Otherwise,
translator will 'sometimes' fails when those 'unimportant' parts appear,
because parser won't consume them after production method already returned.
Transformize' higher statements first,
starting from root and its direct substatements, to
develop and debug root parts. And/Or write debugging results
to standard output from leaf statements if designing
customized classes for them first, or when using up-down approach.
Token objects are not handled specially by default, as they
have good default toString() method.
Token.toString() to return
item.toLowerCase() or item.toUpperCase(), according
to contract you choose.
equals(Object) that compares
container's items as objects. See comments in source.
*/
public class Trans implements Serializable, Cloneable {
/** System newline character(s) that are used when Trans is transformed
to String. It can changed by user. Its value is used during calls to
toString(), write(..), not when containers are composed.
*/
static public final String cr= System.getProperty("line.separator","\n");
/** Internal flag object for concatenation of items, never to be printed itself
neither used by user.
Next element will be concatenated to previous one, its
first line will be concatenated to last line of previous text. Otherwise,
when an object is added to container, its text starts on new line.
Nothing wrong happens if it's added several times in sequence in subclassed code
- then whole sequence of references is treated as one, that 'concatenates'
last line of previous and first line of next object.
It's resolved to its actual static representation at deserialization.
*/
static protected final Trans concatenate= new Concatenate();
/** Default number of spaces before each nested level for all new containers.
Its value can be changed by user (initially 3).
@see #Trans(int). */
static public int defaultOffset= 3;
/** Number of spaces written before each line of this container.
*/
protected int offset= defaultOffset;
/** Physical container. No need for synchronized Vector.
User can synchronize on Trans object itself.
*/
protected ArrayList list= new ArrayList();
/** Creates container with default offset.
@see #defaultOffset
*/
public Trans() {}
/** Creates container with specified offset.
@param offs sets number of spaces before each line of this container
*/
public Trans( int offs) { offset= offs;}
/** Created container with default offset and specified item, if not null.
@param obj first item
*/
public Trans( Object obj) {
if( obj!=null)
list.add( obj);
}
/** Adds object to the end of container, if not null. Its content
is indented and starts on
new line. Next item starts on new line, unless it's concatenated.
@param obj item to be added
*/
public Trans add( Object next)
{
if( next!=null)
list.add( next);
return this;
}
/** Adds object at the first place of container, if not null.
Its content is indented and
starts on new line. Former first object starts on new line, so their contents
are not concatenated together. Name "preadd" is more clear than "ins" or "insert",
because it seemed like 'insert it here' in streamed call. Try:
User can redefine new Trans("Third line").preadd("Second line").preadd("First line")
@param obj item to be added.
*/
public Trans preadd( Object next)
{
if( next!=null)
list.add( 0, next);
return this;
}
/** Object is concatenated, if not null. Whole content is indented
except its first line, that is appended to last line of previous item -
concatenated.
@param obj item to be added at end of container
*/
public Trans conc( Object next)
{
if( next!=null) {
if( list.size() >0)
// If concatenate was always added, preadd() didn;t work correctly.
list.add( concatenate);
list.add( next);
}
return this;
}
/** Object is preconcatenated, if not null.
Whole content is indented and it starts on new line.
Last line is concatenated in front of first line of former first object.
@param obj item to be added at first place of container
*/
public Trans preconc( Object next)
{
if( next!=null) {
list.add( 0, next);
list.add( 1, concatenate);
}
return this;
}
/** Adds system newline character(s). In fact, it adds empty string,
and write(..) engine puts there cr newline
character(s) when it is called.
*/
public Trans newLine() {
list.add( "" );
return this;
}
public Trans add(boolean par) {
list.add( String.valueOf(par) );
return this;
}
public Trans preadd(boolean par) {
list.add( 0,String.valueOf(par) );
return this;
}
public Trans conc(boolean par) {
if( list.size() >0) list.add( concatenate);
list.add( String.valueOf(par) );
return this;
}
public Trans preconc(boolean par) {
list.add( 0, String.valueOf(par) );
list.add( 1, concatenate);
return this;
}
public Trans add(byte par) {
list.add( String.valueOf(par) );
return this;
}
public Trans preadd(byte par) {
list.add( 0,String.valueOf(par) );
return this;
}
public Trans conc(byte par) {
if( list.size() >0) list.add( concatenate);
list.add( String.valueOf(par) );
return this;
}
public Trans preconc(byte par) {
list.add( 0, String.valueOf(par) );
list.add( 1, concatenate);
return this;
}
public Trans add(char par) {
list.add( String.valueOf(par) );
return this;
}
public Trans preadd(char par) {
list.add( 0,String.valueOf(par) );
return this;
}
public Trans conc(char par) {
if( list.size() >0) list.add( concatenate);
list.add( String.valueOf(par) );
return this;
}
public Trans preconc(char par) {
list.add( 0, String.valueOf(par) );
list.add( 1, concatenate);
return this;
}
public Trans add(short par) {
list.add( String.valueOf(par) );
return this;
}
public Trans preadd(short par) {
list.add( 0,String.valueOf(par) );
return this;
}
public Trans conc(short par) {
if( list.size() >0) list.add( concatenate);
list.add( String.valueOf(par) );
return this;
}
public Trans preconc(short par) {
list.add( 0, String.valueOf(par) );
list.add( 1, concatenate);
return this;
}
public Trans add(int par) {
list.add( String.valueOf(par) );
return this;
}
public Trans preadd(int par) {
list.add( 0,String.valueOf(par) );
return this;
}
public Trans conc(int par) {
if( list.size() >0) list.add( concatenate);
list.add( String.valueOf(par) );
return this;
}
public Trans preconc(int par) {
list.add( 0, String.valueOf(par) );
list.add( 1, concatenate);
return this;
}
public Trans add(long par) {
list.add( String.valueOf(par) );
return this;
}
public Trans preadd(long par) {
list.add( 0,String.valueOf(par) );
return this;
}
public Trans conc(long par) {
if( list.size() >0) list.add( concatenate);
list.add( String.valueOf(par) );
return this;
}
public Trans preconc(long par) {
list.add( 0, String.valueOf(par) );
list.add( 1, concatenate);
return this;
}
public Trans add(float par) {
list.add( String.valueOf(par) );
return this;
}
public Trans preadd(float par) {
list.add( 0,String.valueOf(par) );
return this;
}
public Trans conc(float par) {
if( list.size() >0) list.add( concatenate);
list.add( String.valueOf(par) );
return this;
}
public Trans preconc(float par) {
list.add( 0, String.valueOf(par) );
list.add( 1, concatenate);
return this;
}
public Trans add(double par) {
list.add( String.valueOf(par) );
return this;
}
public Trans preadd(double par) {
list.add( 0,String.valueOf(par) );
return this;
}
public Trans conc(double par) {
if( list.size() >0) list.add( concatenate);
list.add( String.valueOf(par) );
return this;
}
public Trans preconc(double par) {
list.add( 0, String.valueOf(par) );
list.add( 1, concatenate);
return this;
}
/** Transforms to String, no first level offset made in this function, so
direct items aren't indented. It can't be cached, see equals(Object).
@see #equals(Object)
*/
public String toString() {
synchronized( getClass() ) { //Because it uses static cr.
return write( new StringBuffer(), -offset, false).toString();
}
}
/**Transforms container's content - all its items to String in recursion,
managing indentation level and concatenation.
Transforms alone characters "\n", "\r" and couples of
"\n\r", "\r\n"to one presence of system
newline character(s). Couples are transformed together only if they are
printed from the same Object with its toString().
@param buffer Buffer of upper container (caller), ending by newline character.
@return Passedbuffer with added content, newline character at
end of each line, but not of last one (so concatenation can be made
to it by the successor).
*/
protected StringBuffer write( StringBuffer buffer, int offs, boolean conc)
/* Because this is protected, it doesn't synchronise( getClass() ) for efficiency,
even it uses static cr. Thus all methods that call it should synchronize this way.
*/
{
int c= list.size()-1;
for( int i=0; i<= c; i++)
{
Object what= list.get( i);
Object prev, next;
if( what==null) //Hm, can this happen? Some old code, oldies are good.
continue;
if ( what instanceof Trans)
{
Trans twhat= (Trans) what;
if( twhat==concatenate )
continue;
if( i>1 && ((prev= list.get(i-1)) instanceof Trans) &&
prev==concatenate || i==0 && conc)
twhat.write( buffer, offset+offs, true);
else
twhat.write( buffer, offset+offs, false);
}
else // not a Trans, call its toString(), parse to lines and shift them
{
boolean concFirstLine=
i>1 && ((prev= list.get(i-1)) instanceof Trans) &&
prev==concatenate || i==0 && conc;
char spcs[]= new char[offset+offs];
for( int j=0; jtoString()
and it can't be cached, because Trans subnodes can be accessed and
changed later by 'reservation'. There is no way to cache
equality or object status in principle. Unchanged hashCode()
means only that object probably didn't change. Anyway, it's not used
often. See source for faster restricted version that compares subnodes as Objects.
equals(Object) in any way, as
standard Trans mechanism that generates its string representation
(write(...)) doesn't use it.
*/
public boolean equals( Object obj) {
return obj instanceof Trans && toString().equals( obj.toString() );
//Faster restricted JavaCC version, see also notes below:
//return obj instanceof Trans && list.equals( ((Trans)obj).list );
}
/*
Commented faster version of equals(Object)
It compares subnodes as Objects, and is usefull for comparing
leaf Trans nodes, consisting of identifiers and fixed strings.
It requires commented version of hashCode(), see java.lang.Object.
It needs specific changes when used in JavaCC:
@see #hashCode()
*/
/** Returns a constant (0). Otherwise it had to return equals() and hashCode()
methods for class Token that call the same methods on
Token's item field.
add(Token), conc(Token)...
that add/conc/.. argument's item field. General methods
add(Object), conc(Object)... don't check whether
argument is of class Token, so they shouldn't be used in way
ResultTrans.add( (Object)SomeToken )...
Trans couldn't be used without JavaCC, or it required a dummy Token class then...
hashCode() can be used then.
hashCode()
of string representation generated by toString().
@see #equals(Object)
*/
public int hashCode() {
return 0;
//For restricted equals():
//return list.hashCode();
}
//} // end of class Trans
/**
Deserialized concatenate object is resolved by its actual static representation.
Thus there is always exactly the one concatenate object in JVM, so references
can be compared to it by operator == instead of slow
equals(). */
private static final class Concatenate extends Trans {
Concatenate() { super("ERROR. CoNcAtEnAtE - never to be printed!!" ); }
public Object readResolve() {
return concatenate;
}
}
} //end of Trans