convert

Documentation

Overview

Package convert extends the interface for the character encodings that transform text to and from Unicode UTF-8.

Index

• Constants
• Variables
• func EncodeAlias(name string) string
• func EncodeUTF32(name string) encoding.Encoding
• func Encoder(name string) (encoding.Encoding, error)
• func EqualLB(r, nl [2]rune) bool
• func Humanize(name string) string
• func Picture(b byte) rune
• func Shorten(name string) string
• func Swap(code rune) rune
• type Convert
  • func (c *Convert) ANSI(b ...byte) ([]rune, error)
  • func (c *Convert) ANSIControls() *Convert
  • func (c *Convert) Chars(b ...byte) ([]rune, error)
  • func (c *Convert) Dump(b ...byte) ([]rune, error)
  • func (c *Convert) FixJISTable()
  • func (c *Convert) LineBreak()
  • func (c *Convert) RunesControls()
  • func (c *Convert) RunesControlsEBCDIC()
  • func (c *Convert) RunesDOS()
  • func (c *Convert) RunesEBCDIC()
  • func (c *Convert) RunesKOI8()
  • func (c *Convert) RunesLatin()
  • func (c *Convert) RunesMacintosh()
  • func (c *Convert) RunesShiftJIS()
  • func (c *Convert) RunesUTF8()
  • func (c *Convert) RunesWindows()
  • func (c *Convert) RunesXRows()
  • func (c *Convert) SkipCode() *Convert
  • func (c *Convert) SkipIgnore(i int) bool
  • func (c *Convert) Swap() (*Convert, error)
  • func (c *Convert) Swaps() (*Convert, error)
  • func (c *Convert) Text(b ...byte) ([]rune, error)
  • func (c *Convert) Transform() error
• type Flag

Examples

• EncodeAlias
• EncodeUTF32
• Encoder
• Humanize
• Picture
• Shorten
• Swap

Constants

const (
	// NUL Null control code.
	NUL = iota
	// SOH Start of heading.
	SOH
	// STX Start of text.
	STX
	// ETX End of text.
	ETX
	// EOT End of transmission.
	EOT
	// ENQ Enquiry.
	ENQ
	// ACK Acknowledge.
	ACK
	// BEL Bell or alert.
	BEL
	// BS Backspace.
	BS
	// HT Horizontal tabulation.
	HT
	// LF Line feed.
	LF
	// VT Vertical tabulation.
	VT
	// FF Form feed.
	FF
	// CR Carriage return.
	CR
	// SO Shift out.
	SO
	// SI Shift in.
	SI
	// DLE Data Link Escape.
	DLE
	// DC1 Device control one.
	DC1
	// DC2 Device control two.
	DC2
	// DC3 Device control three.
	DC3
	// DC4 Device control four.
	DC4
	// NAK Negative acknowledge.
	NAK
	// SYN Synchronous idle.
	SYN
	// ETB End of transmission block.
	ETB
	// CAN Cancel.
	CAN
	// EM End of medium.
	EM
	// SUB Substitute.
	SUB
	// ESC Escape.
	ESC
	// FS File separator.
	FS
	// GS Group separator.
	GS
	// RS Record separator.
	RS
	// US Unit separator.
	US
	// SP Space.
	SP
)

The common ASCII and Unicode control decimal values.

const (
	// LeftSquareBracket [.
	LeftSquareBracket = 91
	// VerticalBar |.
	VerticalBar = 124
	// DEL Delete.
	DEL = 127
	// Dash Hyphen -.
	Dash = 150
	// Nbsp Non-breaking space.
	Nbsp = 160
	// InvertedExclamation ¡.
	InvertedExclamation = 161
	// Cent ¢.
	Cent = 162
	// BrokenBar ¦.
	BrokenBar = 166
	// Negation ¬.
	Negation = 172
	// PlusMinus ±.
	PlusMinus = 177
	// LightVertical light vertical │.
	LightVertical = 179
	// SquareRoot Square root √.
	SquareRoot = 251
	// NBSP Non-breaking space.
	NBSP = 255
	// Delta Δ.
	Delta = 916
	// LeftwardsArrow ←.
	LeftwardsArrow = 8592
	// SquareRootU Unicode square root √.
	SquareRootU = 8730
	// House ⌂.
	House = 8962
	// IntegralExtension ⎮.
	IntegralExtension = 9134
	// SymbolNUL ␀.
	SymbolNUL = 9216
	// SymbolESC ␛.
	SymbolESC = 9243
	// SymbolDEL ␡.
	SymbolDEL = 9249
	// LightVerticalU Box drawing light vertical │.
	LightVerticalU = 9474
	// CheckMark ✓.
	CheckMark = 10003
	// Replacement character �.
	Replacement = 65533
	// Open Box ␣.
	OpenBox = 9251
)

Special ASCII and Unicode character codes and symbols.

const (
	Row8 = 128 // the first cell after the end of a 7-bit row.

)

Variables

var (
	ErrANSI   = errors.New("ansi controls must be chained to c.swap")
	ErrBytes  = errors.New("cannot transform an empty byte slice")
	ErrEncode = errors.New("no input encoding provided")
	ErrName   = errors.New("unknown or unsupported code page name or alias")
	ErrOutput = errors.New("nothing to output")
	ErrWidth  = errors.New("cannot find the number columns from using line break")
	ErrWrap   = errors.New("wrap width must be chained to c.swap")
)

Functions

func EncodeAlias

func EncodeAlias(name string) string

EncodeAlias returns a valid IANA index encoding name from a shorten name or alias.

Example

package main

import (
	"fmt"

	"github.com/bengarrett/retrotxtgo/convert"
)

func main() {
	s := convert.EncodeAlias("437")
	fmt.Println(s)
	s = convert.EncodeAlias("koi8u")
	fmt.Println(s)
}

Output:

IBM437
KOI8-U

func EncodeUTF32

func EncodeUTF32(name string) encoding.Encoding

EncodeUTF32 initializes common UTF-32 encodings.

Example

package main

import (
	"fmt"

	"github.com/bengarrett/retrotxtgo/convert"
)

func main() {
	s := convert.EncodeUTF32("utf-32")
	fmt.Println(s)
}

Output:

UTF-32LE (Use BOM)

func Encoder

func Encoder(name string) (encoding.Encoding, error)

Encoder returns the named character set encoder.

Example

package main

import (
	"fmt"

	"github.com/bengarrett/retrotxtgo/convert"
)

func main() {
	e, _ := convert.Encoder("cp437")
	fmt.Println(e)
	e, _ = convert.Encoder("1252")
	fmt.Println(e)
}

Output:

IBM Code Page 437
Windows 1252

func EqualLB

func EqualLB(r, nl [2]rune) bool

EqualLB reports whether r matches the single or multi-byte, line break character runes.

func Humanize

func Humanize(name string) string

Humanize the encoding by using an shorter, less formal name.

Example

package main

import (
	"fmt"

	"github.com/bengarrett/retrotxtgo/convert"
)

func main() {
	s := convert.Humanize("cp437")
	fmt.Println(s)
	s = convert.Humanize("cp1252")
	fmt.Println(s)
}

Output:

IBM437
Windows-1252

func Picture

func Picture(b byte) rune

Picture converts a byte value to a Unicode Control Picture rune.

Example

package main

import (
	"fmt"

	"github.com/bengarrett/retrotxtgo/convert"
)

func main() {
	const lf = byte(138)
	r := convert.Picture(lf)
	fmt.Printf("%U %s\n", r, string(r))
	const esc = byte(155)
	r = convert.Picture(esc)
	fmt.Printf("%U %s\n", r, string(r))
}

Output:

U+240A ␊
U+241B ␛

func Shorten

func Shorten(name string) string

Shorten the name to a custom name, a common name or an alias.

Example

package main

import (
	"fmt"

	"github.com/bengarrett/retrotxtgo/convert"
)

func main() {
	s := convert.Shorten("cp437")
	fmt.Println(s)
	s = convert.Shorten("IBM-437")
	fmt.Println(s)
}

Output:

437
437

func Swap

func Swap(code rune) rune

Example

package main

import (
	"fmt"

	"github.com/bengarrett/retrotxtgo/convert"
)

func main() {
	fmt.Println(string(convert.Swap(convert.DEL)))
	fmt.Println(string(convert.Swap(convert.SquareRoot)))
}

Output:

Δ
✓

Types

type Convert

type Convert struct {
	Args  Flag // Args are the cmd supplied flag arguments.
	Input struct {
		Encoding  encoding.Encoding // Encoding are the encoding of the input text.
		Input     []byte            // Bytes are the input text as bytes.
		Ignore    []rune            // Ignore these runes.
		LineBreak [2]rune           // Line break controls used by the text.
		UseBreaks bool              // UseBreaks uses the line break controls as new lines.
		Table     bool              // Table flags this text as a code page table.
	}
	Output []rune // Output are the transformed UTF-8 runes.
}

Convert 8-bit code page text encodings or Unicode byte array text to UTF-8 runes.

func (*Convert) ANSI

func (c *Convert) ANSI(b ...byte) ([]rune, error)

ANSI transforms legacy encoded ANSI into modern UTF-8 text. It displays ASCII control codes as characters. It obeys the DOS end of file marker.

func (*Convert) ANSIControls

func (c *Convert) ANSIControls() *Convert

ANSIControls replaces out all ←[ and ␛[ character matches with functional ANSI escape controls.

func (*Convert) Chars

func (c *Convert) Chars(b ...byte) ([]rune, error)

Chars transforms legacy encoded characters and text control codes into UTF-8 characters. It displays both ASCII and ANSI control codes as characters. It ignores the DOS end of file marker.

func (*Convert) Dump

func (c *Convert) Dump(b ...byte) ([]rune, error)

Dump transforms legacy encoded text or ANSI into modern UTF-8 text. It obeys common ASCII control codes. It ignores the DOS end of file marker.

func (*Convert) FixJISTable

func (c *Convert) FixJISTable()

FixJISTable blanks invalid ShiftJIS characters while printing 8-bit tables.

func (*Convert) LineBreak

func (c *Convert) LineBreak()

LineBreak will try to guess the line break representation as a 2 byte value. A guess of Unix will return [10, 0], Windows [13, 10], otherwise a [0, 0] value is returned.

func (*Convert) RunesControls

func (c *Convert) RunesControls()

RunesControls switches out C0 and C1 ASCII controls with Unicode Control Picture represenations.

func (*Convert) RunesControlsEBCDIC

func (c *Convert) RunesControlsEBCDIC()

RunesControlsEBCDIC switches out EBCDIC controls with Unicode Control Picture represenations.

func (*Convert) RunesDOS

func (c *Convert) RunesDOS()

RunesDOS switches out C0, C1 and other controls with PC/MS-DOS picture glyphs.

func (*Convert) RunesEBCDIC

func (c *Convert) RunesEBCDIC()

RunesEBCDIC switches out EBCDIC IBM mainframe controls with Unicode picture represenations. Where no appropriate picture exists a space placeholder is used.

func (*Convert) RunesKOI8

func (c *Convert) RunesKOI8()

RunesKOI8 blanks out unused C0, C1 and other controls spaces for Russian sets.

func (*Convert) RunesLatin

func (c *Convert) RunesLatin()

RunesLatin blanks out unused C0, C1 and other controls spaces for ISO Latin sets.

func (*Convert) RunesMacintosh

func (c *Convert) RunesMacintosh()

RunesMacintosh replaces specific Mac OS Roman characters with Unicode picture represenations.

func (*Convert) RunesShiftJIS

func (c *Convert) RunesShiftJIS()

RunesShiftJIS tweaks some Unicode picture represenations for Shift-JIS.

func (*Convert) RunesUTF8

func (c *Convert) RunesUTF8()

RunesUTF8 tweaks some Unicode picture represenations for UTF-8 Basic Latin.

func (*Convert) RunesWindows

func (c *Convert) RunesWindows()

RunesWindows tweaks some Unicode picture represenations for Windows-125x sets.

func (*Convert) RunesXRows

func (c *Convert) RunesXRows()

RunesXRows blanks out rows 8x and 9x with spaces.

func (*Convert) SkipCode

func (c *Convert) SkipCode() *Convert

SkipCode marks control characters to be ignored. It needs to be applied before Convert.transform().

func (*Convert) SkipIgnore

func (c *Convert) SkipIgnore(i int) bool

SkipIgnore reports whether the rune should be skipped.

func (*Convert) Swap

func (c *Convert) Swap() (*Convert, error)

Swap transforms character map and control codes into UTF-8 unicode runes.

func (*Convert) Swaps

func (c *Convert) Swaps() (*Convert, error)

func (*Convert) Text

func (c *Convert) Text(b ...byte) ([]rune, error)

Text transforms legacy encoded text or ANSI into modern UTF-8 text. It obeys common ASCII control codes. It obeys the DOS end of file marker.

func (*Convert) Transform

func (c *Convert) Transform() error

Transform byte data from named character map encoded text into UTF-8.

type Flag

type Flag struct {
	Controls  []string // Always use these control codes.
	SwapChars []string // Swap out these characters with common alternatives.
	MaxWidth  int      // Maximum text width per-line.
}

Flag are the user supplied values.