1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217
// Copyright (C) 2016 Élisabeth HENRY. // // This file is part of Crowbook. // // Crowbook is free software: you can redistribute it and/or modify // it under the terms of the GNU Lesser General Public License as published // by the Free Software Foundation, either version 2.1 of the License, or // (at your option) any later version. // // Crowbook is distributed in the hope that it will be useful, // but WITHOUT ANY WARRANTY; without even the implied warranty of // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the // GNU Lesser General Public License for more details. // // You should have received a copy of the GNU Lesser General Public License // along with Crowbook. If not, see <http://www.gnu.org/licenses/>. //! Note: this documentation is relative to `crowbook` *as a library*. //! For documentation regarding the *program* `crowbook`, see //! [the Github page](https://github.com/lise-henry/crowbook). //! //! # Usage //! //! Just like any other library, just add a dependency on `crowbook` //! in your `Cargo.toml` file. You will probably want to deactivate //! default features that are mostly useful for the binary: //! //! ```ignore //! crowbook = {version = "0.11", default-features = false} //! ``` //! //! # Book //! //! The central structure of Crowbook is `Book`, which coordinates everything. //! //! Its roles are: //! //! * read a book configuration file and setting the book options accordingly; //! * read the chapters (written in Markdown) listed in this //! configuration file and pass them to to `Parser`, get back an AST and store it in memory //! * call the various renderers according to the book's parameters //! and generate the appopriate files. //! //! ## Example //! //! ```ignore //! use crowbook::Book; //! // Reads configuration file "foo.book" and render all formats according to this //! // configuration file //! Book::new() //! .load_file("foo.book").unwrap() //! .render_all().unwrap(); //! ``` //! //! This is basically the code for the `crowbook` binary (though it contains a //! bit more error handling, checking parameters from command line and so on). //! This is, however, not very interesting for a library usage. //! //! The `Book` structure, however, exposes its `chapter` fields, which contains //! a vector with an element by chapter. With it, you can access the Markdown //! for all chapters represented as an Abstact Syntax Tree (i.e., a vector of `Token`s). //! It is thus possible to create a new renderer (or manipulate this AST in other ways). //! //! # Parser //! //! It is also possible to directly use `Parser` to transform some markdown string or file //! to this AST: //! //! ``` //! use crowbook::{Parser,Token}; //! let mut parser = Parser::new(); //! let result = parser.parse("Some *valid* Markdown").unwrap(); //! assert_eq!(format!("{:?}", result), //! r#"[Paragraph([Str("Some "), Emphasis([Str("valid")]), Str(" Markdown")])]"#); //! ``` //! //! Of course, you probably want to do something else with this AST than display it. //! Let's assume you want to count the number of links in a document. //! //! ``` //! use crowbook::{Parser,Token}; //! fn count(ast: &[Token]) -> u32 { //! let mut n = 0; //! for token in ast { //! match *token { //! // It's a link, increase counter //! Token::Link(_,_,_) => n += 1, //! // It's not a link, let's count the number of links //! // inside of the inner element (if there is one) //! _ => { //! if let Some(sub_ast) = token.inner() { //! n += count(sub_ast); //! } //! } //! } //! } //! n //! } //! //! let md = "# Here's a [link](http://foo.bar) #\n And *another [one](http://foo.bar)* !"; //! //! let mut parser = Parser::new(); //! let ast = parser.parse(md).unwrap(); //! assert_eq!(count(&ast), 2); //! ``` extern crate pulldown_cmark as cmark; extern crate mustache; extern crate yaml_rust; extern crate mime_guess; extern crate walkdir; extern crate rustc_serialize; extern crate rayon; extern crate crowbook_text_processing; extern crate crowbook_intl_runtime; extern crate numerals; extern crate epub_builder; extern crate uuid; #[macro_use] extern crate log; #[macro_use] extern crate lazy_static; #[cfg(feature = "indicatif")] extern crate indicatif; #[cfg(feature = "binary")] extern crate console; #[cfg(feature = "binary")] extern crate textwrap; #[cfg(feature = "proofread")] extern crate hyper; #[cfg(feature = "proofread")] extern crate url; #[cfg(feature = "proofread")] extern crate caribon; #[cfg(feature = "proofread")] extern crate serde; #[cfg(feature = "proofread")] extern crate serde_json; #[cfg(feature = "proofread")] #[macro_use] extern crate serde_derive; #[cfg(feature = "syntect")] extern crate syntect; pub use parser::Parser; pub use book::Book; pub use bookoption::BookOption; pub use bookoptions::BookOptions; pub use error::{Result, Error, Source}; pub use token::Token; pub use token::Data; pub use number::Number; pub use resource_handler::ResourceHandler; pub use renderer::Renderer; pub use book_renderer::BookRenderer; pub use chapter::Chapter; pub use stats::Stats; #[macro_use] #[doc(hidden)] mod localize_macros; #[macro_use] mod html; mod html_dir; mod error; mod book; mod epub; mod latex; mod odt; mod parser; mod token; mod cleaner; mod chapter; mod number; mod resource_handler; mod bookoptions; mod lang; mod renderer; mod book_renderer; mod html_single; mod html_if; mod syntax; mod stats; #[cfg(feature = "binary")] mod style; #[cfg(not(feature = "binary"))] mod style_stubs; #[cfg(not(feature = "binary"))] use style_stubs as style; #[cfg(feature = "indicatif")] mod book_bars; #[cfg(not(feature = "indicatif"))] mod book_bars_stubs; #[cfg(not(feature = "indicatif"))] use book_bars_stubs as book_bars; mod zipper; mod templates; mod bookoption; mod misc; mod text_view; #[cfg(feature = "proofread")] mod grammar_check; #[cfg(feature = "proofread")] mod grammalecte; #[cfg(feature = "proofread")] mod repetition_check; #[cfg(test)] mod tests;