Package eu.bandm.tools.format

Class 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 subclass Format.Compound provides methods for optimal cloning and clean re-calculating of the internal attributes.
    See Also:
    Serialized Form

    • Field Detail

      • pattern_illegal_literal

        public static final java.util.regex.Pattern pattern_illegal_literal
        Characters which are currently not allowed in Format.Literals.

      • literal

        public static final java.util.function.Function<java.lang.String,​Format> literal
        Function re-ification of literal 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

        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
        Indicates that all parameters (minWidth, maxWidth, etc) have to be recalculated.

    • Constructor Detail

      • Format

        protected Format​(int i,
                 int a,
                 boolean mult,
                 boolean ground)

      • Format

        protected Format()

    • Method Detail

      • 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 newline pattern_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,
                           int alternative,
                           Format noparens,
                           Format parens)

      • makeAppend

        protected static Format makeAppend​(java.util.List<Format> f)

      • makeBlock

        protected static Format makeBlock​(java.util.List<Format> f)

      • makeLine

        protected static Format makeLine​(java.util.List<Format> f)

      • makeBeside

        protected static Format makeBeside​(java.util.List<Format> f)

      • makeBeneath

        protected static Format makeBeneath​(java.util.List<Format> f)

      • makeTabular

        protected static Format makeTabular​(java.util.List<Format> f)

      • append

        public static Format append​(java.lang.Iterable<? extends Format> f)
        Creates an Format.Append format.
        In case of zero(0) arguments returns an Format.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 an Format.Block format.
        In case of zero(0) arguments returns an Format.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 an Format.Line format.
        In case of zero(0) arguments returns an Format.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 an Format.Beside format.
        In case of zero(0) arguments returns an Format.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 an Format.Beneath format.
        In case of zero(0) arguments returns an Format.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 an Format.Tabular format.
        In case of zero(0) arguments returns an Format.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 an Format.Comment format.

      • comment

        public static Format comment​(java.lang.String linePrefix,
                             java.lang.Iterable<? extends Format> f)

      • comment

        public static Format comment​(java.lang.String linePrefix,
                             Format... f)

      • indent

        public Format indent​(int i)
        Returns a clone of this with the new value of indent

      • subst

        public static Format subst​(Format body,
                           java.lang.String name,
                           Format value)

      • apply

        public static Format apply​(Format body,
                           java.lang.String name,
                           Format value)

      • applyTo

        public final Format applyTo​(Format... args)
        Central and only tested method for resolving variables. It resolves only Format.BoundVariables, 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).

      • toFormat

        @Deprecated
public Format toFormat​(Format... args)
        Deprecated.

      • 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 an Format.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 structure 
          Beneath
  |  
  |  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.util.List<Format> formats)
        Convenience method, creates a complex format for sequences of Formata. The structure which is created is determinded to 
           outer 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 parenthesis
        outerCombinator - how to combine open, the inner list, and close
        delim - the format to separate the elements of the list, like a comma
        innerCombinator - how to combine the elements of the inner list
        close - the format at the very right of the result, like a closing parenthesis
        formats - 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()
        Indicates that all parameters (minWidth, maxWidth, etc) have to be recalculated.

      • validate

        protected void validate()
        Re-calculates all parameters by calling update(), iff necessary. Is over-ridden by Format.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 by Format.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.

      • 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 class java.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 display
        windowname - the Title of the window
        isHtml - if tree labels use html features

      • testformat

        static Format testformat()

      • main

        public static void main​(java.lang.String[] args)
        Some test method calls.