Documentation
¶
Overview ¶
Package pterm provides an ANSI-based status terminal and password-input.
Index ¶
- Constants
- Variables
- func TrimANSIEscapes(s string) (s1 string)
- type NoPasswordStruct
- type Password
- type StatusDebug
- type StatusTerminal
- func (s *StatusTerminal) CopyLog(writer io.Writer, remove ...bool)
- func (s *StatusTerminal) EndStatus()
- func (s *StatusTerminal) Log(format string, a ...any)
- func (s *StatusTerminal) LogStdout(format string, a ...any)
- func (s *StatusTerminal) LogTimeStamp(format string, a ...any)
- func (s *StatusTerminal) SetTerminal(isTerminal bool, width int)
- func (s *StatusTerminal) Status(statusLines string)
- func (s *StatusTerminal) Width() (width int)
- type WriterWrite
Constants ¶
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" )
const ( // [StatusTerminal.CopyLog] stops output for a writer CopyLogRemoveFile = true // [pterm.StatusTerminalFd] default file descriptor for output STDefaultFd = 0 )
const ( EraseEndOfLine = "\x1b[K" EraseEndOfDisplay = "\x1b[J" MoveCursorToColumnZero = "\r" CursorUp = "\x1b[A" // at top line does nothing NewLine = "\n" // on last line, causes the view to scroll Space = "\x20" )
ANSI escape sequences
const (
// default prompt is “password: ”
DefaultPrompt = ""
)
Variables ¶
var NoPassword = &NoPasswordStruct{}
NoPassword is a value indicating that password input is unavailable
var STDefaultWriter io.Writer
pterm.StatusTerminalFd no write function
Functions ¶
func TrimANSIEscapes ¶ added in v0.4.29
TrimANSIEscapes returns a string where ANSI espace sequences have been removed.
Types ¶
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 ¶
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
HasPassword returns true indicating that interactive password input is available
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 {
// file descriptor, typically os.Stderr
Fd int
// the Printf-style function used for output
Print func(s string)
Write WriterWrite
// configurable whether status texts should be output
IsTerminal atomic.Bool
// 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
- stores self-referencing pointers
func NewStatusTerminalFd ¶ added in v0.4.32
func NewStatusTerminalFd(fieldp *StatusTerminal, fd int, writer io.Writer, copyLog ...io.Writer) (statusTerminal *StatusTerminal)
NewStatusTerminalFd returns a terminal representation for logging and status output
- Fd is file descriptor used for ioctl, ie. needs to be a terminal, default is standard error
- Writer is for output, default writer for Fd
- stores self-referencing pointers
func (*StatusTerminal) CopyLog ¶ added in v0.4.38
func (s *StatusTerminal) CopyLog(writer io.Writer, remove ...bool)
CopyLog adds writers that receives copies of non-status logging
- remove true stops output for a writer
func (*StatusTerminal) EndStatus ¶ added in v0.4.40
func (s *StatusTerminal) EndStatus()
EndStatus stops status output, typically on app exit
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. for two or more arguments, Printf formatting is used. Single argument is not interpreted. For non-ansi-terminal stderr, LogTimeStamp simply prints lines of text.
func (*StatusTerminal) LogStdout ¶ added in v0.4.141
func (s *StatusTerminal) LogStdout(format string, a ...any)
LogStdout outputs to specific logger, ie. stdout
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.
- for 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.
func (*StatusTerminal) SetTerminal ¶ added in v0.4.38
func (s *StatusTerminal) SetTerminal(isTerminal bool, width int)
SetTerminal overrides status regardless of whether a terminal is used
- isTerminal overrides the detection of if ANSI sequences are supported
- width is width to use if width cannot be read from the stream
- if width is -1, reset back to default
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.
func (*StatusTerminal) Width ¶ added in v0.4.30
func (s *StatusTerminal) Width() (width int)
Width returns the current column width of the window
- if not a terminal, the stored width value
type WriterWrite ¶ added in v0.4.38
the Write signature of an io.Writer
Source Files