Line data Source code
1 : // Copyright 2024 The LevelDB-Go and Pebble Authors. All rights reserved. Use
2 : // of this source code is governed by a BSD-style license that can be found in
3 : // the LICENSE file.
4 :
5 : // Package binfmt exposes utilities for formatting binary data with descriptive
6 : // comments.
7 : package binfmt
8 :
9 : import (
10 : "bytes"
11 : "encoding/binary"
12 : "fmt"
13 : "math"
14 : "strconv"
15 : "strings"
16 : "unsafe"
17 : )
18 :
19 : // New constructs a new binary formatter.
20 1 : func New(data []byte) *Formatter {
21 1 : offsetWidth := strconv.Itoa(int(math.Log10(float64(len(data)-1))) + 1)
22 1 : return &Formatter{
23 1 : data: data,
24 1 : lineWidth: 40,
25 1 : offsetFormatStr: "%0" + offsetWidth + "d-%0" + offsetWidth + "d: ",
26 1 : }
27 1 : }
28 :
29 : // Formatter is a utility for formatting binary data with descriptive comments.
30 : type Formatter struct {
31 : buf bytes.Buffer
32 : lines [][2]string // (binary data, comment) tuples
33 : data []byte
34 : off int
35 :
36 : // config
37 : lineWidth int
38 : offsetFormatStr string
39 : }
40 :
41 : // LineWidth sets the Formatter's maximum line width for binary data.
42 1 : func (f *Formatter) LineWidth(width int) *Formatter {
43 1 : f.lineWidth = width
44 1 : return f
45 1 : }
46 :
47 : // More returns true if there is more data in the byte slice that can be formatted.
48 0 : func (f *Formatter) More() bool {
49 0 : return f.off < len(f.data)
50 0 : }
51 :
52 : // Remaining returns the number of unformatted bytes remaining in the byte slice.
53 0 : func (f *Formatter) Remaining() int {
54 0 : return len(f.data) - f.off
55 0 : }
56 :
57 : // Offset returns the current offset within the original data slice.
58 0 : func (f *Formatter) Offset() int {
59 0 : return f.off
60 0 : }
61 :
62 : // PeekInt reads a little-endian integer of the specified width at the current
63 : // offset.
64 1 : func (f *Formatter) PeekInt(w int) int {
65 1 : switch w {
66 0 : case 1:
67 0 : return int(f.data[f.off])
68 0 : case 2:
69 0 : return int(binary.LittleEndian.Uint16(f.data[f.off:]))
70 1 : case 4:
71 1 : return int(binary.LittleEndian.Uint32(f.data[f.off:]))
72 1 : case 8:
73 1 : return int(binary.LittleEndian.Uint64(f.data[f.off:]))
74 0 : default:
75 0 : panic("unsupported width")
76 : }
77 : }
78 :
79 : // Byte formats a single byte in binary format, displaying each bit as a zero or
80 : // one.
81 0 : func (f *Formatter) Byte(format string, args ...interface{}) int {
82 0 : f.printOffsets(1)
83 0 : f.printf("b %08b", f.data[f.off])
84 0 : f.off++
85 0 : f.newline(f.buf.String(), fmt.Sprintf(format, args...))
86 0 : return 1
87 0 : }
88 :
89 : // CommentLine adds a full-width comment line to the output.
90 0 : func (f *Formatter) CommentLine(format string, args ...interface{}) {
91 0 : f.newline("", strings.TrimSpace(fmt.Sprintf(format, args...)))
92 0 : }
93 :
94 : // HexBytesln formats the next n bytes in hexadecimal format, appending the
95 : // formatted comment string to each line and ending on a newline.
96 1 : func (f *Formatter) HexBytesln(n int, format string, args ...interface{}) int {
97 1 : commentLine := strings.TrimSpace(fmt.Sprintf(format, args...))
98 1 : printLine := func() {
99 1 : bytesInLine := min(f.lineWidth/2, n)
100 1 : if f.buf.Len() == 0 {
101 1 : f.printOffsets(bytesInLine)
102 1 : }
103 1 : f.printf("x %0"+strconv.Itoa(bytesInLine*2)+"x", f.data[f.off:f.off+bytesInLine])
104 1 : f.newline(f.buf.String(), commentLine)
105 1 : f.off += bytesInLine
106 1 : n -= bytesInLine
107 : }
108 1 : printLine()
109 1 : commentLine = "(continued...)"
110 1 : for n > 0 {
111 0 : printLine()
112 0 : }
113 1 : return n
114 : }
115 :
116 : // Line prepares a single line of formatted output that will consume n bytes,
117 : // but formatting those n bytes in multiple ways. The line will be prefixed with
118 : // the offsets for the line's entire data.
119 1 : func (f *Formatter) Line(n int) Line {
120 1 : f.printOffsets(n)
121 1 : return Line{f: f, n: n, i: 0}
122 1 : }
123 :
124 : // String returns the current formatted output.
125 1 : func (f *Formatter) String() string {
126 1 : f.buf.Reset()
127 1 : // Identify the max width of the binary data so that we can add padding to
128 1 : // align comments on the right.
129 1 : binaryLineWidth := 0
130 1 : for _, lineData := range f.lines {
131 1 : binaryLineWidth = max(binaryLineWidth, len(lineData[0]))
132 1 : }
133 1 : for _, lineData := range f.lines {
134 1 : fmt.Fprint(&f.buf, lineData[0])
135 1 : if len(lineData[1]) > 0 {
136 1 : if len(lineData[0]) == 0 {
137 0 : // There's no binary data on this line, just a comment. Print
138 0 : // the comment left-aligned.
139 0 : fmt.Fprint(&f.buf, "# ")
140 1 : } else {
141 1 : // Align the comment to the right of the binary data.
142 1 : fmt.Fprint(&f.buf, strings.Repeat(" ", binaryLineWidth-len(lineData[0])))
143 1 : fmt.Fprint(&f.buf, " # ")
144 1 : }
145 1 : fmt.Fprint(&f.buf, lineData[1])
146 : }
147 1 : fmt.Fprintln(&f.buf)
148 : }
149 1 : return f.buf.String()
150 : }
151 :
152 : // Pointer returns a pointer into the original data slice at the specified
153 : // offset.
154 0 : func (f *Formatter) Pointer(off int) unsafe.Pointer {
155 0 : return unsafe.Pointer(&f.data[f.off+off])
156 0 : }
157 :
158 1 : func (f *Formatter) newline(binaryData, comment string) {
159 1 : f.lines = append(f.lines, [2]string{binaryData, comment})
160 1 : f.buf.Reset()
161 1 : }
162 :
163 1 : func (f *Formatter) printOffsets(n int) {
164 1 : f.printf(f.offsetFormatStr, f.off, f.off+n)
165 1 : }
166 :
167 1 : func (f *Formatter) printf(format string, args ...interface{}) {
168 1 : fmt.Fprintf(&f.buf, format, args...)
169 1 : }
170 :
171 : // Line is a pending line of formatted binary output.
172 : type Line struct {
173 : f *Formatter
174 : n int
175 : i int
176 : }
177 :
178 : // Append appends the provided string to the current line.
179 1 : func (l Line) Append(s string) Line {
180 1 : fmt.Fprint(&l.f.buf, s)
181 1 : return l
182 1 : }
183 :
184 : // Binary formats the next n bytes in binary format, displaying each bit as
185 : // a zero or one.
186 1 : func (l Line) Binary(n int) Line {
187 1 : if n+l.i > l.n {
188 0 : panic("binary data exceeds consumed line length")
189 : }
190 1 : for i := 0; i < n; i++ {
191 1 : l.f.printf("%08b", l.f.data[l.f.off+l.i])
192 1 : l.i++
193 1 : }
194 1 : return l
195 : }
196 :
197 : // HexBytes formats the next n bytes in hexadecimal format.
198 1 : func (l Line) HexBytes(n int) Line {
199 1 : if n+l.i > l.n {
200 0 : panic("binary data exceeds consumed line length")
201 : }
202 1 : l.f.printf("%0"+strconv.Itoa(n*2)+"x", l.f.data[l.f.off+l.i:l.f.off+l.i+n])
203 1 : l.i += n
204 1 : return l
205 : }
206 :
207 : // Done finishes the line, appending the provided comment if any.
208 1 : func (l Line) Done(format string, args ...interface{}) int {
209 1 : if l.n != l.i {
210 0 : panic("unconsumed data in line")
211 : }
212 1 : l.f.newline(l.f.buf.String(), fmt.Sprintf(format, args...))
213 1 : l.f.off += l.n
214 1 : return l.n
215 : }
|