The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Mnet-5.25
River stage zero No dependents
1 ++
/ Mnet::Report::Table

NAME

Mnet::Report::Table - Output rows of report data

SYNOPSIS

    # create an example new table object, with csv file output
    my $table = Mnet::Report::Table->new({
        columns => [
            device  => "string",
            time    => "time",
            data    => "integer",
            error   => "error",
        ],
        output  => "csv:file.csv",
    });

    # output error row if script aborts with unreported errors
    $table->row_on_error({ device => $device });

    # output a normal report row, call again to output more
    $table->row({ device => $device, data => $data });

DESCRIPTION

Mnet::Report::Table can be used to create new report table objects, with a row method call to add data, a row_on_error method to ensure errors always appear, with various output options including csv, json, sql, and perl Data::Dumper formats.

METHODS

Mnet::Report::Table implements the methods listed below.

new

    $table = Mnet::Report::Table->new(\%opts)

A new Mnet::Report::Table object can be created with the options showm in the example below:

    my $table = Mnet::Report::Table->new({
        columns => [                # ordered column names and types
            device  => "string",    #   strips eol chars in csv output
            count   => "integer",   #   +/- integer numbers
            error   => "error",     #   first error, see row_on_error()
            time    => "time",      #   time as yyyy/mm/dd hh:mm:ss
            unix    => "epoch",     #   unix time, see perldoc -f time
        ],
        output  => "csv:$file",     # see this module's OUTPUT section
        append  => $boolean,        # set to append output to file
        log_id  => $string,         # see perldoc Mnet::Log new method
        nodefer => $boolean,        # set to output rows immediately
    });

The columns option is required, and is an array reference containing an ordered list of hashed column names of type string, integer, error, time, or epoch.

Columns of type string and integer are set by the user for new rows using the row method in this module. Columns of type error, time, and epoch are set automatically for each row of output.

The output option should be used to specify an output format and filename, as in the example above. Refer to the OUTPUT section below for more information.

The append option opens the output file for appending and doesn't write a heading row, Otherwise the default is to overwrite the output file when the new table object is created.

The nodefer option can be used so that report data rows are output immediately when the row method is called. Otherwise row data is output when the script exits. This can affect the reporting of errors, refer to the row_on_error method below for more information.

Note that new Mnet::Report::Table objects should be created before forking batch children if the Mnet::Batch module is being used.

Errors are issued for invalid options.

row

    $table->row(\%data)

This method will add a row of specified data to the current report table object, as in the following example:

    $table->row({
        device  => $string,
        sample  => $integer,
    })

Note that an error is issued if any keys in the data were not defined as string or integer columns when the new method was used to create the current object.

row_on_error

    $table->row_on_error(\%data)

This method can be used to ensure that an Mnet::Report::Table object with an error column outputs an error row when the script exits if no prior output row reflected that there was an error, as in the example below:

    # declare report object as a global
    use Mnet::Report::Table;
    my $table = Mnet::Report::Table->new({
        output  => "json:file.json",
        columns => [
            input => "text",
            error => "error",
            ttl   => "integer"
        ],
    });

    # call Mnet::Batch::fork here, if using Mnet::Batch module

    # output error row at exit if there was an unreported error
    $table->row_on_error({ input => "error" });

    # output first row, no error, always present in output
    $table->row({ input => "first" });

    # lots of code could go here, with possibility of errors...
    die if int(rand) > .5;

    # output second row, no error, present if die did not occur
    $table->row({ input => "second" });

    # row_on_error output at exit for unpreported errors
    exit;

This ensures that a script does not die after the row_on_error call without any indication of an error in the report output.

The default is to output all report data rows when the script exits. At this time all error columns for all rows will be set with the first of any prior script errors. In this case row_on_error will output an error row if there was an error and the row method was never called.

If the nodefer option was set when a new Mnet::Report::Table object was created then row data is output immediately each time the row method is called, with the error column set only if there was an error before the row method call. Any errors afterward could go unreported. In this case row_on_error will output an extra row at script exit if there was an error after the last row method call, or the row method was never called.

OUTPUT OPTIONS

When a new Mnet::Report::Table object is created the output option can be set to any of the output format types listed in the documentation sections below.

If the Mnet::Log module is loaded report rows are always logged with the info method.

Note the Mnet::Test module --test command line option silently overrides all other report output options, outputting report data using the Mnet::Log module if loaded or sending report output to stdout in Data::Dumper format, for consistant test results.

Output files are opened when an Mnet::Report object is created, with a heading row if necessary. Refer to the new method in this documentation for information on the append and nodefer options that control how the output file is opened and when row data is written.

Output options below can use /dev/stdout as the output file, which works nicely with the Mnet::Log --silent option used with the Mnet::Batch --batch option, allowing report output from all concurrently executing batch children to be easily piped or redirected in aggregate as necessary. However be aware thet /dev/stdout report output is not captured by the Mnet::Tee module.

Note the Mnet::Test module --test command line option silently overrides all other report output options, outputting report data using the Mnet::Log module if loaded or sending report output to stdout in Data::Dumper format, for consistant test results.

output csv

    csv
    csv:$file

The csv output option can be used to output a csv file, /dev/stdout by default, where all values are enclosed in double quotes and separated by commas.

All csv outputs are doule quoted. Any double quote character in the outut data will be escaped with an extra double quote character

All end of line carraige return and linefeed characters in the output data are replaced with spaces in the csv output. Multiline csv output data is not supported.

The output csv file will be created with a heading row when the new method is called unless the append option was set when the new method was called.

Refer to the OUTPUT OPTIONS section of this module for more info.

output dump

    dump
    dump $var
    dump:$var:$file

The dump output option writes one row per line in Data::Dumper format prefixed by the specified var name, defaulting to 'dump' and /dev/stdout.

This dump output can be read back into a perl script as follows:

    use Data::Dumper;
    while (<STDIN>) {
        my ($line, $var) = ($_, undef);
        my $table = $1 if $line =~ s/^\$(\S+)/\$var/ or die;
        eval "$line";
        print Dumper($var);
    }

Refer to the OUTPUT OPTIONS section of this module for more info.

output json

    json
    json:$var
    json:$var:$file

The json output option writes one row per line in json format prefixed by the specified var name, defaulting to 'json' and /dev/stdout. This requires that the JSON module is available.

The output json looks something like the example below:

    var = {"device":"test","error":null};

This json output can be read back into a perl script as follows:

    use JSON;
    use Data::Dumper;
    while (<STDIN>) {
        my ($line, $var) = ($_, undef);
        my $table = $1 if $line =~ s/^(\S+) = // or die;
        $var = decode_json($line);
        print Dumper($var);
    }

Refer to the OUTPUT OPTIONS section of this module for more info.

output sql

    sql
    sql:$table
    sql:"$table"
    sql:$table:$file
    sql:"$table":$file

The sql output option writes one row per line as sql insert statements using the specified table name, double-quoting non-word table names, defaulting to "table" and /dev/stdout, in the following format:

    INSERT INTO <table> (<column>, ...) VALUES (<value>, ...);

Table and column names are double quoted, and values are single quoted. Single quotes in values are escaped with an extra single quote character, LF and CR characters are escaped as '+CHAR(10)+' and '+CHAR(13)+' respectively.

Refer to the OUTPUT OPTIONS section of this module for more info.

output tsv

    tsv
    tsv:$file

The tsv output option can be used to output a tsv file, /dev/stdout by default, where all values are separated by tab characters.

All end of line carraige return, linefeeds, and tab characters in the output data are replaced with spaces in the tsv output. Multiline tsv output data is not supported.

The output tsv file will be created with a heading row when the new method is called unless the append option was set when the new method was called.

Refer to the OUTPUT OPTIONS section of this module for more info.

TESTING

Mnet::Report::Table supports the Mnet::Test module test, record, and replay functionality, tracking report data so it can be included in test results.

SEE ALSO

Data::Dumper

JSON

Mnet

Mnet::Batch

Mnet::Log

Mnet::Test