bitmasker

README

Bitmasker

Bitmasker is a tool used to automate the creation of helper methods when dealing with bitmask-type constant flags. Given the name of an unsigned integer type T that has constants defined, bitmasker will create a new self-contained Go source file implementing the BitMask and fmt.Stringer interfaces.

Getting Started

To get up and running, follow the normal go install procedure:

go install github.com/go-curses/bitmasker

Example Usage

Bitmasker is intended to be used with go:generate but can operated standalone as well. For example:

Given this snippet:

package mental

//go:generate bitmasker -type=State
type State uint

const (
	Unconscious State = 0
	Conscious   State = 1 << iota
	Meditative
	Distracted
	Entertained = Distracted
)

Standalone usage:

bitmasker -type=State

Using go-generate

go generate

In both cases a new file named "state_bitmask.go" will be created with the following contents:

// Code generated by "bitmasker -type=State"; DO NOT EDIT.

package mental

import "strconv"

func _() {
	// An "invalid array index" compiler error signifies that the constant values have changed.
	// Re-run the bitmasker command to generate them again.
	var x [1]struct{}
	_ = x[Unconscious-0]
	_ = x[Conscious-2]
	_ = x[Meditative-4]
	_ = x[Distracted-8]
}

const (
	_State_name_0 = "Unconscious"
	_State_name_1 = "Conscious"
	_State_name_2 = "Meditative"
	_State_name_3 = "Distracted"
)

func (i State) String() (value string) {
	update := func(t State, n string) {
		if i.Has(t) {
			if len(value) > 0 {
				value += " | "
			}
			value += n
		}
	}
	update(State(0), _State_name_0)
	update(State(2), _State_name_1)
	update(State(4), _State_name_2)
	update(State(8), _State_name_3)
	if value == "" {
		return "State(" + strconv.FormatInt(int64(i), 10) + ")"
	}
	return
}

// Has returns TRUE if the given flag is present in the bitmask
func (i State) Has(m State) bool {
	if i == m {
		return true
	}
	return i&m != 0
}

// Set returns the bitmask with the given flag set
func (i State) Set(m State) State {
	return i | m
}

// Clear returns the bitmask with the given flag removed
func (i State) Clear(m State) State {
	return i &^ m
}

// Toggle returns the bitmask with the given flag toggled
func (i State) Toggle(m State) State {
	return i ^ m
}

Running the tests

Unit tests are provided and can be invoked using the normal Go pattern:

go test

Authors

• Kevin C. Krinke - Bitmasker author - kckrinke
• The Go Authors - Stringer derived sources - stringer

License

This project is licensed under the LGPL (specifically v3) - see the LICENSE.md file for details.

Acknowledgments

• Thanks to Golang.org for the stringer program that bitmasker sources are derived from.

Documentation

Overview

Bitmasker is a tool used to automate the creation of helper methods when dealing with bitmask-type constant flags. Given the name of an unsigned integer type T that has constants defined, bitmasker will create a new self-contained Go source file implementing the BitMask and fmt.Stringer interfaces.

func (t T) Has(m T) bool
func (t T) Set(m T) T
func (t T) Clear(m T) T
func (t T) Toggle(m T) T
func (t T) String() string

The file is created in the same package and directory as the package that defines T. It has helpful defaults designed for use with go generate.

Bitmasker works with constants that are consecutive values created using bit-shifted iota.

For example, given this snippet,

package mental

type State uint

const (
  Unconscious State = 0
  Conscious   State = (1 << iota)
  Meditative
  Distracted
  Entertained = Distracted
)

running this command

bitmasker -type=State .

in the same directory will create the file state_bitmask.go, in package mental, containing a definition of the following:

func (t State) Has(m State) bool
func (t State) Set(m State) State
func (t State) Clear(m State) State
func (t State) Toggle(m State) State
func (t State) String() string

The Has method will return true if the State t has the bitmask given as m.

The Set method will return a new State mask that includes the original mask combined with the given mask m.

The Clear method will return a new State mask that has the original mask with the given mask m removed from it's combined value.

The String method will translate the value of a State constant to the string representation of the respective constant name, satisfying the fmt.Stringer interface. A call to fmt.Print(mental.Entertained) will print the string "Distracted".

Typically this process would be run using go generate, like this:

//go:generate bitmasker -type=State

If multiple constants have the same value, the lexically first matching name will be used (in the example, Entertained will print as "Distracted").

With no arguments, it processes the package in the current directory. Otherwise, the arguments must name a single directory holding a Go package or a set of Go source files that represent a single Go package.

The -type flag accepts a comma-separated list of types so a single run can generate methods for multiple types. The default output file is t_bitmask.go, where t is the lower-cased name of the first type listed. It can be overridden with the -output flag.