Package eu.bandm.tools.format

Class Formats

java.lang.Object
eu.bandm.tools.format.Formats
@PropertyDependency("os.name") public class Formats extends Object
Collection of static factory and transformation methods for Formats.

  • Field Details

    • STRING_GUILLEMETS_GERMAN_LEFT

      public static final String STRING_GUILLEMETS_GERMAN_LEFT
      For marking quoted text in messags and documentation text.
      See Also:

    • STRING_GUILLEMETS_GERMAN_RIGHT

      public static final String STRING_GUILLEMETS_GERMAN_RIGHT
      For marking quoted text in messags and documentation text.
      See Also:

    • format_guillemetsGermanLeft

      public static final Format format_guillemetsGermanLeft
      For marking quoted text in messags and documentation text.

    • format_guillemetsGermanRight

      public static final Format format_guillemetsGermanRight
      For marking quoted text in messags and documentation text.

    • pattern_newline

      public static final Pattern pattern_newline
      Matches all maximal adjacent appearances of "carriage return" and "linefeed", such that at least one of them appears and both at most once.

    • pattern_ws

      public static final Pattern pattern_ws
      Matches arbitrary non-empty sequences of blanks and horizontal tabs.

  • Method Details

    • quoteDTDstyle

      public static Format quoteDTDstyle(Format f)
      Creates a literal format which chooses quote symbols not appearing in the data, in XML style.

      If the data does not contain single quotes then the result is an 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 all single quotes in the data with a XML-style "character entity" and frame the result with single quotes.

      Parameters:
      f - the input text. Only the Literal formats contained therein are considered and possibly rewritten.
      Returns:
      the original format, framed by an appropriate quote symbol in an append format, and possibly with rewritten contents.

    • text

      public static Format text(String txt)
      Convenience method for translating multi-line text into a complex format hierarchy. The result will have a structure like 
         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, optional whitespace between them) results to space on the upper level, under the Beneath combinator.
      The current implementation may produce lines with trailing whitespace.
      Parameters:
      txt - the text to convert
      Returns:
      a compound format structure with Literal and Space formats at its leaf positions.

    • textWithVars

      public static Format textWithVars(String txt)
      Transform a text into a complex Format structure, additionally detecting references to numeric variables. These are marked with Variable.DEFAULT_PREFIX. Named variables are not detected. See text(java.lang.String) for details of the result. Additionally all substrings of form [#][0..9]+ are translated to instances of BoundVariable and inserted into the result instead at the same place as the literals in the scheme for text(String). (FreeVariables are not supported.)
      Parameters:
      txt - the text to convert
      Returns:
      a compound format structure with Literal, Space, and BoundVariable formats at its leaf positions.

    • textWithVars

      public static Format textWithVars(String prefix, String txt)
      Transform a text into a complex Format structure, additionally detecting references to numeric variables. These are marked with the given prefix. Named variables are not detected. See text(java.lang.String) for details of the result. Additionally all substrings of form <prefix>[0..9]+ are translated to instances of BoundVariable and inserted into the result instead at the same place as the literals in the scheme for text(String).
      Parameters:
      prefix - used for parsing and display, must not be empty.
      txt - the text to convert
      Returns:
      a compound format structure with Literal, Space, and BoundVariable formats at its leaf positions.
      Throws:
      IllegalArgumentException - if prefix is empty

    • list

      public static Format list(Format open, Format delim, Format close, Format... formats)
      Same as list(Format,CompoundConstructor,Format,CompoundConstructor,Format,Format...), where outerCombinator defaults to CompoundConstructor.beside and innerCombinator defaults to CompoundConstructor.line
      Parameters:
      open - the format at the very left of the result, like an open parenthesis
      delim - the format to separate the elements of the list, like a comma
      close - the format at the very right of the result, like a closing parenthesis
      formats - the sequence of inner elements.
      Returns:
      the complete tree of format objects which represents the lis

    • list

      public static Format list(Format open, Format delim, Format close, List<Format> formats)
      Same as list(Format,CompoundConstructor,Format,CompoundConstructor,Format,List), where outerCombinator defaults to CompoundConstructor.beside and innerCombinator defaults to CompoundConstructor.line
      Parameters:
      open - the format at the very left of the result, like an open parenthesis
      delim - the format to separate the elements of the list, like a comma
      close - the format at the very right of the result, like a closing parenthesis
      formats - the sequence of inner elements.
      Returns:
      the complete tree of format objects which represents the lis

    • list

      public static Format list(Format open, CompoundConstructor outerCombinator, Format delim, CompoundConstructor innerCombinator, Format close, Format... formats)
      Convenience method, creates a complex list display format for sequences of Formats. 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.
      Returns:
      the complete tree of format objects which represents the lis

    • list

      public static Format list(Format open, CompoundConstructor outerCombinator, Format delim, CompoundConstructor innerCombinator, Format close, List<? extends Format> formats)
      Convenience method, creates a complex list display format for sequences of Formats. 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.
      Returns:
      the complete tree of format objects which represents the lis

    • singleLine

      public static Format singleLine(Format format)
      Wraps the given data into a single-line Java-style comment.

      For the final rendering to be meaningful, the result must be rendered in one single line. The current implementation cannot guarantee that a particular format tree will be renedered in only one line, except for a stand-alone literal. The user is responsible that the length of the character data and the rendering conditions give a correct result.

      Parameters:
      format - the contents of the Java doc comment.
      Returns:
      a comment format in the style of a Java doc comment.
      Throws:
      IllegalArgumentException - when the content is known not to fit into one single line.

    • apiDoc

      public static Format apiDoc(List<Format> formats)
      Wraps the given data into a Java-style doc comment.
      Parameters:
      formats - the contents of the Java doc comment
      Returns:
      a comment format in the style of a Java doc comment.

    • multiLine

      public static Format multiLine(List<Format> formats)
      Wraps the given data into a Java-style non-doc multi-line comment.
      Parameters:
      formats - the contents of the Java comment
      Returns:
      a comment format in the style of a Java non-doc comment.

    • quoteJavaStyle

      public static Format quoteJavaStyle(Format f)
      Creates a literal format with all doublequotes contained in the text escaped with a backslash.
      Parameters:
      f - the text contents of which is quoted and returned.
      Returns:
      a format with the quoted contents