pio

package module
Version: v0.0.10 Latest Latest
Warning

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

Go to latest
Published: Aug 14, 2020 License: BSD-3-Clause Imports: 15 Imported by: 15

README

💊 PIO

PIO [Pill for Input/Output] tries to cure headaches by solving problems where go applications use different kinds of print targets or even loggers.

build status report card godocs github issues github closed issues

  • it can combine all your loggers as one
  • it can scan from any source and print
  • opossite is possible too, it use one or more sources to output when printing

Navigate through _examples and integrations to learn if can cure yours too.

🚀 Installation

The only requirement is the Go Programming Language*.

$ go get github.com/kataras/pio

PIO is built on top of the standard library, it has zero external dependencies.

👥 Contributing

If you find that something is not working as expected please open an issue.

If you have any previous experience on this field your PR means gold to me!

📦 Projects using PIO
Package Author Description
golog Gerasimos Maropoulos Simple, fast and easy-to-use level-based logger written entirely in GoLang.

Do not hesitate to put your package on this list via PR!

Documentation

Index

Examples

Constants

View Source
const (
	Black = 30 + iota
	Red
	Green
	Yellow
	Blue
	Magenta
	Cyan
	White
	Gray = White

	ColorReset = 0
)

Standard color codes, any color code can be passed to `Rich` package-level function, when the destination terminal supports.

View Source
const Version = "0.0.10"

Version is the current PIO version.

Variables

View Source
var (
	// ErrCanceled is returned when a hijacker canceled a specific print action.
	ErrCanceled = errors.New("canceled")
	// ErrSkipped it returned from marshaler or hijacker
	// when the content should be skipped and printer should avoid printing it.
	ErrSkipped = errors.New("skipped")
	// ErrHandled can be returned from a hijacker to specify
	// that the hijacker handled the write operation itself,
	// therefore pio does not need to do anything else.
	ErrHandled = errors.New("handled")
)
View Source
var (
	// JSON returns the JSON encoding of Printer#Print%v.
	// A shortcut for `encoding/json#Marshal`
	JSON = MarshalerFunc(json.Marshal)
	// JSONIndent returns the JSON encoding of Printer#Print%v.
	// A shortcut for `encoding/json#MarshalIndent(v, ""," ")`
	JSONIndent = MarshalerFunc(func(v interface{}) ([]byte, error) {
		return json.MarshalIndent(v, "", " ")
	})

	// XML returns the XML encoding of Printer#Print%v.
	// A shortcut for `encoding/xml#Marshal`
	XML = MarshalerFunc(xml.Marshal)
	// XMLIndent returns the XML encoding of Printer#Print%v.
	// A shortcut for `encoding/xml#MarshalIndent(v, ""," ")`
	XMLIndent = MarshalerFunc(func(v interface{}) ([]byte, error) {
		return xml.MarshalIndent(v, "", " ")
	})
)
View Source
var Default = NewRegistry()

Default returns the default, package-level registry instance.

View Source
var ErrMarshalNotFound = errors.New("no marshaler found for this type of dat")

ErrMarshalNotFound or ErrSkipped can be used to skip a specific printer's output operation.

View Source
var ErrMarshalNotResponsible = errors.New("this marshaler is not responsible for this type of data")

ErrMarshalNotResponsible retruns from a marshaler when it's not responsible and should continue to the next marshaler.

View Source
var NewLine = []byte("\n")

NewLine is a slice of bytes which controls the how a new line should be presented.

Defaults to \n.

View Source
var OutputFrom = OutputAdapters{}

OutputFrom is a variable which contains some helpers that can convert some forms of output to compatible `io.Writer` in order to be passed to the `NewPrinter` or `Register` functions.

View Source
var Text = MarshalerFunc(func(v interface{}) ([]byte, error) {
	if b, ok := v.([]byte); ok {
		return b, nil
	}
	if s, ok := v.(string); ok {
		return []byte(s), nil
	}

	return nil, ErrMarshalNotResponsible
})

Text is a Text marshaler, it converts string to a compatible form of []byte.

View Source
var (
	// TotalPrinters holds the number of
	// the total printers created, either by
	// `NewPrinter`, `NewTextPrinter`, `Register` or `RegisterPrinter`
	TotalPrinters int32
)

Functions

func Background added in v0.0.3

func Background(s *string, colorCode *int, format *string)

Background marks the color to background. See `Reversed` too.

func Bold added in v0.0.3

func Bold(s *string, colorCode *int, format *string)

Bold adds a "bold" decoration to the colorful text. See `Underline` and `Reversed` too.

func Bright added in v0.0.3

func Bright(s *string, colorCode *int, format *string)

Bright sets a "bright" or "bold" style to the colorful text.

func IsNop

func IsNop(w io.Writer) bool

IsNop can check wether an `w` io.Writer is a NopOutput.

func NopCloser

func NopCloser() io.Closer

NopCloser returns an `io.Closer` which does nothing.

func NopOutput

func NopOutput() io.Writer

NopOutput returns an `io.Writer` which writes nothing.

func Print

func Print(v interface{}) (int, error)

Print accepts a value of "v", tries to marshal its contents and flushes the result to all available printers.

func Println

func Println(v interface{}) (int, error)

Println accepts a value of "v", tries to marshal its contents and flushes the result to all available printers, it adds a new line at the ending, the result doesn't contain this new line, therefore result's contnets kept as expected.

func Remove

func Remove(printerName string)

Remove deletes a printer item from the printers collection by its name.

func Reversed added in v0.0.3

func Reversed(s *string, colorCode *int, format *string)

Reversed adds a "reversed" decoration to the colorful text. This means that the background will be the foreground and the foreground will be the background color.

See `Bold` and `Underline` too.

func Rich added in v0.0.3

func Rich(s string, colorCode int, options ...RichOption) string

Rich accepts "s" text and a "colorCode" (e.g. `Black`, `Green`, `Magenta`, `Cyan`...) and optional formatters and returns a colorized (and decorated) string text that it's ready to be printed through a compatible terminal.

Look: - Bright - Background - Bold - Underline - Reversed

Example
fmt.Println(Rich("black", Black))
fmt.Println(Rich("cyan", Cyan))

fmt.Println(Rich("background cyan",
	Cyan,
	Background,
))

fmt.Println(Rich("bright yellow",
	Yellow,
	Bright,
))

fmt.Println(Rich("bright bold magenta",
	Magenta,
	Bright,
	Bold,
))

fmt.Println(Rich("bold cyan",
	Cyan,
	Bold,
))

fmt.Println(Rich("bold underline reversed bright cyan",
	Cyan,
	Bright,
	Bold,
	Underline,
	Reversed,
))

fmt.Println(Rich("extended 256-color custom color: 153 (blue-ish)", 153))
fmt.Println(Rich("extended 256-color custom bright reversed color: 153 (blue-ish)", 153,
	Bright,
	Reversed,
))
Output:

�[30mblack�[0m
�[36mcyan�[0m
�[46mbackground cyan�[0m
�[33;1mbright yellow�[0m
�[35;1m�[1mbright bold magenta�[0m
�[36m�[1mbold cyan�[0m
�[36;1m�[7m�[4m�[1mbold underline reversed bright cyan�[0m
�[38;5;153mextended 256-color custom color: 153 (blue-ish)�[0m
�[38;5;153;1m�[7mextended 256-color custom bright reversed color: 153 (blue-ish)�[0m

func Scan

func Scan(r io.Reader, addNewLine bool) (cancel func())

Scan scans everything from "r" and prints its new contents to the printers, forever or until the returning "cancel" is fired, once.

func SupportColors added in v0.0.4

func SupportColors(w io.Writer) bool

SupportColors reports whether the "w" io.Writer is not a file and it does support colors.

func Underline added in v0.0.3

func Underline(s *string, colorCode *int, format *string)

Underline adds an "underline" decoration to the colorful text. See `Bold` and `Reversed` too.

func Wrap

func Wrap(printFn interface{}) io.Writer

Wrap returns a new output based on the "printfFn" if not a compatible output found then it will return a writer which writes nothing.

To check if the wrapping worked you can check if the result `io.Writer` `IsNop`, i.e: std's log.Panicf is not a compatible interface

output := Output(log.Panicf) if IsNop(output) {

// conversation failed, do something or panic.

}

func WriteRich added in v0.0.5

func WriteRich(w io.Writer, s string, colorCode int, options ...RichOption)

WriteRich same as `Rich` but it accepts an `io.Writer` to write to, e.g. a `StringBuilder` or a `pio.Printer`.

Types

type Ctx

type Ctx struct {
	// Printer is the current Printer which this ctx is owned by.
	Printer *Printer
	// Value is the argument passed to the `Printer#Print`.
	//
	// Value shoult not be changed.
	Value interface{}
	// contains filtered or unexported fields
}

Ctx is the current context of the Printer's hijacker, should not be used inside goroutines, exiting this hijacker allows the Printer to continue its execution.

func (*Ctx) Cancel

func (ctx *Ctx) Cancel()

Cancel cancels the printing of this `Value`.

func (*Ctx) MarshalValue

func (ctx *Ctx) MarshalValue() ([]byte, error)

MarshalValue marshals the `Value` and skips the marshal operation on the `Printer#Print` state.

Remember that if `MarshalValue` called after a `SetResult` then it will not operate a marshaling and return the stored result instead.

func (*Ctx) Next

func (ctx *Ctx) Next()

Next allows to continue to the next hijacker,if available, when this hijacker finished.

func (*Ctx) Store

func (ctx *Ctx) Store(result []byte, err error)

Store bypasses the marshaler and sets the result explicitly. If any of the next hijackers try to call the `MarshalValue` then it will return the results that had set here.

type Handler

type Handler func(PrintResult)

Handler is the signature implemented by callers that want to be notified about the results that are being printed to the Printer's output.

Look `Printer#Handle` for more.

type Hijacker

type Hijacker func(*Ctx)

Hijacker is the signature implemented by callers that want to hijack the Print method.

Look `Printer#Hijack` for more.

type Marshaled

type Marshaled interface {
	Marshal() ([]byte, error)
}

Marshaled or (especially British, marshalled) is an interface which is implemented by values that can marshal theirselves.

It's like Marshaler but it doesn't takes an argument.

type Marshaler

type Marshaler interface {
	Marshal(v interface{}) ([]byte, error)
}

Marshaler is the interface implemented by types that can marshal themselves into valid output.

type MarshalerFunc

type MarshalerFunc func(v interface{}) ([]byte, error)

MarshalerFunc is the signature implemented by callers that are responsible to marshal "v" into valid printable result.

Look `Printer#Marshal` for more.

func (MarshalerFunc) Marshal

func (m MarshalerFunc) Marshal(v interface{}) ([]byte, error)

Marshal makes the Marshaler compatible with the standard golang's marshalers, so a marshaler created for a Printer, can be used on std packages as well.

type OutputAdapters

type OutputAdapters struct{}

OutputAdapters is a struct which contains some forms of output and convert them to a compatible `io.Writer` in order to be passed to the `NewPrinter` or `Register` functions.

func (*OutputAdapters) Print

func (a *OutputAdapters) Print(print func(v interface{})) io.Writer

Print converts a func(v interface{}) to a compatible `io.Writer`.

func (*OutputAdapters) PrintVardiadic

func (a *OutputAdapters) PrintVardiadic(print func(v ...interface{})) io.Writer

PrintVardiadic converts a func(v ...interface{}) to a compatible `io.Writer`.

func (*OutputAdapters) Printf

func (a *OutputAdapters) Printf(printf func(format string, args ...interface{})) io.Writer

Printf converts a func(string, ...interface{}) to a compatible `io.Writer`.

func (*OutputAdapters) Println

func (a *OutputAdapters) Println(println func(s string), newLine bool) io.Writer

Println converts a func(string) to a compatible `io.Writer`. if "newLine" is true then "\n" will be appended to the "s".

type PrintResult

type PrintResult struct {
	Written  int
	Error    error
	Contents []byte
	Value    interface{}
}

PrintResult contains some useful information for a `Print` or `WriteTo` action that are available inside handlers.

func (PrintResult) IsFailure

func (p PrintResult) IsFailure() bool

IsFailure returns true if result's content is not safe to read or it's available, otherwise false.

func (PrintResult) IsOK

func (p PrintResult) IsOK() bool

IsOK returns true if result's content is available, otherwise false.

type Printer

type Printer struct {
	Name       string
	IsTerminal bool

	// if Chained is true then the parent `Registry#Print`
	// will continue to search for a compatible printer
	// even if this printer succeed to print the contents.
	Chained bool
	Output  io.Writer

	// These three will complete the interface of the:
	// https://golang.org/pkg/io/#ReadWriteCloser
	// in order to make possible to use everything inside the `io` package.
	// i.e
	// https://golang.org/pkg/io/#example_MultiWriter
	// https://golang.org/pkg/io/#example_TeeReader (piping)
	io.Reader
	io.Writer
	io.Closer
	// DirectOutput will output the contents and flush them as fast as possible,
	// without storing them to the buffer to complete the `ReadWriteCloser` std interface.
	// Enable this if you need performance and you don't use the standard functions like `TeeReader`.
	DirectOutput bool
	// contains filtered or unexported fields
}

Printer is responsible to print the end result.

func Get

func Get(printerName string) *Printer

Get returns a Printer based on the "printerName". If printer with this name can't be found then this function will return nil, so a check for nil is always a good practice.

func NewPrinter

func NewPrinter(name string, output io.Writer) *Printer

NewPrinter returns a new named printer if "output" is nil then it doesn't prints anywhere.

If "name" is empty then it will be filled with "printer_$printers.len".

If the marshaler is nil, meaning that this writer's result will never being proceed, caller should add a marshaler using the `Marshal` function.

Look `OutputFrom` too.

func NewTextPrinter

func NewTextPrinter(name string, output io.Writer) *Printer

NewTextPrinter same as NewPrinter but registers a text marshaler, no matter what kind of "output", which converts string type to a compatible form of slice of bytes.

If "name" is empty then it will be filled with "printer_$printers.len".

Look `OutputFrom` too.

func Register

func Register(printerName string, output io.Writer) *Printer

Register creates and registers a new Printer based on a name(string) and an "output"(io.Writer).

If a printer with the same `Name` is already registered then it will be overridden by this new "printer".

Look `OutputFrom` too.

Returns the just created Printer.

func (*Printer) AddOutput

func (p *Printer) AddOutput(writers ...io.Writer) *Printer

AddOutput adds one or more io.Writer to the Printer. Returns itself.

Look `OutputFrom` and `Wrap` too.

func (*Printer) EnableDirectOutput

func (p *Printer) EnableDirectOutput() *Printer

EnableDirectOutput will output the contents and flush them as fast as possible, without storing them to the buffer to complete the `ReadWriteCloser` std interface. Enable this if you need performance and you don't use the standard functions like `TeeReader`. Returns itself.

func (*Printer) Flush

func (p *Printer) Flush() ([]byte, error)

Flush will consume and flush the Printer's current contents.

func (*Printer) Handle

func (p *Printer) Handle(h func(PrintResult)) *Printer

Handle adds a callback which is called whenever a `Print` is successfully executed, it's being executed after the contents are written to its output.

The callback accepts the final result, can be used as an easy, pluggable, access to all the logs passed to the `Print`. i.e: `Handle(func(result PrintResult){ fmt.Printf("%s\n", result.Contents)})`

Returns itself.

func (*Printer) Hijack

func (p *Printer) Hijack(cb func(ctx *Ctx)) *Printer

Hijack registers a callback which is executed when ever `Print` or `WriteTo` is called, this callback can intercept the final result which will be written or be printed.

Returns itself.

func (*Printer) Marshal

func (p *Printer) Marshal(marshaler Marshaler) *Printer

Marshal adds a "marshaler" to the printer. Returns itself.

func (*Printer) MarshalFunc

func (p *Printer) MarshalFunc(marshaler func(v interface{}) ([]byte, error)) *Printer

MarshalFunc adds a "marshaler" to the printer. Returns itself.

func (*Printer) Print

func (p *Printer) Print(v interface{}) (int, error)

Print of a Printer accepts a value of "v", tries to marshal its contents and flushes the result to the Printer's output.

If "v" implements the `Marshaler` type, then this marshaler is called automatically, first.

Print -> Store[Marshal -> err != nil && result -> Hijack(result) -> Write(result)] -> Flush[Printer.Write(buf) and Handle(buf)]

Returns how much written and an error on failure.

func (*Printer) Println

func (p *Printer) Println(v interface{}) (int, error)

Println accepts a value of "v", tries to marshal its contents and flushes the result to this "p" Printer, it adds a new line at the ending, the result doesn't contain this new line, therefore result's contents kept as expected.

func (*Printer) Priority

func (p *Printer) Priority(prio int) *Printer

Priority changes the order of this printer. Higher value means that the `Registry#Print` will try to print first from this printer. Default order is 0 for all printers.

Returns it self.

func (*Printer) Scan

func (p *Printer) Scan(r io.Reader, addNewLine bool) (cancel func())

Scan scans everything from "r" and prints its new contents to the "p" Printer, forever or until the returning "cancel" is fired, once.

func (*Printer) SetOutput

func (p *Printer) SetOutput(writers ...io.Writer) *Printer

SetOutput sets accepts one or more io.Writer and set a multi-writter instance to the Printer's Output. Returns itself.

Look `OutputFrom` too.

func (*Printer) SetSync added in v0.0.7

func (p *Printer) SetSync(useLocks bool) *Printer

SetSync protects the output writer(s) with a lock.

func (*Printer) Store

func (p *Printer) Store(v interface{}, appendNewLine bool) error

Store will store-only the contents of "v". Returns a PrintResult type in order to the final contents be accessible by third-party tools.

If you want to Print and Flush to the Printer's Output use `Print` instead.

If "appendNewLine" is true then it writes a new line to the Printer's output. Note that it doesn't concat it to the returning PrintResult, therefore the "appendNewLine" it is not affect the rest of the implementation like custom hijackers and handlers.

func (*Printer) WithMarshalers

func (p *Printer) WithMarshalers(marshalers ...Marshaler) *Printer

WithMarshalers same as `Marshal` but accepts more than one marshalers and returns the Printer itself in order to be used side by side with the creational function.

func (*Printer) Write added in v0.0.5

func (p *Printer) Write(b []byte) (n int, err error)

Write implements the io.Writer for the `Printer`.

func (*Printer) WriteTo

func (p *Printer) WriteTo(v interface{}, w io.Writer, appendNewLine bool) ([]byte, error)

WriteTo marshals and writes the "v" to the "w" writer.

Returns this WriteTo's result information such as error, written.

type Registry

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

Registry is the Printer(s) container.

It can be used as follows: reg := NewRegistry().

RegisterPrinter(NewPrinter("err", os.Stderr)).
RegisterPrinter(NewPrinter("default", os.Stdout)).
Print("something")

func NewRegistry

func NewRegistry() *Registry

NewRegistry returns an empty printer Registry.

Note that: Registry have a zero value, so it can be declared with a simple `var` keyword and without pointer.

func RegisterPrinter

func RegisterPrinter(p *Printer) *Registry

RegisterPrinter registers an already-created printer to the registry.

If a printer with the same `Name` is already registered then it will be overridden by this new "printer".

Returns the Registry, therefore it can be used as builder.

func (*Registry) Get

func (reg *Registry) Get(printerName string) *Printer

Get returns a Printer based on the "printerName". If printer with this name can't be found then this function will return nil, so a check for nil is always a good practice.

func (*Registry) Print

func (reg *Registry) Print(v interface{}) (n int, err error)

Print accepts a value of "v", tries to marshal its contents and flushes the result to all available printers.

func (*Registry) Println

func (reg *Registry) Println(v interface{}) (n int, err error)

Println accepts a value of "v", tries to marshal its contents and flushes the result to all available printers, it adds a new line at the ending, the result doesn't contain this new line, therefore result's contents kept as expected.

func (*Registry) Register

func (reg *Registry) Register(printerName string, output io.Writer) *Printer

Register creates and registers a new Printer based on a name(string) and an "output"(io.Writer).

If "printerName" is empty then it will be filled with "printer_$printers.len".

If a printer with the same `Printer#Name` is already registered then it will be overridden by this new "printer".

Look `OutputFrom` too.

Returns the just created Printer.

func (*Registry) RegisterPrinter

func (reg *Registry) RegisterPrinter(printer *Printer) *Registry

RegisterPrinter registers an already-created printer to the registry.

If `Printer#Name` is empty then it will be filled with "printer_$printers.len".

If a printer with the same `Printer#Name` is already registered then it will be overridden by this new "printer".

Returns this Registry, therefore it can be used as builder.

func (*Registry) Remove

func (reg *Registry) Remove(printerName string) *Registry

Remove deletes a printer item from the printers collection by its name.

Returns this Registry, so it can be used as builder.

func (*Registry) Scan

func (reg *Registry) Scan(r io.Reader, addNewLine bool) (cancel func())

Scan scans everything from "r" and prints its new contents to the printers, forever or until the returning "cancel" is fired, once.

type RichOption added in v0.0.5

type RichOption func(s *string, colorCode *int, format *string)

RichOption declares a function which can be passed to the `Rich` function to modify a text.

Builtin options are defined below: - `Bright` - `Background` - `Bold` - `Underline` and - `Reversed`.

Directories

Path Synopsis
_examples
integrations/logrus
Package logrus registers the global logrus logger to the pio ecosystem, install logrus first: $ go get github.com/ Example Code: package main import ( "github.com/kataras/pio" _ "github.com/kataras/pio/_examples/integrations/logrus" ) func main() { pio.Print("This is an info message that will be printed to the logrus' output") }
Package logrus registers the global logrus logger to the pio ecosystem, install logrus first: $ go get github.com/ Example Code: package main import ( "github.com/kataras/pio" _ "github.com/kataras/pio/_examples/integrations/logrus" ) func main() { pio.Print("This is an info message that will be printed to the logrus' output") }

Jump to

Keyboard shortcuts

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