[m-dev.] mdprof_* datastructure.

[Paul Bone]

Hi Zoltan and Julien.


I will be introducing a new tool into the deep_profiler directory.  This
will be a text interface with similar features as mdprof_cgi.  An easier
way to implement this is to introduce an intermediate data structure for
representing the 'reports' that mdprof_cgi presents, before they are
made into HTML or any other format.

Zoltan asked me to run this by him or Julien before I begun modifing
code.  The attached describes a data structure I have in mind if either
of you would like to check it before I continue that would be great.

Thanks.



-------------- next part --------------
======================================
 Deep Profiling Report Data Structure
======================================


Introduction and Motivation
===========================

The mercury deep profiler uses a CGI program to provide a web-interface to the
deep profiler.  This can be easily used by humans to generate reports.  I'm
introducing a tool called mdprof_query that will be able to query the deep
profiler and retrieve a textual representation of the report, this can be used
by other command line tools including test suits for deep and coverage
profiling.

Using one data structure to represent the results of a query (a deep profiling
report) and transforming it into text or html at a later step is the obvious way
to enable a tool such as mdprof_query access to the same features as mdprof_cgi.
It also makes it easy to use the data in other ways in the future.


Data Structure
==============

    The data structure will have to support different types of 'reports', these
    are described below.  Reports will also have a generic structure since
    often there are shared elements.

    :- type report
        --->    report(
                    title       :: maybe(string),
                    content     :: report_content,
                    controls    :: maybe(controls)
                ).
    
    The report_content type should represent one of the following at any one time.

    The title, and controls are described below.

Message
-------

    A simple text message,  In the CGI program these messages are displayed as a
    level 3 html heading.

    an example: 'Shutting down deep profile server'.

Menu
----
    
    A list of recommended queries,
        See Query below,
   
    A table of labels and values,
        Tables are described below, this table is very simple.


Other pages
-----------

    All other reports have a table as their main content, this includes
    cliques, procedures, modules within the program and procedures within a
    module.

    The table is described below.


Common elements
---------------

    Title
        string,

    Controls.
        Controls can be grouped and/or listed, groups have a name and contain
        lists of controls, lists do not give a name to controls.  A control is
        represented as a query (see below).

    Query (link).
        A query should be made from the command 'cmd' type in interface.m, the
        'preferences' (with colour and boxed removed as these are HTML specific
        and the string representing the label or a description of the
        command.

    Table,
        :- type table
            ---> table(
                % Enumeration of what the table stores, this can be used for layout
                % hints.,
                class   :: table_class,
               
                % Number of columns,
                n_cols  :: int,

                % Header row of table.
                header  :: maybe(table_header),
                
                % Data in table,
                rows    :: list(table_row)
            ).

        :- type table_header
            ---> table_header(
                cells   :: list(table_header_cell)            
            ). 

        :- type table_header_cell
            --->    table_header_cell(
                        text    :: string_or_link,
                        
                        % The class may be used by a layout to make decisions
                        % about how to paint this column.
                        class   :: table_col_class
                    )
            ;       table_header_group(
                        title       :: string,
                        subtitles   :: list(string_or_link)
                        
                        % The class may be used by a layout to make decisions
                        % about how to paint this column.
                        class       :: table_col_class
                    ).

        :- type table_row
            --->    table_row(
                        cells   :: list(table_cell)
                    )
            ;       table_section_header(
                        text    :: string_or_link
                    ).
      
        :- type table_cell
            --->    table_cell(
                        text    :: string_or_link
                    )
            ;       table_empty_cell.