README
¶
BINbump
BINbump converts binary screen dumps of the IBM PC graphic and BIOS text mode characters, and CGA, EGA, and VGA colors into a HTML fragment for use in a template or webpage.
See the reference documentation for usage, and examples, including changing the character sets and the color palette.
BINbump was created for and is in use on the website archive Defacto2, home to thousands of ANSI and binary texts and artworks that are now rendered in HTML.
Quick usage
package main
import (
"log"
"os"
"github.com/bengarrett/binbump"
)
func main() {
file, _ := os.Open("file.bin")
defer file.Close()
_, _ = binbump.WriteTo(file, os.Stdout)
}
HTML
BINbump will output a <div> "content division" element containing colors, styles, newlines, and text.
- The div element should be used within a
<pre>"preformatted text" element. - Most ANSI text will want a custom monospaced font, Cascadia Mono handles all the CodePage 437 characters.
- Or use the IBM VGA font for a more authentic recreation,
either font will require a CSS
@font-facerule andfont-familyproperty.
<html>
<head>
<title>Quick usage</title>
</head>
<style>
@font-face {
font-family: cascadia-mono;
src: url(CascadiaMono.woff2) format("woff2");
}
pre {
font-family: cascadia-mono, monospace, serif;
}
</style>
<body>
<pre><!--- binbump output ---><div><span style="color:#aaa;background-color:#000;"> </span><span style="color:#a50;background-color:#0a0;">HI‼︎</span><span style="color:#aaa;background-color:#000;"> </span></div>
</pre>
</body>
</html>
Not supported or known issues
- XBIN
Sauce metadata
BINbump doesn't parse any SAUCE metadata, however this can be done with a separate bengarrett/sauce package.
Similar projects
- Deark is a utility that can output BIN to HTML or an image.
- Ansilove is a collection of tools to convert BIN to images.
- Ultimate Oldschool PC Font Pack offers various retro DOS and PC fonts.
Documentation
¶
Overview ¶
Package binbump converts binary screen dumps of the IBM PC graphic and BIOS text mode characters, and CGA, EGA, and VGA colors into a HTML representation.
Index ¶
- Variables
- func Buffer(r io.Reader, width, maxRows int, pal Palette, charset *charmap.Charmap) (*bytes.Buffer, error)
- func Bytes(r io.Reader) ([]byte, error)
- func String(r io.Reader) (string, error)
- func WriteTo(r io.Reader, w io.Writer) (int64, error)
- type Color
- type Colors
- type Decoder
- type Palette
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ( ErrAttribute = errors.New("attribute is not a 4-bit color value") ErrReader = errors.New("reader is nil") )
Functions ¶
func Buffer ¶
func Buffer(r io.Reader, width, maxRows int, pal Palette, charset *charmap.Charmap) (*bytes.Buffer, error)
Buffer creates a new Buffer containing the HTML elements of the binary dump found in the Reader.
The other arguments are used by the NewDecoder which documents their purpose.
Example ¶
package main
import (
"bytes"
"fmt"
"github.com/bengarrett/binbump"
"golang.org/x/text/encoding/charmap"
)
func main() {
data := []byte{0x41, 0x00, 0x42, 0x08}
const cga = binbump.StandardCGA // cga palette
const width = 160 // columns
charset := charmap.CodePage437
r := bytes.NewReader(data)
buf, _ := binbump.Buffer(r, width, 0, cga, charset)
fmt.Printf("%q", buf.String())
}
Output: "<div><span style=\"color:#000;background-color:#000;\">A</span><span style=\"color:#555;background-color:#000;\">B</span>\n</div>"
Example (Palette) ¶
package main
import (
"bytes"
"fmt"
"github.com/bengarrett/binbump"
"golang.org/x/text/encoding/charmap"
)
func main() {
data := []byte{0x41, 0x00, 0x42, 0x08}
const cga = binbump.RevisedCGA // revised cga palette
const width = 160 // columns
charset := charmap.CodePage437
r := bytes.NewReader(data)
buf, _ := binbump.Buffer(r, width, 0, cga, charset)
fmt.Printf("%q", buf.String())
}
Output: "<div><span style=\"color:#000;background-color:#000;\">A</span><span style=\"color:#4e4e4e;background-color:#000;\">B</span>\n</div>"
func Bytes ¶
Bytes returns the HTML elements of the binary dump found in the Reader. It assumes the Reader is using IBM Code Page 437 encoding.
Example ¶
package main
import (
"bytes"
"fmt"
"github.com/bengarrett/binbump"
)
func main() {
data := []byte{0x41, 0x00, 0x42, 0x08}
r := bytes.NewReader(data)
p, _ := binbump.Bytes(r)
fmt.Printf("%q", p)
}
Output: "<div><span style=\"color:#000;background-color:#000;\">A</span><span style=\"color:#555;background-color:#000;\">B</span>\n</div>"
func String ¶
String returns the HTML elements of the binary dump found in the Reader. It assumes the Reader is using IBM Code Page 437 encoding.
Example ¶
package main
import (
"bytes"
"fmt"
"github.com/bengarrett/binbump"
)
func main() {
data := []byte{0x41, 0x00, 0x42, 0x08}
r := bytes.NewReader(data)
s, _ := binbump.String(r)
fmt.Printf("%q", s)
}
Output: "<div><span style=\"color:#000;background-color:#000;\">A</span><span style=\"color:#555;background-color:#000;\">B</span>\n</div>"
func WriteTo ¶
WriteTo writes to w the HTML elements of the binary dump found in the Reader. It assumes the Reader is using IBM Code Page 437 encoding. If width is <= 0, an 80 columns value is used.
The return int64 is the number of bytes written.
Example ¶
package main
import (
"bufio"
"bytes"
"fmt"
"github.com/bengarrett/binbump"
)
func main() {
data := []byte{0x41, 0x00, 0x42, 0x08}
input := bytes.NewReader(data)
var b bytes.Buffer
output := bufio.NewWriter(&b)
cnt, _ := binbump.WriteTo(input, output)
output.Flush()
fmt.Printf("%d bytes written\n%q", cnt, b.String())
}
Output: 124 bytes written "<div><span style=\"color:#000;background-color:#000;\">A</span><span style=\"color:#555;background-color:#000;\">B</span>\n</div>"
Types ¶
type Color ¶
type Color string
Color code represented as a hexadecimal triplet or six-digit value.
const ( Black Color = "000" // 00 black Blue Color = "00a" // 01 blue Green Color = "0a0" // 02 green Cyan Color = "0aa" // 03 cyan Red Color = "a00" // 04 red Magenta Color = "a0a" // 05 magenta Brown Color = "a50" // 06 brown Gray Color = "aaa" // 07 gray BlackI Color = "555" // 08 intense black BlueI Color = "55f" // 09 intense blue GreenI Color = "5f5" // 10 intense green CyanI Color = "5ff" // 11 intense cyan RedI Color = "f55" // 12 intense red MagentaI Color = "f5f" // 13 intense magenta Yellow Color = "ff5" // 14 intense brown (yellow) White Color = "fff" // 15 intense gray (white) BlueR Color = "0000c4" // 01 blue GreenR Color = "00c400" // 02 green CyanR Color = "00c4c4" // 03 cyan RedR Color = "c40000" // 04 red MagentaR Color = "c400c4" // 05 magenta BrownR Color = "c47e00" // 06 brown GrayR Color = "c4c4c4" // 07 gray BlackIR Color = "4e4e4e" // 08 intense black BlueIR Color = "4e4edc" // 09 intense blue GreenIR Color = "4edc4e" // 10 intense green CyanIR Color = "4ef3f3" // 11 intense cyan RedIR Color = "dc4e4e" // 12 intense red MagentaIR Color = "f34ef3" // 13 intense magenta YellowR Color = "f3f34e" // 14 intense brown (yellow) )
type Decoder ¶
type Decoder struct {
Debug bool // Debug will wrap every character in its own <span> element with a data-xy attribute.
// contains filtered or unexported fields
}
Decoder maintains the screen buffer and print character state.
func NewDecoder ¶
NewDecoder creates a Decoder with a given width (columns). If width <= 0, 160 is used. maxRows should usually be left at 0, its use is only intended for screen dumps that contain tailing NULL or corrupt SAUCE metadata that should be ignored.
Palette can either be StandardCGA or RevisedCGA.
Generally the charset of a binary screen dump is charmap.CodePage437, which is used by default when a nil value is used.
type Palette ¶
type Palette uint
Palette sets the 4-bit (0-15) color codes to a colorset of RGB values.
const ( // StandardCGA is the Color Graphics Adapter colorset defined by IBM for the PC in 1981. StandardCGA Palette = iota // RevisedCGA is the Revised Color Graphics colorset as documented by VilaR, // https://int10h.org/blog/2022/06/ibm-5153-color-true-cga-palette/ RevisedCGA )
Source Files