TETware Generic Report Writer

User Guidelines

Syntax

     grw [-c content] [-f format] [-o out] [-p pagewidth] [-s stylesheet] [journal]

Description

grw parses a TETware journal file and produces a more readable version of the journal as a "report" document. It is designed to produce the report in a variety of different document formats. HTML and plain text are supported by default.

journal is the path of the input file, i.e. the journal file for which the report is to be generated. If a file name of "-" is specified, or no journal file is given, then grw reads from standard input.

Options

-c content Specify the content and layout of the generated report. content is one of the following:
  • Simple case: an integer from 1 - 7. Where

      1   Summary table(s).
      2   Summary table(s).
    Summary breakdown, excluding passes.
      3   Summary table(s).
    Summary breakdown, including passes.
      4   Summary table(s).
    Simple inline report, excluding passes.
      5   Summary table(s).
    Full inline report, excluding passes.
      6   Summary table(s).
    Full inline report, including passes.
      7   Summary table(s).
    Full inline report, including passes.
    Extra detail in inline report.

  • Configurable case: an expression specifying the content. This has the following format (regular expression syntax): 
        [bce]+[TBI]+[pifxc]*
    Where:

       b    Include build mode results.
       c    Include clean mode results.
       e    Include execute mode results.
       T    Produce summary table.
       B    Produce summary breakdown.
       I    Produce an inline report.
       p    Include detail of passes.
       i    Include introductory information about the test run.
       f    Fuller inline report - includes info lines and other tcc/tcm/testcase output. (Use with I to get more detail).
       x    Add extra detail into an inline report. (Use with I and f to get even more detail).
       c    Include configuration details.

    E.g. "bTBpi", "becTI".

    Note that the order of the [TBI]+ letters is significant, and determines the order of the relevant portion of the output, whereas the order of the other letters is not significant.

-f format Specify the document format for the generated report. The supported values of format are:

  html    HTML 4.0.
  chtml    HTML 4.0 with colour information.
This is the default.
  text    Plain text.
-o out Specify the name of the file to take generated output. "-" indicates standard output. This is also the default.
-p pagewidth Specify the page width of the generated output, in bytes. The default is 79. (text format only).
-s stylesheet Specify a URI of a stylesheet to link to in the generated HTML. (chtml and html formats only).

Running grw with no options is effectively:

	grw -c 3 -f chtml -o - -

i.e. read from standard input, write to standard output, produce HTML with colour information, to content level 3.

Return Value

grw exits with one of the following values:

  0   Successful completion.
  1   Errors were encountered while producing the report.
  2   Invalid options.

Programmer Guidelines

This section is for programmers who would like to modify or extend the report writer in some way.

Architecture

The process of producing a report from a TETware journal can be thought of as a pipeline.
Architecture pipeline diagram.
Component Source Files Public Functions Description
Front-end main.c main() Program entry point.
Parser parser.c grw_parsejournal() Parses journal, line by line, and hands parsed line items to handler.
Handler handler.c grw_beginjournal()
grw_handleline()
grw_endjournal()
 Controls content and layout of generated document.
Formatter formatter.c
formatter.h
 grw_createformatter()
grw_begindocument()
grw_enddocument()
grw_printh1()
grw_printh2()
grw_printh3()
grw_print()
grw_starttable()
grw_endtable()
grw_startrow()
grw_endrow()
grw_printcell()
grw_startcell()
grw_endcell()
grw_startulist()
grw_endulist()
grw_printlistentry()
grw_breakline()
grw_printhline()
 Provides a format independent API for writing documents. Also acts as a layer to perform generic operations for the individual formatters.
HTML Formatter html.c grw_createhtmlformatter() Produces HTML.
Text Formatter text.c grw_createtextformatter() Produces plain text.

Remaining source files:

Source Files Description
grw.h Overall header file.
tet_jrnl.h Copy of TETware journal defines.
utils.c General utilities, e.g. error handling, memory management.
svector.c String vector code.

Adding a new document format

Adding a new document format is a matter of plugging in a new component at the end of the pipeline, alongside the "HTML Formatter" and "Text Formatter". Here is an outline of the process:
  1. Create a new source (.c) file implementing a (public) function which will create a new formatter. The existing functions are called grw_createhtmlformatter() and grw_createtextformatter(), so a good name would be grw_createDDDformatter(), where "DDD" is the name of the new document format. The routine must return a pointer to a newly allocated grw_formatter_t structure, with all the function pointers set.
  2. Add a prototype for the new grw_createDDDformatter() function to grw.h.
  3. Edit main.c to call the new routine when the `-f' flag has the relevant value.
  4. Add the new source file to the makefile.
  5. Rebuild.

Changing inbuild defaults

Certain pieces of default information are compiled into the program, but are easily modified in the source. For example:

Information #define(s) Source file
Default document format DEFAULT_FORMAT main.c
Default content level DEFAULT_CONTENT main.c
Basic content levels CONTENT_L1
...
CONTENT_L7		 handler.c
HTML colours COLOR_.. html.c
Default pagewidth DEFAULT_PAGEWIDTH text.c

Copyright © 2000 The Open Group. All rights reserved.