Version: v0.32.0 Latest Latest

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

Go to latest
Published: Sep 23, 2023 License: MIT Imports: 39 Imported by: 2



Package oviewer provides a pager for terminals.

oviewer displays the contents of the file or reader etc... on the current terminal screen. After running a Run, oviewer does not return until the user finishes running. So if you want to do something in concurrent, you need to use goroutine.

There is also a simple usage example below: https://github.com/noborus/mdviewer/

package main

import (

func main() {
    ov, err := oviewer.Open("main.go")
    if err != nil {
    if err := ov.Run(); err != nil {




View Source
const EOFC rune = '~'

EOFC is the EOF character.

View Source
const FormFeed = "\f"

FormFeed is the delimiter that separates the sections. The default delimiter that separates single output from watch.

View Source
const MaxWriteLog int = 10

MaxWriteLog is the maximum number of lines to output to the log when the debug flag is enabled.

View Source
const MouseFlags = tcell.MouseDragEvents

MouseFlags represents which events of the mouse should be captured. Set the mode to MouseDragEvents when the mouse is enabled in oviewer. Does not track mouse movements except when dragging.

View Source
const TargetLineDelimiter = 10

TargetLineDelimiter covers from line 1 to this line, because there are headers and separators.


View Source
var (
	// MemoryLimit is a number that limits the chunks to load into memory.
	MemoryLimit int
	// MemoryLimitFile is a number that limits the chunks loading a file into memory.
	MemoryLimitFile int

	// OverStrikeStyle represents the overstrike style.
	OverStrikeStyle tcell.Style
	// OverLineStyle represents the overline underline style.
	OverLineStyle tcell.Style
	// SkipExtract is a flag to skip extracting compressed files.
	SkipExtract bool
View Source
var (
	// Redirect to standard output.
	//     echo "t" | ov> out
	// Redirects the error output of ov --exec.
	//     ov --exec -- command 2> out

ov output destination.

View Source
var (
	// ErrOutOfRange indicates that value is out of range.
	ErrOutOfRange = errors.New("out of range")
	// ErrNotInMemory indicates that value is not in memory.
	ErrNotInMemory = errors.New("not in memory")
	// ErrFatalCache indicates that the cache value had a fatal error.
	ErrFatalCache = errors.New("fatal error in cache value")
	// ErrMissingFile indicates that the file does not exist.
	ErrMissingFile = errors.New("missing filename")
	// ErrIsDirectory indicates that specify a directory instead of a file.
	ErrIsDirectory = errors.New("is a directory")
	// ErrNotFound indicates not found.
	ErrNotFound = errors.New("not found")
	// ErrCancel indicates cancel.
	ErrCancel = errors.New("cancel")
	// ErrInvalidNumber indicates an invalid number.
	ErrInvalidNumber = errors.New("invalid number")
	// ErrFailedKeyBind indicates keybinding failed.
	ErrFailedKeyBind = errors.New("failed to set keybind")
	// ErrSignalCatch indicates that the signal has been caught.
	ErrSignalCatch = errors.New("signal catch")
	// ErrAlreadyClose indicates that it is already closed.
	ErrAlreadyClose = errors.New("already closed")
	// ErrNoColumn indicates that cursor specified a nonexistent column.
	ErrNoColumn = errors.New("no column")
	// ErrNoDelimiter indicates that the line containing the delimiter could not be found.
	ErrNoDelimiter = errors.New("no delimiter")
	// ErrOverScreen indicates that the specified screen is out of range.
	ErrOverScreen = errors.New("over screen")
	// ErrOutOfChunk indicates that the specified Chunk is out of range.
	ErrOutOfChunk = errors.New("out of chunk")
	// ErrNotLoaded indicates that it cannot be loaded.
	ErrNotLoaded = errors.New("not loaded")
	// ErrEOFreached indicates that EOF has been reached.
	ErrEOFreached = errors.New("EOF reached")
	// ErrPreventReload indicates that reload is prevented.
	ErrPreventReload = errors.New("prevent reload")
	// ErrOverChunkLimit indicates that the chunk limit has been exceeded.
	ErrOverChunkLimit = errors.New("over chunk limit")
	// ErrAlreadyLoaded indicates that the chunk already loaded.
	ErrAlreadyLoaded = errors.New("chunk already loaded")
	// ErrEvictedMemory indicates that it has been evicted from memory.
	ErrEvictedMemory = errors.New("evicted memory")
View Source
var ChunkSize = 10000

ChunkSize is the unit of number of lines to split the file.

View Source
var DefaultContent = content{
	// contains filtered or unexported fields

DefaultContent is a blank Content.

View Source
var EOFContent = content{
	// contains filtered or unexported fields

EOFContent is EOFC only.

View Source
var UpdateInterval = 50 * time.Millisecond

UpdateInterval is the update interval that calls eventUpdate().


func ContentsToStr added in v0.9.5

func ContentsToStr(lc contents) (string, widthPos)

ContentsToStr returns a converted string and byte position, as well as the content position conversion table.

func KeyBindString

func KeyBindString(k KeyBind) string

KeyBindString returns keybind as a string for help.

func NewChunk added in v0.15.0

func NewChunk(start int64) *chunk

NewChunk returns chunk.

func NewStore added in v0.30.0

func NewStore() *store

NewStore returns store.

func RangeStyle added in v0.9.0

func RangeStyle(lc contents, start int, end int, s OVStyle)

RangeStyle applies the style to the specified range. Apply style to contents.

func StrToContents added in v0.9.5

func StrToContents(str string, tabWidth int) contents

StrToContents converts a single-line string into a one line of contents. Parse escape sequences, etc. 1 Content matches the characters displayed on the screen.

func ToTcellStyle added in v0.10.0

func ToTcellStyle(s OVStyle) tcell.Style

ToTcellStyle convert from ovStyle to tcell style.


type Command added in v0.20.0

type Command struct {
	// contains filtered or unexported fields

Command is the structure of the command.

func NewCommand added in v0.20.0

func NewCommand(args ...string) *Command

NewCommand return the structure of Command.

func (*Command) Exec added in v0.20.0

func (cmd *Command) Exec() (*Root, error)

Exec return the structure of oviewer.

func (*Command) Reload added in v0.20.0

func (cmd *Command) Reload() *bufio.Reader

Reload restarts the command.

func (*Command) Wait added in v0.20.0

func (cmd *Command) Wait()

Wait waits for the command to exit.

type Compressed added in v0.8.9

type Compressed int

Compressed represents the type of compression.

const (
	// UNCOMPRESSED is an uncompressed format.
	UNCOMPRESSED Compressed = iota
	// GZIP is gzip compressed format.
	// BZIP2 is bzip2 compressed format.
	// ZSTD is zstd compressed format.
	// LZ4 is lz4 compressed format.
	// XZ is xz compressed format.

func (Compressed) String added in v0.8.9

func (c Compressed) String() string

String returns the string representation of the compressed format.

type Config

type Config struct {
	// KeyBinding
	Keybind map[string][]string
	// Mode represents the operation of the customized mode.
	Mode map[string]general
	// ViewMode represents the view mode.
	// ViewMode sets several settings together and can be easily switched.
	ViewMode string
	// Default keybindings. Disabled if the default keybinding is "disable".
	DefaultKeyBind string
	// StyleColumnRainbow  is the style that applies to the column rainbow color highlight.
	StyleColumnRainbow []OVStyle
	// StyleMultiColorHighlight is the style that applies to the multi color highlight.
	StyleMultiColorHighlight []OVStyle

	// Prompt is the prompt setting.
	Prompt OVPromptConfig

	// StyleHeader is the style that applies to the header.
	StyleHeader OVStyle
	// StyleBody is the style that applies to the body.
	StyleBody OVStyle
	// StyleLineNumber is a style that applies line number.
	StyleLineNumber OVStyle
	// StyleSearchHighlight is the style that applies to the search highlight.
	StyleSearchHighlight OVStyle
	// StyleColumnHighlight is the style that applies to the column highlight.
	StyleColumnHighlight OVStyle
	// StyleMarkLine is a style that marked line.
	StyleMarkLine OVStyle
	// StyleSectionLine is a style that section delimiter line.
	StyleSectionLine OVStyle
	// StyleJumpTargetLine is the line that displays the search results.
	StyleJumpTargetLine OVStyle
	// StyleAlternate is a style that applies line by line.
	StyleAlternate OVStyle
	// StyleOverStrike is a style that applies to overstrike.
	StyleOverStrike OVStyle
	// StyleOverLine is a style that applies to overstrike underlines.
	StyleOverLine OVStyle
	// General represents the general behavior.
	General general
	// BeforeWriteOriginal specifies the number of lines before the current position.
	// 0 is the top of the current screen
	BeforeWriteOriginal int
	// AfterWriteOriginal specifies the number of lines after the current position.
	// 0 specifies the bottom of the screen.
	AfterWriteOriginal int
	// MemoryLimit is a number that limits chunk loading.
	MemoryLimit int
	// MemoryLimitFile is a number that limits the chunks loading a file into memory.
	MemoryLimitFile int
	// Mouse support disable.
	DisableMouse bool
	// IsWriteOriginal is true, write the current screen on quit.
	IsWriteOriginal bool
	// QuitSmall Quit if the output fits on one screen.
	QuitSmall bool
	// CaseSensitive is case-sensitive if true.
	CaseSensitive bool
	// SmartCaseSensitive is lowercase search ignores case, if true.
	SmartCaseSensitive bool
	// RegexpSearch is Regular expression search if true.
	RegexpSearch bool
	// Incsearch is incremental search if true.
	Incsearch bool

	// DisableColumnCycle is disable column cycle.
	DisableColumnCycle bool
	// Debug represents whether to enable the debug output.
	Debug bool

Config represents the settings of ov.

func NewConfig added in v0.5.0

func NewConfig() Config

NewConfig return the structure of Config with default values.

type Document

type Document struct {

	// fileName is the file name to display.
	FileName string
	// Caption is an additional caption to display after the file name.
	Caption string

	// CFormat is a compressed format.
	CFormat Compressed

	// WatchMode is watch mode.
	WatchMode bool
	// contains filtered or unexported fields

The Document structure contains the values for the logical screen.

func NewDocument

func NewDocument() (*Document, error)

NewDocument returns Document.

func NewHelp

func NewHelp(k KeyBind) (*Document, error)

NewHelp generates a document for help.

func NewLogDoc added in v0.5.0

func NewLogDoc() (*Document, error)

NewLogDoc generates a document for log. NewLogDoc makes LogDoc the output destination of go's standard logger.

func OpenDocument added in v0.10.1

func OpenDocument(fileName string) (*Document, error)

OpenDocument opens a file and returns a Document.

func STDINDocument added in v0.10.1

func STDINDocument() (*Document, error)

STDINDocument returns a Document that reads stdin.

func (*Document) BackSearch added in v0.20.0

func (m *Document) BackSearch(ctx context.Context, searcher Searcher, chunkNum int, line int) (int, error)

BackSearch searches backward from the specified line.

func (*Document) BackSearchLine added in v0.10.1

func (m *Document) BackSearchLine(ctx context.Context, searcher Searcher, lN int) (int, error)

BackSearchLine does a backward search on the document and returns a matching line number.

func (*Document) BufEOF

func (m *Document) BufEOF() bool

BufEOF return true if EOF is reached.

func (*Document) BufEndNum

func (m *Document) BufEndNum() int

BufEndNum return last line number.

func (*Document) BufStartNum added in v0.30.0

func (m *Document) BufStartNum() int

BufStartNum return start line number.

func (*Document) ClearCache

func (m *Document) ClearCache()

ClearCache clears the cache.

func (*Document) ContinueReadAll deprecated added in v0.9.0

func (m *Document) ContinueReadAll(ctx context.Context, r io.Reader) error

ContinueReadAll continues to read even if it reaches EOF.

Deprecated: Use ControlFile instead.

func (*Document) ControlFile added in v0.20.0

func (m *Document) ControlFile(file *os.File) error

ControlFile controls file read and loads in chunks. ControlFile can be reloaded by file name.

func (*Document) ControlLog added in v0.20.0

func (m *Document) ControlLog() error

ControlLog controls log. ControlLog is only supported reload.

func (*Document) ControlReader added in v0.20.0

func (m *Document) ControlReader(r io.Reader, reload func() *bufio.Reader) error

ControlReader is the controller for io.Reader. Assuming call from Exec. reload executes the argument function.

func (*Document) CurrentLN added in v0.10.0

func (m *Document) CurrentLN() int

CurrentLN returns the currently displayed line number.

func (*Document) Export added in v0.10.0

func (m *Document) Export(w io.Writer, start int, end int) error

Export exports the document in the specified range.

func (*Document) GetLine

func (m *Document) GetLine(n int) string

GetLine returns one line from buffer. Deprecated: Use LineString instead.

func (*Document) Line added in v0.20.0

func (m *Document) Line(n int) ([]byte, error)

Line returns one line from buffer.

func (*Document) LineStr added in v0.31.0

func (m *Document) LineStr(n int) (string, error)

LineStr returns one line from buffer.

func (*Document) LineString added in v0.20.0

func (m *Document) LineString(n int) string

LineString returns one line from buffer.

func (*Document) NewCache

func (m *Document) NewCache() error

NewCache creates a new cache.

func (*Document) ReadAll deprecated

func (m *Document) ReadAll(r io.Reader) error

ReadAll reads all from the reader. And store it in the lines of the Document. ReadAll needs to be notified on eofCh.

Deprecated: Use ControlReader instead.

func (*Document) ReadFile deprecated

func (m *Document) ReadFile(fileName string) error

ReadFile reads file. If the file name is empty, read from standard input.

Deprecated: Use ControlFile instead.

func (*Document) ReadReader deprecated added in v0.10.1

func (m *Document) ReadReader(r io.Reader) error

ReadReader reads reader. A wrapper for ReadAll.

Deprecated: Use ControlReader instead.

func (*Document) Search added in v0.20.0

func (m *Document) Search(ctx context.Context, searcher Searcher, chunkNum int, line int) (int, error)

Search searches for the search term and moves to the nearest matching line.

func (*Document) SearchLine added in v0.10.1

func (m *Document) SearchLine(ctx context.Context, searcher Searcher, lN int) (int, error)

SearchLine searches the document and returns the matching line number.

func (*Document) Write added in v0.5.0

func (m *Document) Write(p []byte) (int, error)

Write matches the interface of io.Writer(so package log is possible). Therefore, the log.Print output is displayed by logDoc.

type Eventer added in v0.13.0

type Eventer interface {
	// Mode returns the input mode.
	Mode() InputMode
	// Prompt returns the prompt string in the input field.
	Prompt() string
	// Confirm returns the event when the input is confirmed.
	Confirm(i string) tcell.Event
	// Up returns strings when the up key is pressed during input.
	Up(i string) string
	// Down returns strings when the down key is pressed during input.
	Down(i string) string

Eventer is a generic interface for inputs.

type Input

type Input struct {
	Event Eventer

	// Candidate is prepared when the history is used as an input candidate.
	// Header and SkipLines use numbers up and down instead of candidate.
	DelimiterCandidate    *candidate
	ModeCandidate         *candidate
	SearchCandidate       *candidate
	GoCandidate           *candidate
	TabWidthCandidate     *candidate
	WatchCandidate        *candidate
	WriteBACandidate      *candidate
	SectionDelmCandidate  *candidate
	SectionStartCandidate *candidate
	MultiColorCandidate   *candidate
	JumpTargetCandidate   *candidate
	SaveBufferCandidate   *candidate
	// contains filtered or unexported fields

Input represents the status of various inputs. Retain each input list to save the input history.

func NewInput

func NewInput() *Input

NewInput returns all the various inputs.

type InputMode

type InputMode int

InputMode represents the state of the input.

const (
	// Normal is normal mode.
	Normal           InputMode = iota
	ViewMode                   // ViewMode is a view selection input mode.
	Search                     // Search is a search input mode.
	Backsearch                 // Backsearch is a backward search input mode.
	Goline                     // Goline is a move input mode.
	Header                     // Header is the number of headers input mode.
	Delimiter                  // Delimiter is a delimiter input mode.
	TabWidth                   // TabWidth is the tab number input mode.
	Watch                      // Watch is the watch interval input mode.
	SkipLines                  // SkipLines is the number of lines to skip.
	WriteBA                    // WriteBA is the number of ranges to write at quit.
	SectionDelimiter           // SectionDelimiter is a section delimiter input mode.
	SectionStart               // SectionStart is a section start position input mode.
	MultiColor                 // MultiColor is multi-word coloring.
	JumpTarget                 // JumpTarget is the position to display the search results.
	SaveBuffer                 // SaveBuffer is the save buffer.

type KeyBind

type KeyBind map[string][]string

KeyBind is the mapping of action and key.

func GetKeyBinds

func GetKeyBinds(config Config) KeyBind

GetKeyBinds returns the current key mapping.

func (KeyBind) String added in v0.14.0

func (k KeyBind) String() string

String returns keybind as a string for help.

type LineC added in v0.15.0

type LineC struct {
	// contains filtered or unexported fields

LineC is one line of information. Contains content, string, location information.

type LineNumber added in v0.15.0

type LineNumber struct {
	// contains filtered or unexported fields

LineNumber is Number of logical lines and number of wrapping lines on the screen.

type OVPromptConfig added in v0.31.0

type OVPromptConfig struct {
	// Normal is the normal prompt setting.
	Normal OVPromptConfigNormal

OVPromptConfig is the prompt setting.

type OVPromptConfigNormal added in v0.31.0

type OVPromptConfigNormal struct {
	// ShowFilename controls whether to display filename.
	ShowFilename bool
	// InvertColor controls whether the text is colored and inverted.
	InvertColor bool

OVPromptConfigNormal is the normal prompt setting.

type OVStyle added in v0.11.0

type OVStyle struct {
	// Background is a color name string.
	Background string
	// Foreground is a color name string.
	Foreground string
	// If true, add blink.
	Blink bool
	// If true, add bold.
	Bold bool
	// If true, add dim.
	Dim bool
	// If true, add italic.
	Italic bool
	// If true, add reverse.
	Reverse bool
	// If true, add underline.
	Underline bool
	// If true, add strike through.
	StrikeThrough bool
	// If true, add overline (not yet supported).
	OverLine bool
	// If true, sub blink.
	UnBlink bool
	// If true, sub bold.
	UnBold bool
	// If true, sub dim.
	UnDim bool
	// If true, sub italic.
	UnItalic bool
	// If true, sub reverse.
	UnReverse bool
	// If true, sub underline.
	UnUnderline bool
	// If true, sub strike through.
	UnStrikeThrough bool
	// if true, sub underline (not yet supported).
	UnOverLine bool

OVStyle represents a style in addition to the original style.

type Root

type Root struct {
	// tcell.Screen is the root screen.
	// Doc contains the model of ov
	Doc *Document

	// Original string.
	OriginStr string

	// DocList is the list of documents.
	DocList []*Document


	// Original position at the start of search.
	OriginPos int

	// CurrentDoc is the index of the current document.
	CurrentDoc int
	// contains filtered or unexported fields

Root structure contains information about the drawing.

func ExecCommand added in v0.8.9

func ExecCommand(command *exec.Cmd) (*Root, error)

ExecCommand return the structure of oviewer. ExecCommand executes the command and opens stdout/stderr as document.

package main

import (


func main() {
	command := exec.Command("ls", "-alF")
	ov, err := oviewer.ExecCommand(command)
	if err != nil {
	if err := ov.Run(); err != nil {

func NewOviewer

func NewOviewer(docs ...*Document) (*Root, error)

NewOviewer return the structure of oviewer. NewOviewer requires one or more documents.

package main

import (


func main() {
	doc, err := oviewer.NewDocument()
	if err != nil {
	s := "Hello, World!"
	if err := doc.ReadAll(bytes.NewBufferString(s)); err != nil {

	ov, err := oviewer.NewOviewer(doc)
	if err != nil {
	if err := ov.Run(); err != nil {

func NewRoot added in v0.9.0

func NewRoot(r io.Reader) (*Root, error)

NewRoot returns the structure of the oviewer. NewRoot is a simplified version that can be used externally.

package main

import (


func main() {
	r := strings.NewReader(strings.Repeat("north\n", 99))
	ov, err := oviewer.NewRoot(r)
	if err != nil {
	if err := ov.Run(); err != nil {

func Open

func Open(fileNames ...string) (*Root, error)

Open reads the file named of the argument and return the structure of oviewer. If there is no file name, create Root from standard input. If there is only one file name, create Root from that file, but return an error if the open is an error. If there is more than one file name, create Root from multiple files.

package main

import (

func main() {
	ov, err := oviewer.Open("example_test.go")
	if err != nil {
	if err := ov.Run(); err != nil {

func (*Root) AddDocument added in v0.8.0

func (root *Root) AddDocument(m *Document)

AddDocument fires the eventAddDocument event.

func (*Root) BackSearch

func (root *Root) BackSearch(str string)

BackSearch fires a backward search event. This is for calling Search from the outside. Normally, the event is executed from Confirm.

func (*Root) Cancel added in v0.6.2

func (root *Root) Cancel()

Cancel follow mode and follow all mode.

func (*Root) Close added in v0.9.0

func (root *Root) Close()

Close closes the oviewer.

func (*Root) CloseDocument added in v0.8.0

func (root *Root) CloseDocument(m *Document)

CloseDocument fires the eventCloseDocument event.

func (*Root) CopySelect added in v0.6.0

func (root *Root) CopySelect()

CopySelect fires the eventCopySelect event.

func (*Root) DocumentLen added in v0.9.0

func (root *Root) DocumentLen() int

DocumentLen returns the number of Docs.

func (*Root) MoveBottom

func (root *Root) MoveBottom()

MoveBottom fires the event of moving to bottom.

func (*Root) MoveLine

func (root *Root) MoveLine(num int)

MoveLine fires an eventGoto event that moves to the specified line.

func (*Root) MoveTop

func (root *Root) MoveTop()

MoveTop fires the event of moving to top.

func (*Root) Paste added in v0.6.0

func (root *Root) Paste()

Paste fires the eventPaste event.

func (*Root) Quit

func (root *Root) Quit()

Quit fires the eventAppQuit event.

func (*Root) Reload added in v0.10.0

func (root *Root) Reload()

Reload fires the eventReload event.

func (*Root) Run

func (root *Root) Run() error

Run starts the terminal pager.

func (*Root) Search

func (root *Root) Search(str string)

Search fires a forward search event. This is for calling Search from the outside. Normally, the event is executed from Confirm.

func (*Root) SetConfig

func (root *Root) SetConfig(config Config)

SetConfig sets config.

func (*Root) SetDocument

func (root *Root) SetDocument(docNum int)

SetDocument fires the eventDocument event.

func (*Root) SetKeyHandler added in v0.9.6

func (root *Root) SetKeyHandler(name string, keys []string, handler func()) error

SetKeyHandler assigns a new key handler.

func (*Root) SetWatcher added in v0.8.9

func (root *Root) SetWatcher(watcher *fsnotify.Watcher)

SetWatcher sets file monitoring.

func (*Root) Suspend added in v0.9.5

func (root *Root) Suspend()

Suspend fires the eventAppSuspend event.

func (*Root) TailSync added in v0.8.0

func (root *Root) TailSync()

TailSync move to tail and sync.

func (*Root) ViewSync added in v0.8.0

func (root *Root) ViewSync()

ViewSync redraws the whole thing.

func (*Root) WriteLog added in v0.7.1

func (root *Root) WriteLog()

WriteLog write to the log terminal.

func (*Root) WriteOriginal

func (root *Root) WriteOriginal()

WriteOriginal writes to the original terminal.

func (*Root) WriteQuit

func (root *Root) WriteQuit()

WriteQuit sets the write flag and executes a quit event.

type SCR added in v0.15.0

type SCR struct {
	// contains filtered or unexported fields

SCR contains the screen information.

type ScreenMode added in v0.9.0

type ScreenMode int

ScreenMode represents the state of the screen.

const (
	// Docs is a normal document screen mode.
	Docs ScreenMode = iota
	// Help is Help screen mode.
	// LogDoc is Error screen mode.

type Searcher added in v0.10.1

type Searcher interface {
	// Match searches for bytes.
	Match([]byte) bool
	// MatchString searches for strings.
	MatchString(string) bool
	// FindAll searches for strings and returns the index of the match.
	FindAll(string) [][]int
	// String returns the search word.
	String() string

Searcher interface provides a match method that determines if the search word matches the argument string.

func NewSearcher added in v0.10.1

func NewSearcher(word string, searchReg *regexp.Regexp, caseSensitive bool, regexpSearch bool) Searcher

NewSearcher returns the Searcher interface suitable for the search term.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL