coco

README

coco

coco is a colorized-intended library to provide an easy way to display logs on cli-based applications.

Its purpose is to be flexible and easy to configure. In simple words: get what you set.

Accompanied by the fantastic library color, coco is aimed at identifying each log level by a color you can define (or use our default proposal)

[INFO]: Install

go get github.com/synerops/coco

[INFO]: Examples

Getting Started

Without any extra customization, you can configure the library as follows.

// default options pre-defined in the package
opts := coco.Default()

// new instance of the library
ui := coco.New(opts)

// use with one of the levels already defined, 
// in this case: SUCCESS
ui.Success("this is a successful message")

// other served methods are:
ui.Error(errors.New("this is a sample error message"))

ui.Warning("this is a sample warning message")

ui.Info("this is a sample informative message")

Default Options

This is the configuration defined behind coco.Default()

Levels

• error, displayed in the terminal using os.Stderr
• success, displayed in the terminal using os.Stdout
• warning, displayed in the terminal using os.Stdout
• info, hidden by default using io.Discard, this setting can be changed

Colors

• error: color.FgRed
• success: color.FgGreen
• warning: color.FgYellow
• info: color.FgHiCyan

Customization

Change the printable format

// tl;dr
opts.SetFormat(coco.Error, "[%s] -> %s\n")

By default, the format to display each level is: [%s]: %s\n (that's why the level legend is involved in squared brackets). You can change that per level using opts.SetFormat.

// default options pre-defined in the package
opts = coco.Default()

// change the format only on the `error` level
opts.SetFormat(coco.Error, "[%s] -> %s\n")

Change the output writer (a.k.a io.Writer)

// tl;dr
opts.SetWriter(coco.Info, os.Stdout)

You can change the output of the message and use your own Writer (based on the io.Writer interface).

A good example of this method is to use accompanied with a flag to determine whether the application is under debug mode.

// check whether the DEBUG env var is defined and change the output of the INFO level messages
if debugMode := os.Getenv("DEBUG"); debugMode != "" {
    opts.SetWriter(coco.Info, os.Stdout)
}

Change the color (a.k.a color.Attribute)

// tl;dr
opts.SetColor(coco.Warning, color.FgHiYellow)

You can change the color of the level legends to satisfy your particular needs, just make sure to provide an attribute based on the color.Attribute constant.

opts.SetColor(coco.Warning, color.BgHiRed)

New levels

Coco aims to fit your needs, so you can create custom Levels and make them part of the app.

// default options pre-defined in the package
opts := coco.Default()

// define a new level called NOTICE
const levelName = "notice"

// use coco's Output struct to define the structure of the new level
noticeOutput := coco.Output{
    Format: coco.GlobalFormat,
    Writer: os.Stdout,
    Color:  color.FgHiMagenta,
}

if err := opts.NewLevel(levelName, noticeOutput); err != nil {
    fmt.Printf("error while defining a new level: %s\n", err)
}

// new instance of the library
ui := coco.New(opts)

// use with one of the level you just created 
ui.Log(levelName, "this is a sample notice message")

[INFO]: License

The MIT License (MIT) - see LICENSE for more details

[INFO]: Contribute

Feel free to contribute to any aspect of the project. Any initiative will be highly appreciated.

[INFO]: TO-DO

• Improve documentation
• Export the package to Go Packages
• Create a method to change the GlobalFormat and apply it across the levels

[INFO]: Sponsor

coco is sponsored by my tech startup SynerOps where I'm the founder and solo-developer. Feel free to reach me out.

Documentation

Overview

Package coco is a combination of utilities that make it easy to print logs in a readable way for those applications that use the command line. Its goal is to be simple and easy to understand, without extra complexities, in simple words, you get what you set

Index

• Constants
• Variables
• type Level
  • func (l Level) String() string
• type Log
  • func New(opts *Option) *Log
  • func (l *Log) Error(err error)
  • func (l *Log) Info(msg string)
  • func (l *Log) Log(lev Level, msg string)
  • func (l *Log) Success(msg string)
  • func (l *Log) Warning(msg string)
• type Option
  • func Default() *Option
  • func (o *Option) NewLevel(name Level, output Output) error
  • func (o *Option) SetColor(l Level, c color.Attribute)
  • func (o *Option) SetFormat(l Level, f string)
  • func (o *Option) SetWriter(l Level, w io.Writer)
• type Output

Constants

const GlobalFormat = "[%s]: %s\n"

GlobalFormat used by all the levels and indicates how to display the level and its corresponding message

[SUCCESS]: This is an example of a success message following the GlobalFormat

Variables

var ErrLevelAlreadyDefined = errors.New("the level name indicated is in use, please choose another one")

ErrLevelAlreadyDefined is an error message displayed when the user wants to create a new Level but the name selected already exists in the map

Types

type Level

type Level string

Level is a custom type created and exposed with the purpose to bring the user a clear way to create their own levels

const (
	// Error commonly used to display messages that cannot be addressed by the application
	Error Level = "error"

	// Success commonly used to inform the user that the process has been finalized successfully
	Success Level = "success"

	// Warning commonly used to inform the user about an error but the application can continue regardless
	Warning Level = "warning"

	// Info commonly used for debugging purposes and hidden to the final user
	Info Level = "info"
)

func (Level) String

func (l Level) String() string

String converts the custom type Level to its real type

type Log

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

Log structs encapsulates the list of levels defined by default and new ones that might be created by the user

func New

func New(opts *Option) *Log

New returns a newly created log object

func (*Log) Error

func (l *Log) Error(err error)

Error is an alias to the main Log function, which gives the user a quick way to use this Level

func (*Log) Info

func (l *Log) Info(msg string)

Info is an alias to the main Log function, which gives the user a quick way to use this Level

func (*Log) Log

func (l *Log) Log(lev Level, msg string)

Log is the function that combines the settings defined in Options and the levels defined in Level in order to use a variety of alternatives for the particular uses of any application

func (*Log) Success

func (l *Log) Success(msg string)

Success is an alias to the main Log function, which gives the user a quick way to use this Level

func (*Log) Warning

func (l *Log) Warning(msg string)

Warning is an alias to the main Log function, which gives the user a quick way to use this Level

type Option

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

Option is a public struct that brings the user the possibility to modify default configurations on each level. In addition, Option brings the possibility to create new levels

func Default

func Default() *Option

Default is the proposal created by Coco to configure the default levels, based on regular considerations but open to any change the user wants to make

func (*Option) NewLevel

func (o *Option) NewLevel(name Level, output Output) error

NewLevel brings the user the possibility to create custom Levels

func (*Option) SetColor

func (o *Option) SetColor(l Level, c color.Attribute)

SetColor brings the user the possibility to change the color (color.Attribute) of a specific Level

func (*Option) SetFormat

func (o *Option) SetFormat(l Level, f string)

SetFormat brings the user the possibility to change the GlobalFormat of a specific Level

func (*Option) SetWriter

func (o *Option) SetWriter(l Level, w io.Writer)

SetWriter brings the user the possibility to change the default Writer (io.Writer) of a specific Level

type Output

type Output struct {
	Format string
	Writer io.Writer
	Color  color.Attribute
}

Output is the exported struct that brings the user the possibility to manipulate existing or custom Level