sidoc_html5/

lib.rs

pub mod owned;

use std::borrow::Cow;

#[cfg(feature = "extra-validation")]
use std::collections::HashSet;

#[cfg(feature = "extra-validation")]
lazy_static::lazy_static! {
  static ref VOID_ELEMENTS: HashSet<&'static str> = {
    HashSet::from([
      "area", "base", "br", "col", "embed", "hr", "img", "input", "link",
      "meta", "param", "source", "track", "wbr"
    ])
  };
}

enum AttrType<'a> {
  KV(&'a str, String),
  Bool(&'a str),
  Data(&'a str, String),
  BoolData(&'a str)
}

pub struct Element<'a> {
  tag: &'a str,
  classes: Vec<&'a str>,
  alst: Vec<AttrType<'a>>
}

impl<'a> Element<'a> {
  #[must_use]
  pub const fn new(tag: &'a str) -> Self {
    Element {
      tag,
      classes: Vec::new(),
      alst: Vec::new()
    }
  }

  /// Assign a class to this element.
  ///
  /// ```
  /// use sidoc_html5::Element;
  /// let element = Element::new("p")
  ///   .class("warning");
  /// ```
  #[inline]
  #[must_use]
  pub fn class(mut self, cls: &'a str) -> Self {
    self.classes.push(cls);
    self
  }

  /// Assign a class to this element in-place.
  ///
  /// ```
  /// use sidoc_html5::Element;
  /// let mut element = Element::new("p");
  /// element.class_r("warning");
  /// ```
  #[inline]
  pub fn class_r(&mut self, cls: &'a str) -> &mut Self {
    self.classes.push(cls);
    self
  }

  /// Assign a "flag attribute" to the element.
  ///
  /// Flag attributes do not have (explicit) values, and are used to mark
  /// elements as `selected` or `checked` and such.
  ///
  /// ```
  /// use sidoc_html5::Element;
  /// let element = Element::new("input")
  ///   .raw_attr("type", "checkbox")
  ///   .flag("checked");
  /// ```
  #[inline]
  #[must_use]
  pub fn flag(mut self, key: &'a str) -> Self {
    self.alst.push(AttrType::Bool(key));
    self
  }

  #[inline]
  pub fn flag_r(&mut self, key: &'a str) -> &mut Self {
    self.alst.push(AttrType::Bool(key));
    self
  }

  /// Conditionally add a flag attribute.
  ///
  /// Flag attributes do not have (explicit) values, and are used to mark
  /// elements as `selected` or `checked` and such.
  ///
  /// ```
  /// use sidoc_html5::Element;
  /// for id in &[1, 2, 3] {
  ///   let element = Element::new("option")
  ///     .flag_if(*id == 3, "selected");
  /// }
  /// ```
  #[inline]
  /*
  #[deprecated(since = "0.1.2", note = "Use .mod_if() with .flag() instead.")]
  */
  #[must_use]
  pub fn flag_if(mut self, f: bool, key: &'a str) -> Self {
    if f {
      self.alst.push(AttrType::Bool(key));
    }
    self
  }

  /// Add an attribute.
  ///
  /// The attribute value is escaped as needed.
  ///
  /// Note: If the value is guaranteed not to require escaping then prefer the
  /// [`Element::raw_attr()`] method instead.
  ///
  /// ```
  /// use sidoc_html5::Element;
  /// let elem = Element::new("input")
  ///   .attr("name", "foo");
  /// ```
  #[inline]
  #[must_use]
  pub fn attr(mut self, key: &'a str, value: impl AsRef<str>) -> Self {
    debug_assert!(
      key != "class",
      "Use the dedicated .class() method to add classes to elements"
    );
    self.alst.push(AttrType::KV(
      key,
      html_escape::encode_double_quoted_attribute(value.as_ref()).to_string()
    ));
    self
  }

  /// Conditionally add an attribute.
  ///
  /// The value is escaped as needed.
  #[inline]
  /*
  #[deprecated(since = "0.1.2", note = "Use .mod_if() with .attr() instead.")]
  */
  #[must_use]
  pub fn attr_if<V>(self, flag: bool, key: &'a str, value: V) -> Self
  where
    V: AsRef<str>
  {
    debug_assert!(
      key != "class",
      "Use the dedicated .class() method to add classes to elements"
    );

    self.optattr(key, flag.then_some(value))
  }

  /// Add a `data-`-prefixed attribute.
  ///
  /// The attribute value is escaped as needed.
  ///
  /// ```
  /// use sidoc_html5::Element;
  /// let elem = Element::new("tr")
  ///   .data_attr("name", "foo");
  /// ```
  #[inline]
  #[must_use]
  pub fn data_attr(mut self, key: &'a str, value: impl AsRef<str>) -> Self {
    debug_assert!(
      key != "class",
      "Use the dedicated .class() method to add classes to elements"
    );
    self.alst.push(AttrType::Data(
      key,
      html_escape::encode_double_quoted_attribute(value.as_ref()).to_string()
    ));
    self
  }

  #[inline]
  pub fn data_attr_r(
    &mut self,
    key: &'a str,
    value: impl AsRef<str>
  ) -> &mut Self {
    debug_assert!(
      key != "class",
      "Use the dedicated .class() method to add classes to elements"
    );
    self.alst.push(AttrType::Data(
      key,
      html_escape::encode_double_quoted_attribute(value.as_ref()).to_string()
    ));
    self
  }


  #[inline]
  #[must_use]
  pub fn data_flag(mut self, key: &'a str) -> Self {
    self.alst.push(AttrType::BoolData(key));
    self
  }

  /// Conditionally add a boolean `data-` attribute.
  ///
  /// Add a `data-foo=true` attribute to an element:
  /// ```
  /// use sidoc_html5::Element;
  /// let val = 7;
  /// let elem = Element::new("p")
  ///   .data_flag_if(val > 5, "foo");
  /// ```
  #[inline]
  /*
  #[deprecated(
    since = "0.1.2",
    note = "Use .mod_if() with .data_flag() instead."
  )]
  */
  #[must_use]
  pub fn data_flag_if(mut self, flag: bool, key: &'a str) -> Self {
    if flag {
      self.alst.push(AttrType::BoolData(key));
    }
    self
  }

  /// Add an attribute if its optional value is `Some()`; ignore it otherwise.
  ///
  /// The value is escaped as needed.
  ///
  /// Note: If the value is guaranteed to not needing escaping then prefer the
  /// [`Element::raw_optattr()`] method instead.
  ///
  /// ```
  /// use sidoc_html5::Element;
  /// let something = Some("something");
  /// let nothing: Option<&str> = None;
  /// let elem = Element::new("form")
  ///   .optattr("id", something)
  ///   .optattr("name", nothing);
  /// ```
  #[inline]
  #[must_use]
  #[allow(clippy::needless_pass_by_value)]
  pub fn optattr<T>(mut self, key: &'a str, value: Option<T>) -> Self
  where
    T: AsRef<str>
  {
    if let Some(v) = value.as_ref() {
      self.alst.push(AttrType::KV(
        key,
        html_escape::encode_double_quoted_attribute(v).to_string()
      ));
    }
    self
  }

  /// If an an optional input value is set, apply a function on the contained
  /// value to allow it to generate the actual attribute value.  Do nothing
  /// if the optional value is `None`.
  ///
  /// The value returned by the closure is escaped as needed.
  ///
  /// ```
  /// use sidoc_html5::Element;
  /// let something = Some("something");
  /// let elem = Element::new("p")
  ///   .optattr_map("id", something, |v| {
  ///     // Have a value -- format it and append "-aboo" to it.
  ///     format!("{}-aboo", v)
  ///   });
  /// ```
  #[inline]
  /*
  #[deprecated(since = "0.1.2", note = "Use .map_attr() instead.")]
  */
  #[must_use]
  #[allow(clippy::needless_pass_by_value)]
  pub fn optattr_map<T, F>(self, key: &'a str, value: Option<T>, f: F) -> Self
  where
    F: FnOnce(&T) -> String
  {
    self.map_attr(key, value, f)
  }

  #[inline]
  #[must_use]
  #[allow(clippy::needless_pass_by_value)]
  pub fn map_attr<T, F>(mut self, key: &'a str, value: Option<T>, f: F) -> Self
  where
    F: FnOnce(&T) -> String
  {
    if let Some(v) = value.as_ref() {
      let s = f(v);
      self.alst.push(AttrType::KV(
        key,
        html_escape::encode_double_quoted_attribute(&s).to_string()
      ));
    }
    self
  }

  /// If an an optional input value is set, apply a function on the contained
  /// value.
  #[inline]
  /*
  #[deprecated(since = "0.1.2", note = "Use .map() instead.")]
  */
  #[must_use]
  pub fn opt_map<T, F>(self, value: Option<&'_ T>, f: F) -> Self
  where
    F: FnOnce(Self, &T) -> Self
  {
    self.map(value, f)
  }

  #[must_use]
  pub fn map<T, F>(self, value: Option<&'_ T>, f: F) -> Self
  where
    F: FnOnce(Self, &T) -> Self
  {
    if let Some(v) = value.as_ref() {
      f(self, v)
    } else {
      self
    }
  }

  /// If an an optional input value is set, apply a function on the contained
  /// value.
  ///
  /// ```
  /// use sidoc_html5::Element;
  /// let opt_str = Some("enabled");
  /// Element::new("body")
  ///   .map_opt(opt_str, |this, s| {
  ///     this.flag(s)
  ///   });
  /// ```
  #[inline]
  #[must_use]
  pub fn map_opt<T, F>(self, o: Option<T>, f: F) -> Self
  where
    F: FnOnce(Self, T) -> Self
  {
    match o {
      Some(t) => f(self, t),
      None => self
    }
  }

  /// Conditionally call a function to add an attribute with a generated value.
  ///
  /// ```
  /// use sidoc_html5::Element;
  /// let sv = vec!["foo".to_string(), "bar".to_string()];
  /// Element::new("body")
  ///   .map_attr_if(!sv.is_empty(), "data-mylist", &sv, |v: &Vec<String>| {
  ///     v.join(",")
  ///   });
  /// ```
  #[inline]
  #[must_use]
  pub fn map_attr_if<T, F>(
    self,
    flag: bool,
    key: &'a str,
    data: &T,
    f: F
  ) -> Self
  where
    F: FnOnce(&T) -> String
  {
    if flag {
      self.attr(key, f(data))
    } else {
      self
    }
  }


  /// Conditionally call a closure to modify `self` if a predicate is true.
  ///
  /// ```
  /// use sidoc_html5::Element;
  /// let someval = 42;
  /// Element::new("body")
  ///   .map_if(someval == 42, |obj| obj.flag("selected"));
  /// ```
  #[inline]
  #[must_use]
  pub fn map_if<F>(self, flag: bool, f: F) -> Self
  where
    F: FnOnce(Self) -> Self
  {
    if flag {
      f(self)
    } else {
      self
    }
  }

  /// Conditionally call a closure to modify `self`, in-place, if a predicate
  /// is true.
  ///
  /// ```
  /// use sidoc_html5::Element;
  /// let someval = 42;
  /// let mut e = Element::new("body");
  /// e.mod_if(someval == 42, |obj| {
  ///   obj.flag_r("selected");
  /// });
  /// ```
  #[inline]
  pub fn mod_if<F>(&mut self, flag: bool, f: F) -> &mut Self
  where
    F: FnOnce(&mut Self)
  {
    if flag {
      f(self);
    }
    self
  }
}

/// Methods that don't transform the input.
impl<'a> Element<'a> {
  /// Add an attribute.
  ///
  /// The attribute value is not escaped.
  ///
  /// ```
  /// use sidoc_html5::Element;
  /// let elem = Element::new("form")
  ///   .raw_attr("id", "foo");
  /// ```
  #[inline]
  #[must_use]
  #[allow(clippy::needless_pass_by_value)]
  pub fn raw_attr(mut self, key: &'a str, value: impl ToString) -> Self {
    debug_assert!(
      key != "class",
      "Use the dedicated .class() method to add classes to elements"
    );
    self.alst.push(AttrType::KV(key, value.to_string()));
    self
  }

  /// Add an attribute if its optional value is `Some()`; ignore it otherwise.
  ///
  /// The value is assumed not to require escaping.
  ///
  /// ```
  /// use sidoc_html5::Element;
  /// let ss = "something".to_string();
  /// let something = Some(&ss);
  /// let nothing = None::<&String>;
  /// let elem = Element::new("form")
  ///   .raw_optattr("id", something)
  ///   .raw_optattr("name", nothing);
  /// ```
  #[inline]
  #[must_use]
  pub fn raw_optattr<T>(mut self, key: &'a str, value: Option<&T>) -> Self
  where
    T: ToString
  {
    if let Some(v) = value.as_ref() {
      self.alst.push(AttrType::KV(key, v.to_string()));
    }
    self
  }

  /// Add an attribute if a condition is true.
  ///
  /// The attribute value is not escaped.
  #[inline]
  #[allow(clippy::needless_pass_by_value)]
  #[must_use]
  pub fn raw_attr_if(
    self,
    flag: bool,
    key: &'a str,
    value: impl ToString
  ) -> Self {
    debug_assert!(
      key != "class",
      "Use the dedicated .class() method to add classes to elements"
    );
    self.raw_optattr(key, flag.then_some(&value))
  }
}

impl<'a> Element<'a> {
  /// Generate a vector of strings representing each attribute.
  fn gen_attr_list(&self) -> Option<Vec<String>> {
    if self.alst.is_empty() && self.classes.is_empty() {
      None
    } else {
      let mut ret = Vec::new();

      if !self.classes.is_empty() {
        ret.push(format!(r#"class="{}""#, self.classes.join(" ")));
      }

      let it = self.alst.iter().map(|a| match a {
        AttrType::KV(k, v) => {
          format!(r#"{k}="{v}""#)
        }
        AttrType::Bool(a) => (*a).to_string(),
        AttrType::Data(k, v) => {
          format!(r#"data-{k}="{v}""#)
        }
        AttrType::BoolData(a) => {
          format!("data-{a}")
        }
      });

      ret.extend(it);

      Some(ret)
    }
  }
}

impl<'a> Element<'a> {
  /// Call a closure for adding child nodes.
  ///
  /// ```
  /// use sidoc_html5::Element;
  /// let mut bldr = sidoc::Builder::new();
  /// Element::new("div")
  ///   .sub(&mut bldr, |bldr| {
  ///     Element::new("br")
  ///       .add_empty(bldr);
  /// });
  /// ```
  ///
  /// # Panics
  /// If the `extra-validation` feature is enabled, panic if the tag name is
  /// not a known "void" element.
  pub fn sub<F>(self, bldr: &mut sidoc::Builder, f: F)
  where
    F: FnOnce(&mut sidoc::Builder)
  {
    #[cfg(feature = "extra-validation")]
    assert!(!VOID_ELEMENTS.contains(self.tag));

    if let Some(lst) = self.gen_attr_list() {
      bldr.scope(
        format!("<{} {}>", self.tag, lst.join(" ")),
        Some(format!("</{}>", self.tag))
      );
    } else {
      let stag = format!("<{}>", self.tag);
      let etag = format!("</{}>", self.tag);
      bldr.scope(stag, Some(etag));
    }

    f(bldr);

    bldr.exit();
  }
}


/// Methods inserting element into a sidoc context.
impl<'a> Element<'a> {
  /// Consume `self` and add a empty tag representation of element to a sidoc
  /// builder.
  ///
  /// An empty/void tag comes is one which does not have a closing tag:
  /// `<tagname foo="bar">`.
  ///
  /// # Panics
  /// If the `extra-validation` feature is enabled, panic if the tag name is
  /// not a known "void" element.
  #[inline]
  pub fn add_empty(self, bldr: &mut sidoc::Builder) {
    #[cfg(feature = "extra-validation")]
    assert!(VOID_ELEMENTS.contains(self.tag));

    let line = if let Some(alst) = self.gen_attr_list() {
      format!("<{} {}>", self.tag, alst.join(" "))
    } else {
      format!("<{}>", self.tag)
    };

    bldr.line(line);
  }

  /// Consume `self` and add a tag containing text content between the opening
  /// and closing tag to the supplied sidoc builder.
  ///
  /// The supplied text is escaped as needed.
  ///
  /// ```
  /// use sidoc_html5::Element;
  /// let mut bldr = sidoc::Builder::new();
  /// let elem = Element::new("textarea")
  ///   .raw_attr("rows", 8)
  ///   .raw_attr("cols", 32)
  ///   .add_content("This is the text content", &mut bldr);
  /// ```
  ///
  /// The example above should generate:
  /// `<textarea rows="8" cols="32">This is the text content</textarea>`
  ///
  /// # Panics
  /// If the `extra-validation` feature is enabled, panic if the tag name is
  /// not a known "void" element.
  #[inline]
  pub fn add_content(self, text: &str, bldr: &mut sidoc::Builder) {
    #[cfg(feature = "extra-validation")]
    assert!(!VOID_ELEMENTS.contains(self.tag));

    let line = if let Some(alst) = self.gen_attr_list() {
      format!(
        "<{} {}>{}</{}>",
        self.tag,
        alst.join(" "),
        html_escape::encode_text(text),
        self.tag
      )
    } else {
      format!(
        "<{}>{}</{}>",
        self.tag,
        html_escape::encode_text(text),
        self.tag
      )
    };
    bldr.line(line);
  }

  /// Consume `self` and add a tag containing text content between the opening
  /// and closing tag to the supplied sidoc builder.
  ///
  /// The supplied text is not escaped.
  ///
  /// ```
  /// use sidoc_html5::Element;
  /// let mut bldr = sidoc::Builder::new();
  /// let elem = Element::new("button")
  ///   .add_raw_content("Do Stuff", &mut bldr);
  /// ```
  ///
  /// The example above should generate:
  /// `<button>Do Stuff</button>`
  ///
  /// # Panics
  /// If the `extra-validation` feature is enabled, panic if the tag name is
  /// not a known "void" element.
  #[inline]
  pub fn add_raw_content(self, text: &str, bldr: &mut sidoc::Builder) {
    #[cfg(feature = "extra-validation")]
    assert!(!VOID_ELEMENTS.contains(self.tag));

    let line = if let Some(alst) = self.gen_attr_list() {
      format!("<{} {}>{}</{}>", self.tag, alst.join(" "), text, self.tag)
    } else {
      format!("<{}>{}</{}>", self.tag, text, self.tag)
    };
    bldr.line(line);
  }

  /// # Panics
  /// If the `extra-validation` feature is enabled, panic if the tag name is
  /// not a known "void" element.
  pub fn add_opt_content<T>(self, text: &Option<T>, bldr: &mut sidoc::Builder)
  where
    T: AsRef<str>
  {
    #[cfg(feature = "extra-validation")]
    assert!(!VOID_ELEMENTS.contains(self.tag));

    let t = text
      .as_ref()
      .map_or_else(|| Cow::from(""), |t| html_escape::encode_text(t));
    let line = if let Some(alst) = self.gen_attr_list() {
      format!("<{} {}>{}</{}>", self.tag, alst.join(" "), t, self.tag)
    } else {
      format!("<{}>{}</{}>", self.tag, t, self.tag)
    };
    bldr.line(line);
  }


  /// # Panics
  /// If the `extra-validation` feature is enabled, panic if the tag name is
  /// not a known "void" element.
  pub fn add_scope(self, bldr: &mut sidoc::Builder) {
    #[cfg(feature = "extra-validation")]
    assert!(!VOID_ELEMENTS.contains(self.tag));

    let line = if let Some(alst) = self.gen_attr_list() {
      format!("<{} {}>", self.tag, alst.join(" "))
    } else {
      format!("<{}>", self.tag)
    };
    bldr.scope(line, Some(format!("</{}>", self.tag)));
  }

  /// Add an `Element` to a new scope in a `sidoc::Builder`, and call a closure
  /// to allow child nodes to be added within the scope.
  ///
  /// ```
  /// use std::sync::Arc;
  /// use sidoc_html5::Element;
  ///
  /// let mut bldr = sidoc::Builder::new();
  /// let elem = Element::new("div")
  ///   .scope(&mut bldr, |bldr| {
  ///     let elem = Element::new("button")
  ///       .add_raw_content("Do Stuff", bldr);
  ///   });
  ///
  /// let mut r = sidoc::RenderContext::new();
  /// let doc = bldr.build().unwrap();
  /// r.doc("root", Arc::new(doc));
  /// let buf = r.render("root").unwrap();
  ///
  /// // Output should be:
  /// // <div>
  /// //   <button>Do Stuff</button>
  /// // </div>
  /// assert_eq!(buf, "<div>\n  <button>Do Stuff</button>\n</div>\n");
  /// ```
  pub fn scope<F>(self, bldr: &mut sidoc::Builder, f: F)
  where
    F: FnOnce(&mut sidoc::Builder)
  {
    let line = if let Some(alst) = self.gen_attr_list() {
      format!("<{} {}>", self.tag, alst.join(" "))
    } else {
      format!("<{}>", self.tag)
    };
    bldr.scope(line, Some(format!("</{}>", self.tag)));
    f(bldr);
    bldr.exit();
  }
}

// vim: set ft=rust et sw=2 ts=2 sts=2 cinoptions=2 tw=79 :