Package eu.bandm.tools.format
Class Format
- java.lang.Object
-
- eu.bandm.tools.format.Format
-
- All Implemented Interfaces:
Formattable
,java.io.Serializable
,java.lang.Cloneable
- Direct Known Subclasses:
Format.Annotated
,Format.Compound
,Format.Empty
,Format.Literal
,Format.Markup
,Format.Prior
,Format.Space
,Format.Subst
,Format.Variable
public abstract class Format extends java.lang.Object implements java.lang.Cloneable, java.io.Serializable, Formattable
(1) Base class for all kinds of format objects and (2) their factory class.
(And, at the same time, (3) "containing class" for these sub-classes, which are declared "static". But this is intendend as a mere "lexical" comprehension. Of course this is bad design, esp. because each sub-class inherits itself as an inner class. But the initial author of this package prefers larger, but fewer source files !-)
For a detailed description of concepts see the user documentation.
Format objects have algebraic semantics, they are implemented "imutable". They are created by calls to the static factory methods from this class, and cannot be modified, once created.
Therefore complicated structures can be shared and re-used. Their internal attribute caches are once calculated at creation time and need never be updated.
If modifications are necessary, they are done by cloning, i.e. creating new instances. The subclassFormat.Compound
provides methods for optimal cloning and clean re-calculating of the internal attributes.- See Also:
- Serialized Form
-
-
Nested Class Summary
Nested Classes Modifier and Type Class Description static class
Format.Annotated<A>
Foreseen for data annotations, like the metajavareference format.
static class
Format.Append
Prints contained sub-formats horizontally adjacent.static class
Format.Beneath
Prints its sub-formats vertically aligned one beneath the other.static class
Format.Beside
Prints all sub-formats directly adjacent, even if they are multi-line.static class
Format.Block
Prints all sub-formats in the same line as long as possible, and starts a new line for every sub-format which would (probably) exceeded the page width.static class
Format.BoundVariable
Variable identified by a number, resolved by un-named arguments by counting their positions.static class
Format.Comment
Arranges all sub-formats with leading asterisks, like a javadoc comment.static class
Format.Compound
The base class for all formats which combine (= "contain") sub-formats.static class
Format.Context
Realizes a binding from identifiers to formats, for resolvingFormat.FreeVariable
s- bt [__] FIXME DOK FEHLT, NEVER TESTED !?!? NEVER USED !?!?static class
Format.Empty
Needed eg for case distinctions, when one alternative shall produce nothing.static class
Format.Forester
Swing tree Generation ONLY for debugging purposes.static class
Format.FormatPrinter
Central Visitor for formatted printing.static class
Format.FreeVariable
Variable indetified by a alphanumeric name which can be bound explicitly.static class
Format.Line
Prints all sub-formats in the same horizional line if this is possible within the page width, otherwise it prints all sub-formats in one vertical line.static class
Format.Literal
Printed literally to the output.static class
Format.Markup
Printed literally to the output, but not included in width calculation.static class
Format.Matcher
Base class for Visitor and Rewriter, Classifier.static class
Format.MayBreak
Abstract superclass of all compound formats which possibly generate multi-line output when printed.protected static class
Format.NonFormatPrinter
Prints a format discarding all formatting, producing non-human-readable output.static class
Format.Prior
This format prints the "parens" format, if it is (directly or indirectly) contained in a Prior Format with a higher priority 'level" (numerically larger priority code).static class
Format.Rewriter
General purpose Rewriterstatic class
Format.Space
Required for horizontal space (of variable size) or for blank lines (always only one at a time!).static class
Format.Subst
bt [__] FIXME DOK FEHLT, NEVER TESTED !?!? NEVER USED !?!?static class
Format.Tabular
Realizes ONE line of a table, and prints sub-formats starting in the column indicated by the value of theirindent
.static class
Format.Variable
Common abstract base class forFormat.FreeVariable
andFormat.BoundVariable
static class
Format.Visitor
General purpose Visitor
-
Field Summary
Fields Modifier and Type Field Description static Format
comma
A public constant reference to a literal format containing a comma.static int
contentPrefixPrinted
static int
DEFAULT_WIDTH
Default page width used byprintFormat(PrintWriter)
static Format
dot
A public constant reference to a literal format containing a dot.static Format
empty
A constant reference to an empty format.protected boolean
ground
Reflects that this format does not contain variables.protected int
indent
The indentation value explicitly assigned by the user.static int
INDENT_NOT_SET
protected boolean
invalid
protected boolean
isAlwaysMultiline
Reflects whether format contains any (non-singleton)Format.Beneath
formats.protected static int
LENGTH_PREFIX
static java.util.function.Function<java.lang.String,Format>
literal
Function
re-ification ofliteral
factory method.protected int
maxWidth
Contains maximal width, ie assumes that no single optional line-break is inserted.protected int
minWidth
Contains minimal width, if not directly at start of line, ie respecting blanks and not including indentation.static java.util.regex.Pattern
pattern_illegal_literal
Characters which are currently not allowed inFormat.Literal
s.static java.util.regex.Pattern
pattern_newline
static java.util.regex.Pattern
pattern_ws
static java.util.regex.Pattern
pattern_wsWithVars
static Format
space
A constant reference to a space of one(1) column/line.-
Fields inherited from interface eu.bandm.tools.format.Formattable
format
-
-
Method Summary
All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods Modifier and Type Method Description static <A> Format
annotated(Format format, A annotation)
Creates anFormat.Annotated
format.static Format
append(Format... f)
Same asappend(Iterable)
static Format
append(java.lang.Iterable<? extends Format> f)
Creates anFormat.Append
format.static Format
apply(Format body, Format.Context c, boolean partial)
static Format
apply(Format body, Format... args)
static Format
apply(Format body, Formattable... args)
static Format
apply(Format body, java.lang.String name, Format value)
Format
applyPartial(Formattable... args)
Format
applyTo(Format... args)
Central and only tested method for resolving variables.Format
applyTo(Formattable... args)
static Format
beneath(Format... f)
Same asbeneath(Iterable)
static Format
beneath(java.lang.Iterable<? extends Format> f)
Creates anFormat.Beneath
format.static Format
beside(Format... f)
Same asbeside(Iterable)
static Format
beside(java.lang.Iterable<? extends Format> f)
Creates anFormat.Beside
format.static Format
block(Format... f)
Same asblock(Iterable)
static Format
block(java.lang.Iterable<? extends Format> f)
Creates anFormat.Block
format.protected boolean
calcground()
Calculate whether not containing variables.protected int
calcmax()
Calculate maximal width.protected int
calcmin()
Calculate minimal width.protected boolean
calcmult()
Calculate whether more than one line of output.static Format
comment(@Opt java.lang.String prefix, java.lang.String linePrefix, @Opt java.lang.String suffix, Format... f)
Creates anFormat.Comment
format.static Format
comment(@Opt java.lang.String prefix, java.lang.String linePrefix, @Opt java.lang.String suffix, java.lang.Iterable<? extends Format> f)
Creates anFormat.Comment
format.static Format
comment(java.lang.String linePrefix, Format... f)
static Format
comment(java.lang.String linePrefix, java.lang.Iterable<? extends Format> f)
abstract java.lang.String
debugPrefix(int n)
protected abstract void
doprint(Format.FormatPrinter v)
Over-ridden by concrete sub-classes of Format, for performing the adquate print operations.Format
eval(Format.Context c, boolean partial)
Format
format()
Format
indent(int i)
protected boolean
indentIsSet()
protected void
invalidate()
protected boolean
isSpace()
static boolean
isValidContentForLiteral(java.lang.String s)
Returns true iff argument is valid as content of a "literal" format, i.e.static Format
line(Format... f)
Same asline(Iterable)
static Format
line(java.lang.Iterable<? extends Format> f)
Creates anFormat.Line
format.static Format
list(Format open, CompoundConstructor outerCombinator, Format delim, CompoundConstructor innerCombinator, Format close, Format... formats)
static Format
list(Format open, CompoundConstructor outerCombinator, Format delim, CompoundConstructor innerCombinator, Format close, java.lang.Iterable<? extends Format> formats)
static Format
list(Format open, CompoundConstructor outerCombinator, Format delim, CompoundConstructor innerCombinator, Format close, java.util.List<Format> formats)
Convenience method, creates a complex format for sequences ofFormat
a.static Format
list(Format open, Format delim, Format close, Format... formats)
Same aslist(Format,CompoundConstructor,Format,CompoundConstructor,Format,List)
, whereouterCombinator
defaults toCompoundConstructor.beside
andinnerCombinator
defaults toCompoundConstructor.line
static Format
list(Format open, Format delim, Format close, java.util.List<Format> formats)
Same aslist(Format,CompoundConstructor,Format,CompoundConstructor,Format,List)
, whereouterCombinator
defaults toCompoundConstructor.beside
andinnerCombinator
defaults toCompoundConstructor.line
static Format
literal(java.lang.String s)
Create a literal or return an already cached one.static void
main(java.lang.String[] args)
Some test method calls.protected static Format
makeAppend(java.util.List<Format> f)
protected static Format
makeBeneath(java.util.List<Format> f)
protected static Format
makeBeside(java.util.List<Format> f)
protected static Format
makeBlock(java.util.List<Format> f)
protected static Format
makeLine(java.util.List<Format> f)
protected static Format
makeTabular(java.util.List<Format> f)
static Format
markup(java.lang.String s)
Creates a mark-up format (not occupying any space).static Format
markupLeft(java.lang.String s)
Creates a mark-up format (not occupying any space).static Format
markupRight(java.lang.String s)
Creates a mark-up format (not occupying any space).void
printFormat(java.io.PrintWriter pw)
Central public function for printing a formst with a default page width..void
printFormat(java.io.PrintWriter pw, int width)
Central public function for printing a formst with the explicitly given page width..void
printNonFormat(java.io.PrintWriter pw)
print a format without any formatting, not intended for human readers.static Format
prior(int level, int alternative, Format noparens, Format parens)
static Format
prior(int level, Format noparens, Format parens)
Creates aFormat.Prior
format.static Format
quoteDTDstyle(Format f)
Creates a literal format which chooses quote symbols not appearing in the data.static Format
quoteJavaStyle(Format f)
Creates a literal format which quoted doublequotes by escaping them with a backslash.static java.lang.String
showLn(Format f, int depth)
creates a debugging representation of a form term, showing the top "depth" levels.static java.lang.String
showLn(Format f, int depth, int nesting)
static void
showSwingTree(Format f, java.lang.String windowname, boolean isHtml)
Generate a swing tree representation and display it ONLY for debugging.static Format
space(int i)
Creates a space format.static Format
subst(Format body, Format.Context c, boolean partial)
static Format
subst(Format body, Format... args)
static Format
subst(Format body, java.lang.String name, Format value)
static Format
tabular(Format... f)
Same astabular(Iterable)
static Format
tabular(java.lang.Iterable<? extends Format> f)
Creates anFormat.Tabular
format.(package private) static Format
testformat()
static Format
text(java.lang.String txt)
Convenience method for translating multi-line text into a complex format hierarchy.static Format
textWithVars(java.lang.String txt)
Format
toFormat(Format... args)
Deprecated.java.lang.String
toObjString()
call "toString()" from the "Object" superclass, for debugging only !java.lang.String
toString()
Print the format in an unformatted way to a string.java.lang.String
toString(int width)
Print the format in a formatted way to a string (include linefeeds!), with the specified maximal column width.protected void
update()
Just local calculation, assumes that all sub-objects are already valid.protected void
validate()
Re-calculates all parameters by callingupdate()
, iff necessary.static Format
variable(int index)
Creates a newFormat.BoundVariable
with the given number.static Format
variable(java.lang.String name)
Creates a newFormat.FreeVariable
with the given name.
-
-
-
Field Detail
-
pattern_illegal_literal
public static final java.util.regex.Pattern pattern_illegal_literal
Characters which are currently not allowed inFormat.Literal
s.
-
literal
public static final java.util.function.Function<java.lang.String,Format> literal
Function
re-ification ofliteral
factory method.
-
comma
public static final Format comma
A public constant reference to a literal format containing a comma.
-
dot
public static final Format dot
A public constant reference to a literal format containing a dot.
-
space
public static final Format space
A constant reference to a space of one(1) column/line.
-
empty
public static final Format empty
A constant reference to an empty format.
-
pattern_newline
public static final java.util.regex.Pattern pattern_newline
-
pattern_ws
public static final java.util.regex.Pattern pattern_ws
-
pattern_wsWithVars
public static final java.util.regex.Pattern pattern_wsWithVars
-
LENGTH_PREFIX
protected static final int LENGTH_PREFIX
-
INDENT_NOT_SET
public static final int INDENT_NOT_SET
- See Also:
- Constant Field Values
-
indent
protected int indent
The indentation value explicitly assigned by the user. This will determine the number of spaces the format will begin further to the right then its immediate container, IFF the format is the first in an output line.
-
minWidth
protected transient int minWidth
Contains minimal width, if not directly at start of line, ie respecting blanks and not including indentation. This is because after starting a new line, no decision on line break is necessary anyhow.
-
maxWidth
protected transient int maxWidth
Contains maximal width, ie assumes that no single optional line-break is inserted.
-
isAlwaysMultiline
protected transient boolean isAlwaysMultiline
Reflects whether format contains any (non-singleton)Format.Beneath
formats. Needed for "line" and "block", which propagate line breaks contained therein to their own layout.
-
ground
protected transient boolean ground
Reflects that this format does not contain variables.
-
invalid
protected boolean invalid
-
DEFAULT_WIDTH
public static final int DEFAULT_WIDTH
Default page width used byprintFormat(PrintWriter)
- See Also:
- Constant Field Values
-
contentPrefixPrinted
public static final int contentPrefixPrinted
- See Also:
- Constant Field Values
-
-
Method Detail
-
format
public final Format format()
- Specified by:
format
in interfaceFormattable
-
isValidContentForLiteral
public static boolean isValidContentForLiteral(java.lang.String s)
Returns true iff argument is valid as content of a "literal" format, i.e. does neither contain tab nor newline characters.
-
literal
public static Format literal(java.lang.String s)
Create a literal or return an already cached one.- Throws:
java.lang.IllegalArgumentException
- in case the string argument contains tabs or newlinepattern_illegal_literal
.
-
markup
public static Format markup(java.lang.String s)
Creates a mark-up format (not occupying any space).
-
markupRight
public static Format markupRight(java.lang.String s)
Creates a mark-up format (not occupying any space).
-
markupLeft
public static Format markupLeft(java.lang.String s)
Creates a mark-up format (not occupying any space).
-
space
public static Format space(int i)
Creates a space format.
-
prior
public static Format prior(int level, Format noparens, Format parens)
Creates aFormat.Prior
format.
-
append
public static Format append(java.lang.Iterable<? extends Format> f)
Creates anFormat.Append
format.
In case of zero(0) arguments returns anFormat.Empty
format instead.
In case of only one (1) argument returns this argument.
-
block
public static Format block(java.lang.Iterable<? extends Format> f)
Creates anFormat.Block
format.
In case of zero(0) arguments returns anFormat.Empty
format instead.
In case of only one (1) argument returns this argument.
-
line
public static Format line(java.lang.Iterable<? extends Format> f)
Creates anFormat.Line
format.
In case of zero(0) arguments returns anFormat.Empty
format instead.
In case of only one (1) argument returns this argument.
-
beside
public static Format beside(java.lang.Iterable<? extends Format> f)
Creates anFormat.Beside
format.
In case of zero(0) arguments returns anFormat.Empty
format instead.
In case of only one (1) argument returns this argument.
-
beneath
public static Format beneath(java.lang.Iterable<? extends Format> f)
Creates anFormat.Beneath
format.
In case of zero(0) arguments returns anFormat.Empty
format instead.
In case of only one (1) argument returns this argument.
-
tabular
public static Format tabular(java.lang.Iterable<? extends Format> f)
Creates anFormat.Tabular
format.
In case of zero(0) arguments returns anFormat.Empty
format instead.
In case of only one (1) argument returns this argument.
-
comment
public static Format comment(@Opt @Opt java.lang.String prefix, java.lang.String linePrefix, @Opt @Opt java.lang.String suffix, java.lang.Iterable<? extends Format> f)
Creates anFormat.Comment
format.
-
comment
public static Format comment(@Opt @Opt java.lang.String prefix, java.lang.String linePrefix, @Opt @Opt java.lang.String suffix, Format... f)
Creates anFormat.Comment
format.
-
comment
public static Format comment(java.lang.String linePrefix, java.lang.Iterable<? extends Format> f)
-
append
public static Format append(Format... f)
Same asappend(Iterable)
-
block
public static Format block(Format... f)
Same asblock(Iterable)
-
line
public static Format line(Format... f)
Same asline(Iterable)
-
beside
public static Format beside(Format... f)
Same asbeside(Iterable)
-
beneath
public static Format beneath(Format... f)
Same asbeneath(Iterable)
-
tabular
public static Format tabular(Format... f)
Same astabular(Iterable)
-
indent
public Format indent(int i)
-
annotated
public static <A> Format annotated(Format format, A annotation)
Creates anFormat.Annotated
format.
-
variable
public static Format variable(java.lang.String name)
Creates a newFormat.FreeVariable
with the given name.
-
variable
public static Format variable(int index)
Creates a newFormat.BoundVariable
with the given number.
-
subst
public static Format subst(Format body, Format.Context c, boolean partial)
-
apply
public static Format apply(Format body, Format.Context c, boolean partial)
-
apply
public static Format apply(Format body, Formattable... args)
-
applyTo
public final Format applyTo(Format... args)
Central and only tested method for resolving variables. It resolves onlyFormat.BoundVariable
s, ie variables identified by numbers. This is the only one of the many methods of dealing with variables which is ubiquituously applied in meta-tools. It requires that the mapping is total, ie that at least as much parameters are supplied as the highest number of all contained variables plus one (+1).
-
applyTo
public final Format applyTo(Formattable... args)
-
applyPartial
public final Format applyPartial(Formattable... args)
-
quoteDTDstyle
public static Format quoteDTDstyle(Format f)
Creates a literal format which chooses quote symbols not appearing in the data.
If the data does not contain single quotes then the result is anFormat.Append
with single quotes as first and last character.
Otherwise, if data does not contain double quotes, then do the same with double quotes.
Otherwise replace single quotes with a character entity and use single quotes.
-
quoteJavaStyle
public static Format quoteJavaStyle(Format f)
Creates a literal format which quoted doublequotes by escaping them with a backslash. (This is similar to metajave FIXME, but is restricted).
-
text
public static Format text(java.lang.String txt)
Convenience method for translating multi-line text into a complex format hierarchy.
The result will have the structureBeneath | | Block | | Literal | | Space | | Literal | | Space | | Literal | Space | Block | | Literal | | Space | | Literal
The limits of blocks will be given by hard "newlines" contained in the text.
Whitespace will be translated into Space and non-whitespace into Literal
Whitespace at the beginning of a line (following a hard newline) will be translated into indentation.
Empty lines (two consecutive newline characters) results to space on the upper level, under the Beneath combinator.
-
textWithVars
public static Format textWithVars(java.lang.String txt)
-
list
public static Format list(Format open, CompoundConstructor outerCombinator, Format delim, CompoundConstructor innerCombinator, Format close, java.lang.Iterable<? extends Format> formats)
-
list
public static Format list(Format open, Format delim, Format close, Format... formats)
Same aslist(Format,CompoundConstructor,Format,CompoundConstructor,Format,List)
, whereouterCombinator
defaults toCompoundConstructor.beside
andinnerCombinator
defaults toCompoundConstructor.line
-
list
public static Format list(Format open, Format delim, Format close, java.util.List<Format> formats)
Same aslist(Format,CompoundConstructor,Format,CompoundConstructor,Format,List)
, whereouterCombinator
defaults toCompoundConstructor.beside
andinnerCombinator
defaults toCompoundConstructor.line
-
list
public static Format list(Format open, CompoundConstructor outerCombinator, Format delim, CompoundConstructor innerCombinator, Format close, Format... formats)
-
list
public static Format list(Format open, CompoundConstructor outerCombinator, Format delim, CompoundConstructor innerCombinator, Format close, java.util.List<Format> formats)
Convenience method, creates a complex format for sequences ofFormat
a. The structure which is created is determinded toouter combinator | | | | | close | | | inner comb.-----+--- .... ---+ | | | | | Append Append f[last] | | | | | | f[0] delim f[1] delim | open
- Parameters:
open
- the format at the very left of the result, like an open parenthesisouterCombinator
- how to combine open, the inner list, and closedelim
- the format to separate the elements of the list, like a commainnerCombinator
- how to combine the elements of the inner listclose
- the format at the very right of the result, like a closing parenthesisformats
- the sequence of inner elements.
-
showLn
public static java.lang.String showLn(Format f, int depth)
creates a debugging representation of a form term, showing the top "depth" levels.
-
showLn
public static java.lang.String showLn(Format f, int depth, int nesting)
-
debugPrefix
public abstract java.lang.String debugPrefix(int n)
-
indentIsSet
protected boolean indentIsSet()
-
isSpace
protected boolean isSpace()
-
invalidate
protected final void invalidate()
-
validate
protected void validate()
Re-calculates all parameters by callingupdate()
, iff necessary. Is over-ridden byFormat.Compound
for prior descending to sub-formats.
-
update
protected void update()
Just local calculation, assumes that all sub-objects are already valid. This method Is not overridden (only byFormat.Compound
, testing not being a temporary copy). Instead, the differente "calc<..>
" methods are overridden individually.
-
calcmin
protected int calcmin()
Calculate minimal width. Is abstract on this level, but over-ridden by sub-classes.
-
calcmax
protected int calcmax()
Calculate maximal width. Is abstract on this level, but over-ridden by sub-classes.
-
calcmult
protected boolean calcmult()
Calculate whether more than one line of output. Is abstract on this level, but over-ridden by sub-classes.
-
calcground
protected boolean calcground()
Calculate whether not containing variables. Is abstract on this level, but over-ridden by sub-classes.
-
eval
public Format eval(Format.Context c, boolean partial)
-
doprint
protected abstract void doprint(Format.FormatPrinter v)
Over-ridden by concrete sub-classes of Format, for performing the adquate print operations.
-
printFormat
public void printFormat(java.io.PrintWriter pw)
Central public function for printing a formst with a default page width..
-
printFormat
public void printFormat(java.io.PrintWriter pw, int width)
Central public function for printing a formst with the explicitly given page width..
-
printNonFormat
public void printNonFormat(java.io.PrintWriter pw)
print a format without any formatting, not intended for human readers.
-
toString
public java.lang.String toString()
Print the format in an unformatted way to a string.- Overrides:
toString
in classjava.lang.Object
-
toString
public java.lang.String toString(int width)
Print the format in a formatted way to a string (include linefeeds!), with the specified maximal column width.
-
toObjString
public java.lang.String toObjString()
call "toString()" from the "Object" superclass, for debugging only !
-
showSwingTree
public static void showSwingTree(Format f, java.lang.String windowname, boolean isHtml)
Generate a swing tree representation and display it ONLY for debugging.
copied from umod/runtime/SwingBrowser.java:- Parameters:
f
- the Format to displaywindowname
- the Title of the windowisHtml
- if tree labels use html features
-
testformat
static Format testformat()
-
main
public static void main(java.lang.String[] args)
Some test method calls.
-
-