statusbar

README

statusbar

statusbar formats and displays information on the dwm statusbar.

Table of Contents

1. Overview
2. Installation
3. Usage and Documentation
4. Modules
5. REST API
   1. Ping the system
   2. Get list of valid endpoints
   3. Get information about all routines
   4. Get information about routine
   5. Refresh all routines
   6. Refresh routine
   7. Modify routine's settings
   8. Stop all routines
   9. Stop routine
6. Contributing
7. Changelog
   1. 5.2.0
   2. 5.1.1
   3. 5.1.0
   4. 5.0.0
   5. 4.1.2
   6. 4.1.1
   7. 4.1
   8. 4.0
   9. 3.0
   10. 2.0
   11. 1.0

Overview

statusbar is an engine for handling the various components that make up the statusbar. The components are modular routines that handle their own logic for gathering and formatting data, with each routine run in its own thread. The engine triggers the routines to run their update process according to the time interval set by the caller and gathers the individual pieces of data for printing on the statusbar.

Integrating a custom module is very simple. See Modules for more information.

Installation

statusbar is a package, not a stand-alone program. To download the package, you can use gotools in this way:

go get github.com/snhilde/statusbar

That will also pull in the repository's modules for quick activation.

Usage and Documentation

To get up and running with this package, follow these steps:

1. Create a new statusbar object.
2. Add routines to the statusbar.
3. Run the engine.

You can find the complete documentation and usage guidelines at pkg.go.dev. The docs also include an example detailing the steps above.

Modules

statusbar is modular by design, and it's simple to build and integrate modules; you only have to implement a few methods.

This repository includes these modules to get up and running quickly:

Module	Documentation	Major usage
sbbattery	PkgGoDev Doc	Battery usage
sbcputemp	PkgGoDev Doc	CPU temperature
sbcpuusage	PkgGoDev Doc	CPU usage
sbdisk	PkgGoDev Doc	Filesystem usage
sbfan	PkgGoDev Doc	Fan speed
sbgithubclones	PkgGoDev Doc	Github repo clone count
sbload	PkgGoDev Doc	System load averages
sbnetwork	PkgGoDev Doc	Network usage
sbnordvpn	PkgGoDev Doc	NordVPN status
sbram	PkgGoDev Doc	RAM usage
sbtime	PkgGoDev Doc	Current date/time
sbtodo	PkgGoDev Doc	TODO list display
sbvolume	PkgGoDev Doc	Volume percentage
sbweather	PkgGoDev Doc	Weather information

REST API

statusbar comes packaged with a REST API. This API (and all future APIs) is disabled by default. To activate it, you need to call EnableRESTAPI with the port you want the microservice to listen on before running the main Statusbar engine.

The REST API makes use of the wonderful Gin framework. For details on adding/modifying endpoints, see the documentation in the restapi package.

Ping the system

/ping

Sample request:

curl -X GET http://localhost:1234/rest/v1/ping

Default response:

Status: 200 OK

pong

Get list of valid endpoints

/endpoints

Sample request:

curl -X GET http://localhost:1234/rest/v1/endpoints

Default response:

Status: 200 OK

{
	"endpoints": [
		{
			"method": "GET",
			"url": "/ping",
			"description": "Ping the system."
		},
		{
			"method": "GET",
			"url": "/endpoints",
			"description": "Get a list of valid endpoints."
		},
		...
	]
}

Internal error:

Status: 500 Interal Server Error

{
	"error": "error message"
}

Get information about all routines

/routines

Sample request:

curl -X GET http://localhost:1234/rest/v1/routines

Default response:

Status: 200 OK

{
	"routines": {
		"sbbattery": {
			"name": "Battery",
			"uptime": 35212,
			"interval": 30,
			"active": true
		},
		"sbcputemp": {
			"name": "CPU Temp",
			"uptime": 35212,
			"interval": 1,
			"active": true
		},
		...
	}
}

Get information about routine

/routines/{routine}

Parameters	Location	Description
routine	path	Routine's module name

Sample request

curl -X GET http://localhost:1234/rest/v1/routines/sbfan

Default response

Status: 200 OK

{
	"sbfan": {
		"name": "Fan",
		"uptime": 242,
		"interval": 1,
		"active": true
	}
}

Bad request

Status: 400 Bad Request

{
	"error": "invalid routine"
}

Refresh all routines

/routines/refresh

Sample request

curl -X PUT http://localhost:1234/rest/v1/routines/refresh

Default response

Status: 204 No Content

Internal error:

Status: 500 Interal Server Error

{
	"error": "failure"
}

Refresh routine

/routines/refresh/{routine}

Parameters	Location	Description
routine	path	Routine's module name

Sample request

curl -X PUT http://localhost:1234/rest/v1/routines/refresh/sbweather

Default response

Status: 204 No Content

Bad request

Status: 400 Bad Request

{
	"error": "invalid routine"
}

Internal error:

Status: 500 Interal Server Error

{
	"error": "failure"
}

Modify routine's settings

/routines/{routine}

Parameters	Location	Description
routine	path	Routine's module name
interval	body	New interval time, in seconds

Sample request

curl -X PATCH --data '{"interval": 5}' http://localhost:1234/rest/v1/routines/sbcputemp

Default response

Status: 202 Accepted

Bad request

Status: 400 Bad Request

{
	"error": "error message"
}

Internal error:

Status: 500 Interal Server Error

{
	"error": "failure"
}

Stop all routines

/routines

Sample request

curl -X DELETE http://localhost:1234/rest/v1/routines

Default response

Status: 204 No Content

Internal error:

Status: 500 Interal Server Error

{
	"error": "failure"
}

Stop routine

/routines/{routine}

Parameters	Location	Description
routine	path	Routine's module name

Sample request

curl -X DELETE http://localhost:1234/rest/v1/routines/sbgithubclones

Default response

Status: 204 No Content

Bad request

Status: 400 Bad Request

{
	"error": "invalid routine"
}

Internal error:

Status: 500 Interal Server Error

{
	"error": "failure"
}

Contributing

If you find a bug, please submit a pull request. If you think there could be an improvement, please open an issue or submit a pull request with the recommended change. Contributions and new modules are always welcome.

Changelog

5.2.0

• Added REST API.

5.1.1

• Migrated documentation to GoDocs to PkgGoDev Doc

5.1.0

• Added sbgithubclones module to track daily and weekly clone counts for a given repository.
• Engine will now truncate module outputs that are longer than 50 characters.
• Various module enhancements.

5.0.0

• API Break: Changed repository from statusbar4 to statusbar.
• API Break: Redefined RoutineHandler's method Update() to Update() (bool, error).
• API Break: Added method Error() string to RoutineHandler to format error messages separately from the regular output.
• API Break: Added method Name() string to RoutineHandler to allow modules to set their own display name for logging.
• Errors in modules are now handled more gracefully. Modules no longer need to track their own error state; the core engine handles displaying the error as well as either attempting the update procedure again after a predetermined waiting period or stopping the routine completely.
• Implemented normal logging and error logging.

4.1.2

• Updated documentation.

4.1.1

• Changes made to formatting and style as per gofmt and golint recommendations.

4.1.0

• Moved routines and engine into one common repository.

4.0.0

• Complete rewrite in go.
• Simpler formatting and customization.

3.0.0

• Added support for concurrency.
• Made routines modular.

2.0.0

• Ported to Linux.

1.0.0

• Initial release (OpenBSD only).

Documentation

Overview

Package statusbar displays various information on the dwm statusbar.

The design of this statusbar manager is modular by nature; you create the main process with this package and then populate it with only the information you want using individual modules. For example, if you want to show only the time and weather, then you would import only those two modules and add their objects to the statusbar, resulting in only the time and weather to appear on the statusbar for dwm. This modular design allows flexibility in customizing each individual statusbar and ease in management.

This package is the engine that controls the modular routines. For the modules currently integrated with this framework and included in this repository, see the child packages that begin with "sb". There are currently modules that display a range of information, including various system resources, personal TODO lists, the current weather, VPN status, and the current time.

To integrate a custom module into this statusbar framework, the routine's object needs to implement the RoutineHandler interface, which includes these methods:

Update() (bool, error)
String() string
Error() string
Name() string

It is suggested that this object be created by New(), which will also initialize any members of the object (if needed).

The sample code below creates a new statusbar, adds some routines to it, and begins displaying the formatted output. In dwm, we are using the dualstatus patch, which creates a top and bottom bar for extra statusbar real estate. The top bar will display the time, and the bottom bar will display the disk usage and CPU stats.

import (
	"github.com/snhilde/statusbar"
	"github.com/snhilde/statusbar/sbtime"
	"github.com/snhilde/statusbar/sbdisk"
	"github.com/snhilde/statusbar/sbcpuusage"
	"github.com/snhilde/statusbar/sbcputemp"
)

func main() {
	// Create the initial engine.
	bar := statusbar.New()

	// sbtime.New() takes two arguments: time format and a triplet of color codes for normal, warning, and error
	// outputs. It returns a new routine that implements the RoutineHandler interface.
	// bar.Append() takes two arguments: the new routine object and the update interval (how often in seconds the
	// routine should run its Update() method).
	bar.Append(sbtime.New("Jan 2 - 03:04", [3]string{"#FFFFFF", "#BB4F2E", "#A1273E"}), 1)

	// This inserts the splitting character for the dualstatus patch. Before this is called, the routines already
	// added are displayed on the top bar. After this is called, all subsequently added routines are displayed on
	// the bottom bar.
	bar.Split()

	// The second bar will start with the output from the disk routine. It will display the space used
	// and total space of the given filesystem. The routine will update every 5 seconds.
	bar.Append(sbdisk.New([]string{"/"}, [3]string{"#FFFFFF", "#BB4F2E", "#A1273E"}), 5)

	// The next two routines will display (separately) the current percentage of CPU used and the
	// temperature of the CPU, each updated every second.
	bar.Append(sbcpuusage.New([3]string{"#FFFFFF", "#BB4F2E", "#A1273E"}), 1)
	bar.Append(sbcputemp.New([3]string{"#8FFFFF", "#BB4F2E", "#A1273E"}), 1)

	// The statusbar will now run indefinitely, updating every routine at the provided interval. All routines run
	// concurrently in their own thread and are independent of each other.
	bar.Run()
}

Package statusbar formats and displays information on the dwm statusbar by managing modular data routines.

Index

• type RoutineHandler
• type Statusbar
  • func New() Statusbar
  • func (sb *Statusbar) Append(handler RoutineHandler, seconds int)
  • func (sb *Statusbar) EnableRESTAPI(port int)
  • func (sb *Statusbar) Run()
  • func (sb *Statusbar) SetMarkers(left string, right string)
  • func (sb *Statusbar) Split()
  • func (sb *Statusbar) Stop()
  • func (sb *Statusbar) Uptime() int

Examples

• Statusbar.Append

Types

type RoutineHandler

type RoutineHandler interface {
	// Update updates the routine's information. This is run on a periodic interval according to the time provided when
	// adding the routine to the statusbar engine. It returns two arguments: a bool and an error. The bool indicates
	// whether or not the engine should continue to run the routine. You can think of it as representing the "ok"
	// status. The error is any error encountered during the process. For example, on a normal run with no error, Update
	// would return (true, nil). On a run with a non-critical error, Update would return (true, error). On a run with a
	// critical error where the routine should be stopped, Update would return (false, error). The returned error will
	// be logged to stderr. Generally, the error returned from Update should be detailed and specific for debugging the
	// routine, while the error returned from Error should be shorter, more concise, and more general.
	Update() (bool, error)

	// String formats and returns the routine's output.
	String() string

	// Error formats and returns an error message. Generally, the error returned from Error should be shorter, more
	// concise, and more general, while the error returned from Update should be detailed and specific for debugging the
	// routine.
	Error() string

	// Name returns the display name of the module.
	Name() string
}

RoutineHandler allows information monitors (commonly called routines) to be linked in.

type Statusbar

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

Statusbar is the main type for this package. It holds information about the bar as a whole.

func New

func New() Statusbar

New creates a new statusbar. The default delimiters around each routine are square brackets ('[' and ']').

func (*Statusbar) Append

func (sb *Statusbar) Append(handler RoutineHandler, seconds int)

Append adds a routine to the statusbar's list. Routines are displayed in the order they are added. handler is the RoutineHandler module. seconds is the amount of time between each run of the routine.

Example

// Add the sbtime routine to our statusbar.

// sbtime.New() takes two arguments: the format to use for the time string and a triplet of color codes.
timeFmt := "Jan 2 - 03:04"

colorNormal := "#FFFFFF"
colorWarning := "#BB4F2E"
colorError := "#A1273E"
colors := [3]string{colorNormal, colorWarning, colorError}

// Create a new routine.
timeRoutine := sbtime.New(timeFmt, colors)

// Append the routine to the bar.
bar.Append(timeRoutine, 1)

// Or, as a one-liner:
bar.Append(sbtime.New("Jan 2 - 03:04", [3]string{"#FFFFFF", "#BB4F2E", "#A1273E"}), 1)

func (*Statusbar) EnableRESTAPI

func (sb *Statusbar) EnableRESTAPI(port int)

EnableRESTAPI enables the engine to run the REST API on port port. These can be used to interact with the statusbar and its routines while they are running.

func (*Statusbar) Run

func (sb *Statusbar) Run()

Run spins up all the routines and displays them on the statusbar. If the APIs are enabled, this also runs the API engines.

func (*Statusbar) SetMarkers

func (sb *Statusbar) SetMarkers(left string, right string)

SetMarkers sets the left and right delimiters around each routine. If not set, these will default to '[' and ']'.

func (*Statusbar) Split

func (sb *Statusbar) Split()

Split splits the statusbar at this point, when using dualstatus patch for dwm. A semicolon (';') is inserted at this point in the routine list, which signals to dualstatus to split the statusbar at this point. Before this is called, the routines already added are displayed on the top bar. After this is called, all subsequently added routines are displayed on the bottom bar.

func (*Statusbar) Stop

func (sb *Statusbar) Stop()

Stop stops a running Statusbar.

func (*Statusbar) Uptime

func (sb *Statusbar) Uptime() int

Uptime returns the time in seconds denoting how long the statusbar has been running.