//! Writes SVG documents: the declaration and root element, elements and attributes with XML
//! escaping (through `craft-xml`), path data and numbers.
//!
//! The caller decides what to draw and how the file is laid out; this module makes what it
//! writes well-formed. Attribute values and text are escaped, so no value can inject markup.
//!
//! ```
//! use craft_svg::write::{SvgWriter, num, path_data};
//!
//! let mut path = kurbo::BezPath::new();
//! path.move_to((1.0, 2.0));
//! path.line_to((3.5, 2.0));
//! let mut w = SvgWriter::new();
//! w.root().attr("viewBox", format_args!("0 0 {} {}", num(10.0, 1), num(5.0, 1))).open();
//! w.line(1);
//! w.tag("path").attr("d", path_data(&path)).empty();
//! w.line(0);
//! w.close();
//! assert_eq!(
//! w.finish(),
//! "\n"
//! );
//! ```
use std::fmt::{self, Display, Write as _};
pub use craft_xml::Tag;
use kurbo::{BezPath, PathEl, Point};
/// The SVG namespace.
pub const SVG_NS: &str = "http://www.w3.org/2000/svg";
/// A structured SVG scene. Applications provide geometry, styles and attributes; this module
/// owns the SVG element tree and serializes it with XML escaping.
#[derive(Clone, Debug, PartialEq)]
pub struct Scene {
pub width_mm: f64,
pub height_mm: f64,
pub view_box: [f64; 4],
pub elements: Vec,
}
/// Structured SVG elements supported by the path-document writer.
#[derive(Clone, Debug, PartialEq)]
pub enum Element {
Group { attributes: Vec, children: Vec },
Path { attributes: Vec, path: BezPath },
Rect { attributes: Vec, x: f64, y: f64, width: f64, height: f64 },
Text { attributes: Vec, x: f64, y: f64, text: String },
Title(String),
Style(String),
NestedSvg { attributes: Vec, children: Vec },
}
/// An escaped SVG attribute. Element names and attribute names are API constants and must be
/// valid XML names; values are always escaped by the shared writer.
#[derive(Clone, Debug, PartialEq)]
pub struct Attribute {
pub name: String,
pub value: Value,
}
/// Attribute values written by the shared serializer.
#[derive(Clone, Debug, PartialEq)]
pub enum Value {
Text(String),
Number(f64),
Millimetres(f64),
ViewBox([f64; 4]),
TranslateScale { x: f64, y: f64, scale_x: f64, scale_y: f64 },
}
impl Attribute {
pub fn text(name: impl Into, value: impl Into) -> Self {
Self { name: name.into(), value: Value::Text(value.into()) }
}
pub fn number(name: impl Into, value: f64) -> Self {
Self { name: name.into(), value: Value::Number(value) }
}
pub fn millimetres(name: impl Into, value: f64) -> Self {
Self { name: name.into(), value: Value::Millimetres(value) }
}
pub fn view_box(bounds: [f64; 4]) -> Self {
Self { name: "viewBox".into(), value: Value::ViewBox(bounds) }
}
pub fn translate_scale(x: f64, y: f64, scale_x: f64, scale_y: f64) -> Self {
Self { name: "transform".into(), value: Value::TranslateScale { x, y, scale_x, scale_y } }
}
/// A translate/scale transform with three decimal places for positions and four for scales.
pub fn translate_scale_fixed(x: f64, y: f64, scale_x: f64, scale_y: f64) -> Self {
Self::text("transform", format!("translate({} {}) scale({} {})", num(x, 3), num(y, 3), num(scale_x, 4), num(scale_y, 4)))
}
}
impl Scene {
/// Serialize the scene as an SVG 1.1 document.
pub fn write(&self) -> String {
self.write_impl(false)
}
/// Serialize the root viewBox with three decimal places for stable fixed-width output.
pub fn write_fixed_view_box(&self) -> String {
self.write_impl(true)
}
fn write_impl(&self, fixed: bool) -> String {
let mut writer = SvgWriter::new();
let view_box = if fixed {
format!("{} {} {} {}", num(self.view_box[0], 3), num(self.view_box[1], 3), num(self.view_box[2], 3), num(self.view_box[3], 3))
} else {
view_box_data(self.view_box)
};
writer
.root()
.attr("version", "1.1")
.attr("width", format!("{}mm", num(self.width_mm, 3)))
.attr("height", format!("{}mm", num(self.height_mm, 3)))
.attr("viewBox", view_box)
.open();
write_elements(&mut writer, &self.elements, 1);
writer.line(0);
writer.close();
writer.finish()
}
}
fn write_attributes<'a>(mut tag: craft_xml::Tag<'a>, attributes: &'a [Attribute]) -> craft_xml::Tag<'a> {
// SVG consumers disagree about duplicate attributes; make the last supplied value win.
for (index, attribute) in attributes.iter().enumerate() {
if attributes[index + 1..].iter().any(|later| later.name == attribute.name) {
continue;
}
tag = match &attribute.value {
Value::Text(value) => tag.attr(&attribute.name, value),
Value::Number(value) => tag.attr(&attribute.name, num(*value, 3)),
Value::Millimetres(value) => tag.attr(&attribute.name, format!("{}mm", num(*value, 3))),
Value::ViewBox(bounds) => tag.attr(&attribute.name, view_box_data(*bounds)),
Value::TranslateScale { x, y, scale_x, scale_y } => {
tag.attr(&attribute.name, format!("translate({} {}) scale({} {})", num(*x, 3), num(*y, 3), shortest(*scale_x), shortest(*scale_y)))
}
};
}
tag
}
fn shortest(value: f64) -> String {
if value.is_finite() { value.to_string() } else { "0".into() }
}
fn write_elements(writer: &mut SvgWriter, elements: &[Element], depth: usize) {
for element in elements {
writer.line(depth);
match element {
Element::Group { attributes, children } => {
write_attributes(writer.tag("g"), attributes).open();
write_elements(writer, children, depth + 1);
writer.line(depth);
writer.close();
}
Element::Path { attributes, path } => {
let mut attrs = vec![Attribute::text("d", path_data(path))];
attrs.extend(attributes.iter().cloned());
write_attributes(writer.tag("path"), &attrs).empty();
}
Element::Rect { attributes, x, y, width, height } => {
let mut attrs = vec![
Attribute::number("x", *x),
Attribute::number("y", *y),
Attribute::number("width", *width),
Attribute::number("height", *height),
];
attrs.extend(attributes.iter().cloned());
write_attributes(writer.tag("rect"), &attrs).empty();
}
Element::Text { attributes, x, y, text } => {
let mut attrs = vec![Attribute::number("x", *x), Attribute::number("y", *y)];
attrs.extend(attributes.iter().cloned());
write_attributes(writer.tag("text"), &attrs).open();
writer.text(text);
writer.close();
}
Element::Title(text) => {
writer.tag("title").open();
writer.text(text);
writer.close();
}
Element::Style(css) => {
writer.tag("style").open();
writer.text(css);
writer.close();
}
Element::NestedSvg { attributes, children } => {
write_attributes(writer.tag("svg"), attributes).open();
write_elements(writer, children, depth + 1);
writer.line(depth);
writer.close();
}
}
}
}
fn view_box_data(bounds: [f64; 4]) -> String {
format!("{} {} {} {}", shortest(bounds[0]), shortest(bounds[1]), shortest(bounds[2]), shortest(bounds[3]))
}
/// A number written with a fixed count of decimals. A value that is not finite is written as
/// zero, because SVG has no spelling for it.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct Num(f64, usize);
/// `value` with `decimals` decimals: `num(1.5, 3)` is written `1.500`.
pub fn num(value: f64, decimals: usize) -> Num {
Num(value, decimals)
}
impl Display for Num {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
let value = if self.0.is_finite() { self.0 } else { 0.0 };
write!(f, "{value:.*}", self.1)
}
}
/// Path data (the `d` attribute) with every coordinate in its shortest form that reads back
/// as the same number: `M1,2 L3.5,2 Z`.
pub fn path_data(path: &BezPath) -> String {
path.to_svg()
}
/// Path data with `decimals` decimals per coordinate, written compactly: `M1.00 2.00L3.50 2.00Z`.
/// Coordinates that are not finite are written as zero.
pub fn path_data_fixed(path: &BezPath, decimals: usize) -> String {
let mut d = String::new();
let mut command = |letter: char, points: &[Point]| {
d.push(letter);
for (i, p) in points.iter().enumerate() {
let sep = if i == 0 { "" } else { " " };
let _ = write!(d, "{sep}{} {}", num(p.x, decimals), num(p.y, decimals));
}
};
for el in path.elements() {
match *el {
PathEl::MoveTo(p) => command('M', &[p]),
PathEl::LineTo(p) => command('L', &[p]),
PathEl::QuadTo(a, p) => command('Q', &[a, p]),
PathEl::CurveTo(a, b, p) => command('C', &[a, b, p]),
PathEl::ClosePath => command('Z', &[]),
}
}
d
}
/// Builds an SVG document or fragment. Elements are closed for the caller and attribute
/// values and text are escaped. Element and attribute names are written as given: they are
/// the caller's own constants, not checked.
///
/// Whitespace between elements is the caller's: nothing is added unless [`SvgWriter::line`]
/// is called.
#[derive(Clone, Debug, Default)]
pub struct SvgWriter(craft_xml::Writer);
impl SvgWriter {
/// A document: starts with the XML declaration.
pub fn new() -> SvgWriter {
let mut xml = craft_xml::Writer::new();
xml.decl(false);
SvgWriter(xml)
}
/// A fragment, or a document without the XML declaration (for embedding in HTML or JSON).
pub fn fragment() -> SvgWriter {
SvgWriter::default()
}
/// Starts the root tag, `