NAME

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

SYNOPSIS

    my $table = Mnet::Report::Table->new({
        table   => "example",
        output  => "csv:file.csv",
        columns => [ device => "string", error => "error" ],
    });

    $table->row({ device => $device });

DESCRIPTION

This module can be used to create new report table objects, add rows to those tables, with output of those rows at script exit in various formats.

new

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

A new Mnet::Report::Table object can be created for each required table, as in the following example:

    my $table = Mnet::Report::Table->new({
        columns => [                # ordered column names and types
            device  => "string",    #   eol chars stripped for csv output
            count   => "integer",   #   +/- integer numbers
            error   => "error",     #   first error, refer to row_on_error
            time    => "time",      #   row time as yyyy/mm/dd hh:mm:ss
        ],
        log_id  => $optional,       # refer to perldoc Mnet::Log new method
        output  => "csv:$file",     # refer to this module's OUTPUT section
    });

Errors are issued if invalid options are specified.

Refer to the documentation for specific output options below for more info.

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 normal row was output for that object, as in the example below:

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

    # we'll output one row per input line
    $line = Mnet::Batch::fork({ batch => "/dev/stdin" });

    # outputs error row at exit if no normal row methods were output
    $table->row_on_error({ input => $input });

    # lots of code could go here, with possibility of errors...
    my $ttl = int(rand*100);
    die if $ttl > 50;

    # output normal row, assuming no errors
    $table->row({ input => $input, ttl = $ttl });

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

Multiple row_on_error calls can be used to output multiple rows at script exit if there were any errors.

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 input columns are not defined for the current table object or invalid column data is specified.

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, or left undefined.

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

Note that 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 a format similar to Data::Dumper.

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 module --batch option, allowing report output from all concurrently exeecuting batch children to be easily piped or redirected in aggregate as necessary.

Note that /dev/stdout report output is not captured by the Mnet::Tee module, and might be missed if the Mnet::Log module is not being used. In this case you should output the report data to stdout yourself, maybe with Data::Dumper.

output csv

    csv:$file

The csv output option can be used to create csv files.

Note that eol characters are replaced with spaces in csv output.

Scripts that create multiple Mnet::Report::Table objects with output options set to csv need to ensure that the csv filenames are different, otherwise the single csv file created will possibly have different columns mixed together and be missing rows.

All csv output fields are double quoted, and double quotes in column output data are escaped with an extra double quote.

output dump

    dump:$var:$file

The dump output option writes one row per line in Data::Dumper format prefixed by the specified variable name.

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);
    }

Note that dump output is appended to the specified file, so the perl unlink command can be used to remove these files prior to each Mnet::Report::Table new call, if desired. This means it can be ok for multiple Mnet::Report::Table objects to write data to the same file, Use 'dump:$var:/dev/stdout' for output to the user's terminal.

output json

    json:$var:$file

The dump output option writes one row per line in json format prefixed by the table name as the variable name. This requires that the JSON module is available.

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);
    }

Note that json output is appended to the specified file, so the perl unlink command can be used to remove these files prior to each Mnet::Report::Table new call, if desired. This means it can be ok for multiple Mnet::Report::Table objects to write data to the same file. Use 'dump:/dev/stdout' for terminal output.

output sql

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

The dump output option writes one row perl line as sql insert statements.

Note that sql output is appended to the specified file, so the perl unlink command can be used to remove this file prior to the Mnet::Report::Table new call, if desired. This means it can be ok for multiple Mnet::Report::Table objects to write data to the same file. Use 'dump:/dev/stdout' for terminal output.

output test

Normal Mnet::Report::Table output is overriden when the Mnet::Test module is loaded and the --test cli option is present. Normal file output is suppressed and instead test report output is sent to stdout.

The test output option may also be set maually.

TESTING

This module supports the Mnet::Test test, record, and replay functionality, outputting report data so it can be included in testing.

SEE ALSO

Mnet

Mnet::Dump

Mnet::Test

cpanm Mnet

perl -MCPAN -e shell
install Mnet