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
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.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
example
module
|
|
|
mental
Module
|
|
|
internal
|
|
|
testenv
Package testenv contains helper functions for skipping tests based on which tools are present in the environment.
|
Package testenv contains helper functions for skipping tests based on which tools are present in the environment. |
|
typeparams
Package typeparams provides functions to work indirectly with type parameter data stored in go/ast and go/types objects, while these API are guarded by a build constraint.
|
Package typeparams provides functions to work indirectly with type parameter data stored in go/ast and go/types objects, while these API are guarded by a build constraint. |
|
typeparams/genericfeatures
The genericfeatures package provides utilities for detecting usage of generic programming in Go packages.
|
The genericfeatures package provides utilities for detecting usage of generic programming in Go packages. |