Crate crowbook [−] [src]

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

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:

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

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 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.
Chapter	Represents the content of a chapter.
Error	Crowbook Error type.
Parser	A parser that reads markdown and convert it to AST (a vector of `Token`s)
ResourceHandler	Resource Handler.
Source	Source of an error.
Stats

Enums

BookOption	Structure for storing a book option
Data	The inner type for an annotation.
Number	Numbering for a given chapter or part
Token	A single token representing a Markdown element.

Traits

BookRenderer	Thait that must be implemented by the various renderers to render a whole book.
Renderer	Renderer trait, implemented by various renderer to render a list of `Token`s.

Type Definitions

Result

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