Crate markupsth

Expand description

§markupsth

A very simple Rust library for writing almost all kinds of formatted text files, escpially Markup files, such as HTML and XML. Its original purpose was to develop a Text-to-HTML converter, but got slowly extended step-by-step. HTML and XML support is default and implemented, but you can also define your own Markup Language by configuring your individual syntax. There are also some pre-defined formatters to either no formatting at all the Markup output or have some out-of-the-box formatting styles for a beautiful and readable HTML code.

For an individual syntax style (own Markup Language), have a look at the syntax module. For an own formatting style (implement your own Formatter to be used with this crate), have a look at the format module.

§Request for changes

In case of interest, I am also willing to extend this crate any time by new Markup Languages, formatting styles, or any other kind of meaningful modifications. Feel free to contact me via Email provided in the manifest file.

§Examples

By using an implemented Markup Language such as HTML or XML, and a pre-defined Formatter, you can quickly write some converter or HTML-generator. Such a quick-start guide can be seen in the following example.

§Readable HTML

To generate the following HTML code:

<!DOCTYPE html>
<html>
<head>
    <title>New Website</title>
    <link href="css/style.css" rel="stylesheet">
</head>
<body>
    <section>
        <div>
            <div><img src="image.jpg"></div>
            <p>This is HTML</p>
        </div>
    </section>
</body>
</html>

you need to implement:

use markupsth::{
    AutoIndent, FixedRule, Language, MarkupSth, properties,
};

// Setup a document (String), MarkupSth and a default formatter.
let mut document = String::new();
let mut mus = MarkupSth::new(&mut document, Language::Html).unwrap();
// Default Formatter is an AutoIndent, so get it, configure it!
let fmtr = mus.formatter.optional_fixed_ruleset().unwrap();
fmtr.add_tags_to_rule(&["head", "body", "section"], FixedRule::IndentAlways)
    .unwrap();
fmtr.add_tags_to_rule(&["html"], FixedRule::LfAlways).unwrap();
fmtr.add_tags_to_rule(&["title", "link", "div", "p"], FixedRule::LfClosing)
    .unwrap();

// Generate the content of example shown above.
mus.open("html").unwrap();
mus.open("head").unwrap();
mus.open_close_w("title", "New Website").unwrap();
mus.self_closing("link").unwrap();
properties!(mus, "href", "css/style.css", "rel", "stylesheet").unwrap();
mus.close().unwrap();
mus.open("body").unwrap();
mus.open("section").unwrap();
mus.open("div").unwrap();
mus.new_line().unwrap();
mus.open("div").unwrap();
mus.self_closing("img").unwrap();
properties!(mus, "src", "image.jpg").unwrap();
mus.close().unwrap();
mus.open_close_w("p", "This is HTML").unwrap();
mus.close_all().unwrap();
mus.finalize().unwrap();

§Readable XML

To generate the following output:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<directory>
    <title>Wikipedia List of Cities</title>
    <entry>
        <keyword>Hamburg</keyword>
        <entrystext>Hamburg is the residence of ...</entrystext>
    </entry>
    <entry>
        <keyword>Munich</keyword>
        <entrystext>Munich is the residence of ...</entrystext>
    </entry>
</directory>

you have to implement:

use markupsth::{AutoIndent, FixedRule, Language, MarkupSth, properties};

let do_entry = |mus: &mut MarkupSth, name: &str| {
    mus.open("entry").unwrap();
    mus.open("keyword").unwrap();
    mus.text(name).unwrap();
    mus.close().unwrap();
    mus.open("entrystext").unwrap();
    mus.text(&format!("{} is the residence of ...", name))
        .unwrap();
    mus.close().unwrap();
    mus.close().unwrap();
};

// Setup a document (String), MarkupSth and a default formatter.
let mut document = String::new();
let mut mus = MarkupSth::new(&mut document, Language::Html).unwrap();

// Default Formatter is an AutoIndent, so get it, configure it!
let fmtr = mus.formatter.optional_fixed_ruleset().unwrap();
fmtr.add_tags_to_rule(&["directory", "entry"], FixedRule::IndentAlways).unwrap();
fmtr.add_tags_to_rule(&["title", "keyword", "entrystext"], FixedRule::LfClosing).unwrap();

// Generate the content of example shown above.
mus.open("directory").unwrap();
mus.open("title").unwrap();
mus.text("Wikipedia List of Cities").unwrap();
mus.close().unwrap();
do_entry(&mut mus, "Hamburg");
do_entry(&mut mus, "Munich");
mus.close_all().unwrap();
mus.finalize().unwrap();

Re-exports§

pub use crate::format::FixedRule;
pub use crate::format::FixedRuleset;
pub use crate::format::Formatter;
pub use crate::markupsth::MarkupSth;
pub use crate::syntax::Language;
pub use crate::formatters::*;

Modules§

format: Contains implementations to model a tag-sequence, changes on format between two following sequences, any kind of formatter, the state of an arbitrary formatter, or optional features of those formatters to be used in MarkupSth.
formatters: Module contains the pre-implemented formatters of this crate. Suche as the NoFormatting, the AlwaysIndentAlwaysLf, and the AutoIndent, which are ready to be used without any effort.
markupsth: This module is home of MarkupSth, the core and ‘writer’ of this crate. MarkupSth owns the syntax configuration and a Formatter, which can be configured individually.
syntax: This module implements the syntax configuration of any kind of Markup Language within this crate. There are currently pre-defined configurations for HTML and XML available, but also the possibility to individually define your own configuration for another ML.

Macros§

properties: Simplifies using MarkupSth::properties() and calls this method internally.

Functions§

testfile: Crate internal support method for some unittests with external reference files.

Type Aliases§

Result: Crate common definition for an optional Result type.

Crate markupsthCopy item path