progress

README

Progress

Go module for printing progress/task status of command line applications.

Installation

To install this library, use go get:

go get github.com/UpCloudLtd/progress

Usage

To log progress messages with Progress, you need to

• Initialize a Progress instance
• Push messages to the Progress instance

Initialize Progress

To initialize Progress, run progress.NewProgress(...). This initializes the internal message store and message renderer.

To start logging the progress messages, call Start() to launch goroutine responsible for updating the progress log and handling incoming progress updates.

When done with logging progress updates, call Stop() to render the final progress log state and to terminate the goroutine started by Start().

cfg := progress.GetDefaultOutputConfig()
taskLog := progress.NewProgress(cfg)

taskLog.Start()
defer taskLog.Stop()

Push messages

To push messages to the progress log, call Push(...). For example:

taskLog.Push(messages.Update{
    Key:     "error-example",
    Message: "Pushing message to the progress log",
    Status:  messages.MessageStatusStarted,
})

An update can contain four different fileds: Key, Message, Status, and Details. When updating progress message that does not yet exist, Message and Status are required.

Field	Description
Key	Used to identify the message when pushing further updates. If not given when pushing first update to the message, value from Message field is used as Key.
Message	Text to be outputted in the progress log for the related message.
Status	Status of the message, e.g. success, error, warning. Used to determine status indicator and color. Finished statuses (success, error, warning, skipped, unknown) are outputted to persistent log and can not be edited anymore.
ProgressMessage	Progress indicator text to be appended into Message in TTY terminals, e.g. 128 / 384 kB or 24 %. Updating this field will not trigger message write in non-TTY terminals.
Details	Details to be outputted under finished progress log row, e.g. error message.

Progress messages can be updated while they are in pending or started states. Note that pending messages are not outputted at the moment.

When updating existing progress message, unchanged fields can be omitted. For example:

taskLog.Push(messages.Update{
    Key:     "error-example",
    Status:  messages.MessageStatusError,
    Details: "Error: Message details can be used, for example, to communicate error messages to the user.",
})

Development

Use conventional commits when committing your changes.

To lint the code, run golangci-lint run. See its documentation for local installation instructions.

golangci-lint run

To test the code, run go test ./....

go test ./...

To update snapshots, run tests with UPDATE_SNAPSHOTS environment variable set to true.

UPDATE_SNAPSHOTS=true go test ./...

To build and run the example application, run:

go build -o example.bin ./example/example.go
./example.bin

Releasing

When releasing a new version:

1. Merge all changes to be included to the main branch.
2. Prepare CHANGELOG.md for the new release:
   1. Add new heading with the correct version (e.g., ## [v2.3.5]).
   2. Update links at the bottom of the page.
   3. Leave Unreleased section at the top empty.
3. Draft a new release in GitHub releases:
   1. Set the release to create new tag (e.g., v2.3.5).
   2. Select the stable branch.
   3. Title the release with the version number (e.g., v2.3.5).
   4. In the description of the release, paste the changes from CHANGELOG.md for this version release.
4. Publish the release when ready.

Documentation

Index

• type OutputConfig
  • func GetDefaultOutputConfig() *OutputConfig
• type Progress
  • func NewProgress(config *OutputConfig) *Progress
  • func (p Progress) Push(update messages.Update) error
  • func (p *Progress) Start()
  • func (p Progress) Stop()

Types

type OutputConfig

type OutputConfig messages.OutputConfig

func GetDefaultOutputConfig

func GetDefaultOutputConfig() *OutputConfig

GetDefaultOutputConfig returns pointer to a new instance of default output configuration.

type Progress

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

func NewProgress

func NewProgress(config *OutputConfig) *Progress

NewProgress creates new Progress instance. Use nil config for default output configuration.

func (Progress) Push

func (p Progress) Push(update messages.Update) error

Push updates to the progress log. Errors if called before start or if called with an invalid update. Panics if called after Close.

func (*Progress) Start

func (p *Progress) Start()

Start the progress logging in a new goroutine. Panics if called more than once.

func (Progress) Stop

func (p Progress) Stop()

Stop the goroutine handling progress logging and render the final progress state. Panics if called before start or more than once.