cpan/Test-Simple/lib/Test2/EventFacet/Info.pm

   1 package Test2::EventFacet::Info;
   2 use strict;
   3 use warnings;
   4
   5 our $VERSION = '1.302175';
   6
   7 sub is_list { 1 }
   8
   9 BEGIN { require Test2::EventFacet; our @ISA = qw(Test2::EventFacet) }
  10 use Test2::Util::HashBase qw{-tag -debug -important -table};
  11
  12 1;
  13
  14 __END__
  15
  16 =pod
  17
  18 =encoding UTF-8
  19
  20 =head1 NAME
  21
  22 Test2::EventFacet::Info - Facet for information a developer might care about.
  23
  24 =head1 DESCRIPTION
  25
  26 This facet represents messages intended for humans that will help them either
  27 understand a result, or diagnose a failure.
  28
  29 =head1 NOTES
  30
  31 This facet appears in a list instead of being a single item.
  32
  33 =head1 FIELDS
  34
  35 =over 4
  36
  37 =item $string_or_structure = $info->{details}
  38
  39 =item $string_or_structure = $info->details()
  40
  41 Human readable string or data structure, this is the information to display.
  42 Formatters are free to render the structures however they please. This may
  43 contain a blessed object.
  44
  45 If the C<table> attribute (see below) is set then a renderer may choose to
  46 display the table instead of the details.
  47
  48 =item $structure = $info->{table}
  49
  50 =item $structure = $info->table()
  51
  52 If the data the C<info> facet needs to convey can be represented as a table
  53 then the data may be placed in this attribute in a more raw form for better
  54 display. The data must also be represented in the C<details> attribute for
  55 renderers which do not support rendering tables directly.
  56
  57 The table structure:
  58
  59     my %table = {
  60         header => [ 'column 1 header', 'column 2 header', ... ], # Optional
  61
  62         rows => [
  63             ['row 1 column 1', 'row 1, column 2', ... ],
  64             ['row 2 column 1', 'row 2, column 2', ... ],
  65             ...
  66         ],
  67
  68         # Allow the renderer to hide empty columns when true, Optional
  69         collapse => $BOOL,
  70
  71         # List by name or number columns that should never be collapsed
  72         no_collapse => \@LIST,
  73     }
  74
  75 =item $short_string = $info->{tag}
  76
  77 =item $short_string = $info->tag()
  78
  79 Short tag to categorize the info. This is usually 10 characters or less,
  80 formatters may truncate longer tags.
  81
  82 =item $bool = $info->{debug}
  83
  84 =item $bool = $info->debug()
  85
  86 Set this to true if the message is critical, or explains a failure. This is
  87 info that should be displayed by formatters even in less-verbose modes.
  88
  89 When false the information is not considered critical and may not be rendered
  90 in less-verbose modes.
  91
  92 =item $bool = $info->{important}
  93
  94 =item $bool = $info->important
  95
  96 This should be set for non debug messages that are still important enough to
  97 show when a formatter is in quiet mode. A formatter should send these to STDOUT
  98 not STDERR, but should show them even in non-verbose mode.
  99
 100 =back
 101
 102 =head1 SOURCE
 103
 104 The source code repository for Test2 can be found at
 105 F<http://github.com/Test-More/test-more/>.
 106
 107 =head1 MAINTAINERS
 108
 109 =over 4
 110
 111 =item Chad Granum E<lt>exodist@cpan.orgE<gt>
 112
 113 =back
 114
 115 =head1 AUTHORS
 116
 117 =over 4
 118
 119 =item Chad Granum E<lt>exodist@cpan.orgE<gt>
 120
 121 =back
 122
 123 =head1 COPYRIGHT
 124
 125 Copyright 2019 Chad Granum E<lt>exodist@cpan.orgE<gt>.
 126
 127 This program is free software; you can redistribute it and/or
 128 modify it under the same terms as Perl itself.
 129
 130 See F<http://dev.perl.org/licenses/>
 131
 132 =cut