pulldown-cmark-escape-0.10.0/.cargo_vcs_info.json0000644000000001630000000000100153070ustar { "git": { "sha1": "42bff71ea497c493d740324ebe4b3799dc273b8a" }, "path_in_vcs": "pulldown-cmark-escape" }pulldown-cmark-escape-0.10.0/Cargo.toml0000644000000016770000000000100133200ustar # THIS FILE IS AUTOMATICALLY GENERATED BY CARGO # # When uploading crates to the registry Cargo will automatically # "normalize" Cargo.toml files for maximal compatibility # with all versions of Cargo and also rewrite `path` dependencies # to registry (e.g., crates.io) dependencies. # # If you are reading this file be aware that the original Cargo.toml # will likely look very different (and much more reasonable). # See Cargo.toml.orig for the original contents. [package] edition = "2021" rust-version = "1.70" name = "pulldown-cmark-escape" version = "0.10.0" authors = [ "Raph Levien ", "Marcus Klaas de Vries ", ] description = "An escape library for HTML created in the pulldown-cmark project" readme = "README.md" keywords = [ "escape", "html", "markdown", "commonmark", ] categories = ["text-processing"] license = "MIT" repository = "https://github.com/raphlinus/pulldown-cmark" pulldown-cmark-escape-0.10.0/Cargo.toml.orig000064400000000000000000000010301046102023000167600ustar 00000000000000[package] name = "pulldown-cmark-escape" version = "0.10.0" authors = [ "Raph Levien ", "Marcus Klaas de Vries ", ] license = "MIT" description = "An escape library for HTML created in the pulldown-cmark project" repository = "https://github.com/raphlinus/pulldown-cmark" keywords = ["escape", "html", "markdown", "commonmark"] categories = ["text-processing"] edition = "2021" rust-version = "1.70" # Update README.md and azure-pipelines.yml if this changes. readme = "../README.md" pulldown-cmark-escape-0.10.0/README.md000064400000000000000000000154201046102023000153600ustar 00000000000000# pulldown-cmark [![Build Status](https://dev.azure.com/raphlinus/pulldown-cmark/_apis/build/status/pulldown-cmark-CI?branchName=master)](https://dev.azure.com/raphlinus/pulldown-cmark/_build/latest?definitionId=2&branchName=master) [![Docs](https://docs.rs/pulldown-cmark/badge.svg)](https://docs.rs/pulldown-cmark) [![Crates.io](https://img.shields.io/crates/v/pulldown-cmark.svg?maxAge=2592000)](https://crates.io/crates/pulldown-cmark) [Documentation](https://docs.rs/pulldown-cmark/) This library is a pull parser for [CommonMark](http://commonmark.org/), written in [Rust](http://www.rust-lang.org/). It comes with a simple command-line tool, useful for rendering to HTML, and is also designed to be easy to use from as a library. It is designed to be: * Fast; a bare minimum of allocation and copying * Safe; written in pure Rust with no unsafe blocks (except in the opt-in SIMD feature) * Versatile; in particular source-maps are supported * Correct; the goal is 100% compliance with the [CommonMark spec](http://spec.commonmark.org/) Further, it optionally supports parsing footnotes, [Github flavored tables](https://github.github.com/gfm/#tables-extension-), [Github flavored task lists](https://github.github.com/gfm/#task-list-items-extension-) and [strikethrough](https://github.github.com/gfm/#strikethrough-extension-). Rustc 1.70 or newer is required to build the crate. ## Example Example usage: ```rust // Create parser with example Markdown text. let markdown_input = "hello world"; let parser = pulldown_cmark::Parser::new(markdown_input); // Write to a new String buffer. let mut html_output = String::new(); pulldown_cmark::html::push_html(&mut html_output, parser); assert_eq!(&html_output, "

hello world

\n"); ``` ## Why a pull parser? There are many parsers for Markdown and its variants, but to my knowledge none use pull parsing. Pull parsing has become popular for XML, especially for memory-conscious applications, because it uses dramatically less memory than constructing a document tree, but is much easier to use than push parsers. Push parsers are notoriously difficult to use, and also often error-prone because of the need for user to delicately juggle state in a series of callbacks. In a clean design, the parsing and rendering stages are neatly separated, but this is often sacrificed in the name of performance and expedience. Many Markdown implementations mix parsing and rendering together, and even designs that try to separate them (such as the popular [hoedown](https://github.com/hoedown/hoedown)), make the assumption that the rendering process can be fully represented as a serialized string. Pull parsing is in some sense the most versatile architecture. It's possible to drive a push interface, also with minimal memory, and quite straightforward to construct an AST. Another advantage is that source-map information (the mapping between parsed blocks and offsets within the source text) is readily available; you can call `into_offset_iter()` to create an iterator that yields `(Event, Range)` pairs, where the second element is the event's corresponding range in the source document. While manipulating ASTs is the most flexible way to transform documents, operating on iterators is surprisingly easy, and quite efficient. Here, for example, is the code to transform soft line breaks into hard breaks: ```rust let parser = parser.map(|event| match event { Event::SoftBreak => Event::HardBreak, _ => event }); ``` Or expanding an abbreviation in text: ```rust let parser = parser.map(|event| match event { Event::Text(text) => Event::Text(text.replace("abbr", "abbreviation").into()), _ => event }); ``` Another simple example is code to determine the max nesting level: ```rust let mut max_nesting = 0; let mut level = 0; for event in parser { match event { Event::Start(_) => { level += 1; max_nesting = std::cmp::max(max_nesting, level); } Event::End(_) => level -= 1, _ => () } } ``` Note that consecutive text events can happen due to the manner in which the parser evaluates the source. A utility `TextMergeStream` exists to improve the comfort of iterating the events: ```rust use pulldown_cmark::{Event, Parser, Options}; let markdown_input = "Hello world, this is a ~~complicated~~ *very simple* example."; let iterator = TextMergeStream::new(Parser::new(markdown_input)); for event in iterator { match event { Event::Text(text) => println!("{}", text), _ => {} } } ``` There are some basic but fully functional examples of the usage of the crate in the `examples` directory of this repository. ## Using Rust idiomatically A lot of the internal scanning code is written at a pretty low level (it pretty much scans byte patterns for the bits of syntax), but the external interface is designed to be idiomatic Rust. Pull parsers are at heart an iterator of events (start and end tags, text, and other bits and pieces). The parser data structure implements the Rust Iterator trait directly, and Event is an enum. Thus, you can use the full power and expressivity of Rust's iterator infrastructure, including for loops and `map` (as in the examples above), collecting the events into a vector (for recording, playback, and manipulation), and more. Further, the `Text` event (representing text) is a small copy-on-write string. The vast majority of text fragments are just slices of the source document. For these, copy-on-write gives a convenient representation that requires no allocation or copying, but allocated strings are available when they're needed. Thus, when rendering text to HTML, most text is copied just once, from the source document to the HTML buffer. When using the pulldown-cmark's own HTML renderer, make sure to write to a buffered target like a `Vec` or `String`. Since it performs many (very) small writes, writing directly to stdout, files, or sockets is detrimental to performance. Such writers can be wrapped in a [`BufWriter`](https://doc.rust-lang.org/std/io/struct.BufWriter.html). ## Build options By default, the binary is built as well. If you don't want/need it, then build like this: ```bash > cargo build --no-default-features ``` Or put in your `Cargo.toml` file: ```toml pulldown-cmark = { version = "0.9.2", default-features = false } ``` SIMD accelerated scanners are available for the x64 platform from version 0.5 onwards. To enable them, build with simd feature: ```bash > cargo build --release --features simd ``` Or add the feature to your project's `Cargo.toml`: ```toml pulldown-cmark = { version = "0.9.2", default-features = false, features = ["simd"] } ``` ## Authors The main author is Raph Levien. The implementation of the new design (v0.3+) was completed by Marcus Klaas de Vries. ## Contributions We gladly accept contributions via GitHub pull requests. Please see [CONTRIBUTING.md](CONTRIBUTING.md) for more details. pulldown-cmark-escape-0.10.0/src/lib.rs000064400000000000000000000366741046102023000160220ustar 00000000000000// Copyright 2015 Google Inc. All rights reserved. // // Permission is hereby granted, free of charge, to any person obtaining a copy // of this software and associated documentation files (the "Software"), to deal // in the Software without restriction, including without limitation the rights // to use, copy, modify, merge, publish, distribute, sublicense, and/or sell // copies of the Software, and to permit persons to whom the Software is // furnished to do so, subject to the following conditions: // // The above copyright notice and this permission notice shall be included in // all copies or substantial portions of the Software. // // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, // FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE // AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN // THE SOFTWARE. //! Utility functions for HTML escaping. Only useful when building your own //! HTML renderer. use std::fmt::{Arguments, Write as FmtWrite}; use std::io::{self, ErrorKind, Write}; use std::str::from_utf8; #[rustfmt::skip] static HREF_SAFE: [u8; 128] = [ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 1, 1, 1, 0, 0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 0, 1, 0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 0, 0, 0, 1, 1, 0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 0, 0, 0, 1, 0, ]; static HEX_CHARS: &[u8] = b"0123456789ABCDEF"; static AMP_ESCAPE: &str = "&"; static SINGLE_QUOTE_ESCAPE: &str = "'"; /// This wrapper exists because we can't have both a blanket implementation /// for all types implementing `Write` and types of the for `&mut W` where /// `W: StrWrite`. Since we need the latter a lot, we choose to wrap /// `Write` types. #[derive(Debug)] pub struct WriteWrapper(pub W); /// Trait that allows writing string slices. This is basically an extension /// of `std::io::Write` in order to include `String`. pub trait StrWrite { fn write_str(&mut self, s: &str) -> io::Result<()>; fn write_fmt(&mut self, args: Arguments) -> io::Result<()>; } impl StrWrite for WriteWrapper where W: Write, { #[inline] fn write_str(&mut self, s: &str) -> io::Result<()> { self.0.write_all(s.as_bytes()) } #[inline] fn write_fmt(&mut self, args: Arguments) -> io::Result<()> { self.0.write_fmt(args) } } impl StrWrite for String { #[inline] fn write_str(&mut self, s: &str) -> io::Result<()> { self.push_str(s); Ok(()) } #[inline] fn write_fmt(&mut self, args: Arguments) -> io::Result<()> { // FIXME: translate fmt error to io error? FmtWrite::write_fmt(self, args).map_err(|_| ErrorKind::Other.into()) } } impl StrWrite for &'_ mut W where W: StrWrite, { #[inline] fn write_str(&mut self, s: &str) -> io::Result<()> { (**self).write_str(s) } #[inline] fn write_fmt(&mut self, args: Arguments) -> io::Result<()> { (**self).write_fmt(args) } } /// Writes an href to the buffer, escaping href unsafe bytes. pub fn escape_href(mut w: W, s: &str) -> io::Result<()> where W: StrWrite, { let bytes = s.as_bytes(); let mut mark = 0; for i in 0..bytes.len() { let c = bytes[i]; if c >= 0x80 || HREF_SAFE[c as usize] == 0 { // character needing escape // write partial substring up to mark if mark < i { w.write_str(&s[mark..i])?; } match c { b'&' => { w.write_str(AMP_ESCAPE)?; } b'\'' => { w.write_str(SINGLE_QUOTE_ESCAPE)?; } _ => { let mut buf = [0u8; 3]; buf[0] = b'%'; buf[1] = HEX_CHARS[((c as usize) >> 4) & 0xF]; buf[2] = HEX_CHARS[(c as usize) & 0xF]; let escaped = from_utf8(&buf).unwrap(); w.write_str(escaped)?; } } mark = i + 1; // all escaped characters are ASCII } } w.write_str(&s[mark..]) } const fn create_html_escape_table(body: bool) -> [u8; 256] { let mut table = [0; 256]; table[b'&' as usize] = 1; table[b'<' as usize] = 2; table[b'>' as usize] = 3; if !body { table[b'"' as usize] = 4; table[b'\'' as usize] = 5; } table } static HTML_ESCAPE_TABLE: [u8; 256] = create_html_escape_table(false); static HTML_BODY_TEXT_ESCAPE_TABLE: [u8; 256] = create_html_escape_table(true); static HTML_ESCAPES: [&str; 6] = ["", "&", "<", ">", """, "'"]; /// Writes the given string to the Write sink, replacing special HTML bytes /// (<, >, &, ", ') by escape sequences. /// /// Use this function to write output to quoted HTML attributes. /// Since this function doesn't escape spaces, unquoted attributes /// cannot be used. For example: /// /// ```rust /// let mut value = String::new(); /// pulldown_cmark_escape::escape_html(&mut value, "two words") /// .expect("writing to a string is infallible"); /// // This is okay. /// let ok = format!("test"); /// // This is not okay. /// //let not_ok = format!("test"); /// ```` pub fn escape_html(w: W, s: &str) -> io::Result<()> { #[cfg(all(target_arch = "x86_64", feature = "simd"))] { simd::escape_html(w, s, &HTML_ESCAPE_TABLE) } #[cfg(not(all(target_arch = "x86_64", feature = "simd")))] { escape_html_scalar(w, s, &HTML_ESCAPE_TABLE) } } /// For use in HTML body text, writes the given string to the Write sink, /// replacing special HTML bytes (<, >, &) by escape sequences. /// ///
/// /// This function should be used for escaping text nodes, not attributes. /// In the below example, the word "foo" is an attribute, and the word /// "bar" is an text node. The word "bar" could be escaped by this function, /// but the word "foo" must be escaped using [`escape_html`]. /// /// ```html /// bar /// ``` /// /// If you aren't sure what the difference is, use [`escape_html`]. /// It should always be correct, but will produce larger output. /// ///
pub fn escape_html_body_text(w: W, s: &str) -> io::Result<()> { #[cfg(all(target_arch = "x86_64", feature = "simd"))] { simd::escape_html(w, s, &HTML_BODY_TEXT_ESCAPE_TABLE) } #[cfg(not(all(target_arch = "x86_64", feature = "simd")))] { escape_html_scalar(w, s, &HTML_BODY_TEXT_ESCAPE_TABLE) } } fn escape_html_scalar(mut w: W, s: &str, table: &'static [u8; 256]) -> io::Result<()> { let bytes = s.as_bytes(); let mut mark = 0; let mut i = 0; while i < s.len() { match bytes[i..].iter().position(|&c| table[c as usize] != 0) { Some(pos) => { i += pos; } None => break, } let c = bytes[i]; let escape = table[c as usize]; let escape_seq = HTML_ESCAPES[escape as usize]; w.write_str(&s[mark..i])?; w.write_str(escape_seq)?; i += 1; mark = i; // all escaped characters are ASCII } w.write_str(&s[mark..]) } #[cfg(all(target_arch = "x86_64", feature = "simd"))] mod simd { use super::StrWrite; use std::arch::x86_64::*; use std::io; use std::mem::size_of; const VECTOR_SIZE: usize = size_of::<__m128i>(); pub(super) fn escape_html( mut w: W, s: &str, table: &'static [u8; 256], ) -> io::Result<()> { // The SIMD accelerated code uses the PSHUFB instruction, which is part // of the SSSE3 instruction set. Further, we can only use this code if // the buffer is at least one VECTOR_SIZE in length to prevent reading // out of bounds. If either of these conditions is not met, we fall back // to scalar code. if is_x86_feature_detected!("ssse3") && s.len() >= VECTOR_SIZE { let bytes = s.as_bytes(); let mut mark = 0; unsafe { foreach_special_simd(bytes, 0, |i| { let escape_ix = *bytes.get_unchecked(i) as usize; let entry = table[escape_ix] as usize; w.write_str(s.get_unchecked(mark..i))?; mark = i + 1; // all escaped characters are ASCII if entry == 0 { w.write_str(s.get_unchecked(i..mark)) } else { let replacement = super::HTML_ESCAPES[entry]; w.write_str(replacement) } })?; w.write_str(s.get_unchecked(mark..)) } } else { super::escape_html_scalar(w, s, table) } } /// Creates the lookup table for use in `compute_mask`. const fn create_lookup() -> [u8; 16] { let mut table = [0; 16]; table[(b'<' & 0x0f) as usize] = b'<'; table[(b'>' & 0x0f) as usize] = b'>'; table[(b'&' & 0x0f) as usize] = b'&'; table[(b'"' & 0x0f) as usize] = b'"'; table[(b'\'' & 0x0f) as usize] = b'\''; table[0] = 0b0111_1111; table } #[target_feature(enable = "ssse3")] /// Computes a byte mask at given offset in the byte buffer. Its first 16 (least significant) /// bits correspond to whether there is an HTML special byte (&, <, ", >) at the 16 bytes /// `bytes[offset..]`. For example, the mask `(1 << 3)` states that there is an HTML byte /// at `offset + 3`. It is only safe to call this function when /// `bytes.len() >= offset + VECTOR_SIZE`. unsafe fn compute_mask(bytes: &[u8], offset: usize) -> i32 { debug_assert!(bytes.len() >= offset + VECTOR_SIZE); let table = create_lookup(); let lookup = _mm_loadu_si128(table.as_ptr() as *const __m128i); let raw_ptr = bytes.as_ptr().add(offset) as *const __m128i; // Load the vector from memory. let vector = _mm_loadu_si128(raw_ptr); // We take the least significant 4 bits of every byte and use them as indices // to map into the lookup vector. // Note that shuffle maps bytes with their most significant bit set to lookup[0]. // Bytes that share their lower nibble with an HTML special byte get mapped to that // corresponding special byte. Note that all HTML special bytes have distinct lower // nibbles. Other bytes either get mapped to 0 or 127. let expected = _mm_shuffle_epi8(lookup, vector); // We compare the original vector to the mapped output. Bytes that shared a lower // nibble with an HTML special byte match *only* if they are that special byte. Bytes // that have either a 0 lower nibble or their most significant bit set were mapped to // 127 and will hence never match. All other bytes have non-zero lower nibbles but // were mapped to 0 and will therefore also not match. let matches = _mm_cmpeq_epi8(expected, vector); // Translate matches to a bitmask, where every 1 corresponds to a HTML special character // and a 0 is a non-HTML byte. _mm_movemask_epi8(matches) } /// Calls the given function with the index of every byte in the given byteslice /// that is either ", &, <, or > and for no other byte. /// Make sure to only call this when `bytes.len() >= 16`, undefined behaviour may /// occur otherwise. #[target_feature(enable = "ssse3")] unsafe fn foreach_special_simd( bytes: &[u8], mut offset: usize, mut callback: F, ) -> io::Result<()> where F: FnMut(usize) -> io::Result<()>, { // The strategy here is to walk the byte buffer in chunks of VECTOR_SIZE (16) // bytes at a time starting at the given offset. For each chunk, we compute a // a bitmask indicating whether the corresponding byte is a HTML special byte. // We then iterate over all the 1 bits in this mask and call the callback function // with the corresponding index in the buffer. // When the number of HTML special bytes in the buffer is relatively low, this // allows us to quickly go through the buffer without a lookup and for every // single byte. debug_assert!(bytes.len() >= VECTOR_SIZE); let upperbound = bytes.len() - VECTOR_SIZE; while offset < upperbound { let mut mask = compute_mask(bytes, offset); while mask != 0 { let ix = mask.trailing_zeros(); callback(offset + ix as usize)?; mask ^= mask & -mask; } offset += VECTOR_SIZE; } // Final iteration. We align the read with the end of the slice and // shift off the bytes at start we have already scanned. let mut mask = compute_mask(bytes, upperbound); mask >>= offset - upperbound; while mask != 0 { let ix = mask.trailing_zeros(); callback(offset + ix as usize)?; mask ^= mask & -mask; } Ok(()) } #[cfg(test)] mod html_scan_tests { #[test] fn multichunk() { let mut vec = Vec::new(); unsafe { super::foreach_special_simd("&aXaaaa.a'aa9a<>aab&".as_bytes(), 0, |ix| { #[allow(clippy::unit_arg)] Ok(vec.push(ix)) }) .unwrap(); } assert_eq!(vec, vec![0, 9, 14, 15, 19]); } // only match these bytes, and when we match them, match them VECTOR_SIZE times #[test] fn only_right_bytes_matched() { for b in 0..255u8 { let right_byte = b == b'&' || b == b'<' || b == b'>' || b == b'"' || b == b'\''; let vek = vec![b; super::VECTOR_SIZE]; let mut match_count = 0; unsafe { super::foreach_special_simd(&vek, 0, |_| { match_count += 1; Ok(()) }) .unwrap(); } assert!((match_count > 0) == (match_count == super::VECTOR_SIZE)); assert_eq!( (match_count == super::VECTOR_SIZE), right_byte, "match_count: {}, byte: {:?}", match_count, b as char ); } } } } #[cfg(test)] mod test { pub use super::{escape_href, escape_html, escape_html_body_text}; #[test] fn check_href_escape() { let mut s = String::new(); escape_href(&mut s, "&^_").unwrap(); assert_eq!(s.as_str(), "&^_"); } #[test] fn check_attr_escape() { let mut s = String::new(); escape_html(&mut s, r##"&^"'_"##).unwrap(); assert_eq!(s.as_str(), "&^"'_"); } #[test] fn check_body_escape() { let mut s = String::new(); escape_html_body_text(&mut s, r##"&^"'_"##).unwrap(); assert_eq!(s.as_str(), r##"&^"'_"##); } }