Package eu.bandm.tools.format

Class Format

java.lang.Object
eu.bandm.tools.format.Format
All Implemented Interfaces:
Formattable, Serializable, 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 Object implements Cloneable, Serializable, Formattable
(1) Base class for all kinds of format objects and (2) their factory class.

(This class is at the same time (3) a "lexical containing class" for its 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 is superclass of all Formats which combine several formats (horizontally, vertically, etc.) It provides methods for optimal cloning and clean re-calculating of the internal attributes. The static factory methods contained herein (like append(Iterable), append(Format[]), block(Iterable), block(Format[]), line(Iterable), beside(Iterable), beneath(Iterable), tabular(Iterable), comment(String,String,String,Iterable), etc.) will all create only compounds with non-denormalized contents, i.e. with more than one contained Format. But also denormalized instances of Compound subclasses will be displayed correctly.

See Also:

  • Field Details

    • pattern_illegal_literal

      public static final Pattern pattern_illegal_literal
      Matches the characters which are currently not allowed in Format.Literals. These are "carriage return", "linefeed", and "horizontal tab".

    • 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.

    • LENGTH_PREFIX

      protected static final int LENGTH_PREFIX
      Length of common class name prefix, which can be suppressed in debug output.

    • INDENT_NOT_SET

      public static final int INDENT_NOT_SET
      Default value for indentation, meaning no explicit specification.
      See Also:

    • indent

      public final 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 the beginning of its immediate container, iff the format is the first in an output line.

    • minWidth

      public final int minWidth
      Contains the 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

      public final int maxWidth
      Contains the maximal width, ie reflects the printing situation where no single contained optional line-break contained in (the sub-formats of) this format is realized.

    • isAlwaysMultiline

      public final boolean isAlwaysMultiline
      Reflects whether format contains any (non-singleton) Format.Beneath formats. Needed for "line" and "block", which propagate line breaks contained in their content formats to their own layout.

    • ground

      public final boolean ground
      Reflects that this format does not contain variables.

    • DEFAULT_WIDTH

      public static final int DEFAULT_WIDTH
      Default page width used by printFormat(PrintWriter)
      See Also:

  • Constructor Details

    • Format

      protected Format(int i, int a, boolean mult, boolean ground, int indent)
      Private constructor, setting all fields of the Format definition.

    • Format

      protected Format(int i, int a, boolean mult, boolean ground)
      Private constructor, setting all fields of the Format definition, but setting indent to default.

  • Method Details

    • format

      public final Format format()
      Any instance of Format is its own formatting result.
      Specified by:
      format in interface Formattable
      Returns:
      a format that represents this object in a pretty-printable way

    • of

      public static Format of(Object thing)

    • isValidContentForLiteral

      public static boolean isValidContentForLiteral(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(String s)
      Create a literal or return an already cached one.
      Throws:
      IllegalArgumentException - in case the string argument contains tabs or newline pattern_illegal_literal.

    • markup

      public static Format markup(String s)
      Creates a mark-up format (not occupying any space), same as markupRight(String).

    • markupRight

      public static Format markupRight(String s)
      Creates a mark-up format (not occupying any space).

    • markupLeft

      public static Format markupLeft(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 a Format.Prior format.

    • prior

      public static Format prior(int level, int alternative, Format noparens, Format parens)
      Creates a Format.Prior format.

    • makeAppend

      protected static Format makeAppend(List<Format> f)
      Returns an empty format if list is empty, or the only contained format, or an Format.Append format of the multiple contents.

    • makeBlock

      protected static Format makeBlock(List<Format> f)
      Returns an empty format if list is empty, or the only contained format, or a Format.Block format of the multiple contents.

    • makeLine

      protected static Format makeLine(List<Format> f)
      Returns an empty format if list is empty, or the only contained format, or a Format.Line format of the multiple contents.

    • makeBeside

      protected static Format makeBeside(List<Format> f)
      Returns an empty format if list is empty, or the only contained format, or a Format.Beside format of the multiple contents.

    • makeBeneath

      protected static Format makeBeneath(List<Format> f)
      Returns an empty format if list is empty, or the only contained format, or a Format.Beneath format of the multiple contents.

    • makeTabular

      protected static Format makeTabular(List<Format> f)
      Returns an empty format if list is empty, or a Format.Tabular format containing the one or more formats from the list.

    • append

      public static Format append(Iterable<@Opt ? extends Format> f)
      Calls makeAppend(java.util.List<eu.bandm.tools.format.Format>) while ignoring all empty formats and null pointers contained in the argument list.

    • block

      public static Format block(Iterable<@Opt ? extends Format> f)
      Calls makeBlock(java.util.List<eu.bandm.tools.format.Format>) while ignoring all empty formats and null pointers contained in the argument list.

    • line

      public static Format line(Iterable<@Opt ? extends Format> f)
      Calls makeLine(java.util.List<eu.bandm.tools.format.Format>) while ignoring all empty formats and null pointers contained in the argument list.

    • beside

      public static Format beside(Iterable<@Opt ? extends Format> f)
      Calls makeBeside(java.util.List<eu.bandm.tools.format.Format>) while ignoring all empty formats and null pointers contained in the argument list.

    • beneath

      public static Format beneath(Iterable<@Opt ? extends Format> f)
      Calls makeBeneath(java.util.List<eu.bandm.tools.format.Format>) while ignoring all empty formats and null pointers contained in the argument list.

    • tabular

      public static Format tabular(Iterable<@Opt ? extends Format> f)
      Calls makeTabular(java.util.List<eu.bandm.tools.format.Format>) while ignoring all empty formats and null pointers contained in the argument list.

    • comment

      public static Format comment(@Opt @Opt String prefix, String linePrefix, @Opt @Opt String suffix, Iterable<@Opt ? extends Format> f)
      Creates an Format.Comment format. A comment format is created in any case, but all empty formats and null pointers contained in the argument list are ignored.

    • comment

      public static Format comment(@Opt @Opt String prefix, String linePrefix, @Opt @Opt String suffix, Format... f)
      Creates an Format.Comment format. A comment format is created in any case, but all empty formats and null pointers contained in the argument list are ignored.

    • comment

      public static Format comment(String linePrefix, Iterable<? extends Format> f)
      Creates an Format.Comment format. A comment format is created in any case, but all empty formats and null pointers contained in the argument list are ignored. Prefix and suffix default to null = not present.

    • comment

      public static Format comment(String linePrefix, Format... f)
      Creates an Format.Comment format. A comment format is created in any case, but all empty formats and null pointers contained in the argument list are ignored. Prefix and suffix default to null = not present.

    • append

      public static Format append(Format... f)
      Same as append(Iterable)

    • block

      public static Format block(Format... f)
      Same as block(Iterable)

    • line

      public static Format line(Format... f)
      Same as line(Iterable)

    • beside

      public static Format beside(Format... f)
      Same as beside(Iterable)

    • beneath

      public static Format beneath(Format... f)
      Same as beneath(Iterable)

    • tabular

      public static Format tabular(Format... f)
      Same as tabular(Iterable)

    • indent

      public abstract Format indent(int i)
      Returns a clone of this with the new value of indent. (The built-in "clone()" functionality cannot be used, since field "indent" is final).

    • annotated

      public static <A> Format annotated(Format format, @Opt A annotation)
      Creates an Format.Annotated format.

    • variable

      public static Format variable(String name)
      Creates a new Format.FreeVariable with the given name.

    • variable

      public static Format variable(int index)
      Creates a new Format.BoundVariable with the given number.

    • subst

      public static Format subst(Format body, Format.Context c, boolean partial)
      Creates a new Format.Subst substitution object.
      Parameters:
      body - in which the variables shall be resolved
      c - Format.Context which binds names and numbers of variables to Format values
      partial - whether some variables are still unbound

    • subst

      public static Format subst(Format body, Format... args)
      Creates a new Format.Subst substitution object. See subst(Format,Context,boolean), where partial defaults to false.

    • subst

      public static Format subst(Format body, String name, Format value)
      Creates a new Format.Subst substitution object where the variable with the given name is bound to the given Format value. The argument partial defaults to true.

    • apply

      public static Format apply(Format body, Format.Context c, boolean partial)
      Returns the format which results from replacing all Format.Variables by their binding defined in Context c, if any.
      Parameters:
      partial - decides when a Variable not defined in the context is found: if true the Variable stays aunaltered; if false an IllegalArgumentException is thrown.

    • apply

      public static Format apply(Format body, Format... args)
      Returns the format which results from replacing all Format.BoundVariables by the argument on the position given by their number.
      Throws:
      IllegalArgumentException - if a BoundVariable is not defined or a FreeVariable occurs.

    • apply

      public static Format apply(Format body, Formattable... args)
      Returns the format which results from replacing all Format.BoundVariables by the argument on the position given by their number.
      Throws:
      IllegalArgumentException - if a BoundVariable is not defined or a FreeVariable occurs.

    • apply

      public static Format apply(Format body, String name, Format value)
      Returns the format which results from replacing all FreeVariable with the given name by the given value. Evaluation is partial: All unbound Variables stay untouched and no exception occurs.

    • applyTo

      public final Format applyTo(Format... args)
      Most frequently used service provider for resolving variables in formats. It resolves only Format.BoundVariables, ie variables identified by numbers.
      Throws:
      IllegalArgumentException - if a FreeVariable occurs, or a BoundVariable with number beyond the argument count -1.

    • applyTo

      public final Format applyTo(Formattable... args)
      Most frequently used service provider for resolving variables in formats. It resolves only Format.BoundVariables, ie variables identified by numbers.
      Throws:
      IllegalArgumentException - if a FreeVariable occurs, or a BoundVariable with number beyond the argument count -1.

    • applyPartial

      public final Format applyPartial(Formattable... args)
      Most frequently used service provider for resolving variables in formats. It resolves only Format.BoundVariables, ie variables identified by numbers. FreeVariable and BoundVariable with number sbeyond the argument count -1 stays as they are.1

    • showLn

      public static String showLn(Format f, int depth)
      Creates a debugging representation of a Format term, restricted to show only the top "depth" levels.

    • debugPrefix

      public abstract String debugPrefix(int n)
      Overridden by subclasses to deliver a printable representation for debugging purpose.
      Parameters:
      n - the maximal number of characters

    • indentIsSet

      protected boolean indentIsSet()
      Whether an indentation value has been set explicitly.

    • isSpace

      protected boolean isSpace()
      Whether this format is a space.

    • eval

      public Format eval(Format.Context c, boolean partial)
      Return the result of replacing all variables with the bindings in the given Context. Will be overridden only by Variables, which need look-up in the context, and by Compound for descending into the sub-formats. These methods do not use the Visitor/Matcher framework, but direct method invocation and basic method dispatch for descending to child nodes.
      Parameters:
      partial - decides when a Variable not defined in the context is found: if true the Variable stays aunaltered; if false an IllegalArgumentException is thrown.

    • doprint

      protected abstract void doprint(Format.FormatPrinter v)
      Over-ridden by all sub-classes of Format, for performing the adquate print operations. To be printed is the raison d'être of Format objects. These methods do not use the Visitor/Matcher framework, but direct method invocation and basic method dispatch for descending to child nodes.

    • printFormat

      public void printFormat(PrintWriter pw)
      Central public function for printing a format with a default page width.

    • printFormat

      public void printFormat(PrintWriter pw, int width)
      Central public function for printing a format with the explicitly given page width.

    • printNonFormat

      public void printNonFormat(PrintWriter pw)
      Print a format without any formatting: Only small strctures are human-readable, for debugging. Uses Format.NonFormatPrinter.

    • toString

      public String toString()
      Convert a format without any formatting: Only small strctures are human-readable, for debugging. Uses Format.NonFormatPrinter.
      Overrides:
      toString in class Object

    • toString

      public String toString(int width)
      Print the format in a formatted way to a string (include linefeeds!), with the specified maximal column width.

    • toObjString

      public String toObjString()
      Call toString from the Object superclass, for debugging only.

    • maxOfMins

      protected static int maxOfMins(List<Format> subs)
      Calculate the maximum of the minWidth fields of all Formats in "subs".

    • server

      public static FormatServer<Format> server()