svgxml

README

svgxml

This has grown out of my need for a way in Go to manage the structures of SVG images in a way that's more straightforward than working with encoding/xml directly and repeating code across projects. It's incredibly incomplete relative to the SVG spec but works OK for what's implemented.

As this is intended for managing the structure of an image, the focus is on finding, examining, and modifying existing elements. Adding elements can also be done easily if not simply; array management (for element ordering) and generating and setting the values of the XML attributes is left to the user. For the most part, no major abstractions are provided for creating or modifying elements.

What little documentation I have is mainly what's been generated from my code comments; see pkg.go.dev.

Documentation

Index

• Constants
• type AnchorDef
• type CircleDef
• type DefsDef
• type GroupDef
  • func (G *GroupDef) FindPathsById(id any, findFirst bool) ([]*PathDef, error)
• type NumberAttr
• type PathDef
• type RectDef
  • func NewRect[N string | NumberAttr](id, style string, x, y, width, height N) RectDef
• type SVG
  • func NewFromBytes(xmlBytes []byte) (*SVG, error)
  • func NewFromFile(filename string) (*SVG, error)
  • func (S *SVG) AddBackground(colorDef string)
  • func (S *SVG) FindGroupsById(id any, findFirst bool) ([]*GroupDef, error)
  • func (S *SVG) FindPathsById(id any, findFirst bool) ([]*PathDef, error)
  • func (S *SVG) GetViewBox() (ViewBoxDef, error)
  • func (S *SVG) GetXml() ([]byte, error)
  • func (S *SVG) GetXmlIndented(indentPrefix, indentString string) ([]byte, error)
  • func (S *SVG) SetViewBox(box ViewBoxDef)
  • func (S *SVG) WriteFile(filename string) error
• type TSpanDef
• type TextDef
• type ViewBoxDef

Constants

const (
	FindFirst = true
	FindAll   = false
)

Types

type AnchorDef

type AnchorDef struct {
	Id             string      `xml:"id,attr"`
	Download       string      `xml:"Download,attr"`
	Href           string      `xml:"href,attr"`
	HrefLang       string      `xml:"hreflang,attr"`
	ReferrerPolicy string      `xml:"referrerpolicy,attr"`
	Rel            string      `xml:"rel,attr"`
	Target         string      `xml:"target,attr"`
	Type           string      `xml:"type,attr"`
	Xform          string      `xml:"transform,attr,omitempty"`
	G              []GroupDef  `xml:"g"`
	Rect           []RectDef   `xml:"rect"`
	Circle         []CircleDef `xml:"circle"`
}

<a> SVG/XML element

type CircleDef

type CircleDef struct {
	Id     string `xml:"id,attr"`
	CX     string `xml:"cx,attr"`
	CY     string `xml:"cy,attr"`
	Radius string `xml:"r,attr"`
	Style  string `xml:"style,attr,omitempty"`
	Xform  string `xml:"transform,attr,omitempty"`
}

<circle> SVG/XML element

type DefsDef

type DefsDef struct {
	Id string `xml:"id,attr"`
}

<defs> SVG/XML element

type GroupDef

type GroupDef struct {
	G      []GroupDef  `xml:"g,omitempty"`
	Id     string      `xml:"id,attr,omitempty"`
	Xform  string      `xml:"transform,attr,omitempty"`
	Style  string      `xml:"style,attr,omitempty"`
	A      []AnchorDef `xml:"a"`
	Path   []PathDef   `xml:"path"`
	Text   []TextDef   `xml:"text"`
	Rect   []RectDef   `xml:"rect"`
	Circle []CircleDef `xml:"circle"`
}

<g> SVG/XML element

func (*GroupDef) FindPathsById

func (G *GroupDef) FindPathsById(id any, findFirst bool) ([]*PathDef, error)

FindGroupsById traverses a GroupDef object and returns a slice of PathDef with matching ids.

The supplied id may be a string or a compiled regular expression from the regexp package.

Use the FindFirst or FindAll constant as the second parameter to direct cause the method to return only the first matching element or all matching elements, respectively.

type NumberAttr

type NumberAttr interface {
	int | int32 | int64 | float32 | float64
}

type PathDef

type PathDef struct {
	Id    string `xml:"id,attr"`
	D     string `xml:"d,attr"`
	Xform string `xml:"transform,attr,omitempty"`
	Style string `xml:"style,attr,omitempty"`
	Title string `xml:"title,omitempty"`
}

<path> SVG/XML element

type RectDef

type RectDef struct {
	Id     string `xml:"id,attr"`
	X      string `xml:"x,attr"`
	Y      string `xml:"y,attr"`
	Width  string `xml:"width,attr"`
	Height string `xml:"height,attr"`
	Style  string `xml:"style,attr,omitempty"`
	Xform  string `xml:"transform,attr,omitempty"`
}

<rect> SVG/XML element

func NewRect

func NewRect[N string | NumberAttr](id, style string, x, y, width, height N) RectDef

NewRect returns a RectDef object with the supplied parameters. x, y, width, and height can all be string, int, or float.

type SVG

type SVG struct {
	Id      string      `xml:"id,attr"`
	Width   string      `xml:"width,attr"`
	Height  string      `xml:"height,attr"`
	ViewBox string      `xml:"viewBox,attr"`
	Title   string      `xml:"title,attr,omitempty"`
	Version string      `xml:"version,attr"`
	XMLNS   string      `xml:"xmlns,attr"`
	XMLName xml.Name    `xml:"svg"`
	Defs    DefsDef     `xml:"defs"`
	G       []GroupDef  `xml:"g"`
	A       []AnchorDef `xml:"a"`
	Path    []PathDef   `xml:"path"`
	Text    []TextDef   `xml:"text"`
	Rect    []RectDef   `xml:"rect"`
	Circle  []CircleDef `xml:"circle"`
}

SVG is the base struct of an SVG image. The array fields of the struct are the supported tags and will be rendered in first-to-last order (e. g., any circle defined in SVG.Circle will visually cover any other elements within its bounds).

func NewFromBytes

func NewFromBytes(xmlBytes []byte) (*SVG, error)

NewFromBytes accepts a byte slice of SVG XML data and returns an SVG object pointer or an error.

func NewFromFile

func NewFromFile(filename string) (*SVG, error)

NewFromFile accepts a filename containing SVG XML data and returns an object pointer or an error.

This method calls NewFromBytes after successfully reading from the file named in the filename parameter.

func (*SVG) AddBackground

func (S *SVG) AddBackground(colorDef string)

AddBackground takes a color definition, such as "#<hex>" or a name like "red", and creates a group containing a rect matching the image size and specified color.

The new group is prepended to the top-level G slice to ensure that it is the bottom-most visual element in the image.

func (*SVG) FindGroupsById

func (S *SVG) FindGroupsById(id any, findFirst bool) ([]*GroupDef, error)

FindGroupsById traverses a GroupDef object and returns a slice of GroupDef with matching ids.

The supplied id may be a string or a compiled regular expression from the regexp package.

Use the FindFirst or FindAll constant as the second parameter to direct cause the method to return only the first matching element or all matching elements, respectively.

func (*SVG) FindPathsById

func (S *SVG) FindPathsById(id any, findFirst bool) ([]*PathDef, error)

FindPathsById traverses an SVG object and returns a slice of PathDef with matching ids.

The supplied id may be a string or a compiled regular expression from the regexp package.

Use the FindFirst or FindAll constant as the second parameter to direct cause the method to return only the first matching element or all matching elements, respectively.

func (*SVG) GetViewBox

func (S *SVG) GetViewBox() (ViewBoxDef, error)

GetViewBox returns the value of the "viewBox" XML attribute as a ViewBoxDef struct of float64 values.

func (*SVG) GetXml

func (S *SVG) GetXml() ([]byte, error)

GetXml returns the current object as a byte slice.

func (*SVG) GetXmlIndented

func (S *SVG) GetXmlIndented(indentPrefix, indentString string) ([]byte, error)

GetXmlIndented returns the current object as a byte slice, using xml.MarshalIndent.

The indentPrefix and indentString parameters are passed directly to xml.MarshalIndent.

func (*SVG) SetViewBox

func (S *SVG) SetViewBox(box ViewBoxDef)

GetViewBox sets the image's "viewBox" XML attribute from the values in the supplied ViewBoxDef struct.

func (*SVG) WriteFile

func (S *SVG) WriteFile(filename string) error

WriteFile writes an XML representation of the current object to the supplied filename.

The method calls the SVG.GetXml method and writes the XML data to disk rather than returning a byte slice to the caller.

type TSpanDef

type TSpanDef struct {
	Id    string `xml:"id,attr"`
	X     string `xml:"x,attr"`
	Y     string `xml:"y,attr"`
	Xform string `xml:"transform,attr,omitempty"`
	Label string `xml:",chardata"`
}

<tspan> SVG/XML element

type TextDef

type TextDef struct {
	Id         string     `xml:"id,attr"`
	X          string     `xml:"x,attr"`
	Y          string     `xml:"y,attr"`
	Style      string     `xml:"style,attr,omitempty"`
	Xform      string     `xml:"transform,attr,omitempty"`
	TextLength string     `xml:",attr,omitempty"`
	Label      string     `xml:",chardata"`
	TSpan      []TSpanDef `xml:"tspan"`
}

<text> SVG/XML element

type ViewBoxDef

type ViewBoxDef struct {
	X      float64
	Y      float64
	Width  float64
	Height float64
}

"viewBox" attribute of some elements