nemo157 / hamlet Goto Github PK

1.0 3.0 1.0 651 KB

HTML streaming token definitions for Rust

License: Apache License 2.0

Rust 94.70% Shell 5.30%

hamlet's Introduction

hamlet

Provides token definitions for HTML stream processing. The goal of this library is to provide a simple API over which higher abstraction can be built on.

Example

#[macro_use]
extern crate hamlet;

use std::fmt::Write;

fn main() {
    use hamlet::Token;
    let tokens = vec![
        Token::text("Hello, "),
        Token::start_tag("small", attrs!(class="foo")),
        Token::text("world!"),
        Token::end_tag("small"),
    ];

    let mut html = String::from("");
    for token in tokens {
        write!(html, "{}", token);
    }

    assert_eq!(html, "Hello, <small class=\"foo\">world!</small>");
}

License

Licensed under either of

Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you shall be dual licensed as above, without any additional terms or conditions.

hamlet's People

Contributors

Stargazers

Watchers

Forkers

critiqjo

hamlet's Issues

Feature: CloserWriter

Okay, the name is dumb! Anyway, here's the API I'd like:

impl<E> CloserWriter<E> {
    pub fn from_io(w: &mut io::Write) -> CloserWriter<io::Error>;
    pub fn from_fmt(w: &mut fmt::Write) -> CloserWriter<fmt::Error>;

    // Returns the current depth (number of unclosed start_tags).
    // If an `EndTag` is given, verifies if it is correct.
    pub fn write(&mut self, token) -> Result<usize, CloserError<E>>;

    // closes the last tag and returns the new depth
    pub fn close_tag(&mut self) -> Result<usize, CloserError<E>>;

    // closes tags until the specified depth is reached
    pub fn close_till(&mut self, depth) -> Result<(), CloserError<E>>; // useful?
}

enum CloserError<E> {
    CloseUnmatched, // zero-depth close or invalid end-tag
    StreamError(E),
}

Maintaining a stack of tag names will do to accomplish this. Document that raw text, tag names or attribute names are not verified. May be we can provide another wrapper over this called SafeWriter in future. Another possible extension is pretty printing the tags.

Add an error token?

It could be good to add a generic Token::Error(E) variant, so that parsers may convey that an error occurred.

pub enum Token<'a, E> {
    ...
    Error(pub E),
}

I'll leave this open till someone gets time to think about the nitty-gritty details, and issue a PR...

Investigate performance

hamlet is about 75% slower than horrorshow on a very simple hello world benchmark (hamlet bench code, horrorshow bench code, my results). There should be no reason for anywhere near this performance difference, at a guess it's from std::fmt.

Change AttributeList from Cow to plain Vec?

I'm not sure if Cow<[_]> is a clear winner over Vec<_>. The reason behind sticking to Cow[_] is that for empty attribute list, creating a Cow::Borrowed(&[]) must be faster than vec![]. But then again if there's not much gain, or if empty attribute list is not that common, then having Cow is just an overhead.

PS: html5ever uses Vec

Random rants!

General discussion thread!

Request to rebase and open a PR

It would be easier to collaborate if you just leave an initial commit in master adding a README.md (saying "WIP"), Cargo.toml and .gitignore, and open a PR for the rest of the commits. It'd be easier to add inline comments and all... We'll finalize on a design and merge it?

Also, can you add me as a collaborator?

Rename the repo?

What I could come up with: html-duck, html-dodge, hornbill, hairtail, hamlet, ...

Suggest more and let's choose one...