1 // Copyright 2013-2014 The Rust Project Developers. See the COPYRIGHT
2 // file at the top-level directory of this distribution and at
3 // http://rust-lang.org/COPYRIGHT.
4 //
5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
8 // option. This file may not be copied, modified, or distributed
9 // except according to those terms.
10
11 //! Markdown formatting for rustdoc
12 //!
13 //! This module implements markdown formatting through the hoedown C-library
14 //! (bundled into the rust runtime). This module self-contains the C bindings
15 //! and necessary legwork to render markdown, and exposes all of the
16 //! functionality through a unit-struct, `Markdown`, which has an implementation
17 //! of `fmt::Show`. Example usage:
18 //!
19 //! ```rust,ignore
20 //! use rustdoc::html::markdown::Markdown;
21 //!
22 //! let s = "My *markdown* _text_";
23 //! let html = format!("{}", Markdown(s));
24 //! // ... something using html
25 //! ```
26
27 #![allow(non_camel_case_types)]
28
29 use libc;
30 use std::cell::RefCell;
31 use std::fmt;
32 use std::io;
33 use std::slice;
34 use std::str;
35 use collections::HashMap;
36
37 use html::toc::TocBuilder;
38 use html::highlight;
39
40 /// A unit struct which has the `fmt::Show` trait implemented. When
41 /// formatted, this struct will emit the HTML corresponding to the rendered
42 /// version of the contained markdown string.
43 pub struct Markdown<'a>(pub &'a str);
44 /// A unit struct like `Markdown`, that renders the markdown with a
45 /// table of contents.
46 pub struct MarkdownWithToc<'a>(pub &'a str);
47
48 static DEF_OUNIT: libc::size_t = 64;
49 static HOEDOWN_EXT_NO_INTRA_EMPHASIS: libc::c_uint = 1 << 10;
50 static HOEDOWN_EXT_TABLES: libc::c_uint = 1 << 0;
51 static HOEDOWN_EXT_FENCED_CODE: libc::c_uint = 1 << 1;
52 static HOEDOWN_EXT_AUTOLINK: libc::c_uint = 1 << 3;
53 static HOEDOWN_EXT_STRIKETHROUGH: libc::c_uint = 1 << 4;
54 static HOEDOWN_EXT_SUPERSCRIPT: libc::c_uint = 1 << 8;
55 static HOEDOWN_EXT_FOOTNOTES: libc::c_uint = 1 << 2;
56
57 static HOEDOWN_EXTENSIONS: libc::c_uint =
58 HOEDOWN_EXT_NO_INTRA_EMPHASIS | HOEDOWN_EXT_TABLES |
59 HOEDOWN_EXT_FENCED_CODE | HOEDOWN_EXT_AUTOLINK |
60 HOEDOWN_EXT_STRIKETHROUGH | HOEDOWN_EXT_SUPERSCRIPT |
61 HOEDOWN_EXT_FOOTNOTES;
62
63 type hoedown_document = libc::c_void; // this is opaque to us
64
65 struct hoedown_renderer {
66 opaque: *mut hoedown_html_renderer_state,
67 blockcode: Option<extern "C" fn(*mut hoedown_buffer, *hoedown_buffer,
68 *hoedown_buffer, *mut libc::c_void)>,
69 blockquote: Option<extern "C" fn(*mut hoedown_buffer, *hoedown_buffer,
70 *mut libc::c_void)>,
71 blockhtml: Option<extern "C" fn(*mut hoedown_buffer, *hoedown_buffer,
72 *mut libc::c_void)>,
73 header: Option<extern "C" fn(*mut hoedown_buffer, *hoedown_buffer,
74 libc::c_int, *mut libc::c_void)>,
75 other: [libc::size_t, ..28],
76 }
77
78 struct hoedown_html_renderer_state {
79 opaque: *mut libc::c_void,
80 toc_data: html_toc_data,
81 flags: libc::c_uint,
82 link_attributes: Option<extern "C" fn(*mut hoedown_buffer, *hoedown_buffer,
83 *mut libc::c_void)>,
84 }
85
86 struct html_toc_data {
87 header_count: libc::c_int,
88 current_level: libc::c_int,
89 level_offset: libc::c_int,
90 nesting_level: libc::c_int,
91 }
92
93 struct MyOpaque {
94 dfltblk: extern "C" fn(*mut hoedown_buffer, *hoedown_buffer,
95 *hoedown_buffer, *mut libc::c_void),
96 toc_builder: Option<TocBuilder>,
97 }
98
99 struct hoedown_buffer {
100 data: *u8,
101 size: libc::size_t,
102 asize: libc::size_t,
103 unit: libc::size_t,
104 }
105
106 // hoedown FFI
107 #[link(name = "hoedown", kind = "static")]
108 extern {
109 fn hoedown_html_renderer_new(render_flags: libc::c_uint,
110 nesting_level: libc::c_int)
111 -> *mut hoedown_renderer;
112 fn hoedown_html_renderer_free(renderer: *mut hoedown_renderer);
113
114 fn hoedown_document_new(rndr: *mut hoedown_renderer,
115 extensions: libc::c_uint,
116 max_nesting: libc::size_t) -> *mut hoedown_document;
117 fn hoedown_document_render(doc: *mut hoedown_document,
118 ob: *mut hoedown_buffer,
119 document: *u8,
120 doc_size: libc::size_t);
121 fn hoedown_document_free(md: *mut hoedown_document);
122
123 fn hoedown_buffer_new(unit: libc::size_t) -> *mut hoedown_buffer;
124 fn hoedown_buffer_puts(b: *mut hoedown_buffer, c: *libc::c_char);
125 fn hoedown_buffer_free(b: *mut hoedown_buffer);
126
127 }
128
129 /// Returns Some(code) if `s` is a line that should be stripped from
130 /// documentation but used in example code. `code` is the portion of
131 /// `s` that should be used in tests. (None for lines that should be
132 /// left as-is.)
133 fn stripped_filtered_line<'a>(s: &'a str) -> Option<&'a str> {
134 let trimmed = s.trim();
135 if trimmed.starts_with("# ") {
136 Some(trimmed.slice_from(2))
137 } else {
138 None
139 }
140 }
141
142 local_data_key!(used_header_map: RefCell<HashMap<~str, uint>>)
143
144 pub fn render(w: &mut io::Writer, s: &str, print_toc: bool) -> fmt::Result {
145 extern fn block(ob: *mut hoedown_buffer, text: *hoedown_buffer,
146 lang: *hoedown_buffer, opaque: *mut libc::c_void) {
147 unsafe {
148 let opaque = opaque as *mut hoedown_html_renderer_state;
149 let my_opaque: &MyOpaque = &*((*opaque).opaque as *MyOpaque);
150 slice::raw::buf_as_slice((*text).data, (*text).size as uint, |text| {
151 let text = str::from_utf8(text).unwrap();
152 let mut lines = text.lines().filter(|l| {
153 stripped_filtered_line(*l).is_none()
154 });
155 let text = lines.collect::<Vec<&str>>().connect("\n");
156
157 let buf = hoedown_buffer {
158 data: text.as_bytes().as_ptr(),
159 size: text.len() as libc::size_t,
160 asize: text.len() as libc::size_t,
161 unit: 0,
162 };
163 let rendered = if lang.is_null() {
164 false
165 } else {
166 slice::raw::buf_as_slice((*lang).data,
167 (*lang).size as uint, |rlang| {
168 let rlang = str::from_utf8(rlang).unwrap();
169 if rlang.contains("notrust") {
170 (my_opaque.dfltblk)(ob, &buf, lang,
171 opaque as *mut libc::c_void);
172 true
173 } else {
174 false
175 }
176 })
177 };
178
179 if !rendered {
180 let output = highlight::highlight(text, None).to_c_str();
181 output.with_ref(|r| {
182 hoedown_buffer_puts(ob, r)
183 })
184 }
185 })
186 }
187 }
188
189 extern fn header(ob: *mut hoedown_buffer, text: *hoedown_buffer,
190 level: libc::c_int, opaque: *mut libc::c_void) {
191 // hoedown does this, we may as well too
192 "\n".with_c_str(|p| unsafe { hoedown_buffer_puts(ob, p) });
193
194 // Extract the text provided
195 let s = if text.is_null() {
196 "".to_owned()
197 } else {
198 unsafe {
199 str::raw::from_buf_len((*text).data, (*text).size as uint)
200 }
201 };
202
203 // Transform the contents of the header into a hyphenated string
204 let id = s.words().map(|s| {
205 match s.to_ascii_opt() {
206 Some(s) => s.to_lower().into_str(),
207 None => s.to_owned()
208 }
209 }).collect::<Vec<~str>>().connect("-");
210
211 // This is a terrible hack working around how hoedown gives us rendered
212 // html for text rather than the raw text.
213 let id = id.replace("<code>", "").replace("</code>", "");
214
215 let opaque = opaque as *mut hoedown_html_renderer_state;
216 let opaque = unsafe { &mut *((*opaque).opaque as *mut MyOpaque) };
217
218 // Make sure our hyphenated ID is unique for this page
219 let map = used_header_map.get().unwrap();
220 let id = match map.borrow_mut().find_mut(&id) {
221 None => id,
222 Some(a) => { *a += 1; format!("{}-{}", id, *a - 1) }
223 };
224 map.borrow_mut().insert(id.clone(), 1);
225
226 let sec = match opaque.toc_builder {
227 Some(ref mut builder) => {
228 builder.push(level as u32, s.clone(), id.clone())
229 }
230 None => {""}
231 };
232
233 // Render the HTML
234 let text = format!(r#"<h{lvl} id="{id}" class='section-header'><a
235 href="\#{id}">{sec_len,plural,=0{}other{{sec} }}{}</a></h{lvl}>"#,
236 s, lvl = level, id = id,
237 sec_len = sec.len(), sec = sec);
238
239 text.with_c_str(|p| unsafe { hoedown_buffer_puts(ob, p) });
240 }
241
242 unsafe {
243 let ob = hoedown_buffer_new(DEF_OUNIT);
244 let renderer = hoedown_html_renderer_new(0, 0);
245 let mut opaque = MyOpaque {
246 dfltblk: (*renderer).blockcode.unwrap(),
247 toc_builder: if print_toc {Some(TocBuilder::new())} else {None}
248 };
249 (*(*renderer).opaque).opaque = &mut opaque as *mut _ as *mut libc::c_void;
250 (*renderer).blockcode = Some(block);
251 (*renderer).header = Some(header);
252
253 let document = hoedown_document_new(renderer, HOEDOWN_EXTENSIONS, 16);
254 hoedown_document_render(document, ob, s.as_ptr(),
255 s.len() as libc::size_t);
256 hoedown_document_free(document);
257
258 hoedown_html_renderer_free(renderer);
259
260 let mut ret = match opaque.toc_builder {
261 Some(b) => write!(w, "<nav id=\"TOC\">{}</nav>", b.into_toc()),
262 None => Ok(())
263 };
264
265 if ret.is_ok() {
266 ret = slice::raw::buf_as_slice((*ob).data, (*ob).size as uint, |buf| {
267 w.write(buf)
268 });
269 }
270 hoedown_buffer_free(ob);
271 ret
272 }
273 }
274
275 pub fn find_testable_code(doc: &str, tests: &mut ::test::Collector) {
276 extern fn block(_ob: *mut hoedown_buffer, text: *hoedown_buffer,
277 lang: *hoedown_buffer, opaque: *mut libc::c_void) {
278 unsafe {
279 if text.is_null() { return }
280 let (should_fail, no_run, ignore, notrust) = if lang.is_null() {
281 (false, false, false, false)
282 } else {
283 slice::raw::buf_as_slice((*lang).data,
284 (*lang).size as uint, |lang| {
285 let s = str::from_utf8(lang).unwrap();
286 (s.contains("should_fail"),
287 s.contains("no_run"),
288 s.contains("ignore"),
289 s.contains("notrust"))
290 })
291 };
292 if notrust { return }
293 slice::raw::buf_as_slice((*text).data, (*text).size as uint, |text| {
294 let opaque = opaque as *mut hoedown_html_renderer_state;
295 let tests = &mut *((*opaque).opaque as *mut ::test::Collector);
296 let text = str::from_utf8(text).unwrap();
297 let mut lines = text.lines().map(|l| {
298 stripped_filtered_line(l).unwrap_or(l)
299 });
300 let text = lines.collect::<Vec<&str>>().connect("\n");
301 tests.add_test(text, should_fail, no_run, ignore);
302 })
303 }
304 }
305
306 extern fn header(_ob: *mut hoedown_buffer, text: *hoedown_buffer,
307 level: libc::c_int, opaque: *mut libc::c_void) {
308 unsafe {
309 let opaque = opaque as *mut hoedown_html_renderer_state;
310 let tests = &mut *((*opaque).opaque as *mut ::test::Collector);
311 if text.is_null() {
312 tests.register_header("", level as u32);
313 } else {
314 slice::raw::buf_as_slice((*text).data, (*text).size as uint, |text| {
315 let text = str::from_utf8(text).unwrap();
316 tests.register_header(text, level as u32);
317 })
318 }
319 }
320 }
321
322 unsafe {
323 let ob = hoedown_buffer_new(DEF_OUNIT);
324 let renderer = hoedown_html_renderer_new(0, 0);
325 (*renderer).blockcode = Some(block);
326 (*renderer).header = Some(header);
327 (*(*renderer).opaque).opaque = tests as *mut _ as *mut libc::c_void;
328
329 let document = hoedown_document_new(renderer, HOEDOWN_EXTENSIONS, 16);
330 hoedown_document_render(document, ob, doc.as_ptr(),
331 doc.len() as libc::size_t);
332 hoedown_document_free(document);
333
334 hoedown_html_renderer_free(renderer);
335 hoedown_buffer_free(ob);
336 }
337 }
338
339 /// By default this markdown renderer generates anchors for each header in the
340 /// rendered document. The anchor name is the contents of the header spearated
341 /// by hyphens, and a task-local map is used to disambiguate among duplicate
342 /// headers (numbers are appended).
343 ///
344 /// This method will reset the local table for these headers. This is typically
345 /// used at the beginning of rendering an entire HTML page to reset from the
346 /// previous state (if any).
347 pub fn reset_headers() {
348 used_header_map.replace(Some(RefCell::new(HashMap::new())));
349 }
350
351 impl<'a> fmt::Show for Markdown<'a> {
352 fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
353 let Markdown(md) = *self;
354 // This is actually common enough to special-case
355 if md.len() == 0 { return Ok(()) }
356 render(fmt.buf, md.as_slice(), false)
357 }
358 }
359
360 impl<'a> fmt::Show for MarkdownWithToc<'a> {
361 fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
362 let MarkdownWithToc(md) = *self;
363 render(fmt.buf, md.as_slice(), true)
364 }
365 }
librustdoc/html/markdown.rs:346:29-346:29 -fn- definition:
/// previous state (if any).
pub fn reset_headers() {
used_header_map.replace(Some(RefCell::new(HashMap::new())));
references:- 2librustdoc/html/render.rs:
876: markdown::reset_headers();
librustdoc/markdown.rs:
117: reset_headers();
librustdoc/html/markdown.rs:62:1-62:1 -NK_AS_STR_TODO- definition:
type hoedown_document = libc::c_void; // this is opaque to us
struct hoedown_renderer {
opaque: *mut hoedown_html_renderer_state,
references:- 3115: extensions: libc::c_uint,
116: max_nesting: libc::size_t) -> *mut hoedown_document;
117: fn hoedown_document_render(doc: *mut hoedown_document,
118: ob: *mut hoedown_buffer,
--
120: doc_size: libc::size_t);
121: fn hoedown_document_free(md: *mut hoedown_document);
librustdoc/html/markdown.rs:77:1-77:1 -struct- definition:
struct hoedown_html_renderer_state {
opaque: *mut libc::c_void,
toc_data: html_toc_data,
references:- 5215: let opaque = opaque as *mut hoedown_html_renderer_state;
216: let opaque = unsafe { &mut *((*opaque).opaque as *mut MyOpaque) };
--
293: slice::raw::buf_as_slice((*text).data, (*text).size as uint, |text| {
294: let opaque = opaque as *mut hoedown_html_renderer_state;
295: let tests = &mut *((*opaque).opaque as *mut ::test::Collector);
--
308: unsafe {
309: let opaque = opaque as *mut hoedown_html_renderer_state;
310: let tests = &mut *((*opaque).opaque as *mut ::test::Collector);
librustdoc/html/markdown.rs:98:1-98:1 -struct- definition:
struct hoedown_buffer {
data: *u8,
size: libc::size_t,
references:- 29157: let buf = hoedown_buffer {
158: data: text.as_bytes().as_ptr(),
--
189: extern fn header(ob: *mut hoedown_buffer, text: *hoedown_buffer,
190: level: libc::c_int, opaque: *mut libc::c_void) {
--
306: extern fn header(_ob: *mut hoedown_buffer, text: *hoedown_buffer,
307: level: libc::c_int, opaque: *mut libc::c_void) {
librustdoc/html/markdown.rs:132:17-132:17 -fn- definition:
/// left as-is.)
fn stripped_filtered_line<'a>(s: &'a str) -> Option<&'a str> {
let trimmed = s.trim();
references:- 2297: let mut lines = text.lines().map(|l| {
298: stripped_filtered_line(l).unwrap_or(l)
299: });
librustdoc/html/markdown.rs:143:1-143:1 -fn- definition:
pub fn render(w: &mut io::Writer, s: &str, print_toc: bool) -> fmt::Result {
extern fn block(ob: *mut hoedown_buffer, text: *hoedown_buffer,
lang: *hoedown_buffer, opaque: *mut libc::c_void) {
references:- 2355: if md.len() == 0 { return Ok(()) }
356: render(fmt.buf, md.as_slice(), false)
357: }
--
362: let MarkdownWithToc(md) = *self;
363: render(fmt.buf, md.as_slice(), true)
364: }
librustdoc/html/markdown.rs:92:1-92:1 -struct- definition:
struct MyOpaque {
dfltblk: extern "C" fn(*mut hoedown_buffer, *hoedown_buffer,
*hoedown_buffer, *mut libc::c_void),
references:- 4244: let renderer = hoedown_html_renderer_new(0, 0);
245: let mut opaque = MyOpaque {
246: dfltblk: (*renderer).blockcode.unwrap(),
librustdoc/html/markdown.rs:64:1-64:1 -struct- definition:
struct hoedown_renderer {
opaque: *mut hoedown_html_renderer_state,
blockcode: Option<extern "C" fn(*mut hoedown_buffer, *hoedown_buffer,
references:- 3110: nesting_level: libc::c_int)
111: -> *mut hoedown_renderer;
112: fn hoedown_html_renderer_free(renderer: *mut hoedown_renderer);
114: fn hoedown_document_new(rndr: *mut hoedown_renderer,
115: extensions: libc::c_uint,
librustdoc/html/markdown.rs:274:1-274:1 -fn- definition:
pub fn find_testable_code(doc: &str, tests: &mut ::test::Collector) {
extern fn block(_ob: *mut hoedown_buffer, text: *hoedown_buffer,
lang: *hoedown_buffer, opaque: *mut libc::c_void) {
references:- 2librustdoc/test.rs:
283: self.cnt = 0;
284: markdown::find_testable_code(doc, &mut *self);
285: }
librustdoc/markdown.rs:
167: let mut collector = Collector::new(input.to_owned(), libs, true, true);
168: find_testable_code(input_str, &mut collector);
169: test_args.unshift("rustdoctest".to_owned());