Struct crowbook::Book

pub struct Book {
    pub chapters: Vec<Chapter>,
    pub options: BookOptions,
    // some fields omitted
}

A Book.

Probably the central structure for of Crowbook, as it is the one that calls the other ones.

It has the tasks of loading a configuration file, loading chapters and using Parserto parse them, and then calling various renderers (HtmlRendrer, LatexRenderer, EpubRenderer and/or OdtRenderer) to convert the AST into documents.

Examples

use crowbook::{Book, Number};
// Create a book with some options 
let mut book = Book::new();
book.set_options(&[("author", "Joan Doe"),
                   ("title", "An untitled book"),
                   ("lang", "en")]);

// Add a chapter to the book
book.add_chapter_from_source(Number::Default, "# The beginning#\nBla, bla, bla".as_bytes()).unwrap();

// Render the book as html to stdout
book.render_format_to("html", &mut std::io::stdout()).unwrap();

Fields

chapters: Vec<Chapter>

Internal structure. You should not accesss this directly except if you are writing a new renderer.

options: BookOptions

Options of the book

Methods

impl Book

fn new() -> Book

Creates a new, empty Book

fn set_error(&self, msg: &str)

Sets an error message to the progress bar, if it is set

fn add_progress_bar(&mut self, emoji: bool)

Adds a progress bar where where info should be written.

See indicatif doc for more information.

fn add_format<S: Into<String>>(
    &mut self,
    format: &'static str,
    description: S,
    renderer: Box<BookRenderer>
) -> &mut Self

Register a format that can be rendered.

The renderer for this format must implement the BookRenderer trait.

Example

use crowbook::{Result, Book, BookRenderer};
use std::io::Write;
struct Dummy {}
impl BookRenderer for Dummy {
    fn render(&self, book: &Book, to: &mut Write) -> Result<()> {
        write!(to, "This does nothing useful").unwrap();
        Ok(())
     }
}

let mut book = Book::new();
book.add_format("foo",
                "Some dummy implementation",
                Box::new(Dummy{}));

fn set_options<'a, I>(&mut self, options: I) -> &mut Book where
    I: IntoIterator<Item = &'a (&'a str, &'a str)>, 

Sets the options of a Book

Arguments

• options: a (possibly empty) list (or other iterator) of (key, value) tuples.

Example

use crowbook::Book;
let mut book = Book::new();
book.set_options(&[("author", "Foo"), ("title", "Bar")]);
assert_eq!(book.options.get_str("author").unwrap(), "Foo");
assert_eq!(book.options.get_str("title").unwrap(), "Bar");

fn load_file<P: AsRef<Path>>(&mut self, path: P) -> Result<&mut Book>

Loads a book configuration file

Argument

• path: the path of the file to load. The directory of this file is used as a "root" directory for all paths referenced in books, whether chapter files, templates, cover images, and so on.

Example

let mut book = Book::new();
let result = book.load_file("some.book");

fn load_markdown_file<P: AsRef<Path>>(&mut self, path: P) -> Result<&mut Self>

Loads a single markdown file

This is not used to add a chapter to an existing book, but to to load the book configuration file from a single Markdown file.

Since it is designed for single-chapter short stories, this method also sets the tex.class option to article.

Example

use crowbook::Book;
let mut book = Book::new();
book.load_markdown_file("foo.md"); // not unwraping since foo.md doesn't exist

fn read_markdown_config<R: Read>(&mut self, source: R) -> Result<&mut Self>

Reads a single markdown config from a Readable object.

Similar to load_markdown_file, except it reads a source instead of a file.

Example

use crowbook::Book;
let content = "\
---
author: Foo
title: Bar
---


Some content in *markdown*.";

let mut book = Book::new();
book.read_markdown_config(content.as_bytes()).unwrap();
assert_eq!(book.options.get_str("title").unwrap(), "Bar");

fn read_config<R: Read>(&mut self, source: R) -> Result<&mut Book>

Reads a book configuration from a Readable source.

Book configuration

A line with "option: value" sets the option to value

• chapter_name.md adds the (default numbered) chapter

• chapter_name.md adds the (unnumbered) chapter

1. chapter_name.md adds the (custom numbered) chapter

See also

• load_file

Example

use crowbook::Book;
let content = "\
author: Foo
title: Bar

! intro.md
+ chapter_01.md";
 
let mut book = Book::new();
book.read_config(content.as_bytes()); // no unwraping as `intro.md` and `chapter_01.md` don't exist

fn render_format(&self, format: &str)

Renders the book to the given format if output.{format} is set; do nothing otherwise.

Example

use crowbook::Book;
let mut book = Book::new();
/* Will do nothing as book is empty and has no output format specified */
book.render_format("pdf");

fn render_all(&mut self)

Generates output files acccording to book options.

Example

use crowbook::Book;
let content = "\
---
title: Foo
output.tex: /tmp/foo.tex
---


Bar and baz, too.";

Book::new()
      .read_markdown_config(content.as_bytes())
      .unwrap()
      .render_all(); // renders foo.tex in /tmp

fn render_format_with_bar(&self, format: &str, bar: usize)

Renders the book to the given format and reports to progress bar if set

fn render_format_to_file_with_bar<P: Into<PathBuf>>(
    &self,
    format: &str,
    path: P,
    bar: usize
) -> Result<()>

fn render_format_to<T: Write>(&mut self, format: &str, f: &mut T) -> Result<()>

Render book to specified format according to book options, and write the results in the Write object.

This method will fail if the format is not handled by the book, or if there is a problem during rendering, or if the renderer can't render to a byte stream (e.g. multiple files HTML renderer can't, as it must create a directory.)

See also

• render_format_to_file, which creates a new file (that can be a directory).
• render_format, which won't do anything if output.{format} isn't specified in the book configuration file.

fn render_format_to_file<P: Into<PathBuf>>(
    &mut self,
    format: &str,
    path: P
) -> Result<()>

Render book to specified format according to book options. Creates a new file and write the result in it.

This method will fail if the format is not handled by the book, or if there is a problem during rendering.

Arguments

• format: the format to render;
• path: a path to the file that will be created;
• bar: a Progressbar, or None

See also

• render_format_to, which writes in any Writeable object.
• render_format, which won't do anything if output.{format} isn't specified in the book configuration file.

fn add_chapter_from_named_source<R: Read>(
    &mut self,
    number: Number,
    file: &str,
    source: R
) -> Result<&mut Self>

Adds a chapter to the book.

This method is the backend used both by add_chapter and add_chapter_from_source.

fn add_subchapter(&mut self, level: i32, file: &str) -> Result<&mut Self>

Adds a chapter, as a file name, to the book

fn add_chapter(&mut self, number: Number, file: &str) -> Result<&mut Self>

Adds a chapter, as a file name, to the book

Book will then parse the file and store the AST (i.e., a vector of Tokens).

Arguments

• number: specifies if the chapter must be numbered, not numbered, or if its title must be hidden. See Number.
• file: path of the file for this chapter

Returns an error if file does not exist, could not be read, of if there was some error parsing it.

fn add_chapter_from_source<R: Read>(
    &mut self,
    number: Number,
    source: R
) -> Result<&mut Self>

Adds a chapter to the book from a source (any object implementing Read)

Book will then parse the string and store the AST (i.e., a vector of Tokens).

Arguments

• number: specifies if the chapter must be numbered, not numbered, or if its title must be hidden. See Number.
• content: the content of the chapter.

Returns an error if there was some errror parsing content.

impl Book

Return the style of a bar

fn private_add_progress_bar(&mut self, emoji: bool)

Adds a progress bar where where info should be written.

See indicatif doc for more information.

fn bar_finish(&self, bar: Crowbar, state: CrowbarState, msg: &str)

Sets a finished message to the progress bar, if it is set

fn add_second_bar(&mut self, msg: &str, len: u64)

Adds a secondary progress bar to display progress of book parsing

fn inc_second_bar(&self)

Increment second bar

fn add_spinner_to_multibar(&mut self, key: &str) -> usize

Adds a spinner labeled key to the multibar, and set mainbar to "rendering"

fn bar_set_message(&self, bar: Crowbar, msg: &str)

Trait Implementations

impl Drop for Book

fn drop(&mut self)

Executes the destructor for this type.