1 //! Module containing the `Renderer` interface for constructing a 2 //! particular text output. 3 4 pub mod text_renderer; 5 6 /// A type which is a backend for HTML to text rendering. 7 pub trait Renderer { 8 /// Add an empty line to the output (ie between blocks). add_empty_line(&mut self)9 fn add_empty_line(&mut self); 10 11 /// Create a sub-renderer for nested blocks. new_sub_renderer(&self, width: usize) -> Self12 fn new_sub_renderer(&self, width: usize) -> Self; 13 14 /// Start a new block. start_block(&mut self)15 fn start_block(&mut self); 16 17 /// Mark the end of a block. end_block(&mut self)18 fn end_block(&mut self); 19 20 /// Start a new line, if necessary (but don't add a new line). new_line(&mut self)21 fn new_line(&mut self); 22 23 /// Start a new line. new_line_hard(&mut self)24 fn new_line_hard(&mut self); 25 26 /// Add a horizontal table border. add_horizontal_border(&mut self)27 fn add_horizontal_border(&mut self); 28 29 /// Begin a preformatted block. Until the corresponding end, 30 /// whitespace will used verbatim. Pre regions can nest. start_pre(&mut self)31 fn start_pre(&mut self); 32 33 /// Finish a preformatted block started with `start_pre`. end_pre(&mut self)34 fn end_pre(&mut self); 35 36 /// Add some inline text (which should be wrapped at the 37 /// appropriate width) to the current block. add_inline_text(&mut self, text: &str)38 fn add_inline_text(&mut self, text: &str); 39 40 /// Return the current width in character cells width(&self) -> usize41 fn width(&self) -> usize; 42 43 /// Add a line to the current block without starting a new one. add_block_line(&mut self, line: &str)44 fn add_block_line(&mut self, line: &str); 45 46 /// Add a new block from a sub renderer, and prefix every line by the 47 /// corresponding text from each iteration of prefixes. append_subrender<'a, I>(&mut self, other: Self, prefixes: I) where I: Iterator<Item = &'a str>48 fn append_subrender<'a, I>(&mut self, other: Self, prefixes: I) 49 where 50 I: Iterator<Item = &'a str>; 51 52 /// Append a set of sub renderers joined left-to-right with a vertical line, 53 /// and add a horizontal line below. 54 /// If collapse is true, then merge top/bottom borders of the subrenderer 55 /// with the surrounding one. append_columns_with_borders<I>(&mut self, cols: I, collapse: bool) where I: IntoIterator<Item = Self>, Self: Sized56 fn append_columns_with_borders<I>(&mut self, cols: I, collapse: bool) 57 where 58 I: IntoIterator<Item = Self>, 59 Self: Sized; 60 61 /// Returns true if this renderer has no content. empty(&self) -> bool62 fn empty(&self) -> bool; 63 64 /// Return the length of the contained text. text_len(&self) -> usize65 fn text_len(&self) -> usize; 66 67 /// Start a hyperlink 68 /// TODO: return sub-builder or similar to make misuse 69 /// of start/link harder? start_link(&mut self, target: &str)70 fn start_link(&mut self, target: &str); 71 72 /// Finish a hyperlink started earlier. end_link(&mut self)73 fn end_link(&mut self); 74 75 /// Start an emphasised region start_emphasis(&mut self)76 fn start_emphasis(&mut self); 77 78 /// Finish emphasised text started earlier. end_emphasis(&mut self)79 fn end_emphasis(&mut self); 80 81 /// Start a strong region start_strong(&mut self)82 fn start_strong(&mut self); 83 84 /// Finish strong text started earlier. end_strong(&mut self)85 fn end_strong(&mut self); 86 87 /// Start a strikeout region start_strikeout(&mut self)88 fn start_strikeout(&mut self); 89 90 /// Finish strikeout text started earlier. end_strikeout(&mut self)91 fn end_strikeout(&mut self); 92 93 /// Start a code region start_code(&mut self)94 fn start_code(&mut self); 95 96 /// End a code region end_code(&mut self)97 fn end_code(&mut self); 98 99 /// Add an image add_image(&mut self, title: &str)100 fn add_image(&mut self, title: &str); 101 102 /// Record the start of a named HTML fragment record_frag_start(&mut self, fragname: &str)103 fn record_frag_start(&mut self, fragname: &str); 104 } 105