Crate crowbook [−] [src]

Note: this documentation is relative to crowbook as a library. For documentation regarding the program crowbook, see the Github page.

Book

The central structure of Crowbook is Book, who coordinates everything.

Its roles are:

reading a book configuration file and setting the book options accordingly
reading the chapters (written in Markdown) listed in this configuration file to Parser, get back an AST and store it in memory
call HtmlRenderer, EpubRenderer, LatexRenderer and/or OdtRenderer according to the book's parameters and generate the appopriate files.

Example

use crowbook::{Book, InfoLevel};
// Reads configuration file "foo.book" (and set verbosity do default level)
let mut book = Book::new_from_file("foo.book", InfoLevel::Info, &[]).unwrap();
// Render all formats according to this configuration file
book.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 Tokens). 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);

Structs

Book	A Book.
BookOptions	Contains the options of a book.
EpubRenderer	Renderer for Epub
French	Implementation for french 'cleaning'
HtmlDirRenderer	Multiple files HTML renderer
HtmlRenderer	Renders HTML document in a standalone file.
LatexRenderer	LaTeX renderer
Logger	Logs info and warning message and choose whether to display them according to verbosity
OdtRenderer	Rendererer for ODT
Parser	A parser that reads markdown and convert it to AST (a vector of `Token`s)
ResourceHandler	Resource Handler.

Enums

BookOption	Structure for storing a book option
Error	Crowbook's error type
InfoLevel	The level of information to display to a logger#
Number	Numbering for a given chapter
Token	A single token representing a Markdown element.

Traits

Cleaner

Trait for cleaning a string. This trait should be called for text that is e.g. in a paragraph, a title, NOT for code blocks, hyperlinks and so on!

Type Definitions

Result

Crowbook's Result type, used by many methods that can fail