//! Public Rust API for librsvg.

//!

//! This gets re-exported from the toplevel `lib.rs`.

#![warn(missing_docs)]

use std::fmt;

// Here we only re-export stuff in the public API.

pub use crate::{

    accept_language::{AcceptLanguage, Language},

    drawing_ctx::Viewport,

    error::{DefsLookupErrorKind, ImplementationLimit, LoadingError},

    length::{LengthUnit, RsvgLength as Length},

};

// Don't merge these in the "pub use" above!  They are not part of the public API!

use crate::{

    accept_language::{LanguageTags, UserLanguage},

    css::{Origin, Stylesheet},

    document::{Document, LoadOptions, NodeId, RenderingOptions},

    dpi::Dpi,

    drawing_ctx::SvgNesting,

    error::InternalRenderingError,

    length::NormalizeParams,

    node::{CascadedValues, Node},

    rsvg_log,

    session::Session,

    url_resolver::UrlResolver,

};

use url::Url;

use std::path::Path;

use std::sync::Arc;

use gio::prelude::*; // Re-exposes glib's prelude as well

use gio::Cancellable;

use locale_config::{LanguageRange, Locale};

/// Errors that can happen while rendering or measuring an SVG document.

#[non_exhaustive]

pub enum RenderingError {

    /// An error from the rendering backend.

    /// A particular implementation-defined limit was exceeded.

    /// Tried to reference an SVG element that does not exist.

    IdNotFound,

    /// Tried to reference an SVG element from a fragment identifier that is incorrect.

    /// Not enough memory was available for rendering.

    /// The rendering was interrupted via a [`gio::Cancellable`].

    ///

    /// See the documentation for [`CairoRenderer::with_cancellable`].

    Cancelled,

}

impl std::error::Error for RenderingError {}

impl From<cairo::Error> for RenderingError {

}

impl From<InternalRenderingError> for RenderingError {

        // These enums are mostly the same, except for cases that should definitely

        // not bubble up to the public API.  So, we just move each variant, and for the

        // others, we emit a catch-all value as a safeguard.  (We ought to panic in that case,

        // maybe.)

            InternalRenderingError::InvalidTransform => {

        }

}

impl fmt::Display for RenderingError {

        }

}

/// Builder for loading an [`SvgHandle`].

///

/// This is the starting point for using librsvg.  This struct

/// implements a builder pattern for configuring an [`SvgHandle`]'s

/// options, and then loading the SVG data.  You can call the methods

/// of `Loader` in sequence to configure how SVG data should be

/// loaded, and finally use one of the loading functions to load an

/// [`SvgHandle`].

pub struct Loader {

    unlimited_size: bool,

    keep_image_data: bool,

    session: Session,

}

impl Loader {

    /// Creates a `Loader` with the default flags.

    ///

    /// * [`unlimited_size`](#method.with_unlimited_size) defaults to `false`, as malicious

    ///   SVG documents could cause the XML parser to consume very large amounts of memory.

    ///

    /// * [`keep_image_data`](#method.keep_image_data) defaults to

    ///   `false`.  You may only need this if rendering to Cairo

    ///   surfaces that support including image data in compressed

    ///   formats, like PDF.

    ///

    /// # Example:

    ///

    /// ```

    /// use rsvg;

    ///

    /// let svg_handle = rsvg::Loader::new()

    ///     .read_path("example.svg")

    ///     .unwrap();

    /// ```

    #[allow(clippy::new_without_default)]

            unlimited_size: false,

            keep_image_data: false,

        }

    /// Creates a `Loader` from a pre-created [`Session`].

    ///

    /// This is useful when a `Loader` must be created by the C API, which should already

    /// have created a session for logging.

    #[cfg(feature = "capi")]

            unlimited_size: false,

            keep_image_data: false,

            session,

        }

    /// Controls safety limits used in the XML parser.

    ///

    /// Internally, librsvg uses libxml2, which has set limits for things like the

    /// maximum length of XML element names, the size of accumulated buffers

    /// using during parsing of deeply-nested XML files, and the maximum size

    /// of embedded XML entities.

    ///

    /// Set this to `true` only if loading a trusted SVG fails due to size limits.

    ///

    /// # Example:

    /// ```

    /// use rsvg;

    ///

    /// let svg_handle = rsvg::Loader::new()

    ///     .with_unlimited_size(true)

    ///     .read_path("example.svg")    // presumably a trusted huge file

    ///     .unwrap();

    /// ```

    /// Controls embedding of compressed image data into the renderer.

    ///

    /// Normally, Cairo expects one to pass it uncompressed (decoded)

    /// images as surfaces.  However, when using a PDF rendering

    /// context to render SVG documents that reference raster images

    /// (e.g. those which include a bitmap as part of the SVG image),

    /// it may be more efficient to embed the original, compressed raster

    /// images into the PDF.

    ///

    /// Set this to `true` if you are using a Cairo PDF context, or any other type

    /// of context which allows embedding compressed images.

    ///

    /// # Example:

    ///

    /// ```

    /// # use std::env;

    /// let svg_handle = rsvg::Loader::new()

    ///     .keep_image_data(true)

    ///     .read_path("example.svg")

    ///     .unwrap();

    ///

    /// let mut output = env::temp_dir();

    /// output.push("output.pdf");

    /// let surface = cairo::PdfSurface::new(640.0, 480.0, output)?;

    /// let cr = cairo::Context::new(&surface).expect("Failed to create a cairo context");

    ///

    /// let renderer = rsvg::CairoRenderer::new(&svg_handle);

    /// renderer.render_document(

    ///     &cr,

    ///     &cairo::Rectangle::new(0.0, 0.0, 640.0, 480.0),

    /// )?;

    /// # Ok::<(), rsvg::RenderingError>(())

    /// ```

    /// Reads an SVG document from `path`.

    ///

    /// # Example:

    ///

    /// ```

    /// let svg_handle = rsvg::Loader::new()

    ///     .read_path("example.svg")

    ///     .unwrap();

    /// ```

    /// Reads an SVG document from a `gio::File`.

    ///

    /// The `cancellable` can be used to cancel loading from another thread.

    ///

    /// # Example:

    /// ```

    /// let svg_handle = rsvg::Loader::new()

    ///     .read_file(&gio::File::for_path("example.svg"), None::<&gio::Cancellable>)

    ///     .unwrap();

    /// ```

        self,

        file: &F,

        cancellable: Option<&P>,

    ) -> Result<SvgHandle, LoadingError> {

    /// Reads an SVG stream from a `gio::InputStream`.

    ///

    /// The `base_file`, if it is not `None`, is used to extract the

    /// [base URL][crate#the-base-file-and-resolving-references-to-external-files] for this stream.

    ///

    /// Reading an SVG document may involve resolving relative URLs if the

    /// SVG references things like raster images, or other SVG files.

    /// In this case, pass the `base_file` that correspondds to the

    /// URL where this SVG got loaded from.

    ///

    /// The `cancellable` can be used to cancel loading from another thread.

    ///

    /// # Example

    ///

    /// ```

    /// use gio::prelude::*;

    ///

    /// let file = gio::File::for_path("example.svg");

    ///

    /// let stream = file.read(None::<&gio::Cancellable>).unwrap();

    ///

    /// let svg_handle = rsvg::Loader::new()

    ///     .read_stream(&stream, Some(&file), None::<&gio::Cancellable>)

    ///     .unwrap();

    /// ```

        self,

        stream: &S,

        base_file: Option<&F>,

        cancellable: Option<&P>,

    ) -> Result<SvgHandle, LoadingError> {

        } else {

        };

        })

}

/// Handle used to hold SVG data in memory.

///

/// You can create this from one of the `read` methods in

/// [`Loader`].

pub struct SvgHandle {

    session: Session,

    pub(crate) document: Document,

}

// Public API goes here

impl SvgHandle {

    /// Checks if the SVG has an element with the specified `id`.

    ///

    /// Note that the `id` must be a plain fragment identifier like `#foo`, with

    /// a leading `#` character.

    ///

    /// The purpose of the `Err()` case in the return value is to indicate an

    /// incorrectly-formatted `id` argument.

        }

    /// Sets a CSS stylesheet to use for an SVG document.

    ///

    /// During the CSS cascade, the specified stylesheet will be used

    /// with a "User" [origin].

    ///

    /// Note that `@import` rules will not be resolved, except for `data:` URLs.

    ///

    /// [origin]: https://drafts.csswg.org/css-cascade-3/#cascading-origins

            css,

}

// Private methods go here

impl SvgHandle {

        }

        // The public APIs to get geometries of individual elements, or to render

        // them, should only allow referencing elements within the main handle's

        // SVG file; that is, only plain "#foo" fragment IDs are allowed here.

        // Otherwise, a calling program could request "another-file#foo" and cause

        // another-file to be loaded, even if it is not part of the set of

        // resources that the main SVG actually references.  In the future we may

        // relax this requirement to allow lookups within that set, but not to

        // other random files.

            NodeId::External(_, _) => {

                rsvg_log!(

                    "the public API is not allowed to look up external references: {}",

                    node_id

                );

                ))

        }

        } else {

        }

        // The public APIs to get geometries of individual elements, or to render

        // them, should only allow referencing elements within the main handle's

        // SVG file; that is, only plain "#foo" fragment IDs are allowed here.

        // Otherwise, a calling program could request "another-file#foo" and cause

        // another-file to be loaded, even if it is not part of the set of

        // resources that the main SVG actually references.  In the future we may

        // relax this requirement to allow lookups within that set, but not to

        // other random files.

                .document

            NodeId::External(_, _) => {

                unreachable!("caller should already have validated internal node IDs only")

            }

        }

}

/// Can render an `SvgHandle` to a Cairo context.

pub struct CairoRenderer<'a> {

    pub(crate) handle: &'a SvgHandle,

    pub(crate) dpi: Dpi,

    user_language: UserLanguage,

    cancellable: Option<gio::Cancellable>,

    is_testing: bool,

}

// Note that these are different than the C API's default, which is 90.

const DEFAULT_DPI_X: f64 = 96.0;

const DEFAULT_DPI_Y: f64 = 96.0;

/// Contains the computed values of the `<svg>` element's `width`, `height`, and `viewBox`.

///

/// An SVG document has a toplevel `<svg>` element, with optional attributes `width`,

/// `height`, and `viewBox`.  This structure contains the values for those attributes; you

/// can obtain the struct from [`CairoRenderer::intrinsic_dimensions`].

///

/// Since librsvg 2.54.0, there is support for [geometry

/// properties](https://www.w3.org/TR/SVG2/geometry.html) from SVG2.  This means that

/// `width` and `height` are no longer attributes; they are instead CSS properties that

/// default to `auto`.  The computed value for `auto` is `100%`, so for a `<svg>` that

/// does not have these attributes/properties, the `width`/`height` fields will be

/// returned as a [`Length`] of 100%.

///

/// As an example, the following SVG element has a `width` of 100 pixels

/// and a `height` of 400 pixels, but no `viewBox`.

///

/// ```xml

/// <svg xmlns="http://www.w3.org/2000/svg" width="100" height="400">

/// ```

///

/// In this case, the length fields will be set to the corresponding

/// values with [`LengthUnit::Px`] units, and the `vbox` field will be

/// set to to `None`.

pub struct IntrinsicDimensions {

    /// Computed value of the `width` property of the `<svg>`.

    /// Computed value of the `height` property of the `<svg>`.

    /// `viewBox` attribute of the `<svg>`, if present.

}

/// Gets the user's preferred locale from the environment and

/// translates it to a `Locale` with `LanguageRange` fallbacks.

///

/// The `Locale::current()` call only contemplates a single language,

/// but glib is smarter, and `g_get_langauge_names()` can provide

/// fallbacks, for example, when LC_MESSAGES="en_US.UTF-8:de" (USA

/// English and German).  This function converts the output of

/// `g_get_language_names()` into a `Locale` with appropriate

/// fallbacks.

impl UserLanguage {

        }

}

impl<'a> CairoRenderer<'a> {

    /// Creates a `CairoRenderer` for the specified `SvgHandle`.

    ///

    /// The default dots-per-inch (DPI) value is set to 96; you can change it

    /// with the [`with_dpi`] method.

    ///

    /// [`with_dpi`]: #method.with_dpi

            handle,

            is_testing: false,

        }

    /// Configures the dots-per-inch for resolving physical lengths.

    ///

    /// If an SVG document has physical units like `5cm`, they must be resolved

    /// to pixel-based values.  The default pixel density is 96 DPI in

    /// both dimensions.

            ..self

        }

    /// Configures the set of languages used for rendering.

    ///

    /// SVG documents can use the `<switch>` element, whose children have a

    /// `systemLanguage` attribute; only the first child which has a `systemLanguage` that

    /// matches the preferred languages will be rendered.

    ///

    /// This function sets the preferred languages.  The default is

    /// `Language::FromEnvironment`, which means that the set of preferred languages will

    /// be obtained from the program's environment.  To set an explicit list of languages,

    /// you can use `Language::AcceptLanguage` instead.

            user_language,

            ..self

        }

    /// Sets a cancellable to be able to interrupt rendering.

    ///

    /// The rendering functions like [`render_document`] will normally render the whole

    /// SVG document tree.  However, they can be interrupted if you set a `cancellable`

    /// object with this method.  To interrupt rendering, you can call

    /// [`gio::CancellableExt::cancel()`] from a different thread than where the rendering

    /// is happening.

    ///

    /// Since rendering happens as a side-effect on the Cairo context (`cr`) that is

    /// passed to the rendering functions, it may be that the `cr`'s target surface is in

    /// an undefined state if the rendering is cancelled.  The surface may have not yet

    /// been painted on, or it may contain a partially-rendered document.  For this

    /// reason, if your application does not want to leave the target surface in an

    /// inconsistent state, you may prefer to use a temporary surface for rendering, which

    /// can be discarded if your code cancels the rendering.

    ///

    /// [`render_document`]: #method.render_document

            ..self

        }

    /// Queries the `width`, `height`, and `viewBox` attributes in an SVG document.

    ///

    /// If you are calling this function to compute a scaling factor to render the SVG,

    /// consider simply using [`render_document`] instead; it will do the scaling

    /// computations automatically.

    ///

    /// See also [`intrinsic_size_in_pixels`], which does the conversion to pixels if

    /// possible.

    ///

    /// [`render_document`]: #method.render_document

    /// [`intrinsic_size_in_pixels`]: #method.intrinsic_size_in_pixels

        }

    /// Converts the SVG document's intrinsic dimensions to pixels, if possible.

    ///

    /// Returns `Some(width, height)` in pixel units if the SVG document has `width` and

    /// `height` attributes with physical dimensions (CSS pixels, cm, in, etc.) or

    /// font-based dimensions (em, ex).

    ///

    /// Note that the dimensions are floating-point numbers, so your application can know

    /// the exact size of an SVG document.  To get integer dimensions, you should use

    /// [`f64::ceil()`] to round up to the nearest integer (just using [`f64::round()`],

    /// may may chop off pixels with fractional coverage).

    ///

    /// If the SVG document has percentage-based `width` and `height` attributes, or if

    /// either of those attributes are not present, returns `None`.  Dimensions of that

    /// kind require more information to be resolved to pixels; for example, the calling

    /// application can use a viewport size to scale percentage-based dimensions.

        }

    /// Renders the whole SVG document fitted to a viewport

    ///

    /// The `viewport` gives the position and size at which the whole SVG

    /// document will be rendered.

    ///

    /// The `cr` must be in a `cairo::Status::Success` state, or this function

    /// will not render anything, and instead will return

    /// `RenderingError::Cairo` with the `cr`'s current error state.

        &self,

        cr: &cairo::Context,

        viewport: &cairo::Rectangle,

    ) -> Result<(), RenderingError> {

            cr,

            viewport,

    /// Computes the (ink_rect, logical_rect) of an SVG element, as if

    /// the SVG were rendered to a specific viewport.

    ///

    /// Element IDs should look like an URL fragment identifier; for

    /// example, pass `Some("#foo")` to get the geometry of the

    /// element that has an `id="foo"` attribute.

    ///

    /// The "ink rectangle" is the bounding box that would be painted

    /// for fully- stroked and filled elements.

    ///

    /// The "logical rectangle" just takes into account the unstroked

    /// paths and text outlines.

    ///

    /// Note that these bounds are not minimum bounds; for example,

    /// clipping paths are not taken into account.

    ///

    /// You can pass `None` for the `id` if you want to measure all

    /// the elements in the SVG, i.e. to measure everything from the

    /// root element.

    ///

    /// This operation is not constant-time, as it involves going through all

    /// the child elements.

    ///

    /// FIXME: example

        &self,

        id: Option<&str>,

        viewport: &cairo::Rectangle,

    ) -> Result<(cairo::Rectangle, cairo::Rectangle), RenderingError> {

            viewport,

    /// Renders a single SVG element in the same place as for a whole SVG document

    ///

    /// This is equivalent to `render_document`, but renders only a single element and its

    /// children, as if they composed an individual layer in the SVG.  The element is

    /// rendered with the same transformation matrix as it has within the whole SVG

    /// document.  Applications can use this to re-render a single element and repaint it

    /// on top of a previously-rendered document, for example.

    ///

    /// Note that the `id` must be a plain fragment identifier like `#foo`, with

    /// a leading `#` character.

    ///

    /// The `viewport` gives the position and size at which the whole SVG

    /// document would be rendered.  This function will effectively place the

    /// whole SVG within that viewport, but only render the element given by

    /// `id`.

    ///

    /// The `cr` must be in a `cairo::Status::Success` state, or this function

    /// will not render anything, and instead will return

    /// `RenderingError::Cairo` with the `cr`'s current error state.

        &self,

        cr: &cairo::Context,

        id: Option<&str>,

        viewport: &cairo::Rectangle,

    ) -> Result<(), RenderingError> {

            cr,

            viewport,

    /// Computes the (ink_rect, logical_rect) of a single SVG element

    ///

    /// While `geometry_for_layer` computes the geometry of an SVG element subtree with

    /// its transformation matrix, this other function will compute the element's geometry

    /// as if it were being rendered under an identity transformation by itself.  That is,

    /// the resulting geometry is as if the element got extracted by itself from the SVG.

    ///

    /// This function is the counterpart to `render_element`.

    ///

    /// Element IDs should look like an URL fragment identifier; for

    /// example, pass `Some("#foo")` to get the geometry of the

    /// element that has an `id="foo"` attribute.

    ///

    /// The "ink rectangle" is the bounding box that would be painted

    /// for fully- stroked and filled elements.

    ///

    /// The "logical rectangle" just takes into account the unstroked

    /// paths and text outlines.

    ///

    /// Note that these bounds are not minimum bounds; for example,

    /// clipping paths are not taken into account.

    ///

    /// You can pass `None` for the `id` if you want to measure all

    /// the elements in the SVG, i.e. to measure everything from the

    /// root element.

    ///

    /// This operation is not constant-time, as it involves going through all

    /// the child elements.

    ///

    /// FIXME: example

        &self,

        id: Option<&str>,

    ) -> Result<(cairo::Rectangle, cairo::Rectangle), RenderingError> {

    /// Renders a single SVG element to a given viewport

    ///

    /// This function can be used to extract individual element subtrees and render them,

    /// scaled to a given `element_viewport`.  This is useful for applications which have

    /// reusable objects in an SVG and want to render them individually; for example, an

    /// SVG full of icons that are meant to be be rendered independently of each other.

    ///

    /// Note that the `id` must be a plain fragment identifier like `#foo`, with

    /// a leading `#` character.

    ///

    /// The `element_viewport` gives the position and size at which the named element will

    /// be rendered.  FIXME: mention proportional scaling.

    ///

    /// The `cr` must be in a `cairo::Status::Success` state, or this function

    /// will not render anything, and instead will return

    /// `RenderingError::Cairo` with the `cr`'s current error state.

        &self,

        cr: &cairo::Context,

        id: Option<&str>,

        element_viewport: &cairo::Rectangle,

    ) -> Result<(), RenderingError> {

            cr,

            element_viewport,

    #[doc(hidden)]

    #[cfg(feature = "capi")]

    /// Normalizes the svg's width/height properties with a 0-sized viewport

    ///

    /// This assumes that if one of the properties is in percentage units, then

    /// its corresponding value will not be used.  E.g. if width=100%, the caller

    /// will ignore the resulting width value.

    #[doc(hidden)]

    #[doc(hidden)]

    #[cfg(feature = "capi")]

}