README
¶
binutil
Helpers for converting to and from binary and string representations of data
Installation
The simplest way to install the binutil command is to use Homebrew on Mac OS X:
$ brew install rotationalio/tools/binutil
If you have Go v1.19 or later, you can install it directly to your $GOBIN as follows:
$ go install github.com/bbengfort/binutil/cmd/binutil@latest
Finally, you can manually download the appropriate binary from the releases page and extract to a directory in your $PATH such as ~/bin.
Once installed, make sure you can execute the binutil command as follows:
$ binutil --version
Usage
You can use binutil to encode and decode binary strings from the command line. Basic usage is as follows:
$ binutil -d [DECODER] -e [ENCODER] [ENCODED BINARY DATA]
For example, to convert base64 encoded data to hex encoded data:
$ binutil -d base64 -e hex nYOG+hjpWFAGJsaBoLrSeg==
9d8386fa18e958500626c681a0bad27a
To see a list of availabled decoders, use the binutil decoders command:
$ binutil decoders
Registered Decoders:
====================
- ascii
- base64
- base64-raw
- base64-rawurl
- base64-std
- base64-url
- hex
- latin1
- text
- ulid
- utf-8
- uuid
Note: the above list may vary with new releases of binutil!
Generating Random Data
You can also quickly generate random data with the binutil rand command:
$ binutil rand -s 42 -e base64
cdMvYhnbiMymr0zTFWpOcEnnhSQhFe4a+FvJu0p3aBYuAiVvqr8crwx7
The -s specifies the size of the generated data by number of bytes.
This is useful for generating data for tests quickly.
Generating ULID and UUIDs
One important use case for binutil is to manage ULID and UUID in different binary formats (e.g. to insert data into a database via a SQL command). You can generate ULIDs and UUIDs as follows:
$ binutil ulid
ULID 01H3W76DQS0X8PX8ZT62MYAMD1
Time 2023-06-26T11:04:40.313-05:00
Hex Bytes 0188f87336f907516ea3fa30a9e551a1
b64 Bytes AYj4czb5B1Fuo/owqeVRoQ==
The output shows a variety of formats and the timestamp for ULIDs, allowing easy generation of conflict-free IDs for tests and fixtures. To easily copy and paste a UUID:
$ binutil uuid -e uuid -n | pbcopy
Documentation
¶
Index ¶
- Constants
- Variables
- func DecoderNames() []string
- func RegisterDecoder(name string, constructor DecoderConstructor, aliases ...string)
- func Version() string
- type Base64
- type Base64Scheme
- type Decoder
- type DecoderConstructor
- type Encoder
- type Hex
- type MultiPipeline
- func (p *MultiPipeline) Bin2Bin(name string, in []byte) (_ []byte, err error)
- func (p *MultiPipeline) Bin2Str(name string, in []byte) (out string, err error)
- func (p *MultiPipeline) MustBin2Str(name string, in []byte) string
- func (p *MultiPipeline) Str2Bin(name, in string) (out []byte, err error)
- func (p *MultiPipeline) Str2Str(name, in string) (out string, err error)
- type Pipeline
- type Text
- type TextEncoding
- type ULID
- type UUID
Constants ¶
const ( Base64Decoder = "base64" StdBase64Decoder = "base64-std" RawBase64Decoder = "base64-raw" URLBase64Decoder = "base64-url" RawURLBase64Decoder = "base64-rawurl" )
const ( TextDecoder = "text" UTF8Decoder = "utf-8" ASCIIDecoder = "ascii" Latin1Decoder = "latin1" )
const ( VersionMajor = 1 VersionMinor = 0 VersionPatch = 0 VersionReleaseLevel = "" VersionReleaseNumber = 1 )
Version component constants for the current build.
const HexDecoder = "hex"
const ULIDDecoder = "ulid"
const UUIDDecoder = "uuid"
Variables ¶
var ( ErrEmptyPipeline = errors.New("the pipeline has no transformation steps") ErrOverwrite = errors.New("this operation will overwrite existing data") ErrNoData = errors.New("data cannot be empty or nil") ErrUnknownB64Scheme = errors.New("unknown base64 encoding scheme") ErrUnknownStepType = errors.New("initialize a pipeline with a string or Decoder") )
var ( GitVersion string BuildDate string )
The GitVersion and BuildDate are set via ldflags Set the GitVersion via -ldflags="-X 'github.com/bbengfort/binutil.GitVersion=$(git rev-parse --short HEAD)'" Set the BuildDate via -ldflags="-X 'github.com//bbengfort/binutil.BuildDate=$(date +%F)'"
Functions ¶
func DecoderNames ¶
func DecoderNames() []string
func RegisterDecoder ¶
func RegisterDecoder(name string, constructor DecoderConstructor, aliases ...string)
Register a decoder constructor so that the decoder can be referenced by the name suplied and users can instantiate it directly from the type name. Note that names are case insensitive so MyDecoder is the same as mydecoder.
Types ¶
type Base64 ¶
type Base64 struct {
Scheme Base64Scheme
// contains filtered or unexported fields
}
Base64 implements the encoder and decoder interface for Base64 data and strings. Base64 is either an initial decoder or final encoder type and is not used for intermediate binary representations.
The primary paramater for base64 is the scheme which determines what character set and padding is used in the base64 encoding. Standard encoding is the default.
func NewBase64 ¶
func NewBase64(scheme Base64Scheme) *Base64
func (Base64) DecodeBinary ¶
DecodeBinary returns a new Base64 object with the wrapped data, ready to be encoded as a base64 string.
func (Base64) DecodeString ¶
DecodeString decodes the base64 string with the specified scheme and returns an encoder with the data bytes ready to be fetched.
func (Base64) EncodeBinary ¶
EncodeBinary returns the wrapped data if any is available, otherwise returns an error.
func (Base64) EncodeString ¶
EncodeString encodes the wrapped data according to the base64 encoding scheme.
type Base64Scheme ¶
type Base64Scheme uint8
const ( B64SchemeStd Base64Scheme = iota B64SchemeRawStd B64SchemeURL B64SchemeRawURL )
Base64 Encoding Schemes for determining the character set and padding used. Standard encoding uses the RFC 4648 encoding standard and includes padding characters. URL encoding uses the RFC 4648 alternate encoding that is safe for filenames and URLs. RawStd and RawURL omits the padding characters.
func (Base64Scheme) String ¶
func (b Base64Scheme) String() string
type Decoder ¶
type Decoder interface {
DecodeBinary(data []byte) (Encoder, error)
DecodeString(data string) (Encoder, error)
}
Decoder is an object that can unmarshal itself from either a binary or string representation and in both cases ensure that complete data is returned.
func NewDecoder ¶
Create a decoder by name rather than by directly instantiating one.
type DecoderConstructor ¶
type DecoderConstructor func() Decoder
DecoderConstructors are functions that create a new Decoder ready for use.
type Encoder ¶
type Encoder interface {
EncodeBinary() (data []byte, err error)
EncodeString() (data string, err error)
}
An encoder is an object that can marshal either a binary or a string representation of it's underlying data. For example a UUID is 16 bytes binary or it can be a GUID string value. Some representations are strings only; for example JSON is a string representation of data and the binary encoding is simply UTF-8 bytes. In other cases data is binary only; for example protocol buffers are binary data and the string representation may be base64 encoded bytes.
type Hex ¶
type Hex struct {
// contains filtered or unexported fields
}
func (Hex) EncodeBinary ¶
func (Hex) EncodeString ¶
type MultiPipeline ¶
type MultiPipeline struct {
// contains filtered or unexported fields
}
MultiPipeline is able to convert input data type to multiple output types.
func NewMulti ¶
func NewMulti(steps ...string) (_ *MultiPipeline, err error)
func (*MultiPipeline) Bin2Bin ¶
func (p *MultiPipeline) Bin2Bin(name string, in []byte) (_ []byte, err error)
Bin2Bin transforms binary input data into binary output data for the named step.
func (*MultiPipeline) Bin2Str ¶
func (p *MultiPipeline) Bin2Str(name string, in []byte) (out string, err error)
Bin2Str transforms binary input data into a string representation for the named step.
func (*MultiPipeline) MustBin2Str ¶
func (p *MultiPipeline) MustBin2Str(name string, in []byte) string
type Pipeline ¶
type Pipeline struct {
// contains filtered or unexported fields
}
Pipelines manage transformers converting data from the input type to the output type.
func (*Pipeline) Bin2Bin ¶
Bin2Bin transforms binary input data into binary output data by decoding the binary data at each step of the pipeline and encoding it to bytes before passing it to the next step in the pipeline.
func (*Pipeline) Bin2Str ¶
Bin2Str transforms binary input data into a string representation by decoding the binary input data at each step of the pipeline and encoding it to bytes before passing it to the next step in the pipeline. The final step is encoded as a str.
func (*Pipeline) Str2Bin ¶
Str2Bin transforms binary input data into binary output data by decoding the string in the first step of the pipeline then encoding it to bytes before passing it to each additional step to decode as bytes.
type Text ¶
type Text struct {
Encoding TextEncoding
// contains filtered or unexported fields
}
func NewText ¶
func NewText(encoding TextEncoding) *Text
func (Text) EncodeBinary ¶
func (Text) EncodeString ¶
type TextEncoding ¶
type TextEncoding uint8
const ( UTF8Encoding TextEncoding = iota ASCIIEncoding Latin1Encoding )
Text encoding schemes to convert to and from.
func (TextEncoding) String ¶
func (b TextEncoding) String() string
type ULID ¶
type ULID struct {
ULID ulid.ULID
}
Source Files
Directories