Package org.kissweb

Class Groff

java.lang.Object
org.kissweb.Groff
public class Groff extends Object
Class to interface with the groff typesetting system. This is an easy way to generate nicely formatted reports. Of course, the underlying system must have groff/tbl/mm installed.

See: https://www.gnu.org/software/groff

There are two classes in Kiss used to create PDF reports: PDF and Groff. PDF is used when graphics and images are needed. Groff is used when text and tables are needed. It is possible to use both in the same report by creating the PDF with one and appending with the other.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Groff(String fnamePrefix, String title, boolean landscape)
    Initialize a new report.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    addPageTitleLine(String line)
    Add an additional line to the page title.
    void
    column(double num, String msk, int dp)
    Output a numeric double column

    msk is a String consisting of the following characters: B = blank if zero C = add commas L = left justify number P = put parentheses around negative numbers Z = zero fill D = floating dollar sign U = uppercase letters in conversion R = add a percent sign to the end of the number
    void
    column(int num, String msk)
    Output a numeric integer column

    msk is a String consisting of the following characters: B = blank if zero C = add commas L = left justify number P = put parentheses around negative numbers Z = zero fill D = floating dollar sign U = uppercase letters in conversion R = add a percent sign to the end of the number
    void
    column(String col)
    Output a column (title or body of table)
    void
    columnWrap(String col)
    Output a column that may wrap vertically.
    void
    dateColumn(int date)
    Output an integer date column.
    void
    dateColumn(Date date)
    Output a Date date column.
    void
    dateColumn2(int date)
    Output an integer date column.
    void
    dontDeleteIntermediateFiles()
    Prevent the deletion of the intermediate files for debugging purposes.
    void
    endRow()
    Normally not needed.
    void
    endTable()
    To be called at the end of the table
    void
    endTitle()
    Mark the end of the title
    String
    getGroffFileName()
    For debugging.
    String
    getRealFileName()
    The file name returned elsewhere is one convenient for web applications.
    void
    needLines(int n)
    Force a new page if there isn't at least n lines available on the current page.
    static Groff
    newTemplate(String fnamePrefix, String mmTemplateFileName, boolean landscape)
    Initialize a new MM template.
    void
    noAutoPageHeader()
    Do not auto-generate the page title, or if already printed, stop.
    void
    out(String str)
    Write a line to the groff input file.
    void
    outBold(String txt)
    Output a line in bold text.
    void
    outPSPIC(String fname, String witdh)
    Output a Postscript image.
    String
    process()
    Process the groff/tbl/mm input, produce the PDF output file, and return the path to the PDF file.
    String
    process(float sideMargin)
    Process the groff/tbl/mm input, produce the PDF output file, and return the path to the PDF file.
    void
    setFooter(String left, String right)
    Ability to customize what shows on the bottom of each page.
    void
    setRuntime(String rt)
    Manually set the run date string.
    void
    setVariable(String name, String value)
    Used to assign values to template variables.
    void
    setWaitMinutes(long m)
    Set the number of minutes to wait for groff to finish.
    void
    startTable(String colFmt)
    Mark the start of a table.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • Groff

      public Groff(String fnamePrefix, String title, boolean landscape) throws IOException
      Initialize a new report. The files it uses are put in temporary files that are auto-cleaned and in a place that can be served to the front-end. On the front-end side, see JavaScript Utils.showReport()
      Parameters:
      fnamePrefix - final PDF file name prefix
      title - report title or null
      landscape - true if landscape format, portrait otherwise
      Throws:
      IOException

  • Method Details

    • newTemplate

      public static Groff newTemplate(String fnamePrefix, String mmTemplateFileName, boolean landscape) throws IOException
      Initialize a new MM template. When utilizing a template rather than generating a report, there are only two methods used besides this one: setVariable and process.
      Parameters:
      fnamePrefix - final PDF file name prefix
      mmTemplateFileName - path to the MM template
      landscape - true if landscape format, portrait otherwise
      Returns:
      Throws:
      IOException
      See Also:

    • setVariable

      public void setVariable(String name, String value)
      Used to assign values to template variables. Note, this method is only used when processing an MM template.
      Parameters:
      name - name of the variable
      value - value to assign to it
      See Also:

    • noAutoPageHeader

      public void noAutoPageHeader()
      Do not auto-generate the page title, or if already printed, stop.

    • startTable

      public void startTable(String colFmt)
      Mark the start of a table.

      colFmt is a string specifying the layout for each column as specified by tbl.
      Parameters:
      colFmt -

    • setRuntime

      public void setRuntime(String rt)
      Manually set the run date string. An empty string (but not null) will cause no run date to be printed.
      Parameters:
      rt -

    • column

      public void column(String col)
      Output a column (title or body of table)
      Parameters:
      col -

    • endRow

      public void endRow()
      Normally not needed. Done automatically. However, is needed to end a row prematurely.

    • needLines

      public void needLines(int n)
      Force a new page if there isn't at least n lines available on the current page.
      Parameters:
      n - number of lines needed

    • columnWrap

      public void columnWrap(String col)
      Output a column that may wrap vertically.
      Parameters:
      col -

    • column

      public void column(double num, String msk, int dp)
      Output a numeric double column

      msk is a String consisting of the following characters:
      • B = blank if zero
      • C = add commas
      • L = left justify number
      • P = put parentheses around negative numbers
      • Z = zero fill
      • D = floating dollar sign
      • U = uppercase letters in conversion
      • R = add a percent sign to the end of the number
      Parameters:
      num - the number to be output
      msk - Format mask
      dp - number of decimal places (-1 means auto)

    • column

      public void column(int num, String msk)
      Output a numeric integer column

      msk is a String consisting of the following characters:
      • B = blank if zero
      • C = add commas
      • L = left justify number
      • P = put parentheses around negative numbers
      • Z = zero fill
      • D = floating dollar sign
      • U = uppercase letters in conversion
      • R = add a percent sign to the end of the number
      Parameters:
      num - the number to be output
      msk - Format mask

    • dateColumn

      public void dateColumn(int date)
      Output an integer date column. Formats date as MM/DD/YYYY
      Parameters:
      date - integer date formatted as YYYYMMDD

    • dateColumn2

      public void dateColumn2(int date)
      Output an integer date column. Formats date as MM/DD/YY
      Parameters:
      date - integer date formatted as YYYYMMDD

    • dateColumn

      public void dateColumn(Date date)
      Output a Date date column. Formats date as MM/DD/YYYY
      Parameters:
      date -

    • endTitle

      public void endTitle()
      Mark the end of the title

    • endTable

      public void endTable()
      To be called at the end of the table

    • outBold

      public void outBold(String txt)
      Output a line in bold text.
      Parameters:
      txt -

    • addPageTitleLine

      public void addPageTitleLine(String line)
      Add an additional line to the page title.
      Parameters:
      line -

    • dontDeleteIntermediateFiles

      public void dontDeleteIntermediateFiles()
      Prevent the deletion of the intermediate files for debugging purposes.

    • out

      public void out(String str)
      Write a line to the groff input file.
      Parameters:
      str -

    • outPSPIC

      public void outPSPIC(String fname, String witdh)
      Output a Postscript image. The height of the picture is calculated for the picture to retain its aspect ratio along with the width specification.
      Parameters:
      fname - the path to the postscript image file
      witdh - the output width of this picture

    • process

      public String process(float sideMargin) throws IOException, InterruptedException
      Process the groff/tbl/mm input, produce the PDF output file, and return the path to the PDF file. The file name returned is suitable for a web server and not the absolute file path.
      Parameters:
      sideMargin - size of the margin on the left side of the page in inches
      Returns:
      Throws:
      IOException
      InterruptedException
      See Also:

    • process

      public String process() throws IOException, InterruptedException
      Process the groff/tbl/mm input, produce the PDF output file, and return the path to the PDF file. Defaults to a 1-inch side margin.
      Returns:
      Throws:
      IOException
      InterruptedException
      See Also:

    • setFooter

      public void setFooter(String left, String right)
      Ability to customize what shows on the bottom of each page.
      Parameters:
      left - appears on the bottom left
      right - appears on the bottom right

    • getRealFileName

      public String getRealFileName()
      The file name returned elsewhere is one convenient for web applications. This method returns the real file name - not relative to a web server.

    • getGroffFileName

      public String getGroffFileName()
      For debugging. Returns the intermediate groff file. This only makes sense if dontDeleteGroffFile() is called.
      Returns:
      The intermediate troff/groff source file.

    • setWaitMinutes

      public void setWaitMinutes(long m)
      Set the number of minutes to wait for groff to finish. The default is 1 minute.
      Parameters:
      m -