[−][src]Crate svgdom

svgdom is an SVG Full 1.1 processing library, which allows you to parse, manipulate, generate and write an SVG content.

Deprecation

This library was an attempt to create a generic SVG DOM which can be used by various applications. But it the end it turned out that it's easier to use roxmltree + svgtypes to extract only the data you need.

There are two main problems with svgdom:

You can't make a nice API with a Vec-based tree and you can't have a safe API with an Rc-tree.

The current implementation uses so-called Rc-tree, which provides a nice API, but all the checks are done in the runtime, so you can get a panic quite easily. It's also hard/verbose to make immutable nodes. You essentially need two types of nodes: one for immutable and one for mutable "references". A Vec-based tree would not have such problems, but you can't implement the simplest operations with it, like copying an attribute from one node to another since you have to have a mutable and an immutable references for this. And Rust forbids this. So you need some sort of generational indexes and so on. This solution is complicated in its own way. Performance is also in question, since inserting/removing an object in the middle of a Vec is expensive.
The SVG parsing itself is pretty complex too. There are a lot of ways you can implement it.

svgdom creates a custom Rc-tree where all the attributes are stored as owned data. This requires a lot of allocations (usually unnecessary). The parsing/preprocessing algorithm itself can be found in docs/preprocessor.md The problem with it is that you can't tweak it. And in many cases, it produces results that you do not need or do not expect. svgdom was originally used by svgcleaner and resvg and both of these projects are no longer using it.

Purpose

svgdom is designed to simplify generic SVG processing and manipulations. Unfortunately, an SVG is very complex format (PDF spec is 826 pages long), with lots of features and implementing all of them will lead to an enormous library.

That's why svgdom supports only a static subset of an SVG. No scripts, external resources and complex CSS styling. Parser will convert as much as possible data to a simple doc->elements->attributes structure.

For example, the fill parameter of an element can be set: as an element's attribute, as part of a style attribute, inside a style element as CSS2, inside an ENTITY, using a JS code and probably with lots of other methods.

Not to mention, that the fill attribute supports 4 different types of data.

With svgdom you can just use node.has_attribute(AttributeId::Fill) and don't worry where this attribute was defined in the original file.

Same goes for transforms, paths and other SVG types.

The main downside of this approach is that you can't save an original formatting and some data.

See the preprocessor doc for details.

Benefits

The element link(IRI, FuncIRI) is not just a text, but an actual link to another node.
At any time you can check which elements linked to the specific element. See Node's doc for details.
Support for many SVG specific data types like paths, transforms, IRI's, styles, etc. Thanks to svgtypes.
A complete support of text nodes: XML escaping, xml:space.
Fine-grained control over the SVG output.

Limitations

Only SVG elements and attributes will be parsed.
Attribute values, CDATA with CSS, DOCTYPE, text data and whitespaces will not be preserved.
UTF-8 only.
Only most popular attributes are parsed, other stored as strings.
No compressed SVG (.svgz). You should decompress it by yourself.
CSS support is minimal.
SVG 1.1 Full only (no 2.0 Draft, Basic, Tiny subsets).

Differences between svgdom and SVG spec

Library follows SVG spec in the data parsing, writing, but not in the tree structure.
Everything is a Node. There are no separated ElementNode, TextNode, etc. You still have all the data, but not in the specific struct's. You can check the node type via Node::node_type().

Structs

Ancestors	An iterator of nodes to the ancestors a given node.
Angle	Representation of the `<angle>` type.
AspectRatio	Representation of the `preserveAspectRatio` attribute.
Attribute	Representation of the SVG attribute object.
Attributes	An attributes list.
Children	A double ended iterator of nodes to the children of a given node.
Color	Representation of the `<color>` type.
Descendants	An iterator of nodes to a given node and its descendants, in tree order.
Document	Container of `Node`s.
FollowingSiblings	An iterator of nodes to the siblings after a given node.
Length	Representation of the `<length>` type.
LengthList	Representation of the `<list-of-length>` type.
NodeData	Node's data.
NumberList	Representation of the `<list-of-numbers>` type.
Path	Representation of the SVG path data.
Points	Representation of the `<list-of-points>` type.
PrecedingSiblings	An iterator of nodes to the siblings before a given node.
Transform	Representation of the `<transform>` type.
Traverse	A double ended iterator of nodes to a given node and its descendants, in tree order.
ValueWriteOptions	Options for SVG types writing.
ViewBox	Representation of the `<viewBox>` type.
WriteOptions	Options that defines SVG writing.

Enums

Align	Representation of the `align` value of the `preserveAspectRatio` attribute.
AngleUnit	List of all SVG angle units.
AttributeId	List of all SVG attributes.
AttributeValue	Value of the SVG attribute.
ElementId	List of all SVG elements.
Error	SVG DOM errors.
Indent	An XML node indention.
LengthUnit	List of all SVG length units.
ListSeparator	A separator type for a list of values.
NodeEdge	A node type during traverse.
NodeType	List of supported node types.
PaintFallback	Representation of the fallback part of the `<paint>` type.
ParserError	SVG parsing errors.
PathCommand	List of all path commands.
PathSegment	Representation of the path segment.
QName	Qualified name.
QNameRef	Qualified name reference.

Traits

AttributeType	This trait contains methods that check attribute's type according to the SVG spec.
ElementType	This trait contains methods that check element's type according to the SVG spec.
FilterSvg	An iterator over SVG elements.
FilterSvgAttrs	An iterator over SVG attributes.
FilterSvgAttrsMut	An iterator over SVG attributes.
FuzzyEq	A trait for fuzzy/approximate equality comparisons of float numbers.
FuzzyZero	A trait for fuzzy/approximate comparisons of float numbers.
SvgId	A trait for SVG id's.
WriteBuffer	A trait for writing data to the buffer.

Type Definitions

AttributeQName	Type alias for `QName<AttributeId>`.
AttributeQNameRef	Type alias for `QNameRef<AttributeId>`.
Node	Representation of the SVG node.
TagName	Type alias for `QName<ElementId>`.
TagNameRef	Type alias for `QNameRef<ElementId>`.