Categorygithub.com/jimeh/go-render
modulepackage
0.0.2
Repository: https://github.com/jimeh/go-render.git
Documentation: pkg.go.dev
Overview
Versions
1
Dependencies
8
Dependents
1
Files
420 SLOC

# README

go-render

A simple and flexible solution to render a value to a io.Writer using different formats based on a format string argument.

GitHub tag (latest SemVer) Go Reference GitHub issues GitHub pull requests Coverage License Status

Designed around using a custom type/struct to render your output. Thanks to Go's marshaling interfaces, you get JSON, YAML, and XML support almost for free. While plain text output is supported by the type implementing io.Reader, io.WriterTo, fmt.Stringer, and error interfaces, or by simply being a type which can easily be type cast to a byte slice.

Originally intended to easily implement CLI tools which can output their data as plain text, as well as JSON/YAML with a simple switch of a format string. But it can just as easily render to any io.Writer.

The package is designed to be flexible and extensible with a sensible set of defaults accessible via package level functions. You can create your own Renderer for custom formats, or create new handlers that support custom formats.

Import

import "github.com/jimeh/go-render"

Usage

Basic usage to render a value to various formats into a io.Writer:

version := &Version{Version: "1.2.1", Stable: true, Latest: false}

err = render.Pretty(w, "text", version)
// 1.2.1 (stable: true, latest: false)

err = render.Pretty(w, "json", version)
// {
//   "version": "1.2.1",
//   "latest": false,
//   "stable": true
// }

err = render.Compact(w, "json", version)
// {"version":"1.2.1","latest":false,"stable":true}

err = render.Pretty(w, "yaml", version)
// version: 1.2.1
// latest: false
// stable: true

err = render.Pretty(w, "xml", version)
// <version latest="false" stable="true">1.2.1</version>

The above assumes the following Version struct:

type Version struct {
    Version string `json:"version" yaml:"version" xml:",chardata"`
    Latest  bool   `json:"latest" yaml:"latest" xml:"latest,attr"`
    Stable  bool   `json:"stable" yaml:"stable" xml:"stable,attr"`
}

func (v *Version) String() string {
    return fmt.Sprintf(
        "%s (stable: %t, latest: %t)", v.Version, v.Stable, v.Latest,
    )
}

Documentation

Please see the Go Reference for documentation and further examples.

License

MIT

# Functions

Compact is a convenience function that calls the Default renderer's Compact method.
New returns a new Renderer that delegates rendering to the specified Handlers.
NewWith creates a new Renderer with the given formats.
Pretty is a convenience function that calls the Default renderer's Pretty method.
Render renders the given value to the given writer using the given format.

# Variables

Base is a renderer that supports all formats.
Default is the default renderer that is used by package level Render, Compact, Pretty functions.
Err is the base error for the package.
ErrCannotRender is returned when a value cannot be rendered.
No description provided by the author
ErrUnsupportedFormat is returned when a format is not supported by any Handler.
JSONDefualtIndent is the default indentation string used by JSON instances when pretty rendering if no Indent value is set on the JSON instance itself.
XMLDefualtIndent is the default indentation string used by XML instances when pretty rendering if no Indent value is set.
No description provided by the author

# Structs

Binary can render values which implment the encoding.BinaryMarshaler interface.
JSON is a Handler that marshals values to JSON.
Multi is a Handler that tries multiple handlers until one succeeds.
Renderer exposes methods for rendering values to different formats.
Text
Text is a Handler that writes the given value to the writer as text, supporting multiple types and interfaces.
XML is a Renderer that marshals a value to XML.
YAML is a Handler that marshals the given value to YAML.

# Interfaces

FormatsHandler is an optional interface that can be implemented by Handler implementations to return a list of formats that the handler supports.
Handler interface is for single format renderers, which can only render a single format.
PrettyHandler interface is a optional interface that can be implemented by Handler implementations to render a value in a pretty way.