pterm

package module
v0.4.204 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 6, 2025 License: ISC Imports: 12 Imported by: 0

Documentation

Overview

Package pterm provides an ANSI-based status terminal and password-input.

separate module because of import of golang.org/x/term

Index

Constants

View Source 
const (
	// foregorund color red
	Red = "\x1b[38:5:9m"
	// foregorund color green
	Green = "\x1b[38:5:2m"
	// foreground color reset to default
	ResetColors = "\x1b[39;49m"
)
View Source 
const (
	// ANSI erase to end-of-line
	EraseEndOfLine = "\x1b[K"
	// ANSI erase to end-of-display
	EraseEndOfDisplay = "\x1b[J"
	// ANSI move cursor to column zero
	MoveCursorToColumnZero = "\r"
	// ANSI move cursor up
	//	- at top line does nothing
	CursorUp = "\x1b[A"
	// ANSI move cursor down to the left
	//	- on last line, causes the view to scroll
	NewLine = "\n"
	// Space for clearing old status characters
	Space = "\x20"
)

ANSI escape sequences

View Source 
const (
	// [pterm.StatusTerminalFd] default file descriptor for output
	STDefaultFd int = 0
	// [StatusTerminal.SetTerminal] width for reset to default
	DisableSetTerminal int = -1
	// [StatusTerminal.SetTerminal] default isTerminal value
	NoIsTerminal IsTerminal = false
	// [StatusTerminal.SetTerminal] activate isTerminal override
	IsTerminalYes IsTerminal = true
	// [StatusTerminal.CopyLog] remove writer
	CopyLogRemove CopyLogRemover = true
)
View Source 
const (
	// default prompt is “password: ”
	DefaultPrompt = ""
)

Variables

View Source 
var NoPassword = &NoPasswordStruct{}

NoPassword is a value indicating that password input is unavailable

View Source 
var NoPrintf parl.PrintfFunc

pterm.StatusTerminalFd no printf function

View Source 
var STDefaultWriter io.Writer

pterm.StatusTerminalFd no write function

Functions

func TrimANSIEscapes added in v0.4.29 

func TrimANSIEscapes(s string) (s1 string)

TrimANSIEscapes returns a string where ANSI espace sequences have been removed.

Types

type CopyLogRemover added in v0.4.189 

type CopyLogRemover bool

argument type for StatusTerminal.CopyLog

type IsTerminal added in v0.4.189 

type IsTerminal bool

determines status output override for StatusTerminal.SetTerminal

type NoPasswordStruct 

type NoPasswordStruct struct{}

NoPassword is a value indicating that password input is unavailable

func (*NoPasswordStruct) HasPassword 

func (ps *NoPasswordStruct) HasPassword() (hasPassword bool)

HasPassword indicates password input not available

func (*NoPasswordStruct) Password 

func (ps *NoPasswordStruct) Password() (password []byte, err error)

Password return empty password

type Password added in v0.4.152 

type Password struct {
	// password prompt like “password”
	//	- colon-space is appended
	Prompt string
	// Input is where characters are read by [term.ReadPassword]
	//	- must have file descriptor, so [os.File]
	//	- default is [os.Stdin]
	Input *os.File
	// Output is where prompt is written using [io.Write]
	//	- if nil, [parl.Consolew] is used for standard error
	Output io.Writer
}

Password implements reading a password from standard input

func NewPassword 

func NewPassword(prompt string) (passworder *Password)

NewPassword returns an interactive password reader

  • prompt is printed with appended colon-space
  • default prompt is “password: ”
  • not compatible with an active StatusTerminal

func (*Password) HasPassword added in v0.4.152 

func (p *Password) HasPassword() (hasPassword bool)

HasPassword returns true indicating that interactive password input is available

func (*Password) Password added in v0.4.152 

func (p *Password) Password() (password []byte, err error)

Password reads a password interactively form the keyboard

type Printer added in v0.4.189 

type Printer struct {
	// contains filtered or unexported fields
}

Printer offers error-free Print of string delegated to either parl.PrintfFunc or io.Writer

func (*Printer) Print added in v0.4.189 

func (p *Printer) Print(s string)

Print is error-free string printer to parl.PrintfFunc or io.Writer

func (*Printer) SetPrintFunc added in v0.4.189 

func (p *Printer) SetPrintFunc(printfFunc parl.PrintfFunc)

SetPrintFunc sets the parl.PrintfFunc to use

func (*Printer) SetWriter added in v0.4.189 

func (p *Printer) SetWriter(writer io.Writer)

SetWriter sets the io.Writer to use

type StatusDebug added in v0.4.109 

type StatusDebug struct {
	// contains filtered or unexported fields
}

- to activate d, use option “-verbose StatusTerminal..Status”

func NewStatusDebug added in v0.4.109 

func NewStatusDebug(lines []string, width int) (debug *StatusDebug)

- to activate d, use option “-verbose StatusTerminal..Status”

func (*StatusDebug) DebugText added in v0.4.109 

func (d *StatusDebug) DebugText() (text string)

meta formatting string: “01n02e03w004L05N06”

func (*StatusDebug) UpdateOutput added in v0.4.109 

func (d *StatusDebug) UpdateOutput(output string, displayLineCount int) (o string)

inserts the process-complete status at end of status - without changing the length of status

type StatusTerminal added in v0.4.29 

type StatusTerminal struct {
	// contains filtered or unexported fields
}

StatusTerminal provides an updatable status area at the bottom of the terminal window with log lines flowing upwards above it

  • outputs to a single file descriptor or supplied Write method
  • typically the os.Stderr is used
  • uses ANSI escape codes, ie. the stream is expected to support certain ioctl
  • the stream shpould typically not be piped or written to file, since status output involves large amount of control codes
  • supports ncurses-like behavior without putting the terminal in a special mode
  • when in status mode, each Print and Write invocations must output in discrete lines
  • LogTimeStamp prepends compact and specific timestamping

func NewStatusTerminal added in v0.4.29 

func NewStatusTerminal() (statusTerminal *StatusTerminal)

NewStatusTerminal returns a terminal representation for concurrent logging and status output to standard error

func NewStatusTerminalFd added in v0.4.32 

func NewStatusTerminalFd(
	fieldp *StatusTerminal,
	fd int,
	logWriter io.Writer,
	stdoutWriter io.Writer,
	logPrintf parl.PrintfFunc,
	stdoutPrintf parl.PrintfFunc,
	copyLog ...io.Writer,
) (statusTerminal *StatusTerminal)

NewStatusTerminalFd returns a terminal representation for logging and status output

  • fieldp: pointer to optional pre-allocated field
  • fd: file descriptor used for ioctl, ie. needs to be a terminal
  • — status output is written to fd if logWriter not present
  • — fd is used for detecting ANSI capabilities and display width
  • fd STDefaultFd 0: use default standard error: os.Stderr.Fd()
  • logWriter: used for status output
  • logWriter nil: output to fd
  • stdoutWriter: used for LogStdout output
  • stdoutWriter nil: LogStdout outputs to standard output
  • logPrintf, stdoutPrintf: set or NoPrintf
  • copyLog optional: log output should be copied to this writer
  • stores self-referencing pointers
  • StatusTerminal.Status set status string
  • StatusTerminal.Log stderr output no timestamp
  • StatusTerminal.LogStdout stdout output no timestamp
  • StatusTerminal.LogTimeStamp stderr output with timestamp

func (*StatusTerminal) CopyLog added in v0.4.38 

func (s *StatusTerminal) CopyLog(writer io.Writer, remove ...CopyLogRemover)

CopyLog adds writers that receives copies of non-status logging

  • writer: an io.Writer receiving log output
  • remove: present and CopyLogRemove true: stop output to a previous writer
  • thread-safe

func (*StatusTerminal) EndStatus added in v0.4.40 

func (s *StatusTerminal) EndStatus()

EndStatus stops status output, typically on app exit

  • idempotent
  • thread-safe

func (*StatusTerminal) Log added in v0.4.29 

func (s *StatusTerminal) Log(format string, a ...any)

Log outputs text ending with at least one newline while maintaining status information at bottom of screen.

  • default to stderr
  • two or more arguments: Printf formatting used
  • single argument is not interpreted
  • For non-ansi-terminal stderr, LogTimeStamp simply prints lines of text.
  • thread-safe

func (*StatusTerminal) LogStdout added in v0.4.141 

func (s *StatusTerminal) LogStdout(format string, a ...any)

LogStdout outputs to specific logger, ie. stdout

  • default to stdout
  • two or more arguments: Printf formatting used
  • single argument is not interpreted
  • thread-safe

func (*StatusTerminal) LogTimeStamp added in v0.4.29 

func (s *StatusTerminal) LogTimeStamp(format string, a ...any)

LogTimeStamp outputs text ending with at least one newline while maintaining status information at bottom of screen.

  • two or more arguments: Printf formatting is used
  • Single argument is not interpreted
  • The string is preceed by a timestamp and space: "060102 15:04:05-08 "
  • For non-ansi-terminal stderr, LogTimeStamp simply prints lines of text.
  • thread-safe

func (*StatusTerminal) NeedsEndStatus added in v0.4.189 

func (s *StatusTerminal) NeedsEndStatus() (needsEndStatus bool)

NeedsEndStatus is true if a ne- function has been invoked and EndStatus has not been invoked

  • thread-safe

func (*StatusTerminal) SetTerminal added in v0.4.38 

func (s *StatusTerminal) SetTerminal(isTerminal IsTerminal, width int) (isAnsi bool)

SetTerminal overrides status regardless of whether a terminal is used

  • isTerminal: overrides the detection of whether ANSI sequences are supported
  • isTerminal IsTerminalYes true: enable override
  • isTerminal NoIsTerminal false: disable override or noop
  • width: width to use if fd is not ANSI terminal
  • width DisableSetTerminal -1: disable SetTerminal override
  • thread-safe

func (*StatusTerminal) Status added in v0.4.29 

func (s *StatusTerminal) Status(statusLines string)

Status updates a status area at the bottom of the display

  • For non-ansi-terminal stderr, Status does nothing
  • delegates to logPrinter
  • thread-safe

func (*StatusTerminal) Width added in v0.4.30 

func (s *StatusTerminal) Width() (width int)

Width returns the current column width of the window

  • if SetTerminal override active, its provided width value
  • thread-safe

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.
JackTT - Gopher 🇻🇳