Struct bloguen::ops::BlogueDescriptor

pub struct BlogueDescriptor {
    pub name: String,
    pub author: Option<String>,
    pub header_file: (String, PathBuf),
    pub footer_file: (String, PathBuf),
    pub asset_dir_override: Option<String>,
    pub index: Option<BlogueDescriptorIndex>,
    pub machine_data: BTreeMap<MachineDataKind, String>,
    pub feeds: BTreeMap<FeedType, String>,
    pub language: Option<LanguageTag>,
    pub styles: Vec<StyleElement>,
    pub scripts: Vec<ScriptElement>,
    pub data: BTreeMap<String, String>,
}

Generic blogue metadata.

Fields

name: String

The blogue's display name.

author: Option<String>

The blogue's main author(s).

Overriden by post metadata, if present.

If not present, defaults to the current system user's name, which, if not detected, errors out.

header_file: (String, PathBuf)

Data to put before post HTML, templated.

Default: "$ROOT/header.html", then "$ROOT/header.htm".

footer_file: (String, PathBuf)

Data to put after post HTML, templated.

Default: "$ROOT/footer.html", then "$ROOT/footer.htm".

asset_dir_override: Option<String>

Subfolder to move assets to, relative to the output root, if present.

The value is stripped of leading slashes. All backslashes are normalised to forward ones. The value is ended off with a slash, if not already specified.

No override is applied if not present – assets are copied alongside the posts' HTML.

index: Option<BlogueDescriptorIndex>

Metadata specifying how to generate the blogue index file.

If not present, index not generated.

machine_data: BTreeMap<MachineDataKind, String>

Where and which machine datasets to put.

Each value here is a prefix appended to the output directory under which to put the machine data.

Values can't be empty (to put machine data at post root use "./").

feeds: BTreeMap<FeedType, String>

Where and which feeds to put.

Each value here is a file path appended to the output directory into which to put the machine data.

language: Option<LanguageTag>

Default post language.

Overriden by post metadata, if present.

If not present, defaults to the current system language, which, if not detected, defaults to en-GB.

styles: Vec<StyleElement>

A set of style descriptors.

If not present, defaults to empty.

scripts: Vec<ScriptElement>

A set of style descriptors.

If not present, defaults to empty.

data: BTreeMap<String, String>

Additional static data to substitute in header and footer.

If not present, defaults to empty.

Methods

impl BlogueDescriptor

pub fn read(root: &(String, PathBuf)) -> Result<BlogueDescriptor, Error>

Read the blogue descriptor from the specified root firectory.

Examples

Given the following directory layout:

$ROOT
  blogue.toml
  head.html
  footer.htm
  idx_head.html
  центр.html
  index_footer.htm

Given $ROOT/blogue.toml containing:

name = "Блогг"
header = "head.html"
language = "pl"
asset_dir = "assets"

[index]
header = "idx_head.html"
center = "центр.html"
order = "backward"
styles = ["literal:.indented { text-indent: 1em; }"]

[[scripts]]
class = "link"
data = "/content/assets/syllable.js"

[[scripts]]
class = "file"
data = "MathJax-config.js"

[machine_data]
JSON = "metadata/json/"

[feeds]
RSS = "feed.rss"
ATOM = "feed.atom"

[data]
preferred_system = "capitalism"

The following holds:

let root: PathBuf = /* obtained elsewhere */;
let read_tokens = BlogueDescriptor::read(&("$ROOT/".to_string(), root.clone())).unwrap();
assert_eq!(
    read_tokens,
    BlogueDescriptor {
        name: "Блогг".to_string(),
        author: None,
        header_file: ("$ROOT/head.html".to_string(), root.join("head.html")),
        footer_file: ("$ROOT/footer.htm".to_string(), root.join("footer.htm")),
        asset_dir_override: Some("assets/".to_string()),
        machine_data: vec![(MachineDataKind::Json, "metadata/json/".to_string())].into_iter().collect(),
        feeds: vec![(FeedType::Rss, "feed.rss".to_string()),
                    (FeedType::Atom, "feed.atom".to_string())].into_iter().collect(),
        language: Some("pl".parse().unwrap()),
        styles: vec![],
        scripts: vec![ScriptElement::from_link("/content/assets/syllable.js"),
                      ScriptElement::from_path("MathJax-config.js")],
        index: Some(BlogueDescriptorIndex {
            header_file: ("$ROOT/idx_head.html".to_string(), root.join("idx_head.html")),
            center_file: ("$ROOT/центр.html".to_string(), root.join("центр.html")),
            footer_file: ("$ROOT/index_footer.htm".to_string(), root.join("index_footer.htm")),
            center_order: CenterOrder::Backward,
            styles: vec![StyleElement::from_literal(".indented { text-indent: 1em; }")],
            scripts: vec![],
            data: vec![].into_iter().collect(),
        }),
        data: vec![("preferred_system".to_string(),
                    "capitalism".to_string())].into_iter().collect(),
    });

pub fn create_feed_output(
    &self,
    into: &(String, PathBuf),
    fname: &str,
    tp: &FeedType
) -> Result<File, Error>

Create a feed output file of the specified type into the specified subpath in the specified output directory.

Examples

let root: PathBuf = /* obtained elsewhere */;
let descriptor: BlogueDescriptor = /* irrelevant */;
descriptor.create_feed_output(&("$ROOT/".to_string(), root.clone()), "feeds/rss.xml",
                              &FeedType::Rss).unwrap();

assert!(root.join("feeds").join("rss.xml").is_file());

pub fn generate_feed_head<T: Write>(
    &self,
    into: &mut T,
    tp: &FeedType,
    fname: &str,
    language: &LanguageTag,
    author: &str
) -> Result<(), Error>

Generate header for the specified type of feed for this descriptor.

Examples

Given $ROOT/blogue.toml containing:

name = "Блогг"
index = {}

The following holds:

let root: PathBuf = /* obtained elsewhere */;
let mut descriptor = BlogueDescriptor::read(&("$ROOT/".to_string(), root.clone())).unwrap();

let mut out = vec![];
descriptor.generate_feed_head(&mut out, &FeedType::Rss, "feeds/rss.xml",
                                        &LANGUAGE_EN_GB, "nabijaczleweli").unwrap();

let out = String::from_utf8(out).unwrap();
let gendate_local_rfc2822 = /* extracted from output's lastBuildDate tag */;
assert_eq!(out, format!(r###"<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0">
  <channel>
    <docs>https://validator.w3.org/feed/docs/rss2.html</docs>
    <title>Блогг</title>
    <author>nabijaczleweli</author>
    <link>../index.html</link>
    <description>Блогг</description>
    <language>en-GB</language>
    <generator>bloguen 0.1.1</generator>
    <pubDate>{0}</pubDate>
    <lastBuildDate>{0}</lastBuildDate>
"###, gendate_local_rfc2822));

// And

let mut out = vec![];
descriptor.index = None;
descriptor.generate_feed_head(&mut out, &FeedType::Rss, "feeds/rss.xml",
                                        &LANGUAGE_EN_GB, "nabijaczleweli").unwrap();

let out = String::from_utf8(out).unwrap();
let gendate_local_rfc2822 = /* extracted from output's lastBuildDate tag */;
assert_eq!(out, format!(r###"<?xml version="1.0" encoding="UTF-8"?>
<rss version="2.0">
  <channel>
    <docs>https://validator.w3.org/feed/docs/rss2.html</docs>
    <title>Блогг</title>
    <author>nabijaczleweli</author>
    <description>Блогг</description>
    <language>en-GB</language>
    <generator>bloguen 0.1.1</generator>
    <pubDate>{0}</pubDate>
    <lastBuildDate>{0}</lastBuildDate>
"###, gendate_local_rfc2822));

pub fn generate_feed_foot<T: Write>(
    &self,
    into: &mut T,
    tp: &FeedType
) -> Result<(), Error>

Generate footer for the specified type of feed for this descriptor.

Examples

let root: PathBuf = /* obtained elsewhere */;
let descriptor: BlogueDescriptor = /* irrelevant */;

let mut out = vec![];
descriptor.generate_feed_foot(&mut out, &FeedType::Rss).unwrap();

assert_eq!(String::from_utf8(out).unwrap(), r###"  </channel>
</rss>
"###);

Trait Implementations

impl Eq for BlogueDescriptor

impl Clone for BlogueDescriptor

fn clone(&self) -> BlogueDescriptor

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl PartialOrd<BlogueDescriptor> for BlogueDescriptor

fn partial_cmp(&self, other: &BlogueDescriptor) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &BlogueDescriptor) -> bool

This method tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &BlogueDescriptor) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &BlogueDescriptor) -> bool

This method tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &BlogueDescriptor) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl PartialEq<BlogueDescriptor> for BlogueDescriptor

fn eq(&self, other: &BlogueDescriptor) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &BlogueDescriptor) -> bool

This method tests for !=.

impl Ord for BlogueDescriptor

fn cmp(&self, other: &BlogueDescriptor) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

🔬 This is a nightly-only experimental API. (clamp)

Restrict a value to a certain interval.

impl Hash for BlogueDescriptor

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given [Hasher].

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given [Hasher].

impl Debug for BlogueDescriptor

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.