jujusvg

README

jujusvg

A library for generating SVGs from Juju bundles and environments.

Installation

To start using jujusvg, first ensure you have a valid Go environment, then run the following:

go get github.com/juju/jujusvg/v5

Usage

Given a Juju bundle, you can convert this to an SVG programatically. This generates a simple SVG representation of a bundle or bundles that can then be included in a webpage as a visualization.

For an example of how to use this library, please see examples/generatesvg.go. You can run this example like:

go run generatesvg.go bundle.yaml > bundle.svg

The examples directory also includes three sample bundles that you can play around with, or you can use the Juju GUI to generate your own bundles.

Design-related assets

Some assets are specified based on assets provided by the design team. These assets are specified in the defs section of the generated SVG, and can thus be found in the Canvas.definition() method. These assets are, except where indicated, embedded in a go file assigned to an exported variable, so that they may be used like so:

import (
	"io"

	"github.com/juju/jujusvg/v4/assets"
)

// ...

io.WriteString(canvas.Writer, assets.AssetToWrite)

Current assets in use:

• The service block the service block has been deprecated and is now handled with SVGo
• The relation health indicator

Documentation

Overview

jujusvg generates SVG representations of various Juju artifacts, such as charm bundles or live environments.

For more information, please refer to the README file in this directory.

Index

• type Canvas
  • func NewFromBundle(ctx context.Context, b *charm.BundleData, ...) (*Canvas, error)
  • func (c *Canvas) Marshal(w io.Writer)
• type HTTPFetcher
  • func (h *HTTPFetcher) FetchIcons(ctx context.Context, b *charm.BundleData) (map[string][]byte, error)
• type IconFetcher
• type LinkFetcher
  • func (l *LinkFetcher) FetchIcons(ctx context.Context, b *charm.BundleData) (map[string][]byte, error)

Types

type Canvas

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

Canvas holds the parsed form of a bundle or model.

func NewFromBundle

func NewFromBundle(ctx context.Context, b *charm.BundleData, iconURL func(context.Context, *charm.URL) (string, error), fetcher IconFetcher) (*Canvas, error)

NewFromBundle returns a new Canvas that can be used to generate a graphical representation of the given bundle data. The iconURL function is used to generate a URL that refers to an SVG for the supplied charm URL. If fetcher is non-nil, it will be used to fetch icon contents for any icons embedded within the charm, allowing the generated bundle to be self-contained. If fetcher is nil, a default fetcher which refers to icons by their URLs as svg <image> tags will be used.

func (*Canvas) Marshal

func (c *Canvas) Marshal(w io.Writer)

Marshal renders the SVG to the given io.Writer.

type HTTPFetcher

type HTTPFetcher struct {
	// Concurrency specifies the number of GoRoutines to use when fetching
	// icons.  If it is not positive, 10 will be used.  Setting this to 1
	// makes this method nominally synchronous.
	Concurrency int

	// IconURL returns the URL from which to fetch the given entity's icon SVG.
	IconURL func(context.Context, *charm.URL) (string, error)

	// Client specifies what HTTP client to use; if it is not provided,
	// http.DefaultClient will be used.
	Client *http.Client
}

HTTPFetcher is an implementation of IconFetcher which retrieves charm icons from the web using the URL generated by IconURL on that charm. The HTTP Client used may be overridden by an instance of http.Client. The icons may optionally be fetched concurrently.

func (*HTTPFetcher) FetchIcons

func (h *HTTPFetcher) FetchIcons(ctx context.Context, b *charm.BundleData) (map[string][]byte, error)

FetchIcons retrieves icon SVGs over HTTP. If specified in the struct, icons will be fetched concurrently.

type IconFetcher

type IconFetcher interface {
	FetchIcons(context.Context, *charm.BundleData) (map[string][]byte, error)
}

An IconFetcher provides functionality for retrieving icons for the charms within a given bundle. The FetchIcons function accepts a bundle, and returns a map from charm paths to icon data.

type LinkFetcher

type LinkFetcher struct {
	// IconURL returns the URL of the entity for embedding
	IconURL func(context.Context, *charm.URL) (string, error)
}

LinkFetcher fetches icons as links so that they are included within the SVG as remote resources using SVG <image> tags.

func (*LinkFetcher) FetchIcons

func (l *LinkFetcher) FetchIcons(ctx context.Context, b *charm.BundleData) (map[string][]byte, error)

FetchIcons generates the svg image tags given an appropriate URL, generating tags only for unique icons.