README
¶
Go Scroll Buffer
ANSI Scroll Buffer Stages is a simple package meant to emulate the stages in a cli tool where overall output isn't important unless there is a failure. It consists of a simple buffer abstraction that utilizes ANSI escape codes in the background. This can help when there is a large amount of output to the terminal in stages, but the overall result may be important to communicate to the user.
Install
go get github.com/louislef299/scroll
Examples
Simple write to the Buffer:
scroll.Printf("hello world")
Erase the existing Buffer:
// Prints hello world 5x
for i := 0; i < 5; i++ {
scroll.Printf("hello world")
}
scroll.EraseBuffer()
Run print statements in stages:
// Stage 1
for i := 0; i < 5; i++ {
scroll.Printf("%d: hello from stage 1", i + 1)
}
// end stage
scroll.NewStage("stage 1 complete!")
// Stage 2
for i := 0; i < 5; i++ {
scroll.Printf("%d: hello from stage 2", i + 1)
}
// end stage
scroll.NewStage("stage 2 complete!")
Create a custom Buffer:
// Creates a new buffer with a size of 5
buff := scroll.New(context.TODO(), os.Stdout, 5)
// Prints hello world 5x
for i := 0; i < 5; i++ {
buff.Printf("hello world")
}
time.Sleep(time.Second)
buff.NewStage("finish buffer example!")
The ANSI Buffer also implements io.Writer:
log.SetOutput(scroll.New(context.TODO(), 5))
log.Println("written from test")
The writer is unreliable under stress however, as the channels that are created for synchronization are not reliably transferred to packages like log and fmt.
Contributing
The tests are currently visual tests and require a human to watch the output and verify functionality. Not ideal, but that's how it is for now. Feel free to fix it!
References
The scroll package takes some inspiration for the log standard package and Fatih Arslan's color package.
Documentation
¶
Index ¶
- Constants
- Variables
- func EraseBuffer()
- func GetBufferMax() int
- func NewStage(format string, a ...interface{})
- func Printf(format string, a ...interface{})
- func Println(a ...interface{})
- func SetBufferMax(size int)
- func SetContext(ctx context.Context)
- func SetOutput(w io.Writer)
- func SetPrefix(prefix string)
- func SetPrinterColor(color color.Attribute)
- func SetStageColor(color color.Attribute)
- type Buffer
- func (b *Buffer) EraseBuffer()
- func (b *Buffer) GetBufferSize() int
- func (b *Buffer) NewStage(format string, a ...interface{})
- func (b *Buffer) Printf(format string, a ...interface{})
- func (b *Buffer) Println(a ...interface{})
- func (b *Buffer) SetBufferMax(size int)
- func (b *Buffer) SetOutput(w io.Writer)
- func (b *Buffer) SetPrefix(prefix string)
- func (b *Buffer) SetPrinterColor(color color.Attribute)
- func (b *Buffer) SetStageColor(color color.Attribute)
- func (b *Buffer) Write(p []byte) (n int, err error)
Constants ¶
const ( PrinterStage stage = "PRINTER" EraserStage stage = "ERASER" )
const DEFAULT_BUFFER_SIZE = 100
Represents the default buffer size when running on a non-tty terminal
Variables ¶
var ( // IsTerm dynamically prevents usage of ANSI escape sequences if stdout's // file descriptor is not a Terminal. NO_TERMINAL_CHECK is an environment // variable used to override the default terminal check in the case it is // incorrect. IsTerm = (term.IsTerminal(int(os.Stdout.Fd())) || os.Getenv("NO_TERMINAL_CHECK") != "") )
Functions ¶
func EraseBuffer ¶
func EraseBuffer()
EraseBuffer is the exported function that includes Buffer validations.
func GetBufferMax ¶ added in v1.1.0
func GetBufferMax() int
GetBufferMax returns the current maximum buffer length of the standard Buffer.
func NewStage ¶
func NewStage(format string, a ...interface{})
Resets the Buffer buffer by erasing buffer output and printing out the string input to the screen for the standard buffer.
func Printf ¶
func Printf(format string, a ...interface{})
Printf safely executes the channel printing logic and formats the provided string to the standard buffer.
func Println ¶
func Println(a ...interface{})
Println safely executes the channel printing logic and formats the provided string to the standard buffer.
func SetBufferMax ¶ added in v1.1.0
func SetBufferMax(size int)
SetBufferMax sets the buffer size of the standard Buffer.
func SetContext ¶
SetContext sets the context of the standard Buffer.
func SetPrefix ¶
func SetPrefix(prefix string)
SetPrefix sets the prefix for output from the standard Buffer.
func SetPrinterColor ¶
SetPrinterColor sets the output color for scrolling output on the standard Buffer.
func SetStageColor ¶
SetStageColor sets the output color for stage finalizer output on the standard Buffer.
Types ¶
type Buffer ¶
type Buffer struct {
// contains filtered or unexported fields
}
A Buffer represents the streaming buffer used for the ANSI scrolling stages
func Default ¶
func Default() *Buffer
Default returns the standard buffer used by the package-level output functions.
func New ¶
New creates a new Buffer which starts a goroutine to print or erase lines and cancels on context.Done(). Returns a new Buffer to allow for scroll output to be written.
func (*Buffer) EraseBuffer ¶
func (b *Buffer) EraseBuffer()
EraseBuffer is the exported function that includes Buffer validations.
func (*Buffer) GetBufferSize ¶ added in v1.1.0
GetBufferSize returns the current bufferSize of the Buffer.
func (*Buffer) NewStage ¶
NewStage resets the Buffer by erasing the buffer output and printing out the stage input to the screen.
func (*Buffer) Printf ¶
Printf safely executes the channel printing logic and formats the provided string to the temporary buffer.
func (*Buffer) Println ¶
func (b *Buffer) Println(a ...interface{})
Println safely executes the channel printing logic and formats the provided string to the temporary buffer.
func (*Buffer) SetBufferMax ¶ added in v1.1.0
SetBufferMax sets the size of the Buffer.
func (*Buffer) SetPrinterColor ¶
SetPrinterColor sets the output color for scrolling output on the Buffer.
func (*Buffer) SetStageColor ¶
SetStageColor sets the output color for stage finalizer output on the Buffer.
Source Files