1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
|
=head1 NAME
C<Devel::MAT::Cmd> - abstractions for providing commands for C<Devel::MAT>
=head1 METHODS
=head2 printf
Devel::MAT::Cmd->printf( $fmt, @args )
Behaves like perl's core C<printf()> function. Additionally, any argument for
a C<%s> conversion may also be the result of one of the following C<format_*>
methods, which may return a L<String::Tagged> instance.
=head2 print_table
Devel::MAT::Cmd->print_table( $rows, %opts )
Given a 2D array-of-arrays containing strings (which may be plain or formatted
ones returned by the various C<format_*> methods), prints them formatted in a
table shape, aligning the columns.
An element of C<$rows> may be an empty arrayref. This will cause a row of
divisions to be drawn using hyphens (C<->) the full width of each column.
The following named C<%ops> may be supplied:
=over 4
=item headings => ARRAY[STRING]
A list of strings per column to place at the top of the table. These may be
formatted differently to distinguish them.
=item sep => ARRAY[STRING] or STRING
A list of strings per column (or one single string to apply equally to them
all) specifying the separator string to print after each columns. Will default
to a single space if not supplied. Note that this string is interpolated into
a C<sprintf> format string, so any C<%> marks it may contain should be doubled.
=item align => ARRAY[STRING] or STRING
A list of strings per column (or one single string to apply equally to them
all) specifying the alignment of data in the column. Aligns to the right if
the value is C<"right">.
=item indent => INT
A number of spaces to prefix before every row of output. Defaults to zero if
not supplied.
=back
=head2 format_note
$str = Devel::MAT::Cmd->format_note( $str, $idx )
Apply some sort of styling to the a given string.
Starting from zero, successively higher integer values for C<$idx> may influence
the style further. Output with the same index value will appear the same. The
implementation should support at least 3 different styles, but may wrap after
this.
For stylistic consistency, tools should try to stick to the following
conventions for note indexes:
0 - regular notes
1 - secondary notes, lexical variable names
2 - unusual or erroneous conditions, symbol table names
=head2 format_sv
$str = Devel::MAT::Cmd->format_sv( $sv )
Returns a string encoding the address and description of the given SV,
possibly stylised in some way, subject to user customisation, or possibly made
interactive if the UI allows it to be so.
=head2 format_value
$str = Devel::MAT::Cmd->format_value( $val, %opts )
Returns a string formatting a given plain scalar value (which should either
be a string or a number) to indicate it's a value from the user program. If
given a string value, this will be escaped and quoted appropriately.
The following named C<%opts> may be supplied:
=over 4
=item key => BOOL
If true, the value represents a hash key value. Wraps the result in braces
C<{...}> and removes redundant quote marks if the string is valid as a
bareword identifier.
=item index => BOOL
If true, the value represents an array index. Wraps the result in square
brackets C<[...]> and expects the value to be an integer.
=item addr => BOOL
If true, the value represents some (non-SV) address. Prepends a "0x" and
formats the value as a hexadecimal string.
=item pv => BOOL
If true, the value represents a string from the user code. Wraps the result
in quote marks C<"..."> and limits the length to a maximum of 64 characters
(or as specified by the C<maxlen> argument). No truncation if C<maxlen> is
zero.
=back
=head2 format_symbol
$str = Devel::MAT::Cmd->format_symbol( $name, $sv )
Returns a string formatting the given symbol name to indicate that it is a
symbol name. Optionally, the SV object itself can be passed too, which may
save the UI having to look it up from the dumpfile in case it wishes to make
the printed value interactive in some way.
=head2 format_bytes
$str = Devel::MAT::Cmd->format_bytes( $bytes )
Returns a string showing the given byte count in suitably scaled units. This
will use base-1024 sizes in C<KiB>, C<MiB>, C<GiB> or C<TiB> if necessary.
=head2 format_sv_with_value
$str = Devel::MAT::Cmd->format_sv_with_value( $sv )
Similar to L</format_sv>, but printing additional information on some kinds
of SVs to avoid the user needing to use the C<show> to identify it.
For C<SCALAR> SVs it will show the value directly by using L</format_value>,
for C<REF> SVs it will show the referrant SV, and for C<STASH> SVs it will
show the symbol name.
=head2 format_heading
$str = Devel::MAT::Cmd->format_heading( $text, $level )
Returns a string applying some formatting to the given text to make it stand
out as a section or table heading. C<$level> may be used to distinguish
different styles; at least 3 should be provided.
=head1 AUTHOR
Paul Evans <leonerd@leonerd.org.uk>
=cut
|
