Package eu.bandm.tools.format

Class Formats

java.lang.Object
eu.bandm.tools.format.Formats
public class Formats extends Object
Collection of static factory and transformation methods for Formats.

  • Field Details

    • string_guillemetsGermanLeft

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

    • string_guillemetsGermanRight

      public static final String string_guillemetsGermanRight
      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 combinations of "carriage return" and "linefeed", where both appear at most once each.

    • pattern_ws

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

    • pattern_wsWithVars

      public static final Pattern pattern_wsWithVars
      Matches arbitrary non-empty sequemces of blanks and horizontal tabs and numbered variables.

    • no_escape

      public static final int no_escape
      See Also:

    • escape_frame_with_doublequotes

      public static final int escape_frame_with_doublequotes
      See Also:

    • escape_blanks_individually

      public static final int escape_blanks_individually
      See Also:

    • pattern_newlineAndTabs

      public static final Pattern pattern_newlineAndTabs
      Matches one single "linefeed", "carriage return", or "horizontal tab" character.

    • format_dateAndTime

      public static final String format_dateAndTime
      String formatting template for date and time. This string passed as the format control to String.format(String,Object...) with some GregorianCalendar as second argument. Date and Time format is set to the same format as the shell function "makedate" in "etc/calltools.mk", (beside that the latter does currently not include seconds.)
      The result looks like 
      2009-07-21_01h09m07s

      Please note that the day-part is defined by the Java string formatting standard code "%tF", which directly corresponds to "%tY-%tm-%td", and thus verbatim to ISO 8601
      The time-of-day part closely follows the "extended format" of ISO 8601 cf. ISO 8601/en and ISO 8601/de
      BUT the separation character "." is replaced by "h" and "m", to make the string usable as a file name/time stamp! (windoof does not allow colon in file names, and you shouldn't try with unix.)

      Alternatives would have been ...

      1. better readable "%tF %tHh%tMm%tS"
      2. older version "%tF %tT"
      3. completely consistent with "extended" format from ISO8601 is "%tFT%tT"
      But the latter two both work like "%tH:%tM:%tS", thus inserting ":" colon chars. So these again could not be used as (compontens of) file names.
      See Also:

    • CREATED_ON

      public static final String CREATED_ON
      See Also:

    • htmlTag

      public static final Pattern htmlTag

    • htmlBrTag

      public static final Pattern htmlBrTag

  • 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 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 all single quotes in the data with a XML-style "character entity" and use frame with 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 GeneratedLiteral.quote(String), which replaces even more special characters.)
      Parameters:
      f - the text contents of which is quoted and returned.

    • text

      public static Format text(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(String txt)
      Transform a text into a complex Format structure, addtionally detecting references to numeric variables. See text(java.lang.String) for details. Additionally all substrings from {code #0} to {code #9} are translated to instances of Format.BoundVariable.

    • list

      public static Format list(Format open, CompoundConstructor outerCombinator, Format delim, CompoundConstructor innerCombinator, Format close, Iterable<? extends Format> formats)
      Same as list(Format,CompoundConstructor,Format,CompoundConstructor,Format,List)

    • list

      public static Format list(Format open, Format delim, Format close, Format... formats)
      Same as list(Format,CompoundConstructor,Format,CompoundConstructor,Format,List), where outerCombinator defaults to CompoundConstructor.beside and innerCombinator defaults to CompoundConstructor.line

    • 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

    • list

      public static Format list(Format open, CompoundConstructor outerCombinator, Format delim, CompoundConstructor innerCombinator, Format close, Format... formats)
      Same as list(Format,CompoundConstructor,Format,CompoundConstructor,Format,List)

    • 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
      (The argument type "List" instead of "Iterable" has been chosen because addtional length information is convenient for the implementation.)
      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.

    • singleLine

      public static Format singleLine(Format format)
      Wraps the given data into a Java-style single-line comment. ASSUMES that argument does not contain line breaks.

    • apiDoc

      public static Format apiDoc(List<Format> formats)
      Wraps the given data into a Java-style doc comment.

    • multiLine

      public static Format multiLine(Format format)
      Wraps the given data into a Java-style non-doc multi-line comment.

    • stringescape

      public static String stringescape(String data, int mode)
      Escapes blank characters in the given datum according to the methods selected by the mode parameter:

    • replaceNewlinesAndTabs

      public static String replaceNewlinesAndTabs(String s)
      Replaces all occurences of "linefeed", "carriage return", or "horizontal tab" character by a space character. .

    • dateNow_standardFormat

      public static String dateNow_standardFormat()
      Returns the current state of the calendaric clock in the format defined by format_dateAndTime.

    • date_standardFormat

      public static String date_standardFormat(GregorianCalendar now)
      Returns the given date in the format defined by format_dateAndTime.

    • anonymiseLocalFile

      public static String anonymiseLocalFile(String path)

    • generationText

      public static String generationText(String prefix, String[] args, int blankEscapeMode, String argSeparator, String lineSeparator, int maxWidth)
      Generate a primitive string which explains the parameters of a tool application. Concatenates the prefix and the sequence of args, after blank escaping. It joins the args by argSeparator, or by lineSeparator whenever the line length reaches maxWidth.

      All strings in the "args[]" array are considered as potential file paths and thus (heuristically) anonymized by calling anonymiseLocalFile(String).

      Parameters:
      prefix - first part of comment which will not be altered.
      args - arguments to the generation command: blanks will be replaced
      blankEscapeMode - see stringescape(String,int)
      argSeparator - to be inserted after every arg
      lineSeparator - to be inserted when line length is overstepped
      maxWidth - maximal line length

    • generationComment

      public static Format generationComment(String main_class, @Opt @Opt String descriptive_name, @Opt @Opt String name_version, String dateAndTime, int escapemode, boolean html_breaks, String[] args)
      Generates a Format which can be used to document the command line call, which initiated the generation of a certain Java source file.

      The format returned by this method can be attached to the generated structure by calling GeneratedAnnotationTarget.addComment(Format) or GeneratedAnnotationTarget.addComment(Format)
      It can of course also be converted to a string (containing line breaks) by result.toString(70), etc., as documented with Format.
      The result will look like 

       Created on  
 by  (=)   (version )?
 command line:
      All strings in the "args" array are considered as potential file paths and thus (heuristically) anonymized by calling anonymiseLocalFile(String).
      Parameters:
      main_class - must be given,
      descriptive_name - is optional and may contain blanks and special characters
      name_version - may be ==null, omitting the "version ..." text
      dateAndTime - must be given,
      escapemode - how arg-strings which contain whitespace shall be encoded, see stringescape(String,int)
      html_breaks - whether to insert html line break commands and other markup.
      args - the arguments which reached static void main()

    • extractDate

      @Opt public static @Opt String extractDate(String generationComment)
      Extract the date info from a generation comment. This is sensible to avoid the necessity of passing around two different but functional dependent parameters, when the date is required for a html meta element and the whole generationComment for a comment.

    • generationComment

      public static Format generationComment(String name_program, @Opt @Opt String name_version, int escapemode, boolean html_breaks, String[] args)
      Generates a Format which can be used to document the command line call. Acts as generationComment(String,String,String,int,boolean,String[]), but uses dateNow_standardFormat() for date and time.
      Parameters:
      name_program - must be given,
      name_version - may be ==null, omitting the "version ..." text
      escapemode - how arg-strings which contain whitespace shall be encoded, see stringescape(String,int)
      html_breaks - whether to insert html line break commands and other markup.
      args - the arguments which reached static void main()

    • generationComment

      @Deprecated(forRemoval=true) public static Format generationComment(String main_class, @Opt @Opt String name_version, String dateAndTime, int escapemode, boolean html_breaks, String[] args)
      Deprecated, for removal: This API element is subject to removal in a future version.
      for older versions only.
      Calls generationComment(String,String,String,String, int, boolean, String[]) with no descriptive name.

    • removeHtml

      public static String removeHtml(String orig)
      Useful when a comment string shall be used in an HTML body but also in an HTML comment, etc.