/
overview.edoc
118 lines (90 loc) · 3.78 KB
/
overview.edoc
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
@title binpp - Erlang Binary Pretty Printer
@copyright 2012 (c) Adam Rutkowski <hq@mtod.org>
@version 1.1
@doc This lilbrary provides additional utility functions for working with Erlang
<em>binary()</em> and <em>bitstring()</em> types.
You might find it useful if you are going to:
<ul>
<li>Implement or debug arbitrary protocols</li>
<li>Log/dump binary data</li>
<li>Learn how Erlang binaries work</li>
</ul>
<h2>Installation</h2>
<ol>
<li>binpp comes with a Makefile that requires rebar build tool.
If you don't have rebar installed, you may get it from <a href="https://github.com/basho/rebar">Rebar Github repository</a>
</li>
<li>
Download the sources from <a href="http://github.com/jtendo/binpp">binpp Github repository</a>.
<ul>
<li>To build the library run <em>make</em>.</li>
<li>To run the tests run <em>make test</em>.</li>
<li>To generate documentation run <em>make docs</em>.</li>
</ul>
</li>
</ol>
<h2>Example usage</h2>
```
1> Bin.
<<12,242,207,49,82,69,45,130,212,69,80,88,8,81,23,36,86,7,
68,19,133,97,51,216,56,145,88,8,81,...>>
2> binpp:pprint(Bin).
0C F2 CF 31 52 45 2D 82 D4 45 50 58 08 51 17 24 .òÏ1RE-ÔEPX.Q.$
56 07 44 13 85 61 33 D8 38 91 58 08 51 17 24 56 V.D.
a3Ø8X.Q.$V
0A 14 20 4E 24 16 09 60 F4 0A 15 11 01 30 13 89 .. N$..`ô....0.
05 81 0F 09 15 C5 61 33 D8 54 91 52 5D 81 17 24 ....Åa3ØTR].$
11 14 60 23 D1 3D 55 80 ..`#Ñ=U
ok
'''
Binpp will use <em>io:format</em> to output the formatted binary by default, however
there are options making pprint functions return formatted data instead
of performing direct IO write:
```
1> Bin2 = <<"foo bar baz">>.
<<"foo bar baz">>
2> binpp:pprint(Bin2, [{return, iolist}]).
[["66 6F 6F 20 62 61 72 20 62 61 7A ",32,
"foo bar baz","\n"]]
3> binpp:pprint(Bin2, [{return, binary}]).
<<"66 6F 6F 20 62 61 72 20 62 61 7A foo bar baz\n">>
'''
You may use a custom printer function as well:
```
4> binpp:pprint(Bin2, [{printer, fun(O) -> io:format("~s~n", [O]) end}]).
66 6F 6F 20 62 61 72 20 62 61 7A foo bar baz
ok
'''
An additional API is provided for printing binary fragments:
```
5> binpp:pprint(Bin2, {0, 3}, []).
66 6F 6F foo
'''
Also, binary byte-to-byte comparsion:
```
6> binpp:compare(<<1,2,1024:512,3,4>>, <<1,3,1024:512,5,6>>).
-- 02 -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- 03 -- -- -- -- -- -- -- -- -- -- -- -- -- --
-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
-- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
-- -- 03 04 -- -- 05 06
ok
'''
Plus a handy little helper:
```
7> binpp:compare(<<1,2,255,3,1024:512>>, binpp:from_str("01 02 FF CC")).
-- -- -- 03 00 00 00 00 00 00 00 00 00 00 00 00 -- -- -- CC ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ??
00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ??
00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ??
00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ?? ??
00 00 04 00 ?? ?? ?? ??
ok
'''
That's all folks!
<h2>Get involved</h2>
Bug reports can be submitted to: <a href="http://github.com/jtendo/binpp/issues/">binpp issues @ Github</a>.
Patches and feature requests are always welcome!
<h2>Module index:</h2>
<dl>
<dt>{@link binpp}</dt>
<dd>Erlang Binary Pretty Printer</dd>
</dl>