Crate crowbook

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.14.1", 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 Tokens)

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

Trait 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 Tokens.

Type Aliases

Result

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